![]() |
The Boost.Build configuration is specified in the file
user-config.jam
. You can edit the one in the top-level
directory of Boost.Build installation or create a copy in your home directory
and edit that. (See Table 7.1, “Search paths for configuration files” for the
exact search paths.) The primary function of that file is to declare which
compilers and other tools are available. The simplest syntax to configure
a tool is:
using tool-name
;
The using
rule is given a name of tool, and will make that tool
available to Boost.Build. For example, using gcc ;
will make the gcc compiler
available.
Since nothing but a tool name is specified, Boost.Build will
pick some default settings. For example, it will use the
gcc executable found in the
PATH
, or look in some known installation
locations. In most cases, this strategy works automatically. In
case you have several versions of a compiler, it's installed in
some unusual location, or you need to tweak its configuration,
you'll need to pass additional parameters to the
using
rule. The parameters to
using
can be different for each
tool. You can obtain specific documentation for any tool's
configuration parameters by invoking
bjam --help tool-name
.init
That said, for all the compiler toolsets Boost.Build supports
out-of-the-box, the list of parameters to
using
is the same: toolset-name
, version
, invocation-command
, and options
.
The version
parameter identifies the toolset version, in case you have
several installed. It can have any form you like, but
it's recommended that you use a numeric identifier like
7.1
.
The invocation-command
parameter is the command that must be executed to run the
compiler. This parameter can usually be omitted if the compiler
executable
has its “usual
name” and is in the PATH
,
or
was installed in a standard “installation directory”, or
can be found through a global mechanism like the Windows registry.
For example:
using msvc : 7.1 ; using gcc ;
If the compiler can be found in the PATH
but only by a
nonstandard name, you can just supply that name:
using gcc : : g++-3.2 ;
Otherwise, it might be necessary to supply the complete path to the compiler executable:
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 compiler executables for C and C++ are different, path to the C++ compiler executable must be specified. The “invocation 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 ;
Note that in the first call to
using
, the compiler found in the
PATH
will be used, and there's no need to
explicitly specify the command.
As shown above, both the version
and invocation-command
parameters are
optional, but there's an important restriction: if you configure
the same toolset more than once, you must pass the version
parameter every time. For example, the following is not allowed:
using gcc ; using gcc : 3.4 : g++-3.4 ;
because the first using
call does
not specify a version
.
The options
parameter is used to fine-tune the configuration. All of
Boost.Build's standard compiler toolsets accept properties of the
four builtin features cflags
,
cxxflags
, compileflags
and
linkflags
as 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 ;