samien
/
boost
mirror of https://github.com/boostorg/boost


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155
							<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

<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>


<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>
<a href="#Adding_new_test">Adding a new test</a><br>
<a href="#Requirements">Requirements</a><br>
<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>
<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>
<ul>
  <li><i>bjam</i> - Executables and sources are available; see
  <a href="../tools/build/index.html#Jam">Boost.Build docs</a>.&nbsp; 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>
&nbsp;</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>
<ul>
  <li>BOOST_ROOT is set to the directory where the unzipped Boost distribution 
  or CVS working copy resides.&nbsp; For example:<br>
  <br>
  set BOOST_ROOT=/boost_1_29_0<br>
&nbsp;</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>
&nbsp;</li>
  <li>Any environment variables required for particular compilers.&nbsp; 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>
<blockquote>
  <pre>cd %BOOST_ROOT%\status
md bin 2&gt;nul
bjam --dump-tests test &gt;bin\bjam.log 2&gt;&amp;1
start notepad bin\bjam.log
process_jam_log &lt;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</pre>
</blockquote>
<p>Modulo syntax adjustments, the same procedure should work on other operating 
systems.&nbsp; 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 &quot;test&quot;.&nbsp; 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 &gt;bin\bjam.log 2&gt;&amp;1
process_jam_log &lt;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>
<blockquote>
  <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>.&nbsp; 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.&nbsp; 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>
<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
</ul>

<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>

<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>

</body>
</html>