On startup, Boost.Build searches and reads two configuration files:
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 following table explains where both files
Table 3.1. Search paths for configuration files
You can use the --debug-configuration option to find which configuration files are actually loaded.
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:
tool-name : ... ;
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:
If you have a single compiler, and the compiler executable
has its “usual name” and is in the
was installed in a standard “installation directory”, or
can be found using a global system like the Windows registry.
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:
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 ;
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 ;
Note that in the first call to
compiler found in the
PATH will be used, and there is no
need to explicitly specify the command.
Many of toolsets have an
parameter to fine-tune the configuration. All of
Boost.Build's standard compiler toolsets accept four options
options specifying flags that will be
always passed to the corresponding tools. 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 ;
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.