Boost C++ Libraries

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 site-config.jam and user-config.jam.

This section lists all Boost.Build modules that support C++ compilers and documents how each one can be initialized. The name of support module for compiler is also the value for the toolset feature that can be used to explicitly request that compiler.

using gcc : [version] : [c++-compile-command] : [compiler options] ;

using msvc : [version] : [c++-compile-command] : [compiler options] ;
          

using intel-linux : [version] : [c++-compile-command] : [compiler options] ;

using intel-win : [version] : [c++-compile-command] : [compiler options] ;

using acc : [version] : [c++-compile-command] : [compiler options] ;

using borland : [version] : [c++-compile-command] : [compiler options] ;

using como-linux : [version] : [c++-compile-command] : [compiler options] ;

using cw : [version] : [c++-compile-command] : [compiler options] ;

using dmc : [version] : [c++-compile-command] : [compiler options] ;

using hp_cxx : [version] : [c++-compile-command] : [compiler options] ;

using sun : [version] : [c++-compile-command] : [compiler options] ;

-library=stlport4 -features=tmplife -features=tmplrefstatic
          

using vacpp ;

Boost.Build provides special support for some third-party C++ libraries, documented below.

using stlport : [version] : header-path : [library-path] ;

When there are several alternatives, one of them must be selected. The process is as follows:

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

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

Those 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 property in 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 ;

A feature is a normalized (toolset-independent) aspect of a build configuration, such as whether inlining is enabled. Feature names may not contain the '>' character.

Each feature in a build configuration has one or more associated values. Feature values for non-free features may not contain the '<', ':', or '=' characters. Feature values for free features may not contain the '<' character.

A property is a (feature,value) pair, expressed as <feature>value.

A subfeature is a feature that only exists in the presence of its parent feature, and whose identity can be derived (in the context of its parent) from its value. A subfeature's parent can never be another subfeature. Thus, features and their subfeatures form a two-level hierarchy.

A value-string for a feature F is a string of the form value-subvalue1-subvalue2...-subvalueN, where value is a legal value for F and subvalue1...subvalueN are legal values of some of F's subfeatures. For example, the properties <toolset>gcc <toolset-version>3.0.1 can be expressed more conscisely using a value-string, as <toolset>gcc-3.0.1.

A property set is a set of properties (i.e. a collection without duplicates), for instance: <toolset>gcc <runtime-link>static.

A property path is a property set whose elements have been joined into a single string separated by slashes. A property path representation of the previous example would be <toolset>gcc/<runtime-link>static.

A build specification is a property set that fully describes the set of features used to build a target.

rule feature ( name : allowed-values * : attributes * )

A build variant, or (simply variant) is a special kind of composite feature that automatically incorporates the default values of features that . Typically you'll want at least two separate variants: one for debugging, and one for your release code. [ Volodya says: "Yea, we'd need to mention that it's a composite feature and describe how they are declared, in pacticular that default values of non-optional features are incorporated into build variant automagically. Also, do we wan't some variant inheritance/extension/templates. I don't remember how it works in V1, so can't document this for V2.". Will clean up soon -DWA ]

When a target with certain properties is requested, and that target requires some set of properties, it is needed to find the set of properties to use for building. This process is called property refinement and is performed by these rules

Sometime it's desirable to apply certain requirements only for a specific combination of other properties. For example, one of compilers that you use issues a pointless warning that you want to suppress by passing a command line option to it. You would not want to pass that option to other compilers. Conditional properties allow you to do just that. Their syntax is:

        property ( "," property ) * ":" property
      

For example, the problem above would be solved by:

exe hello : hello.cpp : <toolset>yfc:<cxxflags>-disable-pointless-warning ;

The syntax also allows several properties in the condition, for example:

exe hello : hello.cpp : <os>NT,<toolset>gcc:<link>static ;

Target identifier is used to denote a target. The syntax is:

target-id -> (project-id | target-name | file-name )
              | (project-id | directory-name) "//" target-name
project-id -> path
target-name -> path
file-name -> path
directory-name -> path

This grammar allows some elements to be recognized as either

To determine the real meaning a check is made if project-id by the specified name exists, and then if main target of that name exists. For example, valid target ids might be:

a                                    -- target in current project
lib/b.cpp                            -- regular file
/boost/thread                        -- project "/boost/thread"
/home/ghost/build/lr_library//parser -- target in specific project

Rationale:Target is separated from project by special separator (not just slash), because:

Target reference is used to specify a source target, and may additionally specify desired properties for that target. It has this syntax:

target-reference -> target-id [ "/" requested-properties ]
requested-properties -> property-path

For example,

          exe compiler : compiler.cpp libs/cmdline/<optimization>space ;
        

would cause the version of cmdline library, optimized for space, to be linked in even if the compiler executable is build with optimization for speed.

Each generator, in addition to target types that it can produce, have attribute that affects its applicability in particular sitiation. Those attributes are:

Generator's required and optional properties may not include either free or incidental properties. (Allowing this would greatly complicate caching targets).

When trying to construct a target, the first step is to select all possible generators for the requested target type, which required properties are a subset of requested properties. Generators that were already selected up the call stack are excluded. In addition, if any composing generators were selected up the call stack, all other composing generators are ignored (TODO: define composing generators). The found generators are assigned a rank, which is the number of optional properties present in requested properties. Finally, generators with highest rank are selected for futher processing.

When generators are selected, each is run to produce a list of created targets. This list might include targets that are not of requested types, because generators create the same targets as some tool, and tool's behaviour is fixed. (Note: should specify that in some cases we actually want extra targets). If generator fails, it returns an empty list. Generator is free to call 'construct' again, to convert sources to the types it can handle. It also can pass modified properties to 'construct'. However, a generator is not allowed to modify any propagated properties, otherwise when actually consuming properties we might discover that the set of propagated properties is different from what was used for building sources.

For all targets that are not of requested types, we try to convert them to requested type, using a second call to construct. This is done in order to support transformation sequences where single source file expands to several later. See this message for details.

After all generators are run, it is necessary to decide which of successfull invocation will be taken as final result. At the moment, this is not done. Instead, it is checked whether all successfull generator invocation returned the same target list. Error is issued otherwise.

Because target location is determined by the build system, it is sometimes necessary to adjust properties, in order to not break actions. For example, if there's an action that generates a header, say "a_parser.h", and a source file "a.cpp" which includes that file, we must make everything work as if a_parser.h is generated in the same directory where it would be generated without any subvariants.

Correct property adjustment can be done only after all targets are created, so the approach taken is:

In case of quoted includes, no adjustment can give 100% correct results. If target dirs are not changed by build system, quoted includes are searched in "." and then in include path, while angle includes are searched only in include path. When target dirs are changed, we'd want to make quoted includes to be search in "." then in additional dirs and then in the include path and make angle includes be searched in include path, probably with additional paths added at some position. Unless, include path already has "." as the first element, this is not possible. So, either generated headers should not be included with quotes, or first element of include path should be ".", which essentially erases the difference between quoted and angle includes. Note: the only way to get "." as include path into compiler command line is via verbatim compiler option. In all other case, Boost.Build will convert "." into directory where it occurs.

Under certain conditions, an attempt is made to cache results of transformation search. First, the sources are replaced with targets with special name and the found target list is stored. Later, when properties, requested type, and source type are the same, the store target list is retrieved and cloned, with appropriate change in names.