# Building Boost Libraries

Introduction
Preliminaries
Building Boost Libraries
Configuring the tools
Supported Toolsets
Boost.Jam executable

## Introduction

These instructions explain how to accomplish common tasks using Boost.Build, the Boost Build System. The build system uses Boost.Jam, an extension of the Perforce Jam portable make replacement.

For tasks not covered here, see the full build system documentation.

Note that many Boost libraries are implemented entirely within their headers, and so can be used without building object libraries. Libraries that do require building object libraries first include the Python, Regex, and Threads libraries.

## Preliminaries

- Download Boost, and unpack the full directory structure into some root directory.
- Install the Boost.Jam executable if needed. Pre-builts are available. Make sure it's in your path. (Note: Boost requires an enhanced version of Jam; the basic version won't work.)
- Configure the command-line toolset(s) you intend to use. It might be a good idea to verify your command line compiler is working if you don't use it regularly.
- Optional: if you intend to build the Boost.Python library, set environment variables to configure Boost.Build for your Python installation. For more information, see these instructions. If you leave this step out, Boost.Build will print a message about how to do it, and will skip the build for Boost.Python.

## Building Boost Libraries

Using your operating system's command line interpreter, execute the following steps. The sample commands given will work for both UNIX and Windows.

- Change to the Boost root directory. (The directory you unpacked the distribution into; unless you changed it, the name will be boost_n_n_n where n_n_n is the release number. Among others files, it contains c++boost.gif, and subdirectories boost, libs, more, etc.)

  > `chdir boost_1_28_0` (or whatever release you downloaded)

- Invoke the build system, specifying the toolset(s) you wish to use. The example is for the GNU and Metrowerks compilers. For more sophisticated jam invocation options, see this documentation.

  > `bjam "-sTOOLS=gcc metrowerks"`

## Configuring the tools

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

## Supported Toolsets

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 Windows, using Microsoft Visual C++as a back-end.
`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, using the STLport standard library implementation (produces commercially redistributable objects)
`intel-win32` | Intel C++ for Windows using the Dinkumware standard library in the Intel-required Microsoft Visual C++ 6 or 7 installation
`intel-linux` | Intel C++ for Linux
`kcc` | KAI C++
`metrowerks` | Metrowerks CodeWarrior command-line tools
`mingw` | GNU GCC and associated tools in MinGW configuration (produces commercially redistributable objects)
`mipspro` | SGI MIPSpro C and C++
`mipspro` | SGI MIPSpro C and C++
`msvc` | Microsoft Visual C++ command-line tools.
`msvc-stlport` | Microsoft Visual C++ command-line tools, using the STLport standard library implementation
`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, in case you are using the `msvc` toolset for a Visual C++ 6.x.

Unless otherwise specified, the library is assumed to be the one shipped with the compiler.

Additional tools can be supplied by adding an appropriate xxxx-tools.jam file to the tools/build subdirectory, where xxxx is the name of the tool being added. If you write an additional toolset file, please submit it to Boost so others may benefit from your work.

## Boost.Jam executable

Pre-built Boost.Jam executables are available for the following platforms:

- HPUX
- IBM Aix
- Linux-x86
- Microsoft Windows
- SGI Irix
- SUN Solaris
- Compaq Tru64
- Linux-PPC

RedHat Linux RPM packages are available:

- Boost.Jam rpm
- Boost.Jam source rpm

The Boost.Jam source files are included in the Boost distribution, so you can build the Boost.Jam executable yourself:

- For most Unix variants, you can build Boost.Jam by simply invoking `make` in the `tools/build/jam_src` subdirectory of your boost installation.
- Build Instructions are the same as for "Classic Jam", if you need them.
- Your new Boost.Jam executable will be located in a newly-created `tools/build/jam_src/bin.`platform subdirectory.
- There will be two executables generated: `"jam"`, and `"bjam"`. They are in fact a copy of the same binary. The `"bjam"` invocation uses the newer simpler build behaviour. But if you need the traditional Jam/MR behaviour you can use the `"jam"` invocation.
- If you build Boost.Jam for a new platform using the same boost installation, be sure to first remove all object files, executables, and libraries created by the initial make in the `jam_src` directory.

Revised 15 May, 2002

© Copyright 2001 Beman Dawes