![]() |
|
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:
random_device
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.
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.
bjam
toolIn 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.
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.)
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.)
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:
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 "-sTOOLS=toolset" install
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.
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)