NAME
antelopemakefile - Antelope Makefile format
DESCRIPTION
This manual page describes the usage and guidelines for Antelope Makefiles,
including the required environment variables, default targets and rules.
Antelope makefiles all include a single file $(ANTELOPEMAKE) which contains the
boiler plate targets and rules. These rules depend on the environment
variable ANTELOPE, which defines various destination directories.
This central included file is intended to simplify the process of porting
to different architectures. On machines other than Suns, you may find that
GNU make is required rather than the make which your vendor ships.
TARGETS
The included $(ANTELOPEMAKE) defines a
range of targets.
The standard set are the following:
-
all
Creates the library or program in the current directory.
-
Include
Installs include files into $ANTELOPE/include. This is a necessary
first step because of interdependencies among the various libraries.
-
install
Installs the library or program and man pages in the appropriate directories
(see ENVIRONMENT VARIABLES below).
-
uninstall
Removes the library or program and man pages from the appropriate directories
-
clean
Removes executables, libraries, object files and all other intermediate files from the
current directory.
-
purge
Removes the .make.state file created by Sun's make, and various other
temporary files.
The following targets are useful for selectively installing
something from a directory:
-
BIN
make and install only the executable programs
-
PF
make and install only the parameter files
-
DATA
make and install only the data files
-
DEMOS
make and install only the demo files
-
DOCS
make and install only the document files
-
EXAMPLES
make and install only the examples
-
INCLUDE
make and install only the include files
-
MAN
make and install only the man pages
-
GRAPHIC
make and install only graphics.
Finally, these targets have special and unusual applications:
-
static
Creates executables linked against only the static libraries.
If a required library has only a dynamic version, this will not
work. On the other hand, on a Mac, the linker resolves everything
in the dynamic library regardless of the library order on the link
line.
-
purify
Creates executables using the purify command.
STANDARD MACROS
The following macros are useful shorthands for the link libraries
required when a program uses libstock, libcoords, libds, libtr,
liborb or libPkt. Note that libds uses libstock and libcoords,
and libtr uses libds. You may find it convenient to use ldlibs(1) to
figure out what the ldlibs line should be.
-
STOCKLIBS
A convenient macro for the ldlibs line, which defines all the libraries
necessary for programs using the libraries libcoords and libstock.
-
DBLIBS
A convenient macro for the ldlibs line, which defines all the libraries
necessary for programs using the Datascope library libds.
-
TRLIBS
A convenient macro for the ldlibs line, which defines all the libraries
necessary for programs using the trace library libtr.
-
ORBLIBS
A convenient macro for the ldlibs line, which defines all the libraries
necessary for programs using the orb and packet libraries.
-
F77LIBS
The set of libraries necessary to link fortran subroutines with a c main
program. This varies a lot depending on the compiler and operating system.
-
TCLLIBS
(deprecated)
A convenient macro for the ldlibs line, which defines all the tcl
libraries necessary for linking a special purpose tcl shell. (The
package require mechanism is preferred to building a special
purpose shell.)
-
TKLIBS
(deprecated)
A convenient macro for the ldlibs line, which defines all the tcl
libraries necessary for linking a special purpose tk shell; the
TCLLIBS libraries are not included. (The package require
mechanism is preferred to building a special purpose shell.)
-
TCLLIB
Directory from which Tcl/Tk libraries are linked (i.e., -L$(TCLLIB))
-
TCLINCLUDE
Directory where Tcl/Tk include files are found (i.e., -I$(TCLINCLUDE)).
A few tcl/tk include files usually found only in the source directories
are installed here, e.g., "tkint.h".
-
PERL
Path to perl executable
-
VERSION
Used for dynamic library versions.
-
DBG
Debugging flags for the compiler and/or linker. Usually set to "-g".
-
LEX
flex
-
CP
cp -f
-
F77LIBS
Fortran libraries needed when fortran subroutines are loaded with
c main program. The easiest way to deal with this, though, is to
use f77 to link.
-
LORDER
-
TSORT
These programs are used to sort the order in which object files are presented
to the ar(1) or ld(1) programs. This may enhance the link speed or execution
speed somewhat.
-
XINCLUDE
Include directory for X Windows programs.
-
XLIB
Directory containing libX11 and other X Windows libraries.
-
INSTALL
Program to use for install. Antelope uses a perl(1) script deposit(1)
which recognizes various kinds of destinations, creates any necessary
subdirectories, and ensures the proper permissions.
-
MAKE
Make -e is specified so that environment variables override macro
assignments inside a Makefile.
ENVIRONMENT VARIABLES
The following environment variables should be defined before running an
Antelope Makefile:
-
ANTELOPE
This is intended to be the head of a file system hierarchy which contains
the Antelope source, object, man pages and executables.
-
ANTELOPEMAKE
This variable indicates the Antelope specific boiler plate for make -- the
rules that support the targets above.
MAKE VARIABLES
Standard Antelope makefiles set a few variables to indicate the targets that
should be installed, and then may have specific rules for the construction
of some targets. In general, the goal is to keep the Makefiles as small
and simple as possible, and to avoid specifying rules if possible.
The standard set of variables
which may be defined are:
-
BIN
For Makefiles which create an executable, this variable should name the
executable(s), e.g.
BIN=dbloc2 dbloc2_buttons
Most Makefiles name only one executable, but
it's permissible to have several. If BIN is defined, then make install
creates the executable(s) and install it(them) into $(ANTELOPE/bin).
-
LIB
For Makefiles which create a library, this variable names the library.
If LIB is defined, then make install creates the library, installs
it into $(ANTELOPE)/static, and runs ranlib on it (on BSD systems).
LIB=libstock.a
-
DLIB
For Makefiles which create a dynamic library, this variable names the library.
If DLIB is defined, then make install creates the library and installs
it into $(ANTELOPE)/lib.
DLIB=$(LIB:.a=$(DSUFFIX))
-
INCLUDE
Makefiles which create libraries should also create an include file
which declares the routines in the libraries, as well as any special
data structures and parameters which are accessible to the user.
This list of files is installed in $(ANTELOPE)/include
INCLUDE = \
arrays.h \
bury.h
-
PF
Some programs require a variety of parameters (more than comfortably
fit on the command line) to be configured. These programs may use
a parameter file (see pf(3)). Such parameter files
should be named after the program, with a .pf suffix, and declared in
the Makefile with the PF variable. This list of files is
installed in $(ANTELOPE)/data/pf.
PF=pfcheck.pf elog.pf
-
DATADIR
-
DATA
Some routines, usually in libraries, require the presence of a data
file. For example, the niceplot routines require a font file, and
the db routines require schema files. This variable specifies a list
of files which should be installed in $(ANTELOPE)/data/$(DATADIR).
DATA=srnames.fer
DATADIR=regions
-
DEMODIR
-
DEMO
These are for working examples of rtexec systems which can be installed
and started using rtdemo(1). Each such demo is installed in its
own subdirectory $(DEMODIR) under $ANTELOPE/demo.
The actual files installed there are listed in $(DEMO).
-
DOCDIR
-
DOC
Documents other than man pages are installed in their own subdirectory
$(DOCDIR) under $ANTELOPE/doc.
The actual files installed there are listed in $(DOC).
-
HTMLDIR
-
HTML
Web pages are installed in their own subdirectory
$(HTMLDIR) under $ANTELOPE/html. The actual files installed there are listed in $(HTML).
-
EXAMPLEDIR
-
EXAMPLE
Programming examples are installed into a subdirectory $(EXAMPLEDIR) of $ANTELOPE/example.
The actual files installed there are listed in $(EXAMPLE).
-
GRAPHIC
This macro identifies graphic files which web browsers can recognize in <img> blocks;
the identified files are installed into the directory $ANTELOPE/man/graphic;
the html version of man pages can reference these graphics with the special .GR pseudo-troff
code.
-
LICENSES
This macro identifies license files to be put in $ANTELOPE/data/licenses. These files
usually contain the usage and distribution terms of source-code not written directly at BRTT. These
files should be named for installation as
license_program.txt
-
MAN1, MAN3, MAN3F, MAN3P, MAN3T, MAN5, MAN6, MAN7, MAN8, MAN9
These variables define man pages which need to be installed. For
instance, if MAN1 is defined, then make install places the
specified manual page into $(ANTELOPEMAN)/man1. Note that
MAN3P is for perl routines, MAN3T is for tcl/tk routines, and MAN3F is
for fortran routines.
-
CLEAN
The standard make clean removes the usual targets $(BIN) and $(LIB),
and any .o files. However, your Makefile may create intermediate
files which are not removed. Adding these to the CLEAN macro
causes these to be removed also. (Another approach is to add your
own rules for clean).
-
OPENSRCDIR
-
OPENSRC
Source-code for open-source programs are installed into a subdirectory $(OPENSRCDIR) of $ANTELOPE/opensrc.
The actual files installed there are listed in $(OPENSRC).
-
PURGE
Perhaps there are files which are only removed occasionally, not at every
make clean. These can be listed in the PURGE macro.
-
UNINSTALL
The standard make uninstall removes the standard targets $(BIN), $(LIB),
$(DATADIR)/$(DATA), $(INCLUDE), etcetera. However, if you add your
own rules which installed things, then you can either add the ultimate
destinations to the UNINSTALL macro, or write your own uninstall
rule.
In addition to the variables above defining targets, the following variables
are useful for modifying the options used during compiles and links:
-
cflags
special c compiler flags.
-
fflags
special Fortran compiler flags.
It's best to avoid specifying extra compiler flags, as these are often
different for different compilers on different machines.
In particular, it's bad to explicitly specify -g as this makes it
difficult to globally compile using the optimizer.
-
ldlibs
libraries to link.
-
ldflags
flags to the linker program.
-
OPTIMIZE
This can be a blank separated list of c files which should be
compiled with the optimizer turned on.
-
Variables that must be defined BEFORE include $(ANTELOPEMAKE):
The following variables must be defined immediately preceding the
line include $(ANTELOPEMAKE). Order is important.
-
TOOLCHAIN
The compilers used by the Antelope compile process are determined by
the TOOLCHAIN variable. If this is set to native, compilers found along
the execution path are used. If this is set to another value, such as
centos6_gcc530 on Linux, compilers are used from the corresponding subdirectory
of the /opt/antelope/toolchains directory, which must be properly
installed before attempting to build anything else. See the install_toolchain(1)
man-page for details on installing a pre-compiled toolchain. The TOOLCHAIN variable
must be defined before the include $(ANTELOPEMAKE) line or it will be ignored.
TOOLCHAIN may also be set via an environment variable, or on the make(1) command
line with an argument such as
% make TOOLCHAIN=native
-
Variables that must be defined AFTER include $(ANTELOPEMAKE):
The following variables must be defined immediately following the
line include $(ANTELOPEMAKE). Order is important.
-
DIRS
The default rules in $(ANTELOPEMAKE) want to perform recursive makes
through all lower directories. This can be circumvented by specifying
the directories explicitly with a DIRS= line. This can be used
to stop the descent, choose only certain subdirectories, and/or choose
the order in which the make's are run.
-
FIRSTDIRS
Explicitly naming all the subdirectories to choose a particular order
of compilation requires more maintenance: if a directory is added later,
it must also be added to the Makefile. Alternatively, specifying
FIRSTDIRS ensures that make is run in these directories first -- and
then a second time in the default order. (Presumably, nothing happens
the second time).
-
DEST
-
SUBDIR
The default action of the various install rules is to place something
in the bin, lib, data, and man subdirectories of $DEST. Normally DEST is
defined as $(ANTELOPE)$(SUBDIR) in antelopemakefile. Thus the actual
destination directories can be easily changed, by redefining either DEST or SUBDIR.
This is most commonly exploited by
by explicitly specifying SUBDIR=/local before the include $(ANTELOPEMAKE) line,
causing files to be installed in a subdirectory local below $ANTELOPE.
This is useful for maintaining a local collection of
programs compiled against Antelope libraries, without modifying the programs distributed by BRTT.
RULES
$(ANTELOPEMAKE) adds a number of special purpose rules for installing
programs and data files. These are primarily used for building an Antelope
distribution at BRTT, but you may use these rules for installing your own
programs, or compiling the contributed-code ("contrib") software. (The contrib software is compiled
and distributed separately from BRTT software. Although the Antelope User Community
makes compiled versions available at the time of each release, you may wish to compile
versions yourself if bug fixes are released of if you make your own modifications.
See the man-page
contrib(5) for further details.)
In addition, $(ANTELOPEMAKE) recognizes some additional suffixes:
suffix |
interpreter |
.xpl |
$antelope/bin/perl |
.xppl |
perl |
.xtcl |
$antelope/bin/atcl |
.xwish |
$antelope/bin/awish |
.oxtcl |
$antelope/bin/oatcl |
.oxwish $antelope/bin/oawish |
.csh |
/bin/csh |
.wphp ?? |
.php |
php |
These suffixes are similar to the standard .sh suffix; they cause an executable
script to be created from the corresponding source file. In the standard
case of .sh, a file script.sh is copied to a file script, and made executable.
For the new suffixes, it's useful to prepend a few special lines to specify the
interpreter to be used. These "special" lines may change from release to release,
hence it's better to keep them separate from the scripts. (They're actually
kept in the templates directory).
The task of copying the template and script and making the result executable is
accomplished by the script produce(1).
At BRTT, this script is also sometimes used to interpolate certain global values
which may change from release to release into scripts, man pages or data files.
See getid(1) for more detail.
EXAMPLE
Here's a simple Makefile which creates a library.
It's a good idea to include a method for making a dynamic (shared) library
as well as a static library.
INCLUDE=tttaup.h tttaup.i
LIB = libtttaup.a
MAN3= ptime.3 ptime.3f
include $(ANTELOPEMAKE)
DIRS=
OBJS= tt_taup.o subs.o delta.o ptime.o ptime_.o
$(LIB) : $(OBJS)
$(RM) $@
$(AR) $(ARFLAGS) $@ $(OBJS)
$(RANLIB) $@
Running
make install in the directory containing this Makefile installs
tttaup.h and tttaup.i in $(ANTELOPE)/include, ptime.3 and ptime.3f in $(ANTELOPE)/man/man3,
and libtttaup.a in $(ANTELOPE)/lib.
Here's a simple Makefile which creates a program:
PF=dbverify.pf
MAN1=dbverify.1 dbchkwf.1
BIN=dbverify dbchkwf
ldlibs = $(DBLIBS)
include $(ANTELOPEMAKE)
DIRS=
OBJS=dbverify.o check_aview.o dbverify_expr.o dbfind_dups.o\
dbshow_select.o
dbverify : $(OBJS)
$(CC) $(CFLAGS) -o $@ $(OBJS) $(LDFLAGS) $(LDLIBS)
Running
make install in the directory containing this Makefile installs
dbverify.pf in $(ANTELOPE)/data/pf, dbverify.1 and dbchkwf.1 in $(ANTELOPE)/man/man1,
and dbverify and dbchkwf in $(ANTELOPE)/bin. Note the use of the DBLIBS macro
definition, rather than an explicit list.
You can get a prototype copy of a makefile with the command mkmk(1),
which prints a makefile template with comments. This can be edited to
produce a custom makefile:
% mkmk -
BIN=
LIB=
DLIB=$(LIB:.a=$(DSUFFIX))
DATADIR=
DATA=
INCLUDE=
PF=
MAN1=
MAN3=
MAN5=
CLEAN=
cflags=
fflags=
ldflags=
ldlibs=
include $(ANTELOPEMAKE)
DIRS=
OBJS=
$(BIN) : $(OBJS)
$(RM) $@
$(CC) $(CFLAGS) -o $@ $(OBJS) $(LDFLAGS) $(LDLIBS)
OBJS=
$(BIN) : $(OBJS)
$(RM) $@
$(FC) $(FFLAGS) -o $@ $(OBJS) $(LDFLAGS) $(LDLIBS)
OBJS=
$(LIB) : $(OBJS)
$(RM) $@
$(AR) $(ARFLAGS) $@ $(LORDER) $(OBJS) $(TSORT)
$(RANLIB) $@
$(DLIB) : $(OBJS)
$(RM) $@
$(DLD) $(DLDFLAGS) -o $(DLIB) $(LORDER) $(OBJS) $(TSORT) $(DLDLIBS)
DIAGNOSTICS
Standard make(1) diagnostics.
SEE ALSO
antelope(3)
make(1)
mkmk(1)
manpage(1)
ldlibs(1)
template(1)
produce(1)
deposit(1)
getid(1)
BUGS AND CAVEATS
The standard $(ANTELOPEMAKE) replaces the standard rules for generating .f
files from .F files (by running cpp(1)) to keep a local
copy of the .f file, for use by the debugger.
The clean target removes all the BIN targets; this can be a problem if a
target is not itself created by make, but is a static
source file. In this case, make clean removes the original source file.
To avoid this with scripts (for instance), make the source file
target.sh,
and then make will create the executable file target.
AUTHOR
Daniel Quinlan