Chapter 23. Detailed reference

| Home | Libraries | People | FAQ | More

## Chapter 23. Detailed reference

## General information

### Initialization

bjam's first job upon startup is to load the Jam code which 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 location and directories in BOOST_BUILD_PATH are then searched for a file called bootstrap.jam which is interpreted and 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 23.1. Search paths for configuration files

| site-config.jam | user-config.jam
--- | --- | ---
Linux | /etc $HOME $BOOST_BUILD_PATH | $HOME $BOOST_BUILD_PATH
Windows | $SystemRoot $HOME $BOOST_BUILD_PATH | $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 which does not contain slashes or the "=" symbol is either a value of an implicit feature, or target to be built. It is taken to be value of a feature if appropriate feature exists. Otherwise, it is considered a target id. Special target name "clean" has the same effect as "--clean" option.

- An argument with either slashes or the "=" symbol specifies a number of build request elements. In the 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

  More complex form is 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 combination of the property sets. Each split part should have the either the form

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

  or, in case of implicit feature

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

  and will be converted into 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 23.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`