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.

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