## Chapter 7. Detailed reference

## 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 are searched are summarized below:

Table 7.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 the section called “Build Request”). 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 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.

FIXME: That table has moved into "User documentation" section and there's nothing we can add here. Remove this part?