boost.png (6897 bytes) Home Libraries People FAQ More

PrevUpHomeNext

Chapter 26. Detailed reference

Table of Contents

General information
Initialization
Command line
Writing Jamfiles
Generated headers
Build process
Alternative selection
Determining common properties
Definitions
Features and properties
Build Variants
Property refinement
Conditional properties
Target identifiers and references
Generators
Selecting and ranking viable generators
Running generators
Selecting dependency graph
Property adjustment
Transformations cache

General information

Initialization

bjam's first job upon startup is to load the Jam code that implements the build system. To do this, it searches for a file called boost-build.jam, first in the invocation directory, then in its parent and so forth up to the filesystem root, and finally in the directories specified by the environment variable BOOST_BUILD_PATH. When found, the file is interpreted, and should specify the build system location by calling the boost-build rule:

rule boost-build ( location ? )

If location is a relative path, it is treated as relative to the directory of boost-build.jam. The directory specified by that location and the directories in BOOST_BUILD_PATH are then searched for a file called bootstrap.jam, which is expected to bootstrap the build system. This arrangement allows the build system to work without any command-line or environment variable settings. For example, if the build system files were located in a directory "build-system/" at your project root, you might place a boost-build.jam at the project root containing:

boost-build build-system ;

In this case, running bjam anywhere in the project tree will automatically find the build system.

The default bootstrap.jam, after loading some standard definitions, loads two files, which can be provided/customised by user: site-config.jam and user-config.jam.

Locations where those files a search are summarized below:

Table 26.1. Search paths for configuration files

  site-config.jam user-config.jam
Linux

/etc

$HOME

$BOOST_BUILD_PATH

$HOME

$BOOST_BUILD_PATH

Windows

%SystemRoot%

%HOMEDRIVE%%HOMEPATH%

%HOME%

%BOOST_BUILD_PATH%

%HOMEDRIVE%%HOMEPATH%

%HOME%

%BOOST_BUILD_PATH%

Boost.Build comes with default versions of those files, which can serve as templates for customized versions.

Command line

The command line may contain:

  • Jam options,
  • Boost.Build options,
  • Command line arguments

Command line arguments

Command line arguments specify targets and build request using the following rules.

  • An argument that does not contain slashes or the = symbol is either a value of an implicit feature or of a target to be built. It is taken to be value of a feature if an appropriate feature exists. Otherwise, it is considered a target id. Building the special target name “clean” has the same effect as using the --clean option.
  • An argument containing either slashes or the = symbol specifies a number of build request elements (see ???). In its simplest form, it's just a set of properties, separated by slashes, which become a single build request element, for example:

    borland/<runtime-link>static
    

    A more complex form can be used to save typing. For example, instead of

    borland/runtime-link=static borland/runtime-link=dynamic
    

    one can use

    borland/runtime-link=static,dynamic
    

    Exactly, the conversion from argument to build request elements is performed by (1) splitting the argument at each slash, (2) converting each split part into a set of properties and (3) taking all possible combinations of the property sets. Each split part should have the either the form

    feature-name=feature-value1[","feature-valueN]*   
    

    or, in case of implicit features

    feature-value1[","feature-valueN;]*   
    

    will be converted into the property set

    <feature-name>feature-value1 .... <feature-name>feature-valueN
    

For example, the command line

target1 debug gcc/runtime-link=dynamic,static

would cause target called target1 to be rebuilt in debug mode, except that for gcc, both dynamically and statically linked binaries would be created.

Command line options

All of the Boost.Build options start with the "--" prefix. They are described in the following table.

Table 26.2. Command line options

Option Description
--version Prints information on Boost.Build and Boost.Jam versions.
--help Access to the online help system. This prints general information on how to use the help system with additional --help* options.
--clean Removes everything instead of building. Unlike clean target in make, it is possible to clean only some targets.
--debug Enables internal checks.
--dump-projects Cause the project structure to be output.
--no-error-backtrace Don't print backtrace on errors. Primary useful for testing.
--ignore-config Do not load site-config.jam and user-config.jam

PrevUpHomeNext