Boost C++ Libraries
PrevUpHomeNext

Build process

Alternative selection
Determining common properties
Target Paths

The general overview of the build process was given in the user documentation. This section provides additional details, and some specific rules.

To recap, building a target with specific properties includes the following steps:

  1. applying the default build,

  2. selecting the main target alternative to use,

  3. determining the "common" properties,

  4. building targets referred by the the sources list and dependency properties,

  5. adding the usage requirements produced when building dependencies to the "common" properties,

  6. building the target using generators,

  7. computing the usage requirements to be returned.

Alternative selection

When a target has several alternatives, one of them must be selected. The process is as follows:

  1. For each alternative, its condition is defined as the set of base properties in its requirements. Conditional properties are excluded.
  2. An alternative is viable only if all properties in its condition are present in the build request.
  3. If there's only one viable alternative, it's choosen. Otherwise, an attempt is made to find the best alternative. An alternative a is better than another alternative b, if the set of properties in b's condition is a strict subset of the set of properties of a's condition. If one viable alternative is better than all the others, it's selected. Otherwise, an error is reported.

Determining common properties

"Common" properties is a somewhat artificial term. This is the intermediate property set from which both the build request for dependencies and the properties for building the target are derived.

Since the default build and alternatives are already handled, we have only two inputs: the build request and the requirements. Here are the rules about common properties.

  1. Non-free features can have only one value

  2. A non-conditional property in the requirements is always present in common properties.

  3. A property in the build request is present in common properties, unless it is overridden by a property in the requirements.

  4. If either the build request, or the requirements (non-conditional or conditional) include an expandable property (either composite, or with a specified subfeature value), the behaviour is equivalent to explicitly adding all the expanded properties to the build request or the requirements respectively.

  5. If the requirements include a conditional property, and the condition of this property is true in the context of common properties, then the conditional property should be in common properties as well.

  6. If no value for a feature is given by other rules here, it has default value in common properties.

These rules are declarative. They don't specify how to compute the common properties. However, they provide enough information for the user. The important point is the handling of conditional requirements. The condition can be satisfied either by a property in the build request, by non-conditional requirements, or even by another conditional property. For example, the following example works as expected: 

exe a : a.cpp
      : <toolset>gcc:<variant>release
        <variant>release:<define>FOO ;

Target Paths

Several factors determine the location of a concrete file target. All files in a project are built under the directory bin unless this is overridden by the build-dir project attribute. Under bin is a path that depends on the properties used to build each target. This path is uniquely determined by all non-free, non-incidental properties. For example, given a property set containing: <toolset>gcc <toolset-gcc:version>4.6.1 <variant>debug <warnings>all <define>_DEBUG <include>/usr/local/include <link>static, the path will be gcc-4.6.1/debug/link-static. <warnings> is an incidental feature and <define> and <include> are free features, so they do not affect the path.

Sometimes the paths produced by Boost.Build can become excessively long. There are a couple of command line options that can help with this. --abbreviate-paths reduces each element to no more than five characters. For example, link-static becomes lnk-sttc. The --hash option reduces the path to a single directory using an MD5 hash.

There are two features that affect the build directory. The <location> feature completely overrides the default build directory. For example, 

exe a : a.cpp : <location>. ;

builds all the files produced by a in the directory of the Jamfile. This is generally discouraged, as it precludes variant builds.

The <location-prefix> feature adds a prefix to the path, under the project's build directory. For example, 

exe a : a.cpp : <location-prefix>subdir ;

will create the files for a in bin/subdir/gcc-4.6.1/debug
PrevUpHomeNext