libs/test/doc/html/boost_test/adv_scenarios/static_lib_customizations/init_func.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Customizing the module's initialization function</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="../static_lib_customizations.html" title="Static-library variant customizations">
   9 <link rel="prev" href="entry_point.html" title="Customizing the module's entry point">
  10 <link rel="next" href="../shared_lib_customizations.html" title="Shared-library variant customizations">
  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="entry_point.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../static_lib_customizations.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="../shared_lib_customizations.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="boost_test.adv_scenarios.static_lib_customizations.init_func"></a><a class="link" href="init_func.html" title="Customizing the module's initialization function">Customizing
  28         the module's initialization function</a>
  29 </h4></div></div></div>
  30 <p>
  31           In the static library variant, customizing the main entry point is quite
  32           troublesome, because the default test runner compiled into the static library
  33           uses the obsolete initialization function signature. This requires you
  34           to rebuild the <span class="emphasis"><em>Unit Test Framework</em></span> static library
  35           with the defined symbol <a class="link" href="../../utf_reference/link_references/link_boost_test_alternative_init_macro.html" title="BOOST_TEST_ALTERNATIVE_INIT_API"><code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code></a>.
  36           In the Boost root directory you need to invoke command
  37         </p>
  38 <pre class="programlisting"><span class="special">&gt;</span> <span class="identifier">b2</span> <span class="special">--</span><span class="identifier">with</span><span class="special">-</span><span class="identifier">test</span> <span class="identifier">link</span><span class="special">=</span><span class="keyword">static</span> <span class="identifier">define</span><span class="special">=</span><a class="link" href="../../utf_reference/link_references/link_boost_test_alternative_init_macro.html" title="BOOST_TEST_ALTERNATIVE_INIT_API"><code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code></a> <span class="identifier">install</span>
  39 </pre>
  40 <div class="warning"><table border="0" summary="Warning">
  41 <tr>
  42 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../../doc/src/images/warning.png"></td>
  43 <th align="left">Warning</th>
  44 </tr>
  45 <tr><td align="left" valign="top"><p>
  46             This alteration of the static library will affect everybody else who
  47             is linking against the library. Consider using the <a class="link" href="../obsolete_init_func.html" title="The obsolete initialization function">obsolete
  48             test initialization function</a>, which requires no rebuilding. Alternatively,
  49             it may be less intrusive to switch to the <a class="link" href="../shared_lib_customizations.html" title="Shared-library variant customizations">shared
  50             library usage variant</a> instead.
  51           </p></td></tr>
  52 </table></div>
  53 <p>
  54           In one of the source files, you now have to define your custom initialization
  55           function with signature:
  56         </p>
  57 <pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">init_unit_test</span><span class="special">();</span>
  58 </pre>
  59 <p>
  60           The default <a class="link" href="../test_module_runner_overview.html" title="Test module runner">test
  61           runner</a> will use it to initialize the test module. In your source
  62           code, you no longer define macro <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>; instead, you
  63           need to define <a class="link" href="../../utf_reference/link_references/link_boost_test_alternative_init_macro.html" title="BOOST_TEST_ALTERNATIVE_INIT_API"><code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code></a>
  64           in the main file:
  65         </p>
  66 <div class="informaltable"><table class="table">
  67 <colgroup>
  68 <col>
  69 <col>
  70 </colgroup>
  71 <thead><tr>
  72 <th>
  73                   <p>
  74                     In <span class="bold"><strong>exactly one</strong></span> file
  75                   </p>
  76                 </th>
  77 <th>
  78                   <p>
  79                     In all other files
  80                   </p>
  81                 </th>
  82 </tr></thead>
  83 <tbody><tr>
  84 <td>
  85 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span>
  86 <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>
  87
  88 <span class="comment">// init func:</span>
  89 <span class="keyword">bool</span> <span class="identifier">init_unit_test</span><span class="special">()</span>
  90 <span class="special">{</span>
  91   <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span>
  92 <span class="special">}</span>
  93 </pre>
  94                 </td>
  95 <td>
  96 <pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-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>
  97
  98 <span class="comment">//</span>
  99 <span class="comment">// test cases</span>
 100 <span class="comment">//</span>
 101
 102 <span class="comment">// test cases</span>
 103 <span class="comment">//</span>
 104 </pre>
 105                 </td>
 106 </tr></tbody>
 107 </table></div>
 108 <p>
 109           For reporting errors that may occur during the initialization,
 110         </p>
 111 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 112 <li class="listitem">
 113               either you return <code class="computeroutput"><span class="keyword">false</span></code>
 114               (valid only for the new API only, see <a class="link" href="../../utf_reference/link_references/link_boost_test_alternative_init_macro.html" title="BOOST_TEST_ALTERNATIVE_INIT_API"><code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code></a>)
 115             </li>
 116 <li class="listitem">
 117               or you raise an exception such as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">runtime_error</span></code>
 118               or <code class="computeroutput"><a class="link" href="../../../boost/unit_test/framework/setup_error.html" title="Struct setup_error">boost::unit_test::framework::setup_error</a></code>
 119             </li>
 120 </ul></div>
 121 <p>
 122           An error reported in this function aborts the execution of the test module.
 123         </p>
 124 <div class="note"><table border="0" summary="Note">
 125 <tr>
 126 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
 127 <th align="left">Note</th>
 128 </tr>
 129 <tr><td align="left" valign="top"><p>
 130             The reason for defining <a class="link" href="../../utf_reference/link_references/link_boost_test_alternative_init_macro.html" title="BOOST_TEST_ALTERNATIVE_INIT_API"><code class="computeroutput"><span class="identifier">BOOST_TEST_ALTERNATIVE_INIT_API</span></code></a>
 131             is described <a class="link" href="../obsolete_init_func.html" title="The obsolete initialization function">here</a>.
 132           </p></td></tr>
 133 </table></div>
 134 </div>
 135 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 136 <td align="left"></td>
 137 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2019 Boost.Test
 138       contributors<p>
 139         Distributed under the Boost Software License, Version 1.0. (See accompanying
 140         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>)
 141       </p>
 142 </div></td>
 143 </tr></table>
 144 <hr>
 145 <div class="spirit-nav">
 146 <a accesskey="p" href="entry_point.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../static_lib_customizations.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="../shared_lib_customizations.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
 147 </div>
 148 </body>
 149 </html>