# Installation

This section describes how to install Boost.Build from a released Boost source distribution or CVS image. Note that packages prepared for Unix/Linux systems usually make their own choices about where to put things and even which parts of Boost to include. When we say “released source distribution” we mean a distribution of Boost as released on its SourceForge project page. All paths are given relative to the Boost.Build v2 root directory, which is

located in the `tools/build/v2` subdirectory of a full Boost distribution. The Boost.Build subset of boost is also distributed separately, for those who are only interested in getting a build tool. The top-level directory of a Boost.Build distribution contains all the subdirectories of the `tools/build/v2` subdirectory from a full Boost distribution, so it is itself a valid Boost.Build root directory. It also contains the `tools/jam/src` subdirectory of a full Boost distribution, so you can rebuild Boost.Jam from source.

1. Boost.Build uses Boost.Jam, an extension of the Perforce Jam portable `make` replacement. The recommended way to get Boost.Jam 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 necessary to build `bjam` from sources included in the Boost source tree.

2. To install Boost.Jam, copy the executable, called `bjam` or `bjam.exe` to a location accessible in your `PATH`. Go to the Boost.Build root directory and run `bjam `--version``. You should see:

                   Boost.Build V2 (Milestone N)
                   Boost.Jam xx.xx.xx

   where N is the version of Boost.Build you're using.

3. Configure Boost.Build to recognize the build resources (such as compilers and libraries) you have installed on your system. Open the `user-config.jam` file in the Boost.Build root directory and follow the instructions there to describe your toolsets and libraries, and, if necessary, where they are located.

4. You should now be able to go to the `example/hello/` directory and run `bjam` there. A simple application will be built. You can also play with other projects in the `example/` directory.

If you are using Boost's CVS state, be sure to rebuild `bjam` even if you have a previous version. The CVS version of Boost.Build requires the CVS version of Boost.Jam.

When `bjam` is invoked, it always needs to be able to find the Boost.Build root directory, where the interpreted source code of Boost.Build is located. There are two ways to tell `bjam` about the root directory:

- Set the environment variable `BOOST_BUILD_PATH` to the absolute path of the Boost.Build root directory.

- At the root directory of your project or in any of its parent directories, create a file called `boost-build.jam`, with a single line:

      boost-build /path/to/boost.build ;

Information for distributors

If you're planning to package Boost.Build for a Linux distribution, please follow these guidelines:

- Create a separate package for Boost.Jam.

- Create another package for Boost.Build, and make this package install all Boost.Build files to `/usr/share/boost-build` directory. After install, that directory should contain everything you see in Boost.Build release package, except for `jam_src` directory. If you're using Boost CVS to obtain Boost.Build, as opposed to release package, take everything from the `tools/build/v2` directory. For a check, make sure that `/usr/share/boost-build/boost-build.jam` is installed.

  Placing Boost.Build into `/usr/share/boost-build` will make sure that `bjam` will find Boost.Build without any additional setup.

- Provide a `/etc/site-config.jam` configuration file that will contain:

      using gcc ;

  You might want to add dependency from Boost.Build package to gcc, to make sure that users can always build Boost.Build examples.

If those guidelines are met, users will be able to invoke `bjam` without any explicit configuration.