bld: compiling in a separate directory

Overview

One approach to working with the same code base that is to be compiled for several different platforms is to have a common directory tree with the source code and separate directory trees, one per platform, where the derived files are stored. These separate directory trees are referred to as build trees. Once a build tree has been set up, use bld in a subdirectory of the tree to create the derived files. Overall the process is as follows:

1. Create the build tree; clonetree can help with this.
2. At the root of the build tree, create a Blddesc file. When bld is invoked, it starts from the current directory and searches for a file with the name Blddesc. It then processes the contents of the file and generates a file that can be included in a makefile with the following (assuming GNU make or another that supports the include statement): include $(BLDINFO).
3. bld then invokes make (the Blddesc file can be used to override what program is invoked) passing any command-line options that were specified for bld. bld also sets the following macros (via the environment) for make:

   BLDINFO

   Is the absolute location of the file generated from the Blddesc file. This file can be included in a makefile, its contents are described in the description of the Blddesc file.

   DEPINFO

   Is the absolute location of the file that can be used to store automatically generated dependencies. If this file does not already exist, bld will create an empty one so that a makefile which includes a statment like include $(DEPINFO) will never fail because of the missing file.

   MAKEFILE

   Is the location of the makefile used. It may be relative or absolute depending on how the paths are specified within the Blddesc file. If a makefile could not be found, MAKEFILE will be empty.

Blddesc: describing the build tree

The Blddesc file has the following purposes:

• It tells bld where to find the source files.
• It sets search paths for include files and libraries.
• It identifies where to find a include file to define the macros which describe the tools and options used to build the derived files for a platform.

The Blddesc file consists of a series of assignments, one per line, with a name separated by whitespace from the associated value (values with leading whitespace can not be used). Comment lines beginning with # are allowed; end-of-line comments after a variable assignment are not. The variable names that are understood and their meanings are:

PDESC pdesc_path

Specifies the absolute path for the file which defines the make macros for the platform of interest. If PDESC is not specified, then it is assumed that there is not a platform description file available.

SRCPATH src_path1[,src_path2...]

Is a comma-separated list of the absolute paths to the directory trees containing the source files.

INCPATH inc_path1[,inc_path2...]

Is a comma-separated list of directories to search for include files. These are in addition to the directories from the source trees that correspond to the current build directory

FINCDIR directory

To accommodate the MipsPro f77 compiler, which will look for Fortran include files (not those included through the C preprocessor #include directive) in the current directory and in one other directory, you may use FINCDIR to specify the alternate directory.

LIBPATH lib_path1[,lib_path2...]

Is a comma-separated list of directories to search for libraries.

MAKE make_command

Specifies the command that bld should invoke to actually do the building. If MAKE is not set, make (smake on IRIX systems) is used.

USEVPATH true|false

If the value is set to true, then VPATH is used internally to set the paths to the source directories. If false, a .PATH target is used. The default is to use VPATH unless a default make is used which is known to use .PATH and not VPATH.

MAKEFILE name

When SRCPATH is set, bld searches for the makefile in that path using name as the name of the makefile. The default for name is Makefile.

MAKEFILE_OPT option

To pass the name of the makefile to the command which does the building, bld uses option makefile_name. The default for option is -f.

MAKEOPT options

options is copied to the command-line for make after the specification of the makefile and before the arguments to bld are copied. The default is not to insert anything.

bld transforms these definitions into a file suitable for inclusion in a makefile. The form of the file is (assuming VPATH is used, otherwise replace VPATH with a .PATH target with the source directories as dependencies):

BUILD_CURR = abs_path_curr_directory
BUILD_ROOT = abs_path_to_blddesc
include pdesc_path
VPATH = src_path1/rel_path[:src_path2/rel_path...]
PRJ_INCS = -Isrc_path1 [-Isrc_path2...] -Iinc_path1 [-Iinc_path2...]
FPRJ_INCS = -Y I,fortran_include_directory
PRJ_LIBS = -Llib_path1 [-Llib_path2...]
PRJ_LIB_PATH = lib_path1[:lib_path2...]

The values of src_path1, inc_path1, etc. are simply copied from the Blddesc file so it is possible to include in them macro references that make will expand (because the source paths are also examined internally by bld, if you want macro expansion to be done correctly you should use ${VARIABLE_NAME} to refer to the macro value). rel_path is added to the source paths, it is the relative path from the directory containing the Blddesc file to the current directory where the build takes place.

Invoking bld

The command-line syntax for bld is

     bld [options, macro definitions, and targets to pass to make]

bld is affected by the following environment variables:

BLD_DEBUG

If this variable is set to true, bld will write out diagnostic information to standard error.

modified $Date: 2003/12/09 05:24:23 $