Boost.Build 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 flavour 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.

a.o: a.c
    g++ -o a.o -g a.c

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:

add_program ("a", "a.c")

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 multivariant builds, Boost.Build introduces the concept of a 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:

exe a : a.cpp ;

When this declaration is parsed, Boost.Build 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, Boost.Build considers the properties requested on the command line. Supposed you have invoked Boost.Build with:

b2 toolset=gcc toolset=msvc

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, Boost.Build 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. Boost.Build 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 Boost.Build 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.

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

a = b ;

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

	Warning
	All syntax elements, even keywords, must be separated by spaces. For example, omitting the space character before ; will lead to a syntax error.

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

a = "=" ;

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:

a = $(b) $(c) ;

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

rule example
 (
     parameter1 :
     parameter2 ? :
     parameter3 + :
     parameter4 *
 )
 {
    # rule body
 }
 

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:

helper 1 : 2 : 3 ;
x = [ helper 1 : 2 : 3 ] ;

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.

if cond { statements } [ else { statements } ]

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

for var in list { statements }

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

while cond { statements }

Repeatedly execute statements while cond remains true upon entry.

return values ;

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

import module ;
import module : 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:

actions create-file-from-another
{
    create-file-from-another $(<) $(>)
}

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:

rule create-file-from-another ( targets * : sources * : properties * )
{
   if <variant>debug in $(properties)
   {
       OPTIONS on $(targets) = --debug ;
   }
}
actions create-file-from-another
{
    create-file-from-another $(OPTIONS) $(<) $(>)
}

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, Boost.Build 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 Boost.Build 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

	Tip
	You can use the --debug-configuration option to find which configuration files are actually loaded.

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:

using tool-name : ... ;

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

using gcc ;

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 Boost.Build 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:

using tool-name ;

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

using gcc : : g++-3.2 ;
using msvc : : "Z:/Programs/Microsoft Visual Studio/vc98/bin/cl" ;

Some Boost.Build 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:

using msvc : : echo Compiling && foo/bar/baz/cl ;

will work.

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

using gcc : 3.3 ;
using gcc : 3.4 : g++-3.4 ;
using gcc : 3.2 : g++-3.2 ;
using gcc : 5 ;
using clang : 3.9 ;
using msvc : 14.0 ;

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 Boost.Build'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:

using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ;

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

using gcc : 5 : : <cxxflags>"-std=c++14 -O2" ;
using clang : 3.9 : : <cxxflags>-std=c++14 <cxxflags>-O2 ;

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

using gcc : 5 : g++-5 : ; # default is C++ 98
using gcc : 5~c++03 : g++-5 : <cxxflags>-std=c++03 ; # C++ 03
using gcc : 5~gnu03 : g++-5 : <cxxflags>-std=gnu++03 ; # C++ 03 with GNU
using gcc : 5~c++11 : g++-5 : <cxxflags>-std=c++11 ; # C++ 11
using gcc : 5~c++14 : g++-5 : <cxxflags>-std=c++14 ; # C++ 14

These are then used as normal toolsets:

b2 toolset=gcc-5 stage
b2 toolset=gcc-5~c++14 stage

	Warning
	Although the syntax used to specify toolset options is very similar to syntax used to specify requirements in Jamfiles, the toolset options are not the same as features. Don't try to specify a feature value in toolset initialization.

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

b2

b2 lib1 subproject//lib2

b2 toolset=gcc variant=debug optimization=space

b2 link=static link=shared threading=single threading=multi

b2 link=static,shared threading=single,multi

b2 include=static,shared

b2 gcc/link=shared msvc/link=static,shared

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 Boost.Build have the same common signature:

rule rule-name (
     main-target-name :
     sources + :
     requirements * :
     default-build * :
     usage-requirements * )

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”

obj test.release : test.cpp : <variant>release ;
obj test.debug : test.cpp : <variant>debug ;

exe a : a.cpp ;           # a.cpp is the only source file
exe b : [ glob *.cpp ] ;  # all .cpp files in this directory are sources

lib helper : helper.cpp ;
exe a : a.cpp helper ;
# Since all project ids start with slash, ".." is a directory name.
exe b : b.cpp ..//utils ;
exe c : c.cpp /boost/program_options//program_options ;

exe hello : hello.cpp : <include>/opt/boost <define>MY_DEBUG ;

lib util : util.cpp : <link>static ;
obj main : main.cpp : <optimization>off ;

lib network : network.cpp
    : <link>shared:<define>NETWORK_LIB_SHARED
     <variant>release:<define>EXTRA_FAST
    ;

lib network : network.cpp
    : <toolset>gcc,<optimization>speed:<define>USE_INLINE_ASSEMBLER
    ;

lib network : network.cpp
    : <conditional>@my-rule
    ;
rule my-rule ( properties * )
{
    local result ;
    if <toolset>gcc <optimization>speed in $(properties)
    {
        result += <define>USE_INLINE_ASSEMBLER ;
    }
    return $(result) ;
}

exe main : main.cpp : -<define>UNNECESSARY_DEFINE ;

project test : requirements <threading>multi ;
exe test1 : test1.cpp ;
exe test2 : test2.cpp : <threading>single ;
exe test3 : test3.cpp : -<threading>multi ;

exe hello : hello.cpp : : <threading>multi ;

lib demangler : dummy_demangler.cpp ;                # alternative 1
lib demangler : demangler_gcc.cpp : <toolset>gcc ;   # alternative 2
lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3

exe hello : hello.cpp
    [ obj helpers : helpers.cpp : <optimization>off ] ;

explicit install_programs ;

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:

project id : attributes ;

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:

project tennis
    : requirements <threading>multi
    : default-build release
    ;

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 subprojects.

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 rather than Jamfile. When loading a project, Boost.Build 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.

Even when building in a subproject directory, parent project files are always loaded before those of their subprojects, 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.

	Note
	Giving the root project the special name “Jamroot” ensures that Boost.Build won't misinterpret a directory above it as the project root just because the directory contains a Jamfile.

When you've described your targets, you want Boost.Build 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 Boost.Build, 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.

	Tip
	This means that for Boost.Build, you cannot directly obtain a build variant from a Jamfile. There could be several variants requested by the user, and each target can be built with different properties.

b2 app1 lib1//lib1 toolset=gcc variant=debug optimization=full

b2 app1 lib1//lib1 gcc debug optimization=full

explicit hello_test ;