1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 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"><</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">></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"><</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">></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"><</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">></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"><</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">></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"><</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">></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"><</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">></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"><</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">></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 © 2001-2020 Boost.Test contributors<p> 213 Distributed under the Boost Software License, Version 1.0. (See accompanying 214 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>) 215 </p> 216</div></td> 217</tr></table> 218<hr> 219<div class="spirit-nav"> 220<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> 221</div> 222</body> 223</html> 224
