Configuration

Configuration

On startup, Boost.Build searches and reads two configuration files: site-config.jam and user-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 following table explains where both files are searched.

Table 4.1. Search paths for configuration files

	site-config.jam	user-config.jam
Linux	/etc $HOME $BOOST_BUILD_PATH	$HOME $BOOST_BUILD_PATH
Windows	%SystemRoot% %HOMEDRIVE%%HOMEPATH% %HOME% %BOOST_BUILD_PATH%	%HOMEDRIVE%%HOMEPATH% %HOME% %BOOST_BUILD_PATH%

	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

• has its “usual name” and is in the PATH, or

• 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:

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 ;

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

	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.