How do I run Boost Build standalone from the Boost Software Library

Useful Links

• Boost Build Documentation Homepage - http://www.boost.org/tools/build/index.html
  This is the authoritative resource for all things related to Boost Build.

• Boost Build Nightly Build Snapshot
  • Zip - ​http://boost.org/boost-build2/boost-build.zip
  • tar.bz2 - ​http://boost.org/boost-build2/boost-build.tar.bz2

• Boost Build documentation - http://www.boost.org/doc/html/bbv2.html

Assumptions

• Throughout this document I will be using the "3 September 2007" file downloaded from the Nightly Build link from http://www.boost.org/tools/build/v2/index.html
• This document is written for the Windows platform. It should be simple enough to substitute platform specific commands or concepts.
• I used Visual Studio 2005 and the majority of Boost Build messages relate to MSVC the toolset.

Definitions

• Boost.Build - The Boost.Build system is a power build system that supports building complex targets (for example exe's, pdf's, ...) from a variety of sources.
• BJAM - Is a derivative of the JAM language. The Boost.Build system is interpreted and processed by BJAM to do its work.

Handy or Important Tips

Environment Variables

• ""BOOST_BUILD_PATH"" - This environment variable points to the root directory of where the Boost.Build system is located.
• ""BOOST_BUILD_USER_CONFIG"" - This environment variable points to the location of your user-config.jam.

The End State Directory Structure

To help readers of this document better understand what is occurring I will first explain what my expected end state will look like. Obviously in the interests of keeping this document simple this directory structure is very rudimentary but it should provide you with the essentials to come up with something that you can use within your environment. The below screen shot shows my final directory structure:

Explanation of Directories

The directories that I have created for the purpose of this document are located within the "E:\dev" directory. As you can see from the screen shot there are two sub-folders, their purposes are:

• src - This the location of your source code that you will configure Boost.Build to compile.
  • hello - This is a copy of the hello folder sample that comes with Boost Build it contains two files "hello.cpp" and "jamroot".
• tools - This folder contains various development tools that I use. Within this folder I have:
  • bjam - This is the folder I have created to store the compiled BJAM binaries that will be used to invoke the Boost.Build system. Sub-directories within this directory will provide pointers to the location of the Boost.Build system.
    • bin - This directory contains a compiled version of the BJAM executable.
    • 070903-nightly - This contains a copy of the "boost-build.jam" (this points to the 3rd of September 2007 nightly build of the Boost Build System), "site-config.jam" and "user-config.jam"
    • boost-1.34.1 - This contains a copy of the "boost-build.jam" (this points to the Boost Build System that came with the 1.34.1 release of Boost on my file system), "site-config.jam" and "user-config.jam"
    • svn-trunk - This contains a copy of the "boost-build.jam" (this points to a checked out version of the Boost Software Library Build System on my file system), "site-config.jam" and "user-config.jam"
  • boost_build - This is where I have extracted the Boost.Build System Nightly snapshot.

""IMPORTANT NOTE:"" Please be aware that Boost.Build relies on the BJAM executable to interpret the Boost.Build code. Any time bug fixes or additions to the BJAM source code occur you must compile a new version of the BJAM executable.

Explanation of Important files

There are several files that you need to configure which are specific to your environment that Boost.Build requires in order for it to do its job. The below sections are a brief synopsis of some of the information located at http://www.boost.org/doc/html/bbv2/reference.html if there is any confusion the information at the URL is the authoritative source.

boost-build.jam

For Boost.Build to work outside of the Boost Software Library the BJAM executable ("bjam.exe") needs to be able to locate the Boost Build system files. The BJAM executable checks a number of locations until it finds a "boost-build.jam" file. Once found BJAM can interpret the Boost.Build systems files which will in turn process the jamfiles that you create.

Possible locations that BJAM checks for this file include - the current directory, traverses from the current directory to the root directory or it looks at the location specified by the "BOOST_BUILD_PATH" environment variable.

For this example I will be setting up the "BOOST_BUILD_PATH" environment variable which points to my "boost-build.jam" file.

site-config.jam and user-config.jam

You can use these files to convey information about your environment and/or the toolsets (compilers or other tools) you have installed on your system to the Boost.Build system. As each filename suggests the "site-config.jam" file is for site wide settings and the "user-config.jam" is for user specific settings.

Possible locations that BJAM checks for these files include - the current directory, traverses from the current directory to the root directory or it looks at the location specified by the "BOOST_BUILD_USER_CONFIG" environment variable.

For this example I will be setting up the "BOOST_BUILD_USER_CONFIG" environment variable which points to my "user-config.jam" file.

Compiling BJAM

1. Since the JAM source code that BJAM is built off is rarely changed (and stable) I advise downloading the latest nightly build of of the BJAM source (see Useful links at the top of this page for the URL).

For convenance within this document the location I have downloaded and extracted this file to is "E:\dev\tools\boost_build" (If you use a different location please be aware to adjust the folder paths I supply to reflect the location you have the Boost Build System).

2. I then followed the build documentation provided at http://www.boost.org/doc/html/bbv2/installation.html.

A brief synopsis is as follows:

i) Open a command prompt that sets the necessary environment to run your compiler from the command line (for me this was the "Visual Studio 2005 Command Prompt")
ii) Navigate to the jam source location (for me this was "E:\dev\tools\boost-build\jam_src")
iii) Execute the build.bat file

On completion of the above steps you should now have two new folders within the jam_src folder (namely "bootstrap" and "bin.ntx86") BJAM has now been built.

Setting up BJAM for use

3. After step 2 you should now have a compiled version of BJAM located within the "bin.ntx86" directory. To allow for easier choice over what version of the Boost.Build system I use (stable, development or a special local version) I move the BJAM executable to a separate location. I have create a folder "e:\dev\tools\bjam\bin" and moved the "bjam.exe" into it. To do this I run these commands:

i) mkdir e:\dev\tools\bjam\bin
ii) copy bjam.exe e:\dev\tools\bjam\bin

If you invoke BJAM at this point (Navigate to the "E:\dev\tools\bjam\bin" directory and execute "bjam.exe") you will find that BJAM complains that it cannot find the "boost-build.jam" file.

We have one final step prior to moving onto the configuration of the Boost.Build system.

5. Now we need to setup BJAM to be able to run anywhere on your file system. To do this we need to update the path environment variable :

i) set path=%path%;E:\dev\tools\bjam\bin

Setting up Boost.Build for use

Now that BJAM has been compiled and configured to run from anywhere on the file system we need to configure Boost.Build. To do this we need to setup two files ("boost-build.jam" and "user-config.jam").

For the Boost.Build system to work we need to inform BJAM where it can find the Boost.Build system files. To resolve this issue I copied the "boost-build.jam" file from "E:\dev\tools\boost-build" to "E:\dev\tools\bjam\070903-nightly\".

I then edited the file and updated it to read: "boost-build E:/dev/tools/boost-build ;". (""IMPORTANT:"" Ensure that there is one whitespace before the semi-colon at the end of the line!)

At this point it is useful explaining why I have separated the "bjam.exe" and the "boost-build.jam" files. To provide some sanity with my development environment I periodically download the nightly snapshot (maybe once every quarter or bug fix I need). If I am planning to migrate to a newer nightly build or want to test against the trunk of the Boost Software Library I just need to download the latest sources from the Boost Subversion repository and update a single environment variable to point to the new Boost Build root and everything will work.

Now that I have a configured "boost-build.jam" file we need to tell BJAM how to find it. To do this we add a new environment variable (BOOST_BUILD_PATH): Run these commands:

ii) set BOOST_BUILD_PATH=E:\dev\tools\bjam\070903-nightly

6. To check that the Boost.Build system is behaving correctly navigate to the BJAM bin directory and execute "bjam -v" (which should give you the version and copyright notices for BJAM) and "bjam" (which should provide some warnings and an error).

Note: The warnings and error message are safe to ignore. In this instance the Boost.Build system is telling you:

• That Boost.Build does not know what toolset to use and it will use the default which is the MSVC (Microsoft Visual C++) toolset; and
• It is providing you with an error message stating that it cannot find a jamfile which would tell the Boost.Build system what it needs to do to compile/build your source code.

Congratulations although it does not look like it you now have an almost working standalone installation of the Boost.Build System! The only outstanding steps are to configure either the "site-config.jam" or "user-config.jam" file for your environment.

7. To confirm this fact copy the hello directory sample out of the Boost Build examples directory to the "E:\dev\src" directory and run BJAM from within the hello example directory by using these commands:

i) mkdir e:\dev\src\hello
ii) copy E:\dev\tools\boost-build\example\hello e:\dev\src\hello\
iii) cd e:\dev\src\hello
iv) bjam

You should see:

To get rid of the warning messages re-run bjam but specify the toolset by passing it the toolset parameter.

v) bjam --toolset=msvc

You should now see:

Outstanding work left to the reader

The only outstanding items are:

• Create a batch file(s) to automatically setup the Standalone version of BJAM (ie setup the path and BOOST_BUILD_PATH and BOOST_BUILD_USER_CONFIG) environment variables);
• Setup the "site-config.jam" and/or "user-config.jam" files to support your toolsets (compiler(s), linker(s) and other supported types)