Boost Build


This is a natural choice for a boost library. And any library currently accepted into Boost must include Bjam script files. It's got some good features:

  • It's very powerful - basically can be scripted to do just about anything related to build and test.

  • Once it's properly set up, it works well.

  • It includes support for most all C++ environments.

  • Bjam developers are always available to help users set this up.

And some not so good features:

  • Building and Testing of libraries is driven by a special file - Jamfile.v2 - which includes information of the source code modules, composition of modules and tests. Specification of this file requires understand a whole new language as well as understanding a large range of macro commands. It's quite a lot to learn just to be able to build/test a small library.

  • It's not obvious how to use it when building a project which is not a member of the boost tree. I eventually discovered how to do this, but it frustrated me when I was experimenting with this.

  • The standard testing of boost libraries is supported via a Python script which tests ALL the boost libraries and uploads test results to a central web page. Reworking this to accommodate our "decoupled" library model would seem to be a non-trivial and fragile exercise.

  • It's not widely used. Requiring potential users to use boost build diminish the number of users willing to test a library.

These disadvantages discouraged me from requiring Boost Build. Any library which is accepted by Boost will have to include support for Bjam or whatever boost requires at the time. But having to sort this out up front was considered too large a burden on library authors. Never the less, it IS and option.

Here are some websites with information regarding Boost Build

To use Boost Build for testing, we'll rely on the following:

  • http://www.highscore.de/cpp/boostbuild/ for explanation of how bjam works.

  • http://www.boost.org/boost-build2/doc/html/bbv2/builtins/testing.html for an explanation of the Jamfile commands used for testing.

  • The section of Directory Structure shows location of the files Jamroot.jam and Jamfile.jam which the bjam build/test procedure uses to drive the process. Create these files in the designated places in the directory hierarchy of your project. You may also use safe numerics library as an example. Here is the file Jamfile.v2 in the directory safe_numerics/test

    import testing ;
    
    run test_add.cpp test_add1.cpp test_add2.cpp test_add3.cpp
        : # args    
        : # input files
        : # requirements
        : # target-name
        : # default-build ...
    ;
    
    # other tests follow ...

    And here is the Jamroot.jam file in the directory safe_numerics

    import os ;
    
    # Note: we require tha BOOST_ROOT be defined with a valid path
    BOOST_ROOT = [ os.environ BOOST_ROOT ] ;
    ECHO Boost include path is: $(BOOST_ROOT) ;
    
    project safe_numerics
        # : source-location ... # not needed for header only libraries
        : requirements
            <include>$(BOOST_ROOT)
            <toolset>gcc:<cxxflags>-pedantic
            <toolset>gcc:<cxxflags>-std=c++0x
        # : default-build   - default none
        # : build-dir - default = ./bin
    ;
  • We will use an abbreviated version of the procedure document for Library Status on the Boost website. This entails the following steps.

    • set the current directory to <library>/test .

    • set the environmental variable BOOST_ROOT=<boost root directory>

    • invoke bjam --dump-tests <bjam arguments> >bjam.log

      where bjam arguments are some combination of the following:

      • toolset=msvc-9.0

      • variant=debug,release, profile

      • link=static, shared

      • threading=single,multi

      Note that if you specify more than one value for an argument, (e.g. debug,release separated by commas), bjam will build both versions of the tests. Since the same applies to all the possible arguments, so it's possible to generate a large number of combinations of tests with only one command line.

    • invoke library_status library_status.html

      This will build an HTML file in the <library>/test directory named library_status.html. Opening this with any web browser will display all your test results.

    This whole procedure can be encapsulated in the following shell script or similar windows BAT file. This script is found in BOOST_ROOT/tools/regression/src.

    if test $# -eq 0 
    then
        echo "Usage: b2 <b2 arguments>"
        echo "Where typical <b2 arguements> are:"
        echo "  toolset=msvc-7.1,gcc"
        echo "  variant=debug,release,profile"
        echo "  link=static,shared"
        echo "  threading=single,multi"
    else
        bjam --dump-tests $@ >b2.log 2>&1
        library_status library_status.html links.html
    fi

Your boost installation might or might not have b2 installed and working. If not, you'll have to get them built. There are any number of ways to do this depending on your platform. See Getting Started and B2 Installation at the boost website for information on how to do this. Unfortunately, the program library_status is not built by the default installation. But now that you have b2 installed, the following procedure will build the library_status executable.

  • set the current directory to <boost root>/tools/regression/build .

  • invoke b2 toolset=<....> variant=release library_status

  • copy the resulting library_status executable to a place in your path. Most likely this will be the same place where the b2 executable is to be found.

Now you should have everything in place to execute the above described procedure for testing your library and reviewing the results. The focus here has been to describe a simple boost friendly procedure for building and testing one's library. This procedure should permit anyone who has boost installed to run the tests on any download from this site. Users should be encouraged to run the test suite on their local platform/compiler before using the library. In the future we hope to enhance the library status page displayed with a button to upload the test results to a common site so that library authors and potential users can review the test results when ever it might be convenient. However, for now this is the best we have.

There are 0 comments and replies

Comment on This Page