|
|
@@ -1,28 +1,33 @@
|
|
|
<html>
|
|
|
|
|
|
<head>
|
|
|
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
|
-
|
|
|
+<meta http-equiv="Content-Type"
|
|
|
+content="text/html; charset=iso-8859-1">
|
|
|
+<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0">
|
|
|
<title>Boost Regression Test User Documentation</title>
|
|
|
</head>
|
|
|
|
|
|
<body bgcolor="#FFFFFF" text="#000000">
|
|
|
|
|
|
-<table border="1" bgcolor="#007F7F" cellpadding="2">
|
|
|
- <tr>
|
|
|
- <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td>
|
|
|
- <td><a href="../index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Home</big></font></a></td>
|
|
|
- <td><a href="../libs/libraries.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>Libraries</big></font></a></td>
|
|
|
- <td><a href="../people/people.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>People</big></font></a></td>
|
|
|
- <td><a href="../more/faq.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>FAQ</big></font></a></td>
|
|
|
- <td><a href="../more/index.htm"><font face="Arial,Helvetica" color="#FFFFFF"><big>More</big></font></a></td>
|
|
|
- </tr>
|
|
|
+<table border="1" cellpadding="2" bgcolor="#007F7F">
|
|
|
+ <tr>
|
|
|
+ <td bgcolor="#FFFFFF"><img src="../c++boost.gif"
|
|
|
+ alt="c++boost.gif (8819 bytes)" width="277" height="86"></td>
|
|
|
+ <td><a href="../index.htm"><font color="#FFFFFF" size="4"
|
|
|
+ face="Arial,Helvetica">Home</font></a></td>
|
|
|
+ <td><a href="../libs/libraries.htm"><font color="#FFFFFF"
|
|
|
+ size="4" face="Arial,Helvetica">Libraries</font></a></td>
|
|
|
+ <td><a href="../people/people.htm"><font color="#FFFFFF"
|
|
|
+ size="4" face="Arial,Helvetica">People</font></a></td>
|
|
|
+ <td><a href="faq.htm"><font color="#FFFFFF" size="4"
|
|
|
+ face="Arial,Helvetica">FAQ</font></a></td>
|
|
|
+ <td><a href="index.htm"><font color="#FFFFFF" size="4"
|
|
|
+ face="Arial,Helvetica">More</font></a></td>
|
|
|
+ </tr>
|
|
|
</table>
|
|
|
|
|
|
-
|
|
|
<h1>Boost Regression Test User Documentation</h1>
|
|
|
|
|
|
-
|
|
|
<p><a href="#Introduction">Introduction</a><br>
|
|
|
<a href="#Preparation">Preparation</a><br>
|
|
|
<a href="#Execution">Execution</a><br>
|
|
|
@@ -31,53 +36,75 @@
|
|
|
<a href="#History">History</a></p>
|
|
|
|
|
|
<h2><a name="Introduction">Introduction</a></h2>
|
|
|
-<p>Boost's internal regression test suite produces the
|
|
|
-<a href="../status/compiler_status.html">compiler status tables</a>. </p>
|
|
|
-<p>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.</p>
|
|
|
-
|
|
|
-<p>Version 3 of the Boost regression testing framework is based on
|
|
|
-<a href="../tools/build/index.html">Boost.Build</a>, and uses <i>bjam</i> to
|
|
|
-actually run the tests. Because Boost.Build does dependency analysis, only tests
|
|
|
-for which some dependency has change are rerun.</p>
|
|
|
-<p>The reporting of test results as HTML files is accomplished by separate
|
|
|
-<a href="../tools/regression/index.htm">regression reporting
|
|
|
-programs</a> which process the residue and log files from the <i>bjam</i> run.</p>
|
|
|
+
|
|
|
+<p>Boost's internal regression test suite produces the <a
|
|
|
+href="../status/compiler_status.html">compiler status tables</a>.
|
|
|
+</p>
|
|
|
+
|
|
|
+<p>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.</p>
|
|
|
+
|
|
|
+<p>Version 3 of the Boost regression testing framework is based
|
|
|
+on <a href="../tools/build/index.html">Boost.Build</a>, and uses <i>bjam</i>
|
|
|
+to actually run the tests. Because Boost.Build does dependency
|
|
|
+analysis, only tests for which some dependency has change are
|
|
|
+rerun.</p>
|
|
|
+
|
|
|
+<p>The reporting of test results as HTML files is accomplished by
|
|
|
+separate <a href="../tools/regression/index.htm">regression
|
|
|
+reporting programs</a> which process the residue and log files
|
|
|
+from the <i>bjam</i> run.</p>
|
|
|
+
|
|
|
<h2><a name="Preparation">Preparation</a></h2>
|
|
|
-<p>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.</p>
|
|
|
+
|
|
|
+<p>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.</p>
|
|
|
+
|
|
|
<ul>
|
|
|
- <li><i>bjam</i> - Executables and sources are available; see
|
|
|
- <a href="../tools/build/index.html#Jam">Boost.Build docs</a>. Before
|
|
|
- worrying about regression tests, you might want to verify your <i>bjam</i>
|
|
|
- installation works by <a href="../tools/build/index.html#Building">building
|
|
|
- the boost-root/status/Jamfile libraries</a>.<br>
|
|
|
- </li>
|
|
|
- <li><i>process_jam_log</i> and <i>compiler_status</i> -
|
|
|
- <a href="regression.html">Sources and docs</a> are available for these, too. </li>
|
|
|
+ <li><i>bjam</i> - Executables and sources are available; see <a
|
|
|
+ href="../tools/build/index.html#Jam">Boost.Build docs</a>.
|
|
|
+ Before worrying about regression tests, you might want to
|
|
|
+ verify your <i>bjam</i> installation works by <a
|
|
|
+ href="../tools/build/index.html#Building">building the
|
|
|
+ boost-root/status/Jamfile libraries</a>.<br>
|
|
|
+ </li>
|
|
|
+ <li><i>process_jam_log</i> and <i>compiler_status</i> - <a
|
|
|
+ href="regression.html">Sources and docs</a> are available
|
|
|
+ for these, too. </li>
|
|
|
</ul>
|
|
|
+
|
|
|
<h2><a name="Execution">Execution</a></h2>
|
|
|
-<p>These examples assume several environment variables have been set:</p>
|
|
|
+
|
|
|
+<p>These examples assume several environment variables have been
|
|
|
+set:</p>
|
|
|
+
|
|
|
<ul>
|
|
|
- <li>BOOST_ROOT is set to the directory where the unzipped Boost distribution
|
|
|
- or CVS working copy resides. For example:<br>
|
|
|
- <br>
|
|
|
- set BOOST_ROOT=/boost_1_29_0<br>
|
|
|
- </li>
|
|
|
- <li>TOOLS is set to the <a href="../tools/build/index.html#Tools">compiler
|
|
|
- toolsets</a> you wish to use. For example:<br>
|
|
|
- <br>
|
|
|
- set TOOLS=borland gcc intel-win32 metrowerks vc7<br>
|
|
|
- </li>
|
|
|
- <li>Any environment variables required for particular compilers. You
|
|
|
- might wish to test first with one compiler at a time to make sure each toolset
|
|
|
- is fully operational.</li>
|
|
|
+ <li>BOOST_ROOT is set to the directory where the unzipped
|
|
|
+ Boost distribution or CVS working copy resides. For
|
|
|
+ example:<br>
|
|
|
+ <br>
|
|
|
+ set BOOST_ROOT=/boost_1_29_0<br>
|
|
|
+ </li>
|
|
|
+ <li>TOOLS is set to the <a
|
|
|
+ href="../tools/build/index.html#Tools">compiler toolsets</a>
|
|
|
+ you wish to use. For example:<br>
|
|
|
+ <br>
|
|
|
+ set TOOLS=borland gcc intel-win32 metrowerks vc7<br>
|
|
|
+ </li>
|
|
|
+ <li>Any environment variables required for particular
|
|
|
+ compilers. You might wish to test first with one
|
|
|
+ compiler at a time to make sure each toolset is fully
|
|
|
+ operational.</li>
|
|
|
</ul>
|
|
|
-<p>A full set of tests and status tables can then be run thusly on a Window 2000
|
|
|
-system:</p>
|
|
|
+
|
|
|
+<p>A full set of tests and status tables can then be run thusly
|
|
|
+on a Window 2000 system:</p>
|
|
|
+
|
|
|
<blockquote>
|
|
|
- <pre>cd %BOOST_ROOT%\status
|
|
|
+ <pre>cd %BOOST_ROOT%\status
|
|
|
md bin 2>nul
|
|
|
bjam --dump-tests test >bin\bjam.log 2>&1
|
|
|
start notepad bin\bjam.log
|
|
|
@@ -89,67 +116,94 @@ compiler_status --ignore-pass --no-warn %BOOST_ROOT% cs-win32-fail.html cs-win32
|
|
|
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</pre>
|
|
|
</blockquote>
|
|
|
-<p>Modulo syntax adjustments, the same procedure should work on other operating
|
|
|
-systems. Rename the cs-win-xxx output files as appropriate.</p>
|
|
|
-<p>If you execute <i>compiler_status</i> without arguments, you can see the
|
|
|
-available options and tailor your own favorite report.</p>
|
|
|
-<p>If you want to run just a single test, specify it as the <i>bjam</i> target
|
|
|
-rather than "test". For example, to debug configurations, it might be
|
|
|
-useful to just run the <i>config_info</i> test, with a switch to force even
|
|
|
-up-to-date programs be rebuilt:</p>
|
|
|
+
|
|
|
+<p>Modulo syntax adjustments, the same procedure should work on
|
|
|
+other operating systems (an example shell script for this is <a
|
|
|
+href="../tools/regression/run_tests.sh">provided</a>, see the
|
|
|
+script itself for comments and directions). Rename the cs-win-xxx
|
|
|
+output files as appropriate.</p>
|
|
|
+
|
|
|
+<p>If you execute <i>compiler_status</i> without arguments, you
|
|
|
+can see the available options and tailor your own favorite report.</p>
|
|
|
+
|
|
|
+<p>If you want to run just a single test, specify it as the <i>bjam</i>
|
|
|
+target rather than "test". For example, to debug
|
|
|
+configurations, it might be useful to just run the <i>config_info</i>
|
|
|
+test, with a switch to force even up-to-date programs be rebuilt:</p>
|
|
|
+
|
|
|
<blockquote>
|
|
|
- <pre>bjam -a --dump-tests config_info >bin\bjam.log 2>&1
|
|
|
+ <pre>bjam -a --dump-tests config_info >bin\bjam.log 2>&1
|
|
|
process_jam_log <bin\bjam.log
|
|
|
compiler_status %BOOST_ROOT% cs-win32.html
|
|
|
</pre>
|
|
|
</blockquote>
|
|
|
+
|
|
|
<h2><a name="Adding_new_test">Adding a new test</a></h2>
|
|
|
+
|
|
|
<h3>Overall Boost regression tests</h3>
|
|
|
-<p>Adding tests is as simple as adding a single line to the
|
|
|
-<a href="../status/Jamfile">boost-root/status/Jamfile</a>:</p>
|
|
|
+
|
|
|
+<p>Adding tests is as simple as adding a single line to the <a
|
|
|
+href="../status/Jamfile">boost-root/status/Jamfile</a>:</p>
|
|
|
+
|
|
|
<blockquote>
|
|
|
- <pre>run libs/mylib/test/mytest.cpp ;</pre>
|
|
|
+ <pre>run libs/mylib/test/mytest.cpp ;</pre>
|
|
|
</blockquote>
|
|
|
-<p>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.</p>
|
|
|
-<p>For creating more complex tests and test-suites, look at examples in the
|
|
|
-<a href="../status/Jamfile">Jamfile</a>. The <i>bind</i> and <i>config</i>
|
|
|
-test-suites are simple examples, while the <i>regex</i> and <i>threads</i> test
|
|
|
-suites show more of the power of Jam based testing.</p>
|
|
|
+
|
|
|
+<p>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.</p>
|
|
|
+
|
|
|
+<p>For creating more complex tests and test-suites, look at
|
|
|
+examples in the <a href="../status/Jamfile">Jamfile</a>.
|
|
|
+The <i>bind</i> and <i>config</i> test-suites are simple
|
|
|
+examples, while the <i>regex</i> and <i>threads</i> test suites
|
|
|
+show more of the power of Jam based testing.</p>
|
|
|
+
|
|
|
<h3>Private tests for a specific library</h3>
|
|
|
-<p>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
|
|
|
-<a href="../libs/test/test/Jamfile">boost-root/libs/test/test/Jamfile</a>.</p>
|
|
|
+
|
|
|
+<p>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 <a href="../libs/test/test/Jamfile">boost-root/libs/test/test/Jamfile</a>.</p>
|
|
|
|
|
|
<h2><a name="Requirements">Requirements</a></h2>
|
|
|
|
|
|
-<p>The test suite has been designed to meet to the following requirements. </p>
|
|
|
+<p>The test suite has been designed to meet to the following
|
|
|
+requirements. </p>
|
|
|
+
|
|
|
<ul>
|
|
|
-<li>Doesn't depend on an external toolchain. This requirement is met by
|
|
|
-supplying all tools in the regular <a href="download.html">Boost distribution</a>, except
|
|
|
-for a C++ compiler.<li>Tools are written in C++; it is the only language that
|
|
|
-all Boost developers and users are comfortable with.<li>Supports tests which expect an error
|
|
|
-<li>Configuration is independent of the target platform or compiler.
|
|
|
-<li>HTML output
|
|
|
+ <li>Doesn't depend on an external toolchain. This requirement
|
|
|
+ is met by supplying all tools in the regular <a
|
|
|
+ href="download.html">Boost distribution</a>, except for a
|
|
|
+ C++ compiler.</li>
|
|
|
+ <li>Tools are written in C++; it is the only language that
|
|
|
+ all Boost developers and users are comfortable with.</li>
|
|
|
+ <li>Supports tests which expect an error </li>
|
|
|
+ <li>Configuration is independent of the target platform or
|
|
|
+ compiler. </li>
|
|
|
+ <li>HTML output </li>
|
|
|
</ul>
|
|
|
|
|
|
-<p>These requirements rule out any script-based approach such as dejagnu
|
|
|
-(requires Tcl and expect) or even shell scripts. </p>
|
|
|
+<p>These requirements rule out any script-based approach such as
|
|
|
+dejagnu (requires Tcl and expect) or even shell scripts. </p>
|
|
|
+
|
|
|
<h2><a name="History">History</a></h2>
|
|
|
-<p>The version 3 testing.jam and status/Jamfile foundation was contributed by
|
|
|
-Dave Abrahams. The post-bjam processing programs were contributed by Beman
|
|
|
-Dawes.</p>
|
|
|
|
|
|
-<p>The version 2 regression.cpp test program was contributed
|
|
|
-by Jens Maurer, generalizing and improving an earlier version 1 program by Beman Dawes.</p>
|
|
|
+<p>The version 3 testing.jam and status/Jamfile foundation was
|
|
|
+contributed by Dave Abrahams. The post-bjam processing programs
|
|
|
+were contributed by Beman Dawes.</p>
|
|
|
+
|
|
|
+<p>The version 2 regression.cpp test program was contributed by
|
|
|
+Jens Maurer, generalizing and improving an earlier version 1
|
|
|
+program by Beman Dawes.</p>
|
|
|
|
|
|
<hr>
|
|
|
-Revised
|
|
|
-<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->07 January, 2003<!--webbot bot="Timestamp" endspan i-checksum="38578" --><p>
|
|
|
-Original author:
|
|
|
-<a href="../people/jens_maurer.htm">Jens Maurer</a><br>
|
|
|
-Updates: <a href="../people/beman_dawes.html">Beman Dawes</a></p>
|
|
|
|
|
|
+<p>Revised <!--webbot bot="Timestamp" startspan s-type="EDITED"
|
|
|
+s-format="%d %B, %Y" -->09 January, 2003<!--webbot bot="Timestamp"
|
|
|
+i-checksum="38582" endspan --></p>
|
|
|
+
|
|
|
+<p>Original author: <a href="../people/jens_maurer.htm">Jens
|
|
|
+Maurer</a><br>
|
|
|
+Updates: <a href="../people/beman_dawes.html">Beman Dawes</a></p>
|
|
|
</body>
|
|
|
-</html>
|
|
|
+</html>
|
John Maddock