Boost C++ Libraries - Invocation

Invocation

Examples
Options
Properties
Targets

To invoke Boost.Build, type bjam on the command line. Three kinds of command-line tokens are accepted, in any order:

options: Options start with either dash, or two dashes. The standard options are listed below, and each project may add additional options
properties: Properties specify details of what you want to build (e.g. debug or release variant). Syntactically, all command line tokens with equal sign in them are considered to specify properties. In the simplest form, property looks like feature=value
target: All tokens that are neither options nor properties specify what targets to build. The available targets entirely depend on the project you are building.

Examples

To build all targets defined in Jamfile in the current directory with default properties, run:

bjam

To build specific targets, specify them on the command line:

bjam lib1 subproject//lib2

To request a certain value for some property, add property=value to the command line:

bjam toolset=gcc variant=debug optimization=space

Options

Boost.Build recognizes the following command line options.

--help

Invokes the online help system. This prints general information on how to use the help system with additional --help* options.

--clean

Cleans all targets in the current directory and in any subprojects. Note that unlike the clean target in make, you can use --clean together with target names to clean specific targets.

--clean-all

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.

--build-dir

Changes build directories for all project roots being built. When this option is specified, all Jamroot files should declare project name. The build directory for the project root will be computed by concatanating the value of the --build-dir option, 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.

--version

Prints information on Boost.Build and Boost.Jam versions.

-a

Causes all files to be rebuilt.

-n

Do no execute the commands, only print them.

-d+2

Show commands as they are executed.

-d0

Supress all informational messages.

-q

Stop at first error, as opposed to continuing to build targets that don't depend on the failed ones.

-j N

Run up to N commands in parallel.

--debug-configuration

Produces debug information about loading of Boost.Build and toolset files.

--debug-building

Prints what targets are being built and with what properties.

--debug-generators

Produces debug output from generator search process. Useful for debugging custom generators.

--ignore-config

Do not load site-config.jam and user-config.jam configuration files.

Properties

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 feature=value. The complete list of features can be found in the section called “Builtin features”. The most common features are summarized below.

Table 4.2.

Feature	Allowed values	Notes
variant	debug,release
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.
toolset	(Depends on configuration)	The C++ compiler to use. See the section called “C++ Compilers” for a detailed list.
cxxflags	(Arbitrary string)	Custom options to pass to the C++ compiler.
cflags	(Arbitrary string)	Custom options to pass to the C compiler.
includes	(Arbitrary string)	Additional include paths for C and C++ compilers.
define	(Arbitrary string)	Additional macro definitions for C and C++ compilers.
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 toolset-version as the value of the toolset feature, for example toolset=msvc-8.0.

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

bjam 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 commands, for example:

bjam link=static,shared threading=single,multi

The comma has special meaning only if the feature has a fixed set of values, so

bjam include=static,shared

is not treated specially.

Targets

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.