libs/test/doc/html/boost_test/usage_variants.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Usage variants</title>
   5 <link rel="stylesheet" href="../boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../index.html" title="Boost.Test">
   8 <link rel="up" href="../index.html" title="Boost.Test">
   9 <link rel="prev" href="intro/how_to_read.html" title="How to read this documentation">
  10 <link rel="next" href="tests_organization.html" title="Declaring and organizing tests">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="intro/how_to_read.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tests_organization.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="boost_test.usage_variants"></a><a class="link" href="usage_variants.html" title="Usage variants">Usage variants</a>
  28 </h2></div></div></div>
  29 <p>
  30       The <span class="emphasis"><em>Unit Test Framework</em></span> supports three different usage
  31       variants:
  32     </p>
  33 <div class="orderedlist"><ol class="orderedlist" type="1">
  34 <li class="listitem">
  35           <a class="link" href="usage_variants.html#boost_test.usage_variants.single_header">The header-only
  36           variant</a>
  37         </li>
  38 <li class="listitem">
  39           <a class="link" href="usage_variants.html#boost_test.usage_variants.static_lib">The static library
  40           variant</a>
  41         </li>
  42 <li class="listitem">
  43           <a class="link" href="usage_variants.html#boost_test.usage_variants.shared_lib">The shared library
  44           variant</a>
  45         </li>
  46 </ol></div>
  47 <p>
  48       In most cases you shouldn't have problems deciding which one to use, since
  49       there are clear reasons why would you prefer each one. Following sections should
  50       help you with the decision.
  51     </p>
  52 <h4>
  53 <a name="boost_test.usage_variants.h0"></a>
  54       <span class="phrase"><a name="boost_test.usage_variants.single_header"></a></span><a class="link" href="usage_variants.html#boost_test.usage_variants.single_header">Header-only
  55       usage variant</a>
  56     </h4>
  57 <p>
  58       If you prefer to avoid the compilation of standalone library, you should use
  59       the header-only variant of the <span class="emphasis"><em>Unit Test Framework</em></span>. This
  60       variant only requires you to include the unique header: <code class="computeroutput"><span class="preprocessor">#include</span>
  61       <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code> and
  62       there is no need to link with any library. There are several ways to perform
  63       the initialization, but the simplest way is the following:
  64     </p>
  65 <pre class="programlisting"><span class="preprocessor">#define</span> <a class="link" href="utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> <span class="identifier">test</span> <span class="identifier">module</span> <span class="identifier">name</span>
  66 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  67 </pre>
  68 <p>
  69       <a class="link" href="utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> macro needs to be
  70       defined <span class="bold"><strong>before</strong></span> the include and should indicate
  71       the name of the test module. This name can include spaces and does not need
  72       to be wrapped in quotes.
  73     </p>
  74 <p>
  75       <a class="link" href="adv_scenarios/single_header_customizations.html" title="Header-only variant customizations">This
  76       section</a> gives additional details on how to customize this usage variant.
  77       In particular, it is possible to have several compilation units with this variant,
  78       as explained in the section <a class="link" href="adv_scenarios/single_header_customizations/multiple_translation_units.html" title="Header-only with multiple translation units">Header-only
  79       with multiple translation units</a>.
  80     </p>
  81 <h4>
  82 <a name="boost_test.usage_variants.h1"></a>
  83       <span class="phrase"><a name="boost_test.usage_variants.static_lib"></a></span><a class="link" href="usage_variants.html#boost_test.usage_variants.static_lib">Static
  84       library usage variant</a>
  85     </h4>
  86 <p>
  87       For most users, who has an access to pre-built static library <a href="#ftn.boost_test.usage_variants.f0" class="footnote" name="boost_test.usage_variants.f0"><sup class="footnote">[1]</sup></a> of the <span class="emphasis"><em>Unit Test Framework</em></span> or can <a class="link" href="adv_scenarios/build_utf.html" title="Building the Unit Test Framework">build
  88       it</a> themselves, following usage can be most versatile and simple approach.
  89       This usage variant entails two steps.
  90     </p>
  91 <div class="orderedlist"><ol class="orderedlist" type="1">
  92 <li class="listitem">
  93 <p class="simpara">
  94           First, the following line needs to be added to all translation units in
  95           the test module:
  96         </p>
  97 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  98 </pre>
  99 <p class="simpara">
 100           One and <span class="bold"><strong>only one</strong></span> translation unit should
 101           include following lines:
 102         </p>
 103 <pre class="programlisting"><span class="preprocessor">#define</span> <a class="link" href="utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> <span class="identifier">test</span> <span class="identifier">module</span> <span class="identifier">name</span>
 104 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 105 </pre>
 106 <p class="simpara">
 107           <a class="link" href="utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> macro needs
 108           to be defined <span class="bold"><strong>before</strong></span> the include and should
 109           indicate the name of the test module. This name can include spaces and
 110           does not need to be wrapped in quotes.
 111         </p>
 112 </li>
 113 <li class="listitem">
 114           The second step is to link with the <span class="emphasis"><em>Unit Test Framework</em></span>
 115           <span class="bold"><strong>static</strong></span> library.
 116         </li>
 117 </ol></div>
 118 <div class="note"><table border="0" summary="Note">
 119 <tr>
 120 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
 121 <th align="left">Note</th>
 122 </tr>
 123 <tr><td align="left" valign="top"><p>
 124         Header <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
 125         is an <span class="emphasis"><em>aggregate</em></span> header: it includes most of the other
 126         headers that contains the Unit Test Framework definitions.
 127       </p></td></tr>
 128 </table></div>
 129 <p>
 130       The flip side of this usage variant is that each test module following this
 131       usage variant is going to be statically linked with <span class="emphasis"><em>Unit Test Framework</em></span>,
 132       which might be something you want to avoid (to save space for example). For
 133       more information about these configuration options check <a class="link" href="adv_scenarios/static_lib_customizations.html" title="Static-library variant customizations">this
 134       section</a>.
 135     </p>
 136 <h4>
 137 <a name="boost_test.usage_variants.h2"></a>
 138       <span class="phrase"><a name="boost_test.usage_variants.shared_lib"></a></span><a class="link" href="usage_variants.html#boost_test.usage_variants.shared_lib">Shared
 139       library usage variant</a>
 140     </h4>
 141 <p>
 142       In the project with large number of test modules the static library variant
 143       of the <span class="emphasis"><em>Unit Test Framework</em></span> may cause you to waste a lot
 144       of disk space. The solution is to link test module dynamically with the <span class="emphasis"><em>Unit
 145       Test Framework</em></span> built as a shared library. This usage variant entails
 146       two steps.
 147     </p>
 148 <div class="orderedlist"><ol class="orderedlist" type="1">
 149 <li class="listitem">
 150 <p class="simpara">
 151           First you need to add following lines to all translation units in a test
 152           module:
 153         </p>
 154 <pre class="programlisting"><span class="preprocessor">#define</span> <a class="link" href="utf_reference/link_references/link_boost_test_dyn_link.html" title="BOOST_TEST_DYN_LINK"><code class="computeroutput"><span class="identifier">BOOST_TEST_DYN_LINK</span></code></a>
 155 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 156 </pre>
 157 <p class="simpara">
 158           and <span class="bold"><strong>only one</strong></span> translation unit should include
 159           following lines
 160         </p>
 161 <pre class="programlisting"><span class="preprocessor">#define</span> <a class="link" href="utf_reference/link_references/link_boost_test_module_macro.html" title="BOOST_TEST_MODULE"><code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code></a> <span class="identifier">test</span> <span class="identifier">module</span> <span class="identifier">name</span>
 162 <span class="preprocessor">#define</span> <a class="link" href="utf_reference/link_references/link_boost_test_dyn_link.html" title="BOOST_TEST_DYN_LINK"><code class="computeroutput"><span class="identifier">BOOST_TEST_DYN_LINK</span></code></a>
 163 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 164 </pre>
 165 <p class="simpara">
 166           <code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code> and
 167           <code class="computeroutput"><span class="identifier">BOOST_TEST_DYN_LINK</span></code> macros
 168           needs to be defined <span class="bold"><strong>before</strong></span> the include.
 169           <code class="computeroutput"><span class="identifier">BOOST_TEST_MODULE</span></code> should
 170           be set to test module name. This name can include spaces and does not need
 171           to be wrapped in quotes.
 172         </p>
 173 </li>
 174 <li class="listitem">
 175           The second step is to link with the <span class="emphasis"><em>Unit Test Framework</em></span>
 176           <span class="bold"><strong>shared</strong></span> library.
 177         </li>
 178 </ol></div>
 179 <p>
 180       The flip side of this usage variant is that you will need to make sure the
 181       <span class="emphasis"><em>Unit Test Framework</em></span> shared library is accessible at runtime
 182       to a test module.
 183     </p>
 184 <p>
 185       In addition shared library usage variant facilitates custom test runners. For
 186       more information about this check <a class="link" href="adv_scenarios/shared_lib_customizations.html" title="Shared-library variant customizations">this
 187       section</a>.
 188     </p>
 189 <div class="caution"><table border="0" summary="Caution">
 190 <tr>
 191 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../doc/src/images/caution.png"></td>
 192 <th align="left">Caution</th>
 193 </tr>
 194 <tr><td align="left" valign="top"><p>
 195         On Windows, the test module and the <span class="emphasis"><em>Unit Test Framework</em></span>
 196         shared library should link to the same CRT. Not doing so (for instance <span class="emphasis"><em>Unit
 197         Test Framework</em></span> shared library in <span class="emphasis"><em>release</em></span>
 198         mode while the test module is in <span class="emphasis"><em>debug</em></span>) will lead to
 199         crashes.
 200       </p></td></tr>
 201 </table></div>
 202 <div class="footnotes">
 203 <br><hr style="width:100; text-align:left;margin-left: 0">
 204 <div id="ftn.boost_test.usage_variants.f0" class="footnote"><p><a href="#boost_test.usage_variants.f0" class="para"><sup class="para">[1] </sup></a>
 205         these files are distributed with the packaging systems on Linux and OSX for
 206         instance
 207       </p></div>
 208 </div>
 209 </div>
 210 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 211 <td align="left"></td>
 212 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 213       contributors<p>
 214         Distributed under the Boost Software License, Version 1.0. (See accompanying
 215         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 216       </p>
 217 </div></td>
 218 </tr></table>
 219 <hr>
 220 <div class="spirit-nav">
 221 <a accesskey="p" href="intro/how_to_read.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tests_organization.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 222 </div>
 223 </body>
 224 </html>