IMPORTANT THIS IS CURRENTLY A WORK IN PROGRESS AND MIGHT BE INCORRECT

How do I run Boost Build standalone from the Boost distribution

Useful Links used throughout this document

• Boost Build 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

Definitions

• BJAM - In the interests of typing less I have shortened Boost.Build to this.

Compiling BJAM

1. Since BJAM is fairly stable I advise downloading the latest nightly build of BJAM.

Regardless of the version you use as long as you can find the location of the source code for BJAM the following steps should work. Once you have your copy of BJAM extract the file to a location of your choice. For documentation convenance I have extracted it to "E:\dev\tools\boost_build" (Please be aware to adjust the folder paths I supply to reflect the location you have extracted your files to).

????? Include Attachment here (001 - Extraction Location.PNG)

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

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

????? Include Attachment here (002 - After Compiling Two new folders.PNG)

BJAM has now been built.

Setting up BJAM for use

3. Hopefully 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 move the BJAM executable to a seperate location. To do this I create a e:\dev\tools\bjam\bin directory and then move bjam.exe to this location. To do this I run these commands:

i) mkdir ..\..\..\bjam\bin ii) copy bjam.exe ..\..\..\bjam\bin

????? Include Attachment here (003 - Copy BJAM to BIN.PNG)

I also like to keep things neat so I also delete the "bootstrap" and bin.ntx86" folders as they are no longer needed.

4. Navigate to the bjam\bin directory and execute bjam.exe

As you can see from the output of the command bjam.exe 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.exe 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".

Next edit the "boost-build.jam" file you just copied and change it to read: "boost-build E:/dev/tools/boost-build ;".

At this point it is useful explaining why I have seperated the "bjam.exe" file 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 Boost Subversion repository and update the "boost-build.jam" file located within "E:\dev\tools\bjam" to point to the new boost build root and everything will work.

5. 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)

Congratulations although it does not look like it you now have an almost working standalone installation of bjam!

6. At this point to use BJAM anywhere all you need to do is include the bjam.exe in your PATH environment variable. I personally have created a batch file that will: i) Add the directory that bjam.exe is located to the PATH environment variable; and ii) Called the VCVARS.bat file (which is the Visual Studio 2005 Command Prompt).

Without doing anything else BJAM will automajically do the right thing if I run it from a directory with a jamfile.

Before we talk about configuring the toolsets that BJAM we should set