|
Home | Libraries | People | FAQ | More |
Introduction
Preparation
Execution
Adding a new test
Requirements
History
Boost's internal regression test suite produces the compiler status tables.
Although not ordinarily run by Boost library users, it is documented here for the benefit of Boost developers, and for Boost users porting to a new platform.
Version 3 of the Boost regression testing framework is based on Boost.Build, and uses bjam to actually run the tests. Because Boost.Build does dependency analysis, only tests for which some dependency has change are rerun.
The reporting of test results as HTML files is accomplished by separate regression reporting programs which process the residue and log files from the bjam run.
Install the following programs on your system, in some location suitable for program executables. Normally that location must be in a directory which is part of your search path for executables.
These examples assume several environment variables have been set:
A full set of tests and status tables can then be run thusly on a Window 2000 system:
cd %BOOST_ROOT%\status md bin 2>nul bjam --dump-tests test >bin\bjam.log 2>&1 start notepad bin\bjam.log process_jam_log <bin\bjam.log compiler_status %BOOST_ROOT% cs-win32.html rem Specify links file, even though it will be overwritten, so report html includes links rem This works because the generated bookmark names are the same regardless of other settings compiler_status --ignore-pass --no-warn %BOOST_ROOT% cs-win32-fail.html cs-win32-links.html compiler_status --ignore-pass %BOOST_ROOT% cs-win32-warn-or-fail.html cs-win32-links.html compiler_status %BOOST_ROOT% cs-win32-full.html cs-win32-links.html
Modulo syntax adjustments, the same procedure should work on other operating systems (an example shell script for this is provided, see the script itself for comments and directions). Rename the cs-win-xxx output files as appropriate.
If you execute compiler_status without arguments, you can see the available options and tailor your own favorite report.
If you want to run just a single test, specify it as the bjam target rather than "test". For example, to debug configurations, it might be useful to just run the config_info test, with a switch to force even up-to-date programs be rebuilt:
bjam -a --dump-tests config_info >bin\bjam.log 2>&1 process_jam_log <bin\bjam.log compiler_status %BOOST_ROOT% cs-win32.html
Adding tests is as simple as adding a single line to the boost-root/status/Jamfile:
run libs/mylib/test/mytest.cpp ;
Don't forget that Jam is white-space sensitive; delete the space before the semi-colon in the example above, and you will get an introduction to Jam error messages.
For creating more complex tests and test-suites, look at examples in the Jamfile. The bind and config test-suites are simple examples, while the regex and threads test suites show more of the power of Jam based testing.
A library can have its own private set of tests by creating a Jamfile in one of the library's own sub-directories. For an example of this, see boost-root/libs/test/test/Jamfile.
The test suite has been designed to meet to the following requirements.
These requirements rule out any script-based approach such as dejagnu (requires Tcl and expect) or even shell scripts.
The version 3 testing.jam and status/Jamfile foundation was contributed by Dave Abrahams. The post-bjam processing programs were contributed by Beman Dawes.
The version 2 regression.cpp test program was contributed by Jens Maurer, generalizing and improving an earlier version 1 program by Beman Dawes.
Revised 09 January, 2003
Original author: Jens
Maurer
Updates: Beman Dawes