1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 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">></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"><</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> 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"><</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> 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 © 2001-2020 Boost.Test contributors<p> 138 Distributed under the Boost Software License, Version 1.0. (See accompanying 139 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>) 140 </p> 141</div></td> 142</tr></table> 143<hr> 144<div class="spirit-nav"> 145<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> 146</div> 147</body> 148</html> 149
