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.
• My setup is using Visual Studio 2005 and the majority of Boost Build messages relate to MSVC.

Definitions

• BJAM - Is a synonym within this document for Boost.Build.

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:

????? Include Attachment here (000 - End State.PNG)

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 the source code that will be compiled by BJAM. (Hint: This can be located anywhere on your file system)
  • 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 tools that I use. Within this folder I have:
  • bjam - This is the folder I have created to store the necessary information for BJAM to run standalone
    • bin - I have a copy of the BJAM executable located within this folder.
    • 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 BJAM Nightly snapshot.

Explanation of Important files

There are several files that BJAM 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 BJAM to work outside of the Boost Software Library the BJAM executable ("bjam.exe") needs to be able to locate the Boost Build system files. To do this it needs the "boost-build.jam", this file will tell the BJAM executable where to find other files that BJAM requires to interpret the Jamfile's that you create.

BJAM looks for this file in 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.

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 BJAM. As each filename suggests the "site-config.jam" file is for site wide settings and the "user-config.jam" is for user specific settings.

For simplicity within this document I am going to assume that this files are stored in the same location as the "boost-build.jam" file. For more information on the search locations for these files or what types of information these files can contain please check http://www.boost.org/doc/html/bbv2/reference.html

Compiling BJAM

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

For convenance within this document my location of the Boost Build system is "E:\dev\tools\boost_build" (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 more easily allow for using BJAM against stable or development toolsets I recommend moving the BJAM executable to a seperate location. I have create a folder "e:\dev\tools\bjam\bin" and moved "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

4. Navigate to the "E:\dev\tools\bjam\bin" directory and execute "bjam.exe"

As you can see from the output of the command BJAM is complaining that it cannot find the "boost-build.jam" file

????? Include Attachment here (004 - BJAM installed output.PNG)

To fix this error we need to let BJAM know where the Boost Build directory is with the information it needs to be able to run. To do this copy the "boost-build.jam" file from "E:\dev\tools\boost-build" to "E:\dev\tools\bjam\070903-nightly\".

Next edit the "boost-build.jam" file you just copied and change it to read: "boost-build E:/dev/tools/boost-build ;". (IMPORTANT: Ensure that there is one whitespace before the semi-colon)

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.

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 and add a new environment variable (BOOST_BUILD_PATH). Run these commands:

i) set path=%path%;E:\dev\tools\bjam\bin
ii) set BOOST_BUILD_PATH=E:\dev\tools\bjam\070903-nightly

6. To ensure that bjam is behaving correctly navigate to the bin directory you have just created and execute "bjam -v" (which should give you the version and copyright notices) and "bjam" (which should provide some warnings and an error).

????? Include Attachment here (005 - BJAM with boost_build.PNG)

Note: The warnings and error message are safe to ignore. In this instance BJAM is:

• Warning you that it does not know what toolset to use and is going to default to using MSVC (Microsoft Visual C++) toolset; and
• Providing an error stating that it cannot find a jamfile which would tell BJAM what to compile/build.

Congratulations although it does not look like it you now have an almost working standalone installation of bjam! 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:

????? Include Attachment here (007 - compile hello with warnings.PNG)

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:

????? Include Attachment here (007 - compile hello without warnings.PNG)

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) environment variables);
• Setup the "site-config.jam" and/or "user-config.jam" files