boost.png (6897 bytes)

Home
Libraries
People
FAQ
More

Build the Boost libraries

Do you need to build libraries?

Most of Boost's libraries are header-only. If you want to use only those, you are almost done already.
However, you need to build libraries if you want to use one or more of the following libraries:

Some libraries are mostly in header files, but need to be built if you want to use particular features and components:

If you don't want to use any of the libraries and features in the two lists above, you can skip directly to "add the Boost root directory to the compiler's #include <...> path" in order to finish the installation.

Boost.Build

The recommended way to build and install the Boost Libraries is to use Boost.Build, the Boost Build system. This is done using a command-line tool named bjam. If are used doing everything through an IDE, don't worry. The rest of these instructions will walk you through all the steps necessary.
There are of course other ways to build these libraries, but if you try to use any of those, you might get wrong result. Also note that some of the libraries also include non Boost.Build makefiles and/or project files. However, all of them include the needed files for building with Boost.Build.

The bjam tool

In order to build Boost libraries with Boost.Build, you will need a tool named bjam. If you are on a more common platform, it is strongly recommended that you download a prebuilt bjam executable here. Otherwise, or if you are using an unreleased state from CVS (or if you are feeling adventurous), you need to download its sources and build it yourself.
No matter which way you did this, make sure the bjam executable is in your path before you proceed.

Toolsets

The following toolsets are supported by Boost.Build. You can build the libraries for one or more toolsets.
For information about configuring each toolset, click its name in the leftmost column. (Note: It is likely that you will not need this information.)

TOOLS Name Description
borland Borland C++
como Comeau C++ compiler front-end for non-Windows platforms
como-win32 Comeau C++ compiler front-end for Windows, using Microsoft Visual C++as a back-end.
cw Metrowerks CodeWarrior Pro 6.x, 7.x, 8.x, and 9.x command-line tools
darwin Apple Darwin OS hosted GNU GCC
dmc Digital Mars C++.
dmc-stlport Digital Mars C++, using the STLport standard library implementation
edg Edison Design Group compiler front-end (evaluation version)
gcc GNU GCC on Unix and Cygwin.
gcc-stlport GNU GCC on Unix and Cygwin, using the STLport standard library implementation
gcc-nocygwin GNU GCC Cygwin command line compiler tools running in "no-cygwin" mode (produces commercially redistributable objects)
intel-linux Intel C++ for Linux
intel-win32 Intel C++ for Windows using the Dinkumware standard library in the Intel-required Microsoft Visual C++ 6 or 7 installation
kcc KAI C++
kylix Borland C++ for Linux (Kylix).
mingw GNU GCC and associated tools in MinGW configuration (produces commercially redistributable objects)
mingw-stlport GNU GCC and associated tools in MinGW configuration (produces commercially redistributable objects), using the STLport standard library implementation
mipspro SGI MIPSpro C and C++
msvc Microsoft Visual C++ version 6 command-line tools. NOTE; For version 7.x (the .NET series) use the vc7 or vc-7_1 toolsets below.
msvc-stlport Microsoft Visual C++ version 6 command-line tools, using the STLport standard library implementation. NOTE; For version 7.x (the .NET series) use the vc7-stlport or vc-7_1-stlport toolsets below.
sunpro SunPRO C++ compiler
tru64cxx Compaq C++ for Tru64 UNIX (versions prior to 6.5)
tru64cxx65 Compaq C++ Version 6.5 for Tru64 UNIX
vacpp IBM Visual Age C++ command-line tools
vc7 Microsoft Visual C++ command-line tools from Visual Studio .NET.
vc7-stlport Microsoft Visual C++ command-line tools from Visual Studio .NET + STLPort.
vc-7_1 Microsoft Visual C++ command-line tools from Visual Studio .NET 2003.
vc-7_1-stlport Microsoft Visual C++ command-line tools from Visual Studio .NET 2003 + STLPort.

If your platform/compiler/standard libarary combination is not in this table, you cannot follow this guide. See here how you can tailor Boost.Build for your platform.

Now open a command shell, and prepare the environment for building Boost. Usually, the only preparation required is whatever you'd normally do to set up your compiler and linker to be invoked from the command line. For example, to prepare Microsoft VC++, simply run the Visual Studio Command Prompt program that's installed with Visual Studio (or invoke the VCVARS32.BAT or VSVARS32.BAT script in your command shell). Most Windows compilers come with similar tools for setting up the environment. To prepare Unix tools such as GCC, the compiler and linker must be in your PATH. (Depending on your installation, a Unix compiler such as GCC may have additional requirements.) Many Unix operating systems come preconfigured and require no user intervention.
(If you don't want to clutter your environment with settings or you have a nonstandard installations for some of the tools, you need to set variables which point to the toolset installation directories, either in the command shell environment or on the bjam command-line. See here how to do this.
More information on how to use bjam can be found here.)

Boost root directory

The bjam tool will install the headers and libraries at a location depending on your platform. You can tell it to install to a different location. However, you could also simply move the results of running bjam from the default location to wherever you like.

This folder is the Boost root folder. It contains the headers and the libraries

(If you don't build the Boost libraries, because you exclusively use the header-only libraries, the folder containing the downloaded Boost distribution will be your root directory.)

Build and Install

Make sure you are in Boost's root folder. (This is the one where the file boost-build.jam is.)
Make sure bjam is in your path.
Make sure the environment is set up as described above.

Now invoke bjam like this:

bjam "-sTOOLS=toolset" install

where “toolset” needs to be replaced by the name of your toolset which you can pick from the first column of the above table. If, for example, you want to build and install the libraries for Visual Studio .NET 2003, you need to invoke bjam like this:

bjam "-sTOOLS=vc-7_1" install

The default build and install attempts to build all available libraries and install to default locations the libraries and Boost header files. On Unix systems the default install location is "/usr/local", and on Windows systems the default is "C:\Boost". Within those directories libraries are installed to the "lib" subdirectory, and headers to an "include/boost-1_32" subdirectory, the version will reflect the distribution you are installing.
If you need to change the installation directories or you want to tune other aspects of the build, see Configuring the Build.

Of course, sometimes something goes wrong. In this case, bjam will issue a message. Here is a list of common messages together with explanations what they mean. If this doesn't help, refer to the Boost.Build documentation or ask in the Boost.Build mailing list.

Configuring the Build

Note: If you successfully used the default setup as described above, you do not need to read the rest of this document. Goto Telling your compiler and linker about Boost instead.

The build and install system can be controlled through a set of options similar in style to GNU configure options. The options allow you to, among other things, change the install location, disable building of libraries, etc. You can see a summary of the available options by invoking "bjam --help". The full invocation takes the form:

bjam [options...] [install|stage]

Action  
none Only builds the Boost libraries. This lets you do the first part of what the install action normally does without copying the built libraries to the install location.
install Builds and installs Boost libraries and headers.
stage Builds the Boost libraries and copies them into a common directory.
Option  
--help Shows a short summary of the options and syntax of the command.
-sTOOLS=<toolsets> The list of tools to compile with. Usually only one is needed. See this table for available toolsets.
--prefix=PREFIX Install architecture independent files here.
Default; C:\Boost on Win32.
Default; /usr/local on Unix. Linux, etc.
--exec-prefix=EPREFIX Install architecture dependent files here.
Default; PREFIX
--libdir=DIR Install libraries here.
Default; EPREFIX/lib
--includedir=DIR Install source headers here. The Boost headers are installed in a version specific "boost-<version>" subdirectory in this directory.
Default; PREFIX/include
--builddir=DIR Build in this location instead of building within the distribution tree. This moves where the sources for the libraries are compiled to before they are installed. Recommended!
--stagedir=DIR When staging only, with the "stage" action, copy to the given location.
Default; ./stage
--without-<library> Do not build, stage, or install the specified library.
--with-<library> Build, stage, or install the specified library. This changes the default from trying to build all possible libraries, to only building the speicfied libraries.
--with-python-root[=PYTHON_ROOT] Build Boost.Python libraries with the Python devel packages located at PYTHON_ROOT. The Boost.Python libraries are built only if the build can find the Python development package at this location.
Default; C:\tools\python on Win32.
Default; /usr/local on Unix, Linux, etc.
Default; /usr on Cygwin.
--with-pydebug Build Boost.Python libraries using the Python debug runtime. This builds an additional set of libraries for use with the debug version of Python. The regular versions of the Boost.Python libraries are also built.

There are additional options as supported by Boost.Build and Boost.Jam. Of the additional options perhaps the most imporant is "-sBUILD=<features/variants>" which lets you override what is built by default. The "<features/variants>" value is a list, separated by spaces, of build requests. Features take the form of a tag and a value or values. And variants are single symbolic names for a collection of features. For example the default is to request "debug release <runtime-link>static/dynamic <threading>single/multi", in which "debug" and "release" are variants, and the rest features with two values each.

If you have some feedback about the build and install process please drop us a line at the Boost.Build mailing list. We are particularly interested if it works for your platform and if it there is anything that you feel could be done better.

Now you need to Tell your compiler and linker about Boost.

Revised 8 November, 2004

Copyright © Rene Rivera 2003.
Copyright © Jens Maurer 2001.
Copyright © John Maddock 2004.

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)