Getting Started

Documentation

Glish

Learn More

Programming

Contact Us

Version 1.9 Build 1556

News	FAQ
Search	Home

Subsections

• Synopsis
• Description
• Notes
• Examples
• See also

Code development makefile rules

Use of the AIPS++ makefiles for code development.

Synopsis

makefile
makefile.{app,aps,chk,doc,ftn,imp,pkg,scr,tst}

Description

The AIPS++ code development targets are listed below by category. These lists are not exhaustive, but do aim to cover everything of practical use. In particular, they omit targets which are intended for the internal use of the makefiles.

A target is labelled as ``recursive'' if it causes gmake (p) to be invoked in all subdirectories. It is ``general'' if it applies to all makefiles; such targets are defined in makedefs (p). A target is ``specific'' if defined in a specific makefile.

Some targets such as allsys have a general meaning, the specific behaviour of which differs for specific makefiles. These are referred to as ``general/specific'' and where appropriate the details of a target's behaviour are described for each of the generic makefiles, for the top-level makefile (top), and the installation makefile (ins).

Targets which apply only if the RCS source code repositories are present are marked as ``RCS''.

Programmer-oriented variables:

Rules for programmer-oriented targets look for source files first in the programmer directory and if not found search the corresponding subdirectory of $AIPSCODE which is referred to below as $(CODEDIR). This means that programmers can compile code in their own workspace without having to copy source files from $(CODEDIR), thereby minimizing the number of files that need to be present in the programmer's workspace and reducing the possibility that these may be ``stale''.

Certain variables are defined in makedefs (p) for the exclusive use of programmer-oriented rules and may be redefined as necessary on the gmake (p) command line. These are:

• PGMRINCD
  Repository for include files produced by parser/generators such as lex and bison.

  The default makedefs sets this to $PGMRARCH if that directory exists (but the site-specific makedefs may redefine it).

  Output is left in the current directory if $PGMRINCD is blank.

• PGMRAUXD
  Repository for dependency lists and timestamp files generated by the programmer dependency analysis.

  The default makedefs sets this to $PGMRARCH/aux if that directory exists (but the site-specific makedefs may redefine it).

  Output is left in the current directory if $PGMRAUXD is blank.

• PGMRLIBD
  Programmer directory for class object modules and libraries.

  The default makedefs sets this to $PGMRARCH/lib if that directory exists (but the site-specific makedefs may redefine it).

  Output is left in the current directory if $PGMRLIBD is blank.

• PGMRBIND
  Directory where programmer executables are deposited; programmers should add this directory to their PATH.

  The default makedefs sets this to $PGMRARCH/bin if that directory exists (but the site-specific makedefs may redefine it).

  Output is left in the current directory if $PGMRBIND is blank.

• PGMRPTRD
  Directory serving as the programmer template repository.

  The default makedefs sets this to $PGMRARCH/ptrepository as a suggestion and for the convenience of the site-specific makedefs in setting compiler options. However, the site-specific makedefs may redefine it or simply ignore it, and PGMRPTRD is not used directly by any of the makefiles.

  Defaults to a compiler-specific directory if blank.

• EXTRA_PGMRINCL
  Extra include directories to be prepended to the internally defined include path, PGMRINCL, which may also be redefined.

• EXTRA_PGMRLIBS
  Extra object libraries to be appended to the internally defined library list, PGMRLIBS, which may also be redefined.

• OPT
  Optimization level to use for compilations. The exact meaning of this is defined in the site-specific makedefs file.

• OPTLIB
  This variable may be set (to anything) to force a debug programmer compilation to link to the optimized system libraries. This is useful for reducing the size of executables and the time taken to link them if you only wish to debug your own code.

• *FLAGS
  Options to be used for programmer compilations (CPPFLAGS, CFLAGS, C++FLAGS, FFLAGS, LDFLAGS and CXXARFLAGS).

• EXTRA_*FLAGS
  Extra compiler flags to be appended to *FLAGS (CPPFLAGS, CFLAGS, C++FLAGS, FFLAGS, LDFLAGS and CXXARFLAGS).

These variables may be printed with the show_prg target. The *FLAGS variables are the subject of a convention for setting alternate programmer compilation flags described in the section on 11.3.

Programmer-oriented targets:

The programmer-oriented targets are as follows; note that where targets are defined in terms of a gmake (p) variable, for example $(SUBDIRS), it, and all other variables, may be printed via the show_all target:

• all : (default programmer target, general/specific)
  This is declared generally in makedefs as the default target if gmake (p) has not been invoked from a subdirectory of $AIPSCODE. Its dependencies and commands are defined in the specific makefiles to compile all object modules, executables, etc. from files in the current directory.
  • app: Compile this application and put the executable in $(PGMRBIND).
  • aps: Compile all applications which have their main .cc file in the programmer's workspace and put the executables in $(PGMRBIND).
  • chk: Does nothing.
  • doc: Compile all info files and POSTSCRIPT documents with sources in the current directory.
  • ftn: Update all programmer object library modules which have sources in the current directory.
  • imp: Update all programmer object library modules which have sources in the current directory.
  • ins: Compile all utility programs with sources in the current directory.
  • pkg: Does nothing.
  • src: Does nothing.
  • top: Create the include subdirectory and populate it with symbolic links to the implement directories of all installed packages (see mktree (p)).
  • tst: Compile all test programs with sources in the current directory and put the executables in $(PGMRBIND).

• $(SUBDIRS) : (general)
  makedefs sets the SUBDIRS variable to the names of all subdirectories which have a makefile, thus making them recognized targets. If the RCS source code repositories exist then $(SUBDIRS) lists the subdirectories of the corresponding RCS directory. This list is then made the target of a rule for creating the subdirectory and its RCS symlink (see mktree (p)), and initiating a gmake (p) within it. Note that this target has a system-oriented counterpart which behaves similarly.

• clean : (general/specific)
  This target causes intermediate files to be deleted. It is defined generally in makedefs with a dependency which may be defined in the specific makefiles as the target of a rule to delete additional files. General files deleted are * , *%, a.out, and core. The specific makefiles may delete more:
  • app: Deletes * , *%, and $(PCKGMOD).lock from the $(PGMRAUXD) directory, and deletes *.i, *.o, *.cdb, *.cyi, a.out, and core from the $(PGMRBIND) directory.
  • aps: Deletes * , *%, and $(PACKAGE)=*.lock from the $(PGMRAUXD) directory, and deletes *.i, *.o, *.cdb, *.cyi, a.out, and core from the $(PGMRBIND) directory.
  • chk: (none)
  • doc: *.aux, *.bbl, *.blg, *.cp, *.cps, *.dvi, *.fi, *.fis, *.fn, *.fns, *.idx, *.ilg, *.ind, *.ky, *.kys, *.lof, *.log, *.pg, *.pgs, *.toc, *.tp, *.tps, *.vr, *.vrs, *.info, *.info-*
  • ftn: Deletes *.o a.out, and core from the $(PGMRLIBD) directory.
  • imp: Deletes *.i, *.o, *.cdb, *.cyi, a.out, and core from the $(PGMRLIBD) directory, deletes * , *%, *.lcc, and *.ycc from the $(PGMRINCD) directory, and deletes * , *% and $(PCKGMOD).lock from the $(PGMRAUXD) directory.
  • ins: *.i, *.o
  • pkg: (none)
  • src: (none)
  • top: (none)
  • tst: Recursively deletes *_tmp* from the current directory, deletes *  and $(PCKGMOD).lock from the $(PGMRAUXD) directory, and deletes *.i, *.o, *.cdb, *.cyi, a.out, and core from the $(PGMRLIBD) and $(PGMRBIND) directories.

• cleaner : (general/specific)
  This target is defined generally in makedefs with a dependency which may be defined in the specific makefiles as the target of a rule to delete additional files. Generally this target invokes the clean target and then deletes source files in the current directory which have been checked out without a lock. It determines these as any file in the current directory without write permission and with a corresponding RCS version file. The specific makefiles may go further:
  • app: For the application with source code in the current directory or $(CODEDIR); deletes the associated dependency list and timestamp files, deletes the programmer library for the application, recursively deletes any tmplinst subdirectory (see mkinst (p)), and deletes the executable for the application.
  • aps: Deletes the dependency lists and timestamp files for all applications in this package, and deletes the executables for any applications with source code in system or programmer application subdirectories.
  • chk: (none)
  • doc: Deletes all .ps files generated from .latex, .texi, or .tex files, and recursively deletes all directories generated by latex2html from .latex sources.
  • ftn: Deletes the programmer's private FORTRAN library for the package.
  • imp: Deletes the dependency lists and timestamp files for the package/module, and deletes the programmer's private C++ library for the package.
  • ins: Deletes the executables for any utility programs with source code in the current directory or $(CODEDIR).
  • pkg: (none)
  • scr: (none)
  • top: (none)
  • tst: For all test programs with source code in the current directory or $(CODEDIR); deletes the associated dependency lists and timestamp files, deletes the programmer library, recursively deletes any tmplinst subdirectory (see mkinst (p)), and deletes the executables.

• cleanest : (general/specific)
  This target is defined generally in makedefs with a dependency which may be defined in the specific makefiles as the target of a rule to delete additional files. Generally this target just invokes the cleaner target. The specific makefiles may go further:
  • app: (none)
  • aps: (none)
  • chk: (none)
  • doc: (none)
  • ftn: (none)
  • imp: Deletes all of the programmer's dependency lists and timestamp files in $(PGMRAUXD), deletes all object libraries in $(PGMRLIBD), recursively deletes the programmer's template repository $(PGMRPTRD), and recursively deletes any tmplinst subdirectory (see mkinst (p)).
  • ins: (none)
  • pkg: (none)
  • scr: (none)
  • top: (none)
  • tst: (none)

  Note that since this target has the potential to delete much more than was possibly desired by the programmer it is advisable to do a dry run using

     gmake -n cleanest
  

  before using it.

• %.lcc : (specific, pattern rule)
  Preprocess a .l file using $(LEX) and leave the resulting .lcc file in $(PGMRINCD).
  • imp: Preprocess the .l file associated (probably) with a class implementation.

• %.ycc : (specific, pattern rule)
  Preprocess a .y file using $(BISON) and leave the resulting .ycc file in $(PGMRINCD).
  • imp: Preprocess the .y file associated (probably) with a class implementation.

• %.d : (specific, pattern rule)
  List the dependencies of a source file. A side effect of this is to update the dependency list for the particular source file if necessary. The contents of the programmer dependency list may differ from that for a system compilation of the same source file if the programmer has private versions of the source file or any of the relevant header files.
  • app: List the dependencies of an application.
  • imp: List the dependencies of a class implementation file.
  • tst: List the dependencies of a test program.

• %.i : (specific, pattern rule)
  Apply the C preprocessor $(CPP) to a source file in the current directory or $(CODEDIR) and put the resulting .i file in $(PGMRLIBD).
  • app: Preprocess the .cc file for an application. The include path will be augmented with current directory (i.e. -I.) and of the corresponding system directory, $(CODEDIR), in that order. This allows applications to maintain their own include files.
  • imp: Preprocess the .cc file for a class implementation.
  • tst: Preprocess the .cc file for a test program. The include path will be augmented with current directory (i.e. -I.) and of the corresponding system directory, $(CODEDIR), in that order. This allows test programs to maintain their own include files.

• %.o : (specific, pattern rule)
  Produce an object module from the corresponding source file in the current directory or $(CODEDIR) and put it in $(PGMRLIBD). Debug compilations are done by default, but optimized compilations can be selected via the OPT variable or alternate programmer compilation flags (see 11.3).
  • app: Compile the .cc file for an application into an object module and put it in $(PGMRLIBD). The include path is augmented with current directory (i.e. -I.) and of the corresponding system directory, $(CODEDIR), in that order. This allows applications to maintain their own include files.
  • ftn: Compile the .f file for a FORTRAN subroutine into an object module and put it in $(PGMRLIBD).
  • imp: Compile the .cc file for a C++ class implementation into an object module and put it in $(PGMRLIBD).
  • ins: Compile the .c file for a utility program into an object module and leave it in the current directory.
  • tst: Compile the .cc file for a test program into an object module and put it in $(PGMRLIBD). The include path is augmented with current directory (i.e. -I.) and of the corresponding system directory, $(CODEDIR), in that order. This allows test programs to maintain their own include files.

• mylib(%.o) : (specific, pattern rule)
  Compile an object module using the %.o pattern rule and insert it into a private library in $(PGMRLIBD), then apply $(RANLIB) to the library.
  • ftn: Compile the .f file for a FORTRAN subroutine and insert it into a private FORTRAN library.
  • imp: Compile the .cc file for a C++ class implementation and insert it into a private C++ library.

• % : (specific, catch-all pattern rule or static pattern rule)
  Compile an object module or executable.
  • app: Catch-all pattern rule to compile an executable. Debug compilations are done by default, but optimized compilations can be selected via the OPT variable or alternate programmer compilation flags (see makedefs (p)).

    The include path will be augmented with current directory (i.e. -I.) and of the corresponding system directory, $(CODEDIR), in that order. This allows an application to maintain a set of include files specific to it.

    The executable will be linked against the library list specified by $(PGMRLIBS) in which private programmer libraries are listed before system libraries (see above).

    The executable will be left in $(PGMRBIND).

  • doc: Catch-all pattern rule to invoke latex2html on the corresponding .latex source file.
  • ftn: Catch-all pattern rule to compile a FORTRAN subroutine if the corresponding library module is out-of-date. The resultant object module is left in the $(PGMRLIBD) directory and is not inserted into the library. Refer to the entry for the imp makefile.
  • imp: Catch-all pattern rule to compile a class implementation if the corresponding library module is out-of-date. The resultant object module is left in the $(PGMRLIBD) directory and is not inserted into the library.

    This rule may be used in conjunction with update_mylib to update several library modules in one invokation of gmake (p) without updating the library for each one. For example,

       gmake Bloggs Boggle update_mylib
    

    Note that this is not the same as

       gmake Bloggs.o Boggle.o update_mylib
    

    Which may cause the object modules to be compiled even if the library modules are up-to-date with respect to their sources.

  • ins: Static pattern rule on $(ALLEXES) to compile a utility program leaving the executable in the current directory.
  • tst: Catch-all pattern rule to compile an executable. Debug compilations are done by default, but optimized compilations can be selected via the OPT variable or alternate programmer compilation flags (see makedefs (p)).

    The executable will be linked against the library list specified by $(PGMRLIBS) in which private programmer libraries are listed before system libraries (see above).

    The executable will be left in $(PGMRBIND).

• depend : (specific)
  Determine dependencies for all sources in the current directory.
  • app: Determine dependencies for the application.
  • aps: Determine dependencies for all applications which have their main .cc file in the programmer's workspace, $(PGMREXES).
  • imp: Determine dependencies for all class implementations with sources in the current directory, $(PGMRIMPS).
  • tst: Determine dependencies for all test programs with sources in the current directory, $(PGMREXES).

• dependencies : (specific, recursive)
  Determine dependencies for all sources in the current directory and in $(CODEDIR).
  • aps: Determine programmer dependencies for all programmer and system applications in this package, $(ALLEXES). This comprises all applications which have their main .cc file in the programmer's workspace, $(PGMREXES), and in the corresponding system directory, $(AIPSEXES).
  • imp: Determine dependencies for all class implementations in the current directory and in $(CODEDIR) and likewise for all subdirectories.
  • tst: Determine dependencies for all test programs in the current directory and in $(CODEDIR).

• exorcise : (specific)
  Delete stale entries from dependency lists and programmer libraries after a source file has been removed from the current directory (e.g. via checkin). Recurses into any tmplinst subdirectory to do the same thing there.
  • app: Cleans up the dependency list and programmer library for the application.
  • imp: Cleans up the dependency list for the software module and the programmer library for the package.
  • tst: Cleans up the dependency list and programmer library for the test program.

• mylib : (specific)
  Compile all sources in the current directory and in $(CODEDIR) to build a complete private object library.
  • app: Instantiate do-it-yourself templates (see mkinst (p)). If a semaphore file called MyTemplatesOnly exists in the programmer's directory then system templates will be excluded from the compilation.
  • ftn: Build a private FORTRAN library.
  • imp: Build a private C++ library.
  • tst: Instantiate do-it-yourself templates (see mkinst (p)). If a semaphore file called MyTemplatesOnly exists in the programmer's directory then system templates will be excluded from the compilation.

• mylibs : (specific)
  Invoke the mylib rule in the current directory and all subdirectories.
  • ftn: Invoke mylib in the current directory and all subdirectories.
  • imp: Invoke mylib in the current directory and all subdirectories.

• tmplinst : (specific)
  Invoke mkinst (p) to generate do-it-yourself template instantiation files. If there is no templates file in the current directory then mkinst is invoked with input from /dev/null in order to delete any stale template instantiation files.
  • app: Generate do-it-yourself template instantiation files for an application.
  • imp: Generate do-it-yourself template instantiation files for a class implementation module.
  • tst: Generate do-it-yourself template instantiation files for an test program.

• inst : (specific)
  Invoke the tmplinst rule to generate do-it-yourself template instantiation files and then invoke the mylib rule in the tmplinst subdirectory to compile and insert them into an object library.
  • app: Generate and compile do-it-yourself templates for an application.
  • imp: Generate and compile do-it-yourself templates for a class implementation module.
  • tst: Generate and compile do-it-yourself templates for a test program(s).

• update_mylib : (specific)
  Insert all object modules into a private library and then apply $(RANLIB) to it. The object modules and library reside in $(PGMRLIBD). The object modules are deleted after the library has been updated.
  • app: Update a private object library associated with an application.
  • ftn: Update a private FORTRAN library.
  • imp: Update a private C++ library.
  • tst: Update a private object library associated with a test program.

• %.dvi : (specific, pattern rule)
  Compile a .dvi file.
  • doc: Compile the .dvi file from the .texi, .latex, or .tex file (in that order of preference) in the current directory or $(CODEDIR) and leave it in the current directory.

    Included files will be searched for in the corresponding .dir subdirectory of the current directory and of $(CODEDIR) in that order. Any L^ATEX-related .bib bibliography files contained in these directories will be processed by BIBTEX.

• %.ps : (specific, pattern rule)
  Compile a .ps POSTSCRIPT file.
  • doc: Compile a .ps POSTSCRIPT file from the corresponding .dvi file in the current directory. If necessary the .dvi file will be generated automatically by gmake (p) by rule-chaining the %.dvi pattern rule.

• doc : (specific)
  Compile all printable documents.
  • doc: Compile all *.texi, *.latex and *.tex files in the current directory into *.ps POSTSCRIPT files and leave them in the current directory.

Notes

• The implement makefile includes the system dependency lists and so may start slowly as it checks to see whether the list is up-to-date (regardless of whether the particular target uses it or not). Inclusion of the dependency list can be circumvented by setting the NODEP variable (to anything). This causes the makefile to start considerably faster.

  NODEP is set automatically if gmake (p) is invoked from a directory which does not reside under $AIPSROOT, that is, a programmer invokation. However, system-oriented targets may also be invoked from a programmer directory, and this would cause the dependency analysis to be circumvented, and the dependency list to be ignored. This may be legitimate if the target invoked does not actually use the dependency list, for example chkout, cleancode or cleansys. In fact, the code distribution system sets NODEP explicitly when it invokes the top-level makefile for these recursive targets for the system (inhale (p)). However, NODEP must not be set for an invokation of the implement makefile for a target which does use the dependency list. A proper resolution of this problem would require the facility for a makefile to examine its target list, but this is not currently possible.

• If the AIPS++ RCS source code repositories are present in an installation all AIPS++ makefiles access them via a symbolic link $AIPSROOT/rcs which is usually set to point to slave. Therefore, the slave RCS repositories are normally the ones consulted. However, it is possible to reset the rcs ``switch'' to master to cause gmake (p) to checkout and/or rebuild AIPS++ from the master repositories. exhale (p) uses this mechanism when constructing a new base release. However, it requires good bandwidth to the master and is only feasible in Socorro.

Examples

The mylib target for the implement makefile rebuilds a programmer's private library in its entirety, including all object modules generated from sources in $(CODEDIR). To rebuild only the modules with sources in the programmer's directory the following would suffice:

   cd $HOME/aips++/code/aips/implement
   gmake

This is the recommended way of updating a private libarary.

See also

The GNU Make manual.
The GNU manual page for gmake.
The unix manual page for ranlib(1).
AIPS++ variable names (§1.2).
gmake (p), GNU make.
makedefs (p), AIPS++ makefile definitions.
mkinst (p), Generate template instantiation files from a list.
updatelib (p), update an AIPS++ object library.