The simplest project that B2 can construct is stored in example/hello/ directory. The project is described by a file called Jamfile that contains:

Even with this simple setup, you can do some interesting things. First of all, just invoking b2 will build the hello executable by compiling and linking hello.cpp. By default, the debug variant is built. Now, to build the release variant of hello, invoke

Note that the debug and release variants are created in different directories, so you can switch between variants or even build multiple variants at once, without any unnecessary recompilation. Let us extend the example by adding another line to our project’s Jamfile:

Now let us build both the debug and release variants of our project again:

Note that two variants of hello2 are linked. Since we have already built both variants of hello, hello.cpp will not be recompiled; instead the existing object files will just be linked into the corresponding variants of hello2. Now let us remove all the built products:

It is also possible to build or clean specific targets. The following two commands, respectively, build or clean only the debug version of hello2.

To represent aspects of target configuration such as debug and release variants, or single- and multi-threaded builds portably, B2 uses features with associated values. For example, the debug-symbols feature can have a value of on or off. A property is just a (feature, value) pair. When a user initiates a build, B2 automatically translates the requested properties into appropriate command-line flags for invoking toolset components like compilers and linkers.

There are many built-in features that can be combined to produce arbitrary build configurations. The following command builds the project’s release variant with inlining disabled and debug symbols enabled:

Properties on the command-line are specified with the syntax:

The release and debug that we have seen in b2 invocations are just a shorthand way to specify values of the variant feature. For example, the command above could also have been written this way:

variant is so commonly-used that it has been given special status as an implicit feature—B2 will deduce its identity just from the name of one of its values.

A complete description of features can be found in the section called “Features and properties”.

So far we have only considered examples with one project, with one user-written Jamfile file. A typical large codebase would be composed of many projects organized into a tree. The top of the tree is called the project root. Every subproject is defined by a file called Jamfile in a descendant directory of the project root. The parent project of a subproject is defined by the nearest Jamfile file in an ancestor directory. For example, in the following directory layout:

the project root is top/. The projects in top/app/ and top/util/foo/ are immediate children of the root project.

Projects inherit all attributes (such as requirements) from their parents. Inherited requirements are combined with any requirements specified by the subproject. For example, if top/Jamfile has

in its requirements, then all of its sub-projects will have it in their requirements, too. Of course, any project can add include paths to those specified by its parents. ^[2] More details can be found in the section called “Projects”.

Invoking b2 without explicitly specifying any targets on the command line builds the project rooted in the current directory. Building a project does not automatically cause its sub-projects to be built unless the parent project’s Jamfile explicitly requests it. In our example, top/Jamfile might contain:

which would cause the project in top/app/ to be built whenever the project in top/ is built. However, targets in top/util/foo/ will be built only if they are needed by targets in top/ or top/app/.

When building a target X that depends on first building another target Y (such as a library that must be linked with X), Y is called a dependency of X and X is termed a dependent of Y.

To get a feeling of target dependencies, let’s continue the above example and see how top/app/Jamfile can use libraries from top/util/foo. If top/util/foo/Jamfile contains

then to use this library in top/app/Jamfile, we can write:

While app.cpp refers to a regular source file, ../util/foo//bar is a reference to another target: a library bar declared in the Jamfile at ../util/foo.

Suppose we build app with:

Which properties will be used to build foo? The answer is that some features are propagated — B2 attempts to use dependencies with the same value of propagated features. The <optimization> feature is propagated, so both app and foo will be compiled with full optimization. But <define> is not propagated: its value will be added as-is to the compiler flags for a.cpp, but won’t affect foo.

Let’s improve this project further. The library probably has some headers that must be used when compiling app.cpp. We could manually add the necessary #include paths to the app requirements as values of the <include> feature, but then this work will be repeated for all programs that use foo. A better solution is to modify util/foo/Jamfile in this way:

Usage requirements are applied not to the target being declared but to its dependents. In this case, <include>. will be applied to all targets that directly depend on foo.

Another improvement is using symbolic identifiers to refer to the library, as opposed to Jamfile location. In a large project, a library can be used by many targets, and if they all use Jamfile location, a change in directory organization entails much work. The solution is to use project ids—symbolic names not tied to directory layout. First, we need to assign a project id by adding this code to Jamfile:

Second, we modify app/Jamfile to use the project id:

The /library-example/foo//bar syntax is used to refer to the target bar in the project with id /library-example/foo. We’ve achieved our goal—if the library is moved to a different directory, only top/Jamfile must be modified. Note that project ids are global—two Jamfiles are not allowed to assign the same project id to different directories.

Libraries can be either static, which means they are included in executable files that use them, or shared (a.k.a. dynamic), which are only referred to from executables, and must be available at run time. B2 can create and use both kinds.

The kind of library produced from a lib target is determined by the value of the link feature. Default value is shared, and to build a static library, the value should be static. You can request a static build either on the command line:

or in the library’s requirements:

We can also use the <link> property to express linking requirements on a per-target basis. For example, if a particular executable can be correctly built only with the static version of a library, we can qualify the executable’s target reference to the library as follows:

No matter what arguments are specified on the b2 command line, important will only be linked with the static version of helpers.

Specifying properties in target references is especially useful if you use a library defined in some other project (one you can’t change) but you still want static (or dynamic) linking to that library in all cases. If that library is used by many targets, you could use target references everywhere:

but that’s far from being convenient. A better approach is to introduce a level of indirection. Create a local alias target that refers to the static (or dynamic) version of foo:

The alias rule is specifically used to rename a reference to a target and possibly change the properties.

Sometimes, particular relationships need to be maintained among a target’s build properties. For example, you might want to set specific #define when a library is built as shared, or when a target’s release variant is built. This can be achieved using conditional requirements.

In the example above, whenever network is built with <link>shared, <define>NETWORK_LIB_SHARED will be in its properties, too. Also, whenever its release variant is built, <define>EXTRA_FAST will appear in its properties.

Sometimes the ways a target is built are so different that describing them using conditional requirements would be hard. For example, imagine that a library actually uses different source files depending on the toolset used to build it. We can express this situation using target alternatives:

When building demangler, B2 will compare requirements for each alternative with build properties to find the best match. For example, when building with <toolset>gcc alternative (2), will be selected, and when building with <toolset>msvc alternative (3) will be selected. In all other cases, the most generic alternative (1) will be built.

To link to libraries whose build instructions aren’t given in a Jamfile, you need to create lib targets with an appropriate file property. Target alternatives can be used to associate multiple library files with a single conceptual target. For example:

This example defines two alternatives for lib2, and for each one names a prebuilt file. Naturally, there are no sources. Instead, the <file> feature is used to specify the file name.

Once a prebuilt target has been declared, it can be used just like any other target:

As with any target, the alternative selected depends on the properties propagated from lib2’s dependents. If we build the release and debug versions of `app it will be linked with lib2_release.a and lib2_debug.a, respectively.

System libraries — those that are automatically found by the toolset by searching through some set of predetermined paths — should be declared almost like regular ones:

We again don’t specify any sources, but give a name that should be passed to the compiler. If the gcc toolset were used to link an executable target to pythonlib, -lpython22 would appear in the command line (other compilers may use different options).

We can also specify where the toolset should look for the library:

And, of course, target alternatives can be used in the usual way:

A more advanced use of prebuilt targets is described in the section called “Targets in site-config.jam”.

B2 has a few unique concepts that are introduced in this section. The best way to explain the concepts is by comparison with more classical build tools.

When using any flavor of make, you directly specify targets and commands that are used to create them from other target. The below example creates a.o from a.c using a hardcoded compiler invocation command.

This is a rather low-level description mechanism and it’s hard to adjust commands, options, and sets of created targets depending on the compiler and operating system used.

To improve portability, most modern build system provide a set of higher-level functions that can be used in build description files. Consider this example:

This is a function call that creates the targets necessary to create an executable file from the source file a.c. Depending on configured properties, different command lines may be used. However, add_program is higher-level, but rather thin level. All targets are created immediately when the build description is parsed, which makes it impossible to perform multi-variant builds. Often, change in any build property requires a complete reconfiguration of the build tree.

In order to support true multi-variant builds, B2 introduces the concept of a metatarget definition main target metatarget metatarget — an object that is created when the build description is parsed and can be called later with specific build properties to generate actual targets.

Consider an example:

When this declaration is parsed, B2 creates a metatarget, but does not yet decide what files must be created, or what commands must be used. After all build files are parsed, B2 considers the properties requested on the command line. Supposed you have invoked B2 with:

In that case, the metatarget will be called twice, once with toolset=gcc and once with toolset=msvc. Both invocations will produce concrete targets, that will have different extensions and use different command lines.

Another key concept is build property. A build property is a variable that affects the build process. It can be specified on the command line, and is passed when calling a metatarget. While all build tools have a similar mechanism, B2 differs by requiring that all build properties are declared in advance, and providing a large set of properties with portable semantics.

The final concept is property propagation. B2 does not require that every metatarget is called with the same properties. Instead, the "top-level" metatargets are called with the properties specified on the command line. Each metatarget can elect to augment or override some properties (in particular, using the requirements mechanism, see the section called “Requirements”). Then, the dependency metatargets are called with the modified properties and produce concrete targets that are then used in the build process. Of course, dependency metatargets maybe in turn modify build properties and have dependencies of their own.

For a more in-depth treatment of the requirements and concepts, you may refer to SYRCoSE 2009 B2 article.

This section will describe the basics of the Boost.Jam language—just enough for writing Jamfiles. For more information, please see the Boost.Jam documentation.

Boost.Jam has an interpreted, procedural language. On the lowest level, a Boost.Jam program consists of variables and rules (the Jam term for functions). They are grouped into modules—there is one global module and a number of named modules. Besides that, a Boost.Jam program contains classes and class instances.

Syntactically, a Boost.Jam program consists of two kinds of elements—keywords (which have a special meaning to Boost.Jam) and literals. Consider this code:

which assigns the value b to the variable a. Here, = and ; are keywords, while a and b are literals.

If you want to use a literal value that is the same as some keyword, the value can be quoted:

All variables in Boost.Jam have the same type—list of strings. To define a variable one assigns a value to it, like in the previous example. An undefined variable is the same as a variable with an empty value. Variables can be accessed using the $(variable) syntax. For example:

Rules are defined by specifying the rule name, the parameter names, and the allowed value list size for each parameter.

When this rule is called, the list passed as the first argument must have exactly one value. The list passed as the second argument can either have one value of be empty. The two remaining arguments can be arbitrarily long, but the third argument may not be empty.

The overview of Boost.Jam language statements is given below:

This code calls the named rule with the specified arguments. When the result of the call must be used inside some expression, you need to add brackets around the call, like shown on the second line.

This is a regular if-statement. The condition is composed of:

Executes statements for each element in list, setting the variable var to the element value.

Repeatedly execute statements while cond remains true upon entry.

This statement should be used only inside a rule and returns values to the caller of the rule.

The first form imports the specified module. All rules from that module are made available using the qualified name: module.rule. The second form imports the specified rules only, and they can be called using unqualified names.

Sometimes, you need to specify the actual command lines to be used when creating targets. In the jam language, you use named actions to do this. For example:

This specifies a named action called create-file-from-another. The text inside braces is the command to invoke. The $(<) variable will be expanded to a list of generated files, and the $(>) variable will be expanded to a list of source files.

To adjust the command line flexibly, you can define a rule with the same name as the action and taking three parameters — targets, sources and properties. For example:

In this example, the rule checks if a certain build property is specified. If so, it sets the variable OPTIONS that is then used inside the action. Note that the variables set "on a target" will be visible only inside actions building that target, not globally. Were they set globally, using variable named OPTIONS in two unrelated actions would be impossible.

More details can be found in the Jam reference, the section called “Rules”.

On startup, B2 searches and reads three configuration files: site-config.jam, user-config.jam, and project-config.jam. The first one is usually installed and maintained by a system administrator, and the second is for the user to modify. You can edit the one in the top-level directory of your B2 installation or create a copy in your home directory and edit the copy. The third is used for project specific configuration. The following table explains where the files are searched.

Any of these files may also be overridden on the command line.

Usually, user-config.jam just defines the available compilers and other tools (see the section called “Targets in site-config.jam” for more advanced usage). A tool is configured using the following syntax:

The using rule is given the name of tool, and will make that tool available to B2. For example,

will make the GCC compiler available.

All the supported tools are documented in the section called “Builtin tools”, including the specific options they take. Some general notes that apply to most C++ compilers are below.

For all the C++ compiler toolsets that B2 supports out-of-the-box, the list of parameters to using is the same: toolset-name, version, invocation-command, and options.

If you have a single compiler, and the compiler executable

it can be configured by simply:

If the compiler is installed in a custom directory, you should provide the command that invokes the compiler, for example:

Some B2 toolsets will use that path to take additional actions required before invoking the compiler, such as calling vendor-supplied scripts to set up its required environment variables. When the compiler executables for C and C++ are different, the path to the C++ compiler executable must be specified. The command can be any command allowed by the operating system. For example:

will work.

To configure several versions of a toolset, simply invoke the using rule multiple times:

Note that in the first call to using, the compiler found in the PATH will be used, and there is no need to explicitly specify the command.

Many of toolsets have an options parameter to fine-tune the configuration. All of B2’s standard compiler toolsets accept four options cflags, cxxflags, compileflags and linkflags as options specifying flags that will be always passed to the corresponding tools. There must not be a space between the tag for the option name and the value. Values of the cflags feature are passed directly to the C compiler, values of the cxxflags feature are passed directly to the C++ compiler, and values of the compileflags feature are passed to both. For example, to configure a gcc toolset so that it always generates 64-bit code you could write:

If multiple of the same type of options are needed, they can be concatenated with quotes or have multiple instances of the option tag.

Multiple variations of the same tool can be used for most tools. These are delineated by the version passed in. Because the dash '-' cannot be used here, the convention has become to use the tilde '~' to delineate variations.

These are then used as normal toolsets:

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

A Main target is a user-defined named entity that can be built, for example an executable file. Declaring a main target is usually done using one of the main target rules described in the section called “Builtin rules”. The user can also declare custom main target rules as shown in the section called “Main target rules”.

Most main target rules in B2 have the same common signature:

Some main target rules have a different list of parameters as explicitly stated in their documentation.

The actual requirements for a target are obtained by refining the requirements of the project where the target is declared with the explicitly specified requirements. The same is true for usage-requirements. More details can be found in the section called “Property refinement”.

As mentioned before, targets are grouped into projects, and each Jamfile is a separate project. Projects are useful because they allow us to group related targets together, define properties common to all those targets, and assign a symbolic name to the project that can be used in referring to its targets.

Projects are named using the project rule, which has the following syntax:

Here, attributes is a sequence of rule arguments, each of which begins with an attribute-name and is followed by any number of build properties. The list of attribute names along with its handling is also shown in the table below. For example, it is possible to write:

The possible attributes are listed below.

Project id is a short way to denote a project, as opposed to the Jamfile’s pathname. It is a hierarchical path, unrelated to filesystem, such as "boost/thread". Target references make use of project ids to specify a target.

Source location specifies the directory where sources for the project are located.

Project requirements are requirements that apply to all the targets in the projects as well as all sub-projects.

Default build is the build request that should be used when no build request is specified explicitly.

The default values for those attributes are given in the table below.

Besides defining projects and main targets, Jamfiles often invoke various utility rules. For the full list of rules that can be directly used in Jamfile see the section called “Builtin rules”.

Each subproject inherits attributes, constants and rules from its parent project, which is defined by the nearest Jamfile in an ancestor directory above the subproject. The top-level project is declared in a file called Jamroot, or Jamfile. When loading a project, B2 looks for either Jamroot or Jamfile. They are handled identically, except that if the file is called Jamroot, the search for a parent project is not performed. A Jamfile without a parent project is also considered the top-level project.

Even when building in a subproject directory, parent project files are always loaded before those of their sub-projects, so that every definition made in a parent project is always available to its children. The loading order of any other projects is unspecified. Even if one project refers to another via the use-project or a target reference, no specific order should be assumed.

When you’ve described your targets, you want B2 to run the right tools and create the needed targets. This section will describe two things: how you specify what to build, and how the main targets are actually constructed.

The most important thing to note is that in B2, unlike other build tools, the targets you declare do not correspond to specific files. What you declare in a Jamfile is more like a “metatarget.” Depending on the properties you specify on the command line, each metatarget will produce a set of real targets corresponding to the requested properties. It is quite possible that the same metatarget is built several times with different properties, producing different files.

Programs are created using the exe rule, which follows the common syntax. For example:

This will create an executable file from the sources—​in this case, one C++ file, one library file present in the same directory, and another library that is created by B2. Generally, sources can include C and C++ files, object files and libraries. B2 will automatically try to convert targets of other types.

Library targets are created using the lib rule, which follows the common syntax. For example:

This will define a library target named helpers built from the helpers.cpp source file. It can be either a static library or a shared library, depending on the value of the <link> feature.

Library targets can represent:

The syntax for prebuilt libraries is given below:

The name property specifies the name of the library without the standard prefixes and suffixes. For example, depending on the system, z could refer to a file called z.so, libz.a, or z.lib, etc. The search feature specifies paths in which to search for the library in addition to the default compiler paths. search can be specified several times or it can be omitted, in which case only the default compiler paths will be searched. The file property specifies the file location.

The difference between using the file feature and using a combination of the name and search features is that file is more precise.

For convenience, the following syntax is allowed:

which has exactly the same effect as:

When a library references another library you should put that other library in its list of sources. This will do the right thing in all cases. For portability, you should specify library dependencies even for searched and prebuilt libraries, otherwise, static linking on Unix will not work. For example:

Usage requirements are often very useful for defining library targets. For example, imagine that you want you build a helpers library and its interface is described in its helpers.hpp header file located in the same directory as the helpers.cpp source file. Then you could add the following to the Jamfile located in that same directory:

which would automatically add the directory where the target has been defined (and where the library’s header file is located) to the compiler’s include path for all targets using the helpers library. This feature greatly simplifies Jamfiles.

The alias rule gives an alternative name to a group of targets. For example, to give the name core to a group of three other targets with the following code:

Using core on the command line, or in the source list of any other target is the same as explicitly using im, reader, and writer.

Another use of the alias rule is to change build properties. For example, if you want to link statically to the Boost Threads library, you can write the following:

and use only the threads alias in your Jamfiles.

You can also specify usage requirements for the alias target. If you write the following:

then using header_only_library in sources will only add an include path. Also note that when an alias has sources, their usage requirements are propagated as well. For example:

will compile main.cpp with additional includes required for using the specified static libraries.

This section describes various ways to install built targets and arbitrary files.

B2 has convenient support for running unit tests. The simplest way is the unit-test rule, which follows the common syntax. For example:

The unit-test rule behaves like the exe rule, but after the executable is created it is also run. If the executable returns an error code, the build system will also return an error and will try running the executable on the next invocation until it runs successfully. This behavior ensures that you can not miss a unit test failure.

There are few specialized testing rules, listed below:

They are given a list of sources and requirements. If the target name is not provided, the name of the first source file is used instead. The compile* tests try to compile the passed source. The link* rules try to compile and link an application from all the passed sources. The compile and link rules expect that compilation/linking succeeds. The compile-fail and link-fail rules expect that the compilation/linking fails.

There are two specialized rules for running executables, which are more powerful than the unit-test rule. The run rule has the following signature:

The rule builds application from the provided sources and runs it, passing args and input-files as command-line arguments. The args parameter is passed verbatim and the values of the input-files parameter are treated as paths relative to containing Jamfile, and are adjusted if b2 is invoked from a different directory. The run-fail rule is identical to the run rule, except that it expects that the run fails.

All rules described in this section, if executed successfully, create a special manifest file to indicate that the test passed. For the unit-test rule the files is named target-name.passed and for the other rules it is called target-name.test. The run* rules also capture all output from the program, and store it in a file named target-name.output.

If the preserve-test-targets feature has the value off, then run and the run-fail rules will remove the executable after running it. This somewhat decreases disk space requirements for continuous testing environments. The default value of preserve-test-targets feature is on.

It is possible to print the list of all test targets (except for unit-test) declared in your project, by passing the --dump-tests command-line option. The output will consist of lines of the form:

It is possible to process the list of tests, B2 output and the presence/absence of the *.test files created when test passes into human-readable status table of tests. Such processing utilities are not included in B2.

The following features adjust behavior of the testing metatargets.

For most main target rules, B2 automatically figures out the commands to run. When you want to use new file types or support new tools, one approach is to extend B2 to support them smoothly, as documented in Extender Manual. However, if the new tool is only used in a single place, it might be easier just to specify the commands to run explicitly.

Three main target rules can be used for that. The make rule allows you to construct a single file from any number of source file, by running a command you specify. The notfile rule allows you to run an arbitrary command, without creating any files. And finally, the generate rule allows you to describe a transformation using B2’s virtual targets. This is higher-level than the file names that the make rule operates with and allows you to create more than one target, create differently named targets depending on properties, or use more than one tool.

The make rule is used when you want to create one file from a number of sources using some specific command. The notfile is used to unconditionally run a command.

Suppose you want to create the file file.out from the file file.in by running the command in2out. Here is how you would do this in B2:

If you run b2 and file.out does not exist, B2 will run the in2out command to create that file. For more details on specifying actions, see the section called “Boost.Jam Language”.

It could be that you just want to run some command unconditionally, and that command does not create any specific files. For that you can use the notfile rule. For example:

The only difference from the make rule is that the name of the target is not considered a name of a file, so B2 will unconditionally run the action.

The generate rule is used when you want to express transformations using B2’s virtual targets, as opposed to just filenames. The generate rule has the standard main target rule signature, but you are required to specify the generating-rule property. The value of the property should be in the form @rule-name, the named rule should have the following signature:

and will be called with an instance of the project-target class, the name of the main target, an instance of the property-set class containing build properties, and the list of instances of the virtual-target class corresponding to sources. The rule must return a list of virtual-target instances. The interface of the virtual-target class can be learned by looking at the build/virtual-target.jam file. The generate example contained in the B2 distribution illustrates how the generate rule can be used.

Precompiled headers is a mechanism to speed up compilation by creating a partially processed version of some header files, and then using that version during compilations rather then repeatedly parsing the original headers. B2 supports precompiled headers with gcc and msvc toolsets.

To use precompiled headers, follow the following steps:

The pch example in B2 distribution can be used as reference.

Please note the following:

Usually, B2 handles implicit dependencies completely automatically. For example, for C++ files, all #include statements are found and handled. The only aspect where user help might be needed is implicit dependency on generated files.

By default, B2 handles such dependencies within one main target. For example, assume that main target "app" has two sources, "app.cpp" and "parser.y". The latter source is converted into "parser.c" and "parser.h". Then, if "app.cpp" includes "parser.h", B2 will detect this dependency. Moreover, since "parser.h" will be generated into a build directory, the path to that directory will automatically be added to the include path.

Making this mechanism work across main target boundaries is possible, but imposes certain overhead. For that reason, if there is implicit dependency on files from other main targets, the <implicit-dependency> feature must be used, for example:

The above example tells the build system that when scanning all sources of "app" for implicit-dependencies, it should consider targets from "parser" as potential dependencies.

B2 supports cross compilation with the gcc and msvc toolsets.

When using gcc, you first need to specify your cross compiler in user-config.jam (see the section called “Configuration”), for example:

After that, if the host and target os are the same, for example Linux, you can just request that this compiler version be used:

If you want to target a different operating system from the host, you need to additionally specify the value for the target-os feature, for example:

For the complete list of allowed operating system names, please see the documentation for target-os feature.

When using the msvc compiler, it’s only possible to cross-compile to a 64-bit system on a 32-bit host. Please see the section called “64-bit support” for details.

B2 supports automatic, or manual, loading of generated build files from package managers. For example using the Conan package manager which generates conanbuildinfo.jam files B2 will load that files automatically when it loads the project at the same location. The included file can define targets and other project declarations in the context of the project it’s being loaded into. Control over what package manager file is loaded can be controlled with (in order of priority):

use-packages rule:

The use-packages rule allows one to specify in the projects themselves kind of package definitions to use either as the ones for a built-in package manager support. For example:

Or to specify a glob pattern to find the file with the definitions. For instance:

--use-package-manager command line option:

The --use-package-manager=NAME command line option allows one to non-intrusively specify per invocation which of the built-in package manager types to use.

PACKAGE_MANAGER_BUILD_INFO variable:

The PACKAGE_MANAGER_BUILD_INFO variable, which is taken from the environment or defined with the -sX=Y option, specifies a glob pattern to use to find the package definitions.

Built-in detection:

There are a number of built-in glob patterns to support popular package managers. Currently the supported ones are:

B2 supports automatic searching for referenced global projects. For example, if you have references to /boost/predef with some minimal configuration B2 can find the B2 project for it and automatically resolve the reference. The searching supports two modes: finding regular B2 project directories, and package/config style loading of single jam files.

This section contains the list of all rules that can be used in Jamfile — both rules that define new targets and auxiliary rules.

This section documents the features that are built-in into B2. For features with a fixed set of values, that set is provided, with the default value listed first.

The include order is not guaranteed if used multiple times on a single target.

If more are necessary, they could be added with stage.add-install-dir.

B2 comes with support for a large number of C++ compilers, and other tools. This section documents how to use those tools.

Before using any tool, you must declare your intention, and possibly specify additional information about the tool’s configuration. This is done by calling the using rule, typically in your user-config.jam, for example:

additional parameters can be passed just like for other rules, for example:

The options that can be passed to each tool are documented in the subsequent sections.

This section describes the modules that are provided by B2. The import rule allows rules from one module to be used in another module or Jamfile.

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:

This section explains how to extend B2 to accommodate your local requirements — primarily to add support for non-standard tools you have. Before we start, be sure you have read and understood the concept of metatarget, Concepts, which is critical to understanding the remaining material.

The current version of B2 has three levels of targets, listed below.

In most cases, you will only have to deal with concrete targets and the process that creates concrete targets from metatargets. Extending metatarget level is rarely required. The jam targets are typically only used inside the command line patterns.

Say you’re writing an application that generates C++ code. If you ever did this, you know that it’s not nice. Embedding large portions of C++ code in string literals is very awkward. A much better solution is:

It’s quite easy to achieve. You write special verbatim files that are just C++, except that the very first line of the file contains the name of a variable that should be generated. A simple tool is created that takes a verbatim file and creates a cpp file with a single char* variable whose name is taken from the first line of the verbatim file and whose value is the file’s properly quoted content.

Let’s see what B2 can do.

First off, B2 has no idea about "verbatim files". So, you must register a new target type. The following code does it:

The first parameter to type.register gives the name of the declared type. By convention, it’s uppercase. The second parameter is the suffix for files of this type. So, if B2 sees code.verbatim in a list of sources, it knows that it’s of type VERBATIM.

Next, you tell B2 that the verbatim files can be transformed into C++ files in one build step. A generator is a template for a build step that transforms targets of one type (or set of types) into another. Our generator will be called verbatim.inline-file; it transforms VERBATIM files into CPP files:

Lastly, you have to inform B2 about the shell commands used to make that transformation. That’s done with an actions declaration.

Now, we’re ready to tie it all together. Put all the code above in file verbatim.jam, add import verbatim ; to Jamroot.jam, and it’s possible to write the following in your Jamfile:

The listed verbatim files will be automatically converted into C++ source files, compiled and then linked to the codegen executable.

In subsequent sections, we will extend this example, and review all the mechanisms in detail. The complete code is available in the example/customization directory.

The first thing we did in the introduction was declaring a new target type:

The type is the most important property of a target. B2 can automatically generate necessary build actions only because you specify the desired type (using the different main target rules), and because B2 can guess the type of sources from their extensions.

The first two parameters for the type.register rule are the name of new type and the list of extensions associated with it. A file with an extension from the list will have the given target type. In the case where a target of the declared type is generated from other sources, the first specified extension will be used.

Sometimes you want to change the suffix used for generated targets depending on build properties, such as toolset. For example, some compiler uses extension elf for executable files. You can use the type.set-generated-target-suffix rule:

A new target type can be inherited from an existing one.

The above code defines a new type derived from SHARED_LIB. Initially, the new type inherits all the properties of the base type - in particular generators and suffix. Typically, you’ll change the new type in some way. For example, using type.set-generated-target-suffix you can set the suffix for the new type. Or you can write a special generator for the new type. For example, it can generate additional meta-information for the plugin. In either way, the PLUGIN type can be used whenever SHARED_LIB can. For example, you can directly link plugins to an application.

A type can be defined as "main", in which case B2 will automatically declare a main target rule for building targets of that type. More details can be found later.

Sometimes, a file can refer to other files via some include system. To make B2 track dependencies between included files, you need to provide a scanner. The primary limitation is that only one scanner can be assigned to a target type.

First, we need to declare a new class for the scanner:

All the complex logic is in the common-scanner class, and you only need to override the method that returns the regular expression to be used for scanning. The parentheses in the regular expression indicate which part of the string is the name of the included file. Only the first parenthesized group in the regular expression will be recognized; if you can’t express everything you want that way, you can return multiple regular expressions, each of which contains a parenthesized group to be matched.

After that, we need to register our scanner class:

The value of the second parameter, in this case include, specifies the properties that contain the list of paths that should be searched for the included files.

Finally, we assign the new scanner to the VERBATIM target type:

That’s enough for scanning include dependencies.

This section will describe how B2 can be extended to support new tools.

For each additional tool, a B2 object called generator must be created. That object has specific types of targets that it accepts and produces. Using that information, B2 is able to automatically invoke the generator. For example, if you declare a generator that takes a target of the type D and produces a target of the type OBJ, when placing a file with extension .d in a list of sources will cause B2 to invoke your generator, and then to link the resulting object file into an application. (Of course, this requires that you specify that the .d extension corresponds to the D type.)

Each generator should be an instance of a class derived from the generator class. In the simplest case, you don’t need to create a derived class, but simply create an instance of the generator class. Let’s review the example we’ve seen in the introduction.

We declare a standard generator, specifying its id, the source type and the target type. When invoked, the generator will create a target of type CPP with a source target of type VERBATIM as the only source. But what command will be used to actually generate the file? In B2, actions are specified using named "actions" blocks and the name of the action block should be specified when creating targets. By convention, generators use the same name of the action block as their own id. So, in above example, the "inline-file" actions block will be used to convert the source into the target.

There are two primary kinds of generators: standard and composing, which are registered with the generators.register-standard and the generators.register-composing rules, respectively. For example:

The first (standard) generator takes a single source of type VERBATIM and produces a result. The second (composing) generator takes any number of sources, which can have either the CPP or the LIB type. Composing generators are typically used for generating top-level target type. For example, the first generator invoked when building an exe target is a composing generator corresponding to the proper linker.

You should also know about two specific functions for registering generators: generators.register-c-compiler and generators.register-linker. The first sets up header dependency scanning for C files, and the seconds handles various complexities like searched libraries. For that reason, you should always use those functions when adding support for compilers and linkers.

(Need a note about UNIX)

Custom generator classes

The standard generators allows you to specify source and target types, an action, and a set of flags. If you need anything more complex, you need to create a new generator class with your own logic. Then, you have to create an instance of that class and register it. Here’s an example how you can create your own generator class:

This generator will work exactly like the verbatim.inline-file generator we’ve defined above, but it’s possible to customize the behavior by overriding methods of the generator class.

There are two methods of interest. The run method is responsible for the overall process - it takes a number of source targets, converts them to the right types, and creates the result. The generated-targets method is called when all sources are converted to the right types to actually create the result.

The generated-targets method can be overridden when you want to add additional properties to the generated targets or use additional sources. For a real-life example, suppose you have a program analysis tool that should be given a name of executable and the list of all sources. Naturally, you don’t want to list all source files manually. Here’s how the generated-targets method can find the list of sources automatically:

The generated-targets method will be called with a single source target of type EXE. The call to virtual-target.traverse will return all targets the executable depends on, and we further find files that are not produced from anything. The found targets are added to the sources.

The run method can be overridden to completely customize the way the generator works. In particular, the conversion of sources to the desired types can be completely customized. Here’s another real example. Tests for the Boost Python library usually consist of two parts: a Python program and a C++ file. The C++ file is compiled to Python extension that is loaded by the Python program. But in the likely case that both files have the same name, the created Python extension must be renamed. Otherwise, the Python program will import itself, not the extension. Here’s how it can be done:

First, we separate all source into python files, libraries and C++ sources. For each C++ source we create a separate Python extension by calling generators.construct and passing the C++ source and the libraries. At this point, we also change the extension’s name, if necessary.

Often, we need to control the options passed the invoked tools. This is done with features. Consider an example:

We first define a new feature. Then, the flags invocation says that whenever verbatim.inline-file action is run, the value of the verbatim-options feature will be added to the OPTIONS variable, and can be used inside the action body. You’d need to consult online help (--help) to find all the features of the toolset.flags rule.

Although you can define any set of features and interpret their values in any way, B2 suggests the following coding standard for designing features.

Most features should have a fixed set of values that is portable (tool neutral) across the class of tools they are designed to work with. The user does not have to adjust the values for a exact tool. For example, <optimization>speed has the same meaning for all C++ compilers and the user does not have to worry about the exact options passed to the compiler’s command line.

Besides such portable features there are special 'raw' features that allow the user to pass any value to the command line parameters for a particular tool, if so desired. For example, the <cxxflags> feature allows you to pass any command line options to a C++ compiler. The <include> feature allows you to pass any string preceded by -I and the interpretation is tool-specific. (See Can I get capture external program output using a Boost.Jam variable? for an example of very smart usage of that feature). Of course one should always strive to use portable features, but these are still be provided as a backdoor just to make sure B2 does not take away any control from the user.

Using portable features is a good idea because:

Steps for adding a feature

Adding a feature requires three steps:

Another example

Here’s another example. Let’s see how we can make a feature that refers to a target. For example, when linking dynamic libraries on Windows, one sometimes needs to specify a "DEF file", telling what functions should be exported. It would be nice to use this file like this:

Actually, this feature is already supported, but anyway…​

Variants and composite features.

Sometimes you want to create a shortcut for some set of features. For example, release is a value of <variant> and is a shortcut for a set of features.

It is possible to define your own build variants. For example:

will define a new variant with the specified set of properties. You can also extend an existing variant:

In this case, super_release will expand to all properties specified by release, and the additional one you’ve specified.

You are not restricted to using the variant feature only. Here’s example that defines a brand new feature:

This will allow you to specify the value of feature parallelism, which will expand to link to the necessary library.

A main target rule (e.g “exe” Or “lib”) creates a top-level target. It’s quite likely that you’ll want to declare your own and there are two ways to do that.

The first way applies when your target rule should just produce a target of specific type. In that case, a rule is already defined for you! When you define a new type, B2 automatically defines a corresponding rule. The name of the rule is obtained from the name of the type, by down-casing all letters and replacing underscores with dashes. For example, if you create a module obfuscate.jam containing:

and import that module, you’ll be able to use the rule "obfuscated-cpp" in Jamfiles, which will convert source to the OBFUSCATED_CPP type.

The second way is to write a wrapper rule that calls any of the existing rules. For example, suppose you have only one library per directory and want all cpp files in the directory to be compiled into that library. You can achieve this effect using:

If you want to make it even simpler, you could add the following definition to the Jamroot.jam file:

allowing you to reduce the Jamfile to just

Note that because you can associate a custom generator with a target type, the logic of building can be rather complicated. For example, the boostbook module declares a target type BOOSTBOOK_MAIN and a custom generator for that type. You can use that as example if your main target rule is non-trivial.

If your extensions will be used only on one project, they can be placed in a separate .jam file and imported by your Jamroot.jam. If the extensions will be used on many projects, users will thank you for a finishing touch.

The using rule provides a standard mechanism for loading and configuring extensions. To make it work, your module should provide an init rule. The rule will be called with the same parameters that were passed to the using rule. The set of allowed parameters is determined by you. For example, you can allow the user to specify paths, tool versions, and other options.

Here are some guidelines that help to make B2 more consistent:

This is not possible, since Jamfile does not have "current" value of any feature, be it toolset, build variant or anything else. For a single run of B2, any given main target can be built with several property sets. For example, user can request two build variants on the command line. Or one library is built as shared when used from one application, and as static when used from another. Each Jamfile is read only once so generally there is no single value of a feature you can access in Jamfile.

A feature has a specific value only when building a target, and there are two ways you can use that value:

The most likely case is that you are trying to compile the same file twice, with almost the same, but differing properties. For example:

The above snippet requires two different compilations of a.cpp, which differ only in their include property. Since the include feature is declared as free B2 does not create a separate build directory for each of its values and those two builds would both produce object files generated in the same build directory. Ignoring this and compiling the file only once would be dangerous as different includes could potentially cause completely different code to be compiled.

To solve this issue, you need to decide if the file should be compiled once or twice.

A good question is why B2 can not use some of the above approaches automatically. The problem is that such magic would only help in half of the cases, while in the other half it would be silently doing the wrong thing. It is simpler and safer to ask the user to clarify his intention in such cases.

Many users would like to use environment variables in Jamfiles, for example, to control the location of external libraries. In many cases it is better to declare those external libraries in the site-config.jam file, as documented in the recipes section. However, if the users already have the environment variables set up, it may not be convenient for them to set up their site-config.jam files as well and using the environment variables might be reasonable.

Boost.Jam automatically imports all environment variables into its built-in .ENVIRON module so user can read them from there directly or by using the helper os.environ rule. For example:

or a bit more realistic:

For internal reasons, B2 sorts all the properties alphabetically. This means that if you write:

then the command line with first mention the a include directory, and then b, even though they are specified in the opposite order. In most cases, the user does not care. But sometimes the order of includes, or other properties, is important. For such cases, a special syntax is provided:

The && symbols separate property values and specify that their order should be preserved. You are advised to use this feature only when the order of properties really matters and not as a convenient shortcut. Using it everywhere might negatively affect performance.

On Unix-like operating systems, the order in which static libraries are specified when invoking the linker is important, because by default, the linker uses one pass though the libraries list. Passing the libraries in the incorrect order will lead to a link error. Further, this behavior is often used to make one library override symbols from another. So, sometimes it is necessary to force specific library linking order.

B2 tries to automatically compute the right order. The primary rule is that if library a "uses" library b, then library a will appear on the command line before library b. Library a is considered to use b if b is present either in the a library’s sources or its usage is listed in its requirements. To explicitly specify the use relationship one can use the <use> feature. For example, both of the following lines will cause a to appear before b on the command line:

The same approach works for searched libraries as well:

The SHELL builtin rule may be used for this purpose:

You might want to use your project’s root location in your Jamfiles. To access it just declare a path constant in your Jamroot.jam file using:

After that, the TOP variable can be used in every Jamfile.

If one file must be compiled with special options, you need to explicitly declare an obj target for that file and then use that target in your exe or lib target:

Of course you can use other properties, for example to specify specific C/C++ compiler options:

You can also use conditional properties for finer control:

Before answering the questions, let us recall a few points about shared libraries. Shared libraries can be used by several applications, or other libraries, without physically including the library in the application which can greatly decrease the total application size. It is also possible to upgrade a shared library when the application is already installed.

However, in order for application depending on shared libraries to be started the OS may need to find the shared library when the application is started. The dynamic linker will search in a system-defined list of paths, load the library and resolve the symbols. Which means that you should either change the system-defined list, given by the LD_LIBRARY_PATH environment variable, or install the libraries to a system location. This can be inconvenient when developing, since the libraries are not yet ready to be installed, and cluttering system paths may be undesirable. Luckily, on Unix there is another way.

An executable can include a list of additional library paths, which will be searched before system paths. This is excellent for development because the build system knows the paths to all libraries and can include them in the executables. That is done when the hardcode-dll-paths feature has the true value, which is the default. When the executables should be installed, the story is different.

Obviously, installed executable should not contain hardcoded paths to your development tree. (The install rule explicitly disables the hardcode-dll-paths feature for that reason.) However, you can use the dll-path feature to add explicit paths manually. For example:

will allow the application to find libraries placed in the /usr/lib/snake directory.

If you install libraries to a nonstandard location and add an explicit path, you get more control over libraries which will be used. A library of the same name in a system location will not be inadvertently used. If you install libraries to a system location and do not add any paths, the system administrator will have more control. Each library can be individually upgraded, and all applications will use the new library.

Which approach is best depends on your situation. If the libraries are relatively standalone and can be used by third party applications, they should be installed in the system location. If you have lots of libraries which can be used only by your application, it makes sense to install them to a nonstandard directory and add an explicit path, like the example above shows. Please also note that guidelines for different systems differ in this respect. For example, the Debian GNU guidelines prohibit any additional search paths while Solaris guidelines suggest that they should always be used.

It is desirable to declare standard libraries available on a given system. Putting target declaration in a specific project’s Jamfile is not really good, since locations of the libraries can vary between different development machines and then such declarations would need to be duplicated in different projects. The solution is to declare the targets in B2’s site-config.jam configuration file:

Recall that both site-config.jam and user-config.jam are projects, and everything you can do in a Jamfile you can do in those files as well. So, you declare a project id and a target. Now, one can write:

in any Jamfile.

In modern C++, libraries often consist of just header files, without any source files to compile. To use such libraries, you need to add proper includes and possibly defines to your project. But with a large number of external libraries it becomes problematic to remember which libraries are header only, and which ones you have to link to. However, with B2 a header-only library can be declared as B2 target and all dependents can use such library without having to remember whether it is a header-only library or not.

Header-only libraries may be declared using the alias rule, specifying their include path as a part of its usage requirements, for example:

The includes specified in usage requirements of my-lib are automatically added to all of its dependents build properties. The dependents need not care if my-lib is a header-only or not, and it is possible to later make my-lib into a regular compiled library without having to add the includes to its dependents declarations.

If you already have proper usage requirements declared for a project where a header-only library is defined, you do not need to duplicate them for the alias target:

B2 is the name of the complete build system. The executable that runs it is b2. That executable is written in C and implements performance-critical algorithms, like traversal of dependency graph and executing commands. It also implements an interpreted language used to implement the rest of B2. This executable is formally called "B2 engine".

The B2 engine is derived from an earlier build tool called Perforce Jam. Originally, there were just minor changes, and the filename was bjam. Later on, with more and more changes, the similarity of names became a disservice to users, and as of Boost 1.47.0, the official name of the executable was changed to b2. A copy named bjam is still created for compatibility, but you are encouraged to use the new name in all cases.

Perforce Jam was an important foundation, and we gratefully acknowledge its influence, but for users today, these tools share only some basics of the interpreted language.