Changes between Version 1 and Version 2 of Boost_Build_Standalone


Ignore:
Timestamp:
Sep 4, 2007, 9:06:08 AM (15 years ago)
Author:
Peter Foley
Comment:

Updated content to be finished ready for review by other people (its just missing the screenshots)

Legend:

Unmodified
Added
Removed
Modified

  • Boost_Build_Standalone

    v1 v2  
    1 = IMPORTANT THIS IS CURRENTLY A WORK IN PROGRESS AND MIGHT BE INCORRECT =
     1= How do I run Boost Build standalone from the Boost Software Library =
    22
    3 
    4 
    5 
    6 = How do I run Boost Build standalone from the Boost distribution =
    7 
    8 == Useful Links used throughout this document ==
    9  * Boost Build Homepage - http://www.boost.org/tools/build/index.html
     3== Useful Links ==
     4 * Boost Build Documentation Homepage - http://www.boost.org/tools/build/index.html [[BR]]
    105   This is the authoritative resource for all things related to Boost Build.
    116
    … …  
    2015 * 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
    2116 * This document is written for the Windows platform.  It should be simple enough to substitute platform specific commands or concepts.
    22  * My setup is using Visual Studio 2005
     17 * My setup is using Visual Studio 2005 and the majority of Boost Build messages relate to MSVC.
    2318
    2419== Definitions ==
    25  * BJAM - In the interests of typing less I have shortened Boost.Build to this.
     20 * BJAM - Is a synonym within this document for Boost.Build.
     21
     22== The End State Directory Structure ==
     23
     24To 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:
     25
     26????? Include Attachment here (000 - End State.PNG)
     27
     28=== Explanation of Directories ===
     29
     30The 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)
     32  * 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.
     36   * 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"
     37   * 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"
     38   * 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.
     40
     41=== Explanation of Important files ===
     42
     43There 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.
     44
     45==== boost-build.jam ====
     46
     47For 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.
     48
     49BJAM 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.
     50
     51==== site-config.jam and user-config.jam ====
     52
     53You 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.
     54
     55For 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
     56
    2657
    2758== Compiling BJAM ==
    2859
    29 1. Since BJAM is fairly stable I advise downloading the latest nightly build of BJAM. 
     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).
    3061
    31 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).
     62For 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).
    3263
    33 ????? Include Attachment here (001 - Extraction Location.PNG)
    34 
    35 2. I then followed the build documentation provided at http://www.boost.org/doc/html/bbv2/installation.html.
     64'''2.''' I then followed the build documentation provided at http://www.boost.org/doc/html/bbv2/installation.html.
    3665
    3766A brief synopsis is as follows:
    38  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")
    39  ii) Navigate to the jam source location (for me this was "E:\dev\tools\boost-build\jam_src")
    40  iii) Execute the build.bat file
     67 '''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")[[BR]]
     68 '''ii)''' Navigate to the jam source location (for me this was "E:\dev\tools\boost-build\jam_src")[[BR]]
     69 '''iii)''' Execute the build.bat file[[BR]]
    4170
    42 At the completion of the above steps you should now have two new folders within the jam_src folder (namely "bootstrap" and "bin.ntx86")
    4371
    44 ????? Include Attachment here (002 - After Compiling Two new folders.PNG)
    45 
    46 BJAM has now been built.
     72On 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.
    4773
    4874== Setting up BJAM for use ==
    4975
    50 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:
     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:
    5177
    52  i) mkdir ..\..\..\bjam\bin
    53  ii) copy bjam.exe ..\..\..\bjam\bin
     78 '''i)''' mkdir e:\dev\tools\bjam\bin[[BR]]
     79 '''ii)''' copy bjam.exe e:\dev\tools\bjam\bin[[BR]]
    5480
    55 ????? Include Attachment here (003 - Copy BJAM to BIN.PNG)
     81'''4.''' Navigate to the "E:\dev\tools\bjam\bin" directory and execute "bjam.exe"
    5682
    57 I also like to keep things neat so I also delete the "bootstrap" and bin.ntx86" folders as they are no longer needed.
    58 
    59 4. Navigate to the bjam\bin directory and execute bjam.exe
    60 
    61 As you can see from the output of the command bjam.exe is complaining that it cannot find the "boost-build.jam" file
     83As you can see from the output of the command BJAM is complaining that it cannot find the "boost-build.jam" file
    6284
    6385????? Include Attachment here (004 - BJAM installed output.PNG)
    6486
    65 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".
     87To 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\".
    6688
    67 Next edit the "boost-build.jam" file you just copied and change it to read: "boost-build E:/dev/tools/boost-build ;".
     89Next 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)
    6890
    69 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.
     91At 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.
    7092
    71 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). 
     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]]
     95 '''ii)''' set BOOST_BUILD_PATH=E:\dev\tools\bjam\070903-nightly[[BR]]
     96
     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). 
    7298
    7399????? Include Attachment here (005 - BJAM with boost_build.PNG)
    74100
    75 Congratulations although it does not look like it you now have an almost working standalone installation of bjam!
     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.
    76104
    77 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:
    78  i) Add the directory that bjam.exe is located to the PATH environment variable; and
    79  ii) Called the VCVARS.bat file (which is the Visual Studio 2005 Command Prompt).
     105Congratulations 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.
    80106
    81 Without doing anything else BJAM will automajically do the right thing if I run it from a directory with a jamfile.
     107'''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:
     108 '''i)''' mkdir e:\dev\src\hello[[BR]]
     109 '''ii)''' copy E:\dev\tools\boost-build\example\hello e:\dev\src\hello\[[BR]]
     110 '''iii)''' cd e:\dev\src\hello[[BR]]
     111 '''iv)''' bjam[[BR]]
    82112
    83 Before we talk about configuring the toolsets that BJAM we should set
     113You should see:
     114
     115????? Include Attachment here (007 - compile hello with warnings.PNG)
     116
     117To get rid of the warning messages re-run bjam but specify the toolset by passing it the toolset parameter.
     118 '''v)''' bjam --toolset=msvc
     119
     120You should now see:
     121
     122
     123????? Include Attachment here (007 - compile hello without warnings.PNG)
     124
     125== Outstanding work left to the reader ==
     126
     127The only outstanding items are:
     128 * Create a batch file(s) to automatically setup the Standalone version of BJAM (ie setup the path and BOOST_BUILD_PATH) environment variables);
     129 * Setup the "site-config.jam" and/or "user-config.jam" files