Changes between Version 3 and Version 4 of Boost_Build_Standalone


Ignore:
Timestamp:
Sep 17, 2007, 1:37:26 PM (15 years ago)
Author:
Peter Foley
Comment:

Update the document based on feedback from the Boost.Build news group

Legend:

Unmodified
Added
Removed
Modified

  • Boost_Build_Standalone

    v3 v4  
    1515 * 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
    1616 * This document is written for the Windows platform.  It should be simple enough to substitute platform specific commands or concepts.
    17  * My setup is using Visual Studio 2005 and the majority of Boost Build messages relate to MSVC.
     17 * I used Visual Studio 2005 and the majority of Boost Build messages relate to MSVC the toolset.
    1818
    1919== Definitions ==
    20  * BJAM - Is a synonym within this document for Boost.Build.
     20 * 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.
     21 * BJAM - Is a derivative of the JAM language.  The Boost.Build system is interpreted and processed by BJAM to do its work.
     22
     23== Handy or Important Tips ==
     24
     25=== Environment Variables ===
     26 * ""BOOST_BUILD_PATH"" - This environment variable points to the root directory of where the Boost.Build system is located.
     27 * ""BOOST_BUILD_USER_CONFIG"" - This environment variable points to the location of your user-config.jam.
     28
    2129
    2230== The End State Directory Structure ==
    … …  
    2937
    3038The 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:
    31  * src - This the location of the source code that will be compiled by BJAM.  (Hint: This can be located anywhere on your file system)
     39 * src - This the location of your source code that you will configure Boost.Build to compile.
    3240  * hello - This is a copy of the hello folder sample that comes with Boost Build it contains two files "hello.cpp" and "jamroot".
    33  * tools - This folder contains various tools that I use.  Within this folder I have:
    34   * bjam - This is the folder I have created to store the necessary information for BJAM to run standalone
    35    * bin - I have a copy of the BJAM executable located within this folder.
     41 * tools - This folder contains various development tools that I use.  Within this folder I have:
     42  * 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.
     43   * bin - This directory contains a compiled version of the BJAM executable.
    3644   * 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"
    3745   * 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"
    3846   * 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"
    39   * boost_build - This is where I have extracted the BJAM Nightly snapshot.
     47  * boost_build - This is where I have extracted the Boost.Build System Nightly snapshot.
     48
     49""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.
    4050
    4151=== Explanation of Important files ===
    4252
    43 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.
     53There 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.
    4454
    4555==== boost-build.jam ====
    4656
    47 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.
     57For 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.
    4858
    49 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.
     59Possible 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.
     60
     61For this example I will be setting up the "BOOST_BUILD_PATH" environment variable which points to my "boost-build.jam" file.
    5062
    5163==== site-config.jam and user-config.jam ====
    5264
    53 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.
     65You 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.
    5466
    55 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
     67Possible 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.
     68
     69For this example I will be setting up the "BOOST_BUILD_USER_CONFIG" environment variable which points to my "user-config.jam" file.
    5670
    5771
    5872== Compiling BJAM ==
    5973
    60 '''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).
     74'''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).
    6175
    62 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).
     76For 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).
    6377
    6478'''2.''' I then followed the build documentation provided at http://www.boost.org/doc/html/bbv2/installation.html.
    … …  
    7488== Setting up BJAM for use ==
    7589
    76 '''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:
     90'''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:
    7791
    7892 '''i)''' mkdir e:\dev\tools\bjam\bin[[BR]]
    7993 '''ii)''' copy bjam.exe e:\dev\tools\bjam\bin[[BR]]
    8094
    81 '''4.''' Navigate to the "E:\dev\tools\bjam\bin" directory and execute "bjam.exe"
    82 
    83 As you can see from the output of the command BJAM is complaining that it cannot find the "boost-build.jam" file
     95If 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.
    8496
    8597[[Image(004_ bjam_installed_output.PNG)]]
    8698
    87 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\".
     99We have one final step prior to moving onto the configuration of the Boost.Build system.
    88100
    89 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)
     101'''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 :
     102 '''i)''' set path=%path%;E:\dev\tools\bjam\bin[[BR]]
     103
     104
     105== Setting up Boost.Build for use ==
     106
     107Now 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").
     108
     109For 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\".
     110
     111I then edited the file and updated it to read: "boost-build E:/dev/tools/boost-build ;".
     112(""IMPORTANT:"" Ensure that there is one whitespace before the semi-colon at the end of the line!)
    90113
    91114At 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.
    92115
    93 '''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:
    94  '''i)''' set path=%path%;E:\dev\tools\bjam\bin[[BR]]
     116Now 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:
     117
    95118 '''ii)''' set BOOST_BUILD_PATH=E:\dev\tools\bjam\070903-nightly[[BR]]
    96119
    97 '''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). 
     120'''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). 
    98121
    99122[[Image(006_bjam_with_boost_build.PNG)]]
    100123
    101 '''Note:'''  The warnings and error message are safe to ignore.  In this instance BJAM is:
    102  * Warning you that it does not know what toolset to use and is going to default to using MSVC (Microsoft Visual C++) toolset; and
    103  * Providing an error stating that it cannot find a jamfile which would tell BJAM what to compile/build.
     124'''Note:'''  The warnings and error message are safe to ignore.  In this instance the Boost.Build system is telling you:
     125 * 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
     126 * 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.
    104127
    105 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.
     128Congratulations 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.
    106129
    107130'''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:
    … …  
    125148
    126149The only outstanding items are:
    127  * Create a batch file(s) to automatically setup the Standalone version of BJAM (ie setup the path and BOOST_BUILD_PATH) environment variables);
    128  * Setup the "site-config.jam" and/or "user-config.jam" files
     150 * 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);
     151 * Setup the "site-config.jam" and/or "user-config.jam" files to support your toolsets (compiler(s), linker(s) and other supported types)