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
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
bjambuild/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 numericslibrary as an example. Here is the file
Jamfile.v2in the directory
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.jamfile in the directory
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 ;
set the current directory to
set the environmental variable
BOOST_ROOT=<boost root directory>
bjam --dump-tests <bjam arguments> >bjam.log
where bjam arguments are some combination of the following:
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.
This will build an HTML file in the
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
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
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
set the current directory to
b2 toolset=<....> variant=release library_status
copy the resulting
library_statusexecutable 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.