| Home | Libraries | People | FAQ | More

## Chapter 24. User documentation

This section will provide the information necessary to create your own projects using Boost.Build. The information provided here is relatively high-level, and Chapter 26, Detailed reference as well as the on-line help system must be used to obtain low-level documentation (see ???).

Boost.Build actually consists of two parts - Boost.Jam, a build engine with its own interpreted language, and Boost.Build itself, implemented in Boost.Jam's language. The chain of events when you type bjam on the command line is:

1. Boost.Jam tries to find Boost.Build and loads the top-level module. The exact process is described in the section called “Initialization”

2. The top-level module loads user-defined configuration files, `user-config.jam` and `site-config.jam`, which define available toolsets.

3. The Jamfile in the current directory is read. That in turn might cause reading of further Jamfiles. As a result, a tree of projects is created, with targets inside projects.

4. Finally, using the build request specified on the command line, Boost.Build decides which targets should be built, and how. That information is passed back to Boost.Jam, which takes care of actually running commands.

So, to be able to successfully use Boost.Build, you need to know only three things:

- How to configure Boost.Build

- How to write Jamfiles

- How the build process works

- Some Basics about the Boost.Jam language. See the Boost.Jam and Classic Jam documentation.

## Configuration

The Boost.Build configuration is specified in the file `user-config.jam`. You can edit the one that comes with Boost.Build, or create a copy in your home directory and edit that. (See the reference 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.

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 ;