BOOST-TEST-SUITE(1)

NAME
boost-test-suite - run Boost test suite

SYNOPSIS
boost-test-suite [-Vcdhipv] [-D domain] [-I URL] [-N name] [-S schedule] [-T title] [-U username] [-b directory] [-l logfile] [-t toolsets] [-- args]

DESCRIPTION
The boost-test-suite program provides a simple framework for running tests of Boost (http://www.boost.org/). As it runs, boost-test-suite takes care of downloading the necessary Boost test script and running it with parameters appropriate for simple testing applications. It may, however, be configured for more advanced uses, as the options args are passed directly to the test script.

boost-test-suite also generates a file, “comment.html”, that is required by the Boost test suite for reporting the test results. This file contains information summarizing the test environment, including how to retrieve the patches used in the test. A number of command line arguments serve to control the content of this file.

The testing process and requirements are described in greater detail at the following site:

http://www.boost.org/development/running_regression_tests.html

Note that the Boost test framework requires a network connection, as it updates the local copy of Boost with the most current version prior to running the tests and then uploads the results, which are summarized here:

http://www.boost.org/development/tests/trunk/developer/summary.html

Any patches used in the test are imported either directly from the installed package, which comes with the current set of patches, or from a URL referring to an “index file” describing the patch set (See INDEX FILE FORMAT for more information).

In general use, it is best to run tests both with and without patches (i.e., without and with the -p option) on the same machine. This provides the most useful information for both the Boost the pkgsrc communities. Further, unless you intend to develop new sets of patches, it is best to rely on the standard set of patches imported by default (i.e., without specifying either the -I or the -i options). This will ensure consistency among instances of the tests so that a wide array of platforms will be tested with the same configuration.

It is important that the pkgsrc community run the Boost test suite often as it not only improves cross-platform support for Boost itself, but it improves our packages by regularly testing our pkgsrc-specific patches and improves the quality of our compilers by exercising the toolchain.

Please contribute available resources to the testing so we can ensure the best Boost packages and compilers possible.

OPTIONS
The following options are available:

-D domain
    Insert domain into the “comment.html” file as the domain portion of the email address for contacting the operator responsible for the test suite runs. The structure of the “comment.html” file tries to avoid creating full email addresses from this information that can be directly harvested.

-I URL
    Import the index file from URL, which must be interpretable as a URL by ftp(1). By default, patches are imported from a standard repository to maintain consistency among test instances. However, nonstandard index files may be made available, thereby allowing the testing of additional patch sets. See INDEX FILE FORMAT below for a description of such index files.

-N name
    Insert name into the “comment.html” file as the name of the operator responsible for the test suite runs.

-S schedule
    Insert schedule into the “comment.html” file as the comment describing the scheduling of test suite runs.

-T title
    Insert title (together with basic system information) into the “comment.html” file as the title of the test suite runs.

-U username
    Insert username into the “comment.html” file as the user portion of the email address for contacting the operator responsible for the test suite runs. The structure of the “comment.html” file tries to avoid creating full email addresses from this information that can be directly harvested.

-V  Print version information and exit.

-b directory
    Run the Boost tests in directory. By default, the tests will be run in @BOOST_TEST_BASEDIR@.

-c  Clean and remove the test directory after running the tests. If the tests fail, this cleanup will not occur so that the files can be examined to determine the cause of the failure.

-d  Generate debug output and include it in “comment.html”.

-h  Print a brief help page.

-i  Do not import patches. Instead, use the fixed set distributed with the package.

-l logfile
    Log the output of the test runs to logfile. Note that a relative path will be resolved relative to the test directory.

-p  Do not patch the source prior to running the tests.

-t toolsets
    Use toolsets (a comma-delimited list of valid toolsets) as the “toolsets” argument to the Boost test script.

-v  Increase the verbosity of output. This option may be repeated.

INDEX FILE FORMAT
Sets of patches are defined in an “index file”. The URL of this file is specified with the -I command line option; if this is not given, a standard URL is used instead. The purpose of this file is to define both the URL used to refer to patches in the “comment.html” file and the URL(s) used by ftp(1) to download the patches. Blank lines and comments beginning with # are ignored. A single line beginning with `URL:' defines the URL inserted into “comment.html”. All other lines are expected to be valid URLs, interpretable by ftp(1), specifying patch files to import.

EXAMPLES
boost-test-suite can be usefully run with no command line options or with only the -p option (to avoid patches altogether). However, because the test results will be embedded within a large table of other results, it is best to specify some identifying information that is more useful than the defaults. The following command gives the test an explicit title (Drofnats) and provides contact information so that inquiries about the test can be directed to the right person (in this case R.J. Drofnats, rj@drofnats.com).

boost-test-suite -T Drofnats -N "R.J. Drofnats" -U rj -D drofnats.com

Ideally, the Boost test suite will be run on a regular basis with and without patches. This may be accommplished with the following crontab(5) entries.

#minute hour mday month wday command
0 2 * * * @PREFIX@/sbin/boost-test-suite
0 14 * * * @PREFIX@/sbin/boost-test-suite -p

In these cases it is most apprpriate to include additional identifying information (such as shown in the first example above). Further, if the tests are run regularly, it is appropriate to use the -S command line option to indicate the schedule.

boost-test-suite -S "Tests are run regularly at 0200 UTC-8"

Of course, in practice all of the options illustrated here should be combined to construct an appropriate set of command line options.

SEE ALSO
cron(8), crontab(5), and ftp(1).

More information about Boost and the testing process is avaiable from http://www.boost.org/ and http://www.boost.org/development/running_regression_tests.html. The test results themselves are available from http://www.boost.org/development/tests/trunk/developer/summary.html.

AUTHOR
Brook Milligan