BaBar Software Release Tools Information

Especially: GNUmakefiles

Recent Changes

• 08 Apr, 2000 - Included Steve Gowdy's updates (BobJ)
• 12 Feb, 2000 - Updated 'srtpath' discussion (BobJ)
• 02 Aug, 1998 - Attempted to bring up to date (BobJ)
• 19 Mar, 1998 - Updated some links (John Bartelt)
• 09 Dec, 1997 - Updated section on package directory structure (Bob)
• 12 Aug, 1997 - Added discussion of 'srtpath' (Bob)
• 03 Dec, 1996 - Changed more bin rules for consistency (Bob)
• 27 Nov, 1996 - Changed bin rule example (Bob)
• 27 Apr, 1996 - Added detail throughout, recolibs.mk (Bob)
• 23 Mar, 1996 - More text, added hints (Bob)

General Information

This is a tricky problem, because the system must

• transparently support multiple platforms within the same directory,
• handle multiple versions of multiple packages, and
• work at many different sites,
• when used by very inventive people.

Recommendations

Please try, as much as possible, to stay within the GNU /BFROOT/doc/www/recommendations for makefile structure. They really help portability.

To help limit link order problems

• AppUserBuild.cc files and the files containing main() for a test program should not be put into a library. This can be done easily in the GNUmakefile using

      BINCCFILES := AppUserBuild.cc
  

  There are also BINCFILES and BINFFILES variables for defining C and FORTRAN files respectively.
• Use the PackageList system to maintain your link order.

To limit cross platform problems:

• Use the correct form of the link rule:

  $(bindir)$(BINS): AppUserBuild.o
  

• Do not build compiler or linker specific options into individual GNUmakefiles. Assume that options are different from platform to platform, so allow SRT to handle them.
• Do not let specific system libraries appear in GNUmakefiles; they should be contained within the arch_spec_*.mk files. In particular, there should be no -L options outside the SoftRelTools files; do not put them into package GNUmakefiles.

When attempting to change the arch_spec_*.mk files:

• These have to work in a lot of places, on a lot of machines. Before adding your favorite feature, recall the first principle of the Hippocratic Oath: "First, do no harm."
• LDFLAGS should contain any -L options needed, and LOADLIBES should contain just about everything else.

Setting up your PATH

Many, but not all sites, have an "srtpath" alias defined to do this. If your site is one of them, you can do "srtpath $BFARCH 2.4.1" to set your PATH. (The $BFARCH is there because srtpath can also set the architecture in use, for example if you want to turn-off the default use of optimization by the compiler). If you just say "srtpath" you'll be prompted for the choices.

Before srtpath was developed, the original way to do this was to use the BFCURRENT environment variable and/or a ~/BFCURRENT file, which the SRTstartup.csh script would use to manipulate the PATH variable. This still works, but is somewhat unwieldy:

• Make sure the BFCURRENT environment variable is set to the name of the production release you are using (e.g. "current" or "2.4.1")
• "source ~/SRTstartup.csh", assuming you have copied SRTstartup.csh to your home directory so it can be found easily. You may also be able to locate it at $BFDIST/releases/current/SoftRelTools/Srtstartup.csh.

Its important that either SRTstartup.csh or srtpath be used to configure the PATH every time you start to use a test release. Relying on SRTstartup.csh setting the path to the "current" release is not a reliable solution.

Reference Information

Package Makefiles

• If you want the GNUmakefile to descend into subdirectories and process the GNUmakefile(s) found within, add the subdirectories' names to the SUBDIRS variable.
• Files used just when building a binary, and thus not included in the library, should be added to the BINCCFILES, BINCFILES or BINFFILES variables. AppUserBuild.cc is a good example of this.

Environment variables

BFDIST

Specifies the root location for finding releases and versions at a particular site.

BFARCH

Used by the GNUmakefiles to determine which architecture is being targeted. Also used to form the pathname of architecture-specific files like bin, lib and tmp. Normally one of OVF1V4, AIX4, SunOS5 or VxWorks. We use suffixes like -noOptimize to indicate particular varients, such as not opimizing code, so comparisons should always be for the existance of a particular substring.

BFCURRENT

Name of the release to be used by default. Usually something like "0.6.2" or "test". Note that a given test release may override this variable by having a .current file defined, in which case a message will be given the user.

BFOVERRIDE

(optional) Location to search for SRT files before the $BFCURRENT release. Note that this is a release directory name, so changed files from the SoftRelTools package should go in $BFOVERRIDE/SoftRelTools, etc.

BFROOT

Many sites have a BFROOT symbol defined, and by default assign BFDIST to $BFROOT/dist, although this is by no means required at remote sites.

CERN

(optional, sort of) The default access to the CERNLIBs is through this symbol. Remote sites can override that if desired by installing a locally created bbCERNLIB script.

GNUmakefile targets

installdirs

Create needed subdirectories. Done automatically by various scripts, but should be done before doing any other targets when moving to a new architecture.

clean

Delete all gmake-made files. Note that this is done for all architectures, not just the current one.

cold

Do a complete build from scratch, including attempting to build all tool packages (SoftRelTools, dbin, dbio, etc) in the proper order.

include

synonym for inc

inc

create any include files needed, e.g. run dbin and dbio

dbx

create .dbxinit file for the debugger.

lib

compile and create libraries

bin

link primary executables

extrabins

link secondary executables

all

Do installdirs, inc, dbx, lib, bin in all subdirectories. This is also the default target if none is specified.

test

Build executables that are used for production testing, followed by running the tests.

foo.lib

Does "gmake lib" in just the "foo" subdirectory. Similar syntax will also work for the all, include, bin and test targets.

Note that "features" of the way gmake handles include files imply that most or all .d files will be built the first time gmake descends into a directory, regardless of what the target is. This can cause a problem if some files that are #include'd are missing, etc.

GNUmakefile variables

The following can be overridden from the gmake command to change options, etc.

VERBOSE

If set to "yes" (case specific), this causes gmake to return to the default behavior of printing what its doing.

FC

FORTRAN77 compiler to use when compiling .f files. Note that .F files are handled as a special case.

FCFLAGS

Options for the FORTRAN compiler.

F77BBOPT

Options for the f77bb command which is generated for some architectures to compile .F files; other architectures use the FC command to compile .F

CC

Compiler to use for .c files

CCFLAGS

Options for the C compiler

CXX

C++ compiler to use for .cc and .cxx files

CXXFLAGS

Options for the C++ compiler.

CPP

C preprocessor. This is not used explicitly when compiler C or C++, but is used to create dependency files.

CPPFLAGS

Used in the explicit cpp step when making .f from .F, and added to the CXX and CC command lines after their own specifics flags. This is intended to contain only flags to control cpp

FCPPFLAGS

Used before CPPFLAGS in the cpp step when making .f from .F; this is intended to contain fortran-specific cpp options

LDFLAGS

This should contain flags and commands for the linker, such as -L, but should not contain specific libraries and object files

LOADLIBES

This should contain the -l commands that request a given library should be included in a link. It should not contain any other flags or options, particularly not -L.

F90C

(obsolete)

F90CFLAGS

(obsolete)

FIDLE

(obsolete)

IDLFLAGS

(obsolete)

Used for specific files, and thus targets:

SUBDIRS

Names of subdirectories to be processed by gmake.

BINS

Primary binaries to be produced by the "bin" target.

EXTRABINS

Secondary binaries to be produced by the "extrabins" target

The following are used by the system, and should almost never overridden from the command line.

workdir

Usually tmp/$BFARCH/packageName, place for temporary files, .f made from .F, etc

libdir

Usually lib/$BFARCH, where .o and .a are put

bindir

Usually bin/$BFARCH, where executables are put

mandir

Usually man/, where man pages should be copied

docdir

(obsolete) Used to be where document files were placed. They are now kept in the dividual packages.

SHELL

shell to use, normally /bin/sh

testLink

option for shell test command that is used to test whether a given file is actually a link

RANLIB

If a given system does not need ranlib, this should be empty

AR

ar command to build a library (lib*.a) from object (.o) files

ARFLAGS

flags needed besides "r" to add a .o to a .a library

RM

rm command and options

Generic configuration files

standard.mk

This is included by every package-specific makefile to provide the various compilation rules, etc. It is intended to be architecture independent, but as we migrate from f77bb to native FC support of .F files there are currently some special case rules for handling .F files.

Architecture specific configuration files

The following define options needed on specific platforms. You should not use these directly, but rather allow PackageList to select and order them for you.

arch_spec.mk

Define architecture specific values for the GNUmakefile symbols. This file in included by standard.mk, hence after any includes done in the individual package makefiles. It should not redefine the LOADLIBES variables; those are done in the following files.

The rest of these files are intended to handle link libraries for specific required features. If needed, they should be included by PackageList in the following order. Note that they append to LDFLAGS, SYSLIBS and LOADLIBES; be careful when explicitly setting these in the gmake command.

arch_spec_Tcl.mk

Needed if the Tcl user interface code is referenced.

arch_spec_XDR.mk

Needed if any XDR I/O code is referenced, including via dbio.

arch_spec_X11.mk

Needed if X11 code is referenced.

arch_spec_RW.mk

Needed if the Rogue Wave Tools.h++ class library is referenced.

arch_spec_fortmain.mk

Needed if the program being linked has a FORTRAN main program. This mechanism is not yet perfect; see gnbase/src/GNUmakefile for an example.

arch_spec_f77.mk

Needed if FORTRAN code is being linked. Note you need this even if the only thing being linked is FORTRAN, because the recommendation is to use g++ for linking to handle static initialization of the inevitable C++ code that leaks in via libraries.

Local modifications

Hints

Loadmaps

      gmake McTrkr.bin LDFLAGS="-Wl,-M$PWD/loadmap"

Library and executable names

• Libraries are always named for the package that contains them. RecoUtils creates libRecoUtils.a, gnutil creates libgnutil.a, etc. Note that there are historical exceptions (CLHEP creates libclhep.a, gnbase creates libbbgeom.a, among others), but these will eventually fade away.
• Reconstruction applications based on an AppUserBuild object usually create an executable named <packagename>App. RecoUtils creates RecoUtilsApp, SvtReco creates SvtRecoApp, etc. The exception to this is FrameExample, which creates appexample.
• Test programs, whose only purpose is to test a few member functions, etc, often create a program called test<.packagename>.. This is a less common usage, with testAbsTrack, testBbrGeom being two examples.
• There are a lot of other names with no particular pattern.
• DO NOT name your test program "test". These is a UNIX command by that same name, and your test program will conflict with it.

Package Directory Structure

• Everything in a single package directory

Older packages can still use one of several other structures, although new packages should use the above standard form:

• All header files in a single subdirectory named "include", with .cc files in a "src" directory
• All header files in a single subdirectory with the same name as the package, with .cc files in a "src" directory

Although originally supported, the following structure has not been permitted since May 1996:

• All externally-referenced header files in a single subdirectory with the same name as the package, with .cc files and internally used headers in a "src" directory

Other sources of information

• The SoftRelTools package itself contains a lot of documentation. In particular, see the files:
  • README
  • HOWTO-GNUmakefile
  • HOWTO-dependency
• SoftRelTools is closely coupled to PackageList. The doc subdirectory of the PackageList package contains useful documentation.
• Torre's reference sheet is particularly useful to users, though it is not being actively maintained.
• A slightly old description of the software release tools. (Its taken from the "test" release at SLAC, but check the sell-by date on the title page).
• User and administrator how-to documentation. (See the previous comments about documentation dates)