Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.

Home
Libraries
People
FAQ
More

Getting Started

Introduction

These instructions are intended to help you get started using the Boost Libraries. This walks you through getting, building, and installing the libraries. To summarize these are the steps to get Boost built and installed:

  1. Download Boost.
  2. Install Boost.Jam.
  3. Configure your compiler toolset.
  4. Go to Boost distribution directory.
  5. Build and install.

Download

1 The Boost Libraries are distributed through the SourceForge file distribution system. Click here to download releases from SourceForge. And unpack the release to a convenient location.

The Boost release includes all of the libraries and other material from the web site. It is available in ZIP, TAR.GZ, and TAR.BZ2 formats. Past releases are also available.

It is also possible to download current snapshots of work-in-progress from Boost's CVS repository.

.zip file

The .zip format is widely supported by both free decoders and commercial compress/archive utilities. If you don't already have a .zip file decoder, download one from the Info-ZIP web site, which supplies versions for many operating systems.

Text file line endings in the .zip file are as supplied by each library developer.  This works fine for Windows, but not for Unix/Linux.  The .tar.gz and .tar.bz2 files supply Unix/Linux friendly line endings.

.tar.gz and .tar.bz2 files

The .tar.gz format is widely supported on Unix/Linux platforms. Some Windows compress/archive utilities can read the format as well.  Because the gzip format compresses the archive as a single file rather than compressing each file individually, the .tar.gz file is smaller that the .zip file.

The .tar.bz2 format is becoming widely available on Unix/Linux platforms and is built into many tar utilities. This format differs for the .tar.gz format in the compression used, which is considerably better and therefore creates smaller files.

Text file line endings in the .tar.gz and .tar.bz2 files have been converted to newlines for ease of use on Unix/Linux platforms.

Boost CVS Repository

All Boost files, including the entire distribution tree including web site HTML is maintained in a CVS repository. Command line, GUI, or browser access is available.

Boost CVS access via command line or graphical clients

For those who have CVS clients installed, the libraries are also available from the public Boost CVS repository. Free command line clients (often already installed on Linux/Unix systems) are available for many systems, and free GUI clients are available for Windows, Mac, and other systems.

See the much improved CVS documentation (Section F) from SourceForge, which includes links to the home pages for various GUI and command line clients.

The general procedure for command-line clients is something like this:

cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/boost login
[Hit <return> when it asks for a password]
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/boost checkout boost
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/boost logout
Read the manual for your CVS client for further information.

This access is read-only; if you are a library author and wish to have CVS write access, please contact one of the moderators.

Boost CVS access via web Browser

For access to the CVS archive from any modern web browser, you can also use the web browser  interface.  Try one of the color diffs to see how a file has changed over time. Note: this interface is only suitable for viewing individual files and their revision histories.

Documentation generated from BoostBook in CVS

Some of the Boost documentation is generated from BoostBook XML source stored in the CVS repository, and will not appear directly in the CVS tree as readable HTML. View a nightly build of the generated HTML on the Nightly Generated Documentation page. Where generated HTML is missing from the CVS tree, an attempt has been made to include redirection to this nightly build, but if you are away from an internet connection you may want to download the generated documentation archive from the aforementioned page so you can browse those documents offline.

Preparation

The recommended way to build and install the Boost Libraries is to use Boost.Build, the Boost Build system. The rest of these instructions explain that use, but it is up to you to use this method, or not. Note that some of the libraries also include non Boost.Build makefiles and/or project files. But all include the needed files for building with Boost.Build.

2 The build system uses Boost.Jam, an extension of the Perforce Jam portable make replacement. The recommended way to get Boost.Jam if you are using a Boost distribution is to download a prebuilt executable from SourceForge. If a prebuilt executable is not provided for your platform or you are using Boost's sources in an unreleased state, it may be neccessary to build bjam from sources included in the Boost source tree. To install Boost.Jam, copy the bjam executable to a location accessible in your PATH.

Configuring the tools

Before using Boost.Build you will need to configure the compiler tools you are using. The build system's toolsets are designed to work in either of two ways:

  1. The user sets up all of the environment for each toolset he wants to use in the normal way. For example, for Microsoft VC++, ...VC98/Bin or .../VC7/Bin is in the PATH environment variable, VCVARS32.BAT or VSVARS32.BAT has been invoked, etc. For Metrowerks CodeWarrior, cwenv.bat or equivalent has been called and ...Other Metrowerks Tools/Command Line Tools is in the path. Many Unix operating systems come preconfigured this way and require no user intervention.

  2. The user doesn't want his environment cluttered with settings or has nonstandard installations for some of his tools. Instead, he or she sets variables which point to the toolset installation directories, either in the command shell environment or on the bjam command-line. These variables are used by the build system to locate the tools and invoke the necessary setup. To set the variables on the bjam command-line you use the "-s" option. For example:

    bjam "-sGCC_ROOT_DIRECTORY=/usr/local/gcc-3.3.2"

    Some variables, like the toolset TOOLS variable, can accept multiple values separated by spaces. Others, like the path above, can contain spaces. For such circumstances you should use quotes appropriate for your command interpreter.

Supported Toolsets

3 The following toolsets are supported by Boost.Build. For information about configuring each toolset, click its name in the leftmost column.

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.

Build and Install

The common build and install process is driven by the top-level build file (Jamfile).

4

First you need to change to the directory where you have the Boost distribution you downloaded. For example:

chdir boost-1.31.0

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_31" subdirectory, the version will reflect the distribution you are installing.

5 Invoke the build system, specifying the toolset(s) you wish to use, to build and install. For example for GNU/GCC.

bjam "-sTOOLS=gcc" install

Or if you are interested only in the built libraries you can have them built and collected to a common directory without installation.

bjam "-sTOOLS=gcc" stage

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.
--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.

Results

The results of building come in to forms: static libraries, and dynamic libraries. Depending on the platform the libraries produced have different names to accommodate the platform requirements. For a single Boost library the build with the default will produce eight different libraries. For example building the Boost.Datetime library on Unix type system it would produce:

  1. libboost_date_time-gcc-d-1_31.so
  2. libboost_date_time-gcc-mt-d-1_31.so
  3. libboost_date_time-gcc-1_31.so
  4. libboost_date_time-gcc-mt-1_31.so
  5. libboost_date_time-gcc-d-1_31.a
  6. libboost_date_time-gcc-mt-d-1_31.a
  7. libboost_date_time-gcc-1_31.a
  8. libboost_date_time-gcc-mt-1_31.a
· Library Prefix
 
lib
· Library Name
boost_date_time
· Toolset
- gcc
· Threading
- mt
· Runtime
- d
· Boost Version
- 1_31
· Library Type
.a  

Library Prefix

The "lib" prefix on the libraries is a requirement on many platforms, like Unix, and on others like GCC running on Windows. The prefix is therefore added to all libraries on Unix type systems, and to static libraries on Windows. That is on Unix shared libraries and static libraries (object archives) are named respectively:

On Windows shared libraries do not have the prefix to differentiate the import libraries from static libraries. Consequently on Windows the libraries are named:

*.dll Dynamic library version.
*.lib Import library for the dll.
lib*.lib Static library version.

Library Name

For Boost libraries the name has the "boost_" prefix to separate them from other libraries in your system.

Toolset

The toolset name is an abbreviation based on the compiler you are building with. The abbreviation is composed of a short, 2 to 4 characters, tag for the compiler and a version number of the compiler's major and minor revision (if available). For example if your toolset is "gcc-3_2_3" the toolset tag would be "gcc32". The toolset abbreviations used are as follows:

TOOLS Name Abbreviation
borland bcb
como como
como-win32 como
cw cw
darwin osx
dmc dmc
dmc-stlport dmc
edg edg
gcc gcc
gcc-stlport gcc
gcc-nocygwin gcc
intel-linux il
intel-win32 iw
kcc kcc
kylix bck
mingw mgw
mingw-stlport mgw
mipspro mp
msvc vc
msvc-stlport vc
sunpro sw
tru64cxx tru
tru64cxx65 tru
vacpp xlc
vc7 vc
vc7-stlport vc
vc-7_1 vc
vc-7_1-stlport vc
Others The first part of the toolset name.

Threading

This tag indicates if the library is compiled with threading support. If threading is enabled "-mt" is added, otherwise nothing is added.

Runtime

This specifies the type of runtime the library was compiled against, and the type of code that is compiled. More commonly this encodes the ABI variation used in the code. For each feature of the runtime system and code compilation option a single letter is added to this tag.

Key Feature
s Static link to runtime.
g Debug runtime.
y Debug Python system.
d Debug enabled code.
p STLport runtime, instead of the vendor toolset runtime.
n STLport runtime using the "native" IO streams instead of the STLport IO streams.

For example if you compile debug code for STLport using native IO streams, and statically link to the debug runtime the tag would be: "-sgdpn".

Boost Version

This is the short label for the version of the Boost Libraries. The major and minor version numbers are taken together separated by an underscore. For example version 1.31.0 would be tagged as "-1_31". The patch version number is not included because it is assumed that patch versions are upward compatible.

Library Type

The extension holds the type of library. This follows the platform requirements. On Windows this is ".dll" for shared libraries, and ".lib" for static libraries including import libraries. On Unix this is ".a" for static libraries (archives), and ".so" for shared libraries. For toolsets that support it in Unix they will also have a full version extension (for example ".so.1.31.0") with a symbolic link for the un-versioned library.

Automatic Linking on Windows

For most Boost libraries that have separate source, the correct build variant is linked against automatically when you include one of that library's header files.  For this feature to work, your compiler must support the #pragma comment(lib, name) feature (Microsoft Visual C++, Intel C++, Metrowerks C++ , and Borland C++ all support this).

If you are linking to a dynamic runtime, then you can choose to link to either a static or a dynamic Boost library, the default is to do a static link.  You can alter this for a specific library whatever by defining BOOST_WHATEVER_DYN_LINK to force Boost library whatever to be linked dynamically.  Alternatively you can force all Boost libraries to dynamic link by defining BOOST_ALL_DYN_LINK.

This feature can be disabled for Boost library whatever by defining BOOST_WHATEVER_NO_LIB, or for all of Boost by defining BOOST_ALL_NO_LIB.

If you want to observe which libraries are being linked against then defining BOOST_LIB_DIAGNOSTIC will cause the auto-linking code to emit a #pragma message each time a library is selected for linking.

There are some Boost libraries (Boost.Test is one one special case), where automatic linking is not supported for technical reasons: please consult the documentation for each of the libraries you are using for more information, and the Boost.Config documentation for more information on configuration macros.  The following table shows the current supported configurations, (Boost libraries not listed here consist of headers only):

Library Static Link Dynamic Link Default linkage Automatic library selection Comments
Date-Time Yes Yes static Yes  
Filesystem Yes

Yes

static Yes  
Graph Yes No static No The separate Graph library source is needed only when reading an AT&T graphviz file.
Program Options Yes Yes static Yes  
Python Yes Yes dynamic No Since all Python extensions are DLL's it makes sense to dynamic link to the Boost Python library by default (static linking is only really an option if you are embedding python).
Regex Yes Yes static Yes  
Serialisation Yes No static No Automatic linking support will be introduced in a future release.
Signals Yes Yes static Yes  
Test Yes No static No Which library you link to depends upon which program entry point you define, rather than which Boost.Test features you use.
Thread Partial Yes dynamic Yes For technical reasons static linking is supported on only one Windows compiler (Visual C++).

Additional Steps

Depending on your platform and configuration you may need to perform some additional configuration to get Boost to build and install.


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)