. Home . Libraries . People . FAQ . More

Getting Started

• Introduction
• Download
  • .zip file
  • .tar.gz and .tar.bz2 files
  • Boost CVS Repository
• Preparation
  • Configuring the tools
  • Supported Toolsets
• Build and Install
• Results
• Additional Steps

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

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.

.zip file

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

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.boost.sourceforge.net:/cvsroot/boost login
[Hit <return> when it asks for a password]
cvs -z3 -d:pserver:anonymous@cvs.boost.sourceforge.net:/cvsroot/boost checkout boost
cvs -d:pserver:anonymous@cvs.boost.sourceforge.net:/cvsroot/boost logout

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

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.

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 is in the path, vcvars32.bat or equivalent 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=/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 circumstancesyou should use quotes appropriate for your command interpreter.
   

Supported Toolsets

Build and Install

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

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.

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]

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/multiple", 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

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:

• lib*.so
• lib*.a

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
• *.lib
• lib*.lib

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:

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.

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.

Additional Steps

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

• Configure the boost source code. This step should not be required on the vast majority of platforms, but if you're trying to build Boost on an untested or unsupported platform it may be necessary.
  
  
• If Boost.Build has problems detecting your Python installation it will print a short messages about how to configure for finding the Python installation. For more information, see these detailed instructions.

Revised 1 December, 2003

Copyright © Rene Rivera 2003.
Copyright © Jens Maurer 2001.

Use, modification, and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)