Chapter 21. User documentation

| Home | Libraries | People | FAQ | More

## Chapter 21. 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 detailed reference as well as the on-line help system must be used to obtain low-level documentation (see the help option).

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

1. Boost.Jam tries to find Boost.Build and loads the top-level module. The exact process is described in the section on initialization

2. Boost.Build 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 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'd need to know only three things:

- How to configure Boost.Build

- How to write Jamfiles

- How the build process works

## Configuration

The Boost.Build configuration is specified in the file "user-config.jam". You can edit the one which 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 declarate 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 available the gcc compiler.

Since nothing but tool name is specified, Boost.Build will pick some default settings -- for example will use gcc found in path, or look in some known installation locations. For ordinary users, this is quite fine. In case you have several version of a compiler, or it's located in some unusual location, or you need to tweak the configuration, you'd need to pass additional parameters to the "using" rule. Generally, for every tool module, the parameters differ, and you can obtain the documentaiton by running

    bjam --help <tool-name>.init

on the command line. However, for all compilers the meaning of the first three parameters is the same: version, invocation command and options.

The "version" parameter identifies the compiler, in case you have several. 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 which must be executed to run the compiler. This might be just compiler name, or a name with a path in it. Here are some examples.

To configure a compiler installed in non-standard location and not present in path, you can do the following:

    using msvc : : Z:/Programs/Microsoft Visual Studio/vc98/bin/cl.exe ;

To configure several versions of a compiler, the following can be used.

    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 path will be used, and there's no need to explicitly specify the command.

As shown above, both "version" and "invocation command" parameters are optional, but there's an important restriction: if you configure the same compiler more then 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" does not specify the version.

The `options` parameter is used to fine-tune the configuration. All compilers allow to pass four option, intentionally similiar in spelling to builtin features: `cflags`, `cxxflags`, `compileflags` and `linkflags`. They specify additional options which will be always passed to the corresponding tools. The `cflags` option applies only to the C compiler, the `cxxflags` option applies only to the C++ compiler and the `compileflags` options applies to both. For example, to use 64 bit mode with gcc you can use:

    using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ;