# Building Boost Libraries

Read This First!

Boost.Build is fairly new as yet. Some features are missing or incomplete. Instructions for accomplishing basic tasks (this page) are rudimentary. But enough functionality is working well to make using Boost.Build worthwhile. The important bits-and-pieces are all there - what's left is some of the relatively minor glue to make the system smooth and easy to use. Secondary tasks like copying libraries to installation specific directories are weak.

If there isn't a configuration file (see Tools) available for your favorite compiler, consider contributing one.

Note that the underlying Boost.Jam build engine is mature software, and the original Jam build engine has been widely used for many years. The Boost specific extensions are well on their way to becoming stable, and have begun to attract interest and use outside of Boost.

Introduction
Preliminaries
Building Boost Libraries
More on using the tools
Tools available
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 Boost Python, Regular Expression, and Thread 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.)
- Set any environment variables required to run your compiler and related tools from the command line. (It might be a good idea to verify your command line compiler is working if you don't use it regularly.) If you don't want to clutter your environment, see More on using the tools for alternatives.

## 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. Among others, it contains the file c++boost.gif, and subdirectories boost, libs, more, etc.)

> `chdir my_boost`

- Build the Boost libraries for your tools. The example is for the GNU and Metrowerks compilers.

> `jam -sBOOST_ROOT=. -sTOOLS="gcc metrowerks"`

- If you don't want to specify `BOOST_ROOT` on the command-line, you can instead set the `BOOST_ROOT` environment variable (an absolute path is recommended).

## More on using 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.
2. The user doesn't want his environment cluttered with this junk and wants to avoid the many other things done by the vendor's script files. Instead, he or she sets variables which point to the toolset installation directories (possibly in the Jamrules, or a user-setup.jam file invoked by the Jamrules). These variables are used by the build system to locate the tools and invoke the necessary setup. They are described in the comments in each toolset's .jam file.

## Tools available

TOOLS Name | Description
`borland` | Borland command line compiler tools
`como` | Comeau command line compiler tools
`gcc` | GNU GCC command line compiler tools
`gcc-stlport` | GNU GCC command line compiler tools, using the STLport library
`intel-win32` | Intel command line compiler tools under Win32 using the Microsoft library
`intel-linux` | Intel command line compiler tools under Linux
`kcc` | KAI command line compiler tools
`metrowerks` | Metrowerks CodeWarrior command line compiler tools
`msvc` | Microsoft Visual C++ command line compiler tools
`msvc-stlport` | Microsoft Visual C++ command line compiler tools, using the STLport library
`vacpp` | IBM Visual Age C++ command line compiler tools

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:

- IBM Aix
- Linux-x86
- Microsoft Windows (includes Boost.Build files and boost-build helper program).
- SGI Irix
- SUN Solaris

RedHat Linux RPM packages are available:

- Boost.Jam rpm
- Boost.Build rpm
- Boost.Jam source rpm
- Boost.Build 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.
- 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 28 November, 2001

© Copyright 2001 Beman Dawes