To invoke Boost.Build, type b2 on the command line. Three kinds of command-line tokens are accepted, in any order:
Options start with either one or two dashes. The standard options are listed below, and each project may add additional options
Properties specify details of what you want to build (e.g. debug or release variant). Syntactically, all command line tokens with an equal sign in them are considered to specify properties. In the simplest form, a property looks like
All tokens that are neither options nor properties specify what targets to build. The available targets entirely depend on the project you are building.
To build all targets defined in the Jamfile in the current directory with the default properties, run:
To build specific targets, specify them on the command line:
b2 lib1 subproject//lib2
To request a certain value for some property, add
b2 toolset=gcc variant=debug optimization=space
Boost.Build recognizes the following command line options.
Invokes the online help system. This prints general information on how to use the help system with additional --help* options.
Cleans all targets in the current directory and in any subprojects. Note that unlike the
cleantarget in make, you can use
--cleantogether with target names to clean specific targets.
Cleans all targets, no matter where they are defined. In particular, it will clean targets in parent Jamfiles, and targets defined under other project roots.
Changes the build directories for all project roots being built. When this option is specified, all Jamroot files must declare a project name. The build directory for the project root will be computed by concatanating the value of the
--build-diroption, the project name specified in Jamroot, and the build dir specified in Jamroot (or
bin, if none is specified).
The option is primarily useful when building from read-only media, when you can't modify Jamroot.
Compresses target paths by abbreviating each component. This option is useful to keep paths from becoming longer than the filesystem supports. See also the section called “Target Paths”.
Compresses target paths using an MD5 hash. This option is useful to keep paths from becoming longer than the filesystem supports. This option produces shorter paths than --abbreviate-paths does, but at the cost of making them less understandable. See also the section called “Target Paths”.
Prints information on the Boost.Build and Boost.Jam versions.
Causes all files to be rebuilt.
Do no execute the commands, only print them.
Stop at the first error, as opposed to continuing to build targets that don't depend on the failed ones.
Run up to
Ncommands in parallel.
Produces debug information about the loading of Boost.Build and toolset files.
Prints what targets are being built and with what properties.
Produces debug output from the generator search process. Useful for debugging custom generators.
Supress all informational messages.
Enable cummulative debugging levels from 1 to n. Values are:
- Show the actions taken for building targets, as they are executed (the default).
- Show "quiet" actions and display all action text, as they are executed.
- Show dependency analysis, and target/source timestamps/paths.
- Show arguments and timming of shell invocations.
- Show rule invocations and variable expansions.
- Show directory/header file/archive scans, and attempts at binding to targets.
- Show variable settings.
- Show variable fetches, variable expansions, and evaluation of '"if"' expressions.
- Show variable manipulation, scanner tokens, and memory usage.
- Show profile information for rules, both timing and memory.
- Show parsing progress of Jamfiles.
- Show graph of target dependencies.
- Show change target status (fate).
Enable debugging level
Write the updating actions to the specified file instead of running them.
Set the variable
valuein the global scope of the jam language interpreter, overriding variables imported from the environment.
In the simplest case, the build is performed with a single set of properties,
that you specify on the command line with elements in the form
The complete list of features can be found in the section called “Builtin features”.
The most common features are summarized below.
|link||shared,static||Determines if Boost.Build creates shared or static libraries|
|threading||single,multi||Cause the produced binaries to be thread-safe. This requires proper support in the source code itself.|
|address-model||32,64||Explicitly request either 32-bit or 64-bit code generation. This typically requires that your compiler is appropriately configured. Please refer to the section called “C++ Compilers” and your compiler documentation in case of problems.|
|toolset||(Depends on configuration)||The C++ compiler to use. See the section called “C++ Compilers” for a detailed list.|
|include||(Arbitrary string)||Additional include paths for C and C++ compilers.|
|define||(Arbitrary string)||Additional macro definitions for C and C++ compilers. The string should be either
|cxxflags||(Arbitrary string)||Custom options to pass to the C++ compiler.|
|cflags||(Arbitrary string)||Custom options to pass to the C compiler.|
|linkflags||(Arbitrary string)||Custom options to pass to the C++ linker.|
|runtime-link||shared,static||Determines if shared or static version of C and C++ runtimes should be used.|
If you have more than one version of a given C++ toolset (e.g. configured in
user-config.jam, or autodetected, as happens with msvc), you can
request the specific version by passing
the value of the
toolset feature, for example
If a feature has a fixed set of values it can be specified more than once on the command line. In which case, everything will be built several times -- once for each specified value of a feature. For example, if you use
b2 link=static link=shared threading=single threading=multi
Then a total of 4 builds will be performed. For convenience, instead of specifying all requested values of a feature in separate command line elements, you can separate the values with commas, for example:
b2 link=static,shared threading=single,multi
The comma has this special meaning only if the feature has a fixed set of values, so
is not treated specially.
All command line elements that are neither options nor properties are the names of the targets to build. See the section called “Target identifiers and references”. If no target is specified, the project in the current directory is built.