Installing Boost.Build

Problem

You want to obtain and install Boost.Build.

Solution

Consult the Boost.Build documentation at www.boost.org/boost-build2 or follow these steps:

1. Go to the Boost homepage, www.boost.org, and follow the Download link to Boost's SourceForge download area.
2. Download and unpack either the latest release of the package boost or the latest release of the package boost-build. The former includes the full collection of Boost libraries, while the latter is a standalone release of Boost.Build. Place the unpacked files in a suitable permanent location.
3. Download and unpack the latest version of the package boost-jam for your platform; this package includes a prebuilt bjam executable. If the package boost-jam is not available for your platform, follow the instructions provided with the package you downloaded in step 2 to build the executable from the source.
4. Copy bjam to a location in your PATH environment variable.
5. Permanently set the environment variable BOOST_BUILD_PATH to the Boost. Build root directory. If you downloaded the package boost in step 1, the root directory is the subdirectory tools/build/v2 of your Boost installation; otherwise, it is the directory boost-build.
6. Configure Boost.Build for your toolsets and libraries by editing the configuration file user-config.jam, located in the Boost.Build root directory. The file user-config.jam contains comments explaining how to do this.

Discussion

The most difficult part of using Boost.Build is downloading and installing it. Eventually Boost may provide a graphical installation utility, but for the time being, you must follow the above steps.

The purpose of step five is to help the build tool, bjam, find the root directory of the build system. This step is not strictly necessary, however, since there is another way to accomplish the same thing: simply create a file called boost-build.jam, with the single line:

boost-build boost-build-root ;

and place it in the root directory of your project or in any of its parent directories. The second method may be preferable if you wish to distribute Boost.Build with your source code, since it makes the installation process easier for end users.

The sixth step is potentially the most complex, but in practice it is usually simple. If you have just a single version of your toolset installed, and if it's installed in a standard location, it's sufficient for user-config.jam to consist of a single line of the form:

using ;

For example, if you use Visual C++, the following will usually suffice:

using msvc ;

And if you use GCC, you can simply write:

using gcc ;

Things are slightly more complicated if you have more than one version of a toolset installed, or if your toolset is installed in an unusual location. If your toolset is installed in an unusual location, you tell Boost.Build where to find it by passing the command to invoke the toolset's compiler as the third argument to using. For example:

using msvc : : "C:/Tools/Compilers/Visual Studio/Vc7/bin/cl" ;

If you have several versions of a toolset installed, you can invoke the using rule several times with a single toolset name, passing a version identifier as the second argument and the compiler command as the third argument. For example, you might configure two versions of the Intel toolset as follows:

using intel : 7.1 : "C:/Program Files/Intel/Compiler70/IA32/Bin/icl" ; using intel : 8.0 : "C:/Program Files/Intel/CPP/Compiler80/IA32/Bin/icl" ;

The names used by Boost.Build for the seven toolsets covered in this chapter are given in Table 1-14.