1[/ 2 / Copyright (c) 2003 Boost.Test contributors 3 / 4 / Distributed under the Boost Software License, Version 1.0. (See accompanying 5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 /] 7 8[section:static_lib_customizations Static-library variant customizations] 9 10[section:entry_point Customizing the module's entry point] 11 12In the static library variant, customizing the main entry point is quite troublesome, because the definition 13of function `main` is already compiled into the static library. This requires you to rebuild the __UTF__ 14static library with the defined symbol __BOOST_TEST_NO_MAIN__. In the Boost root directory you need to 15invoke command 16 17``` 18> b2 --with-test link=static define=__BOOST_TEST_NO_MAIN__ define=__BOOST_TEST_ALTERNATIVE_INIT_API__ install 19``` 20 21[warning This removal of entry point definition from the static library will affect everybody else who is 22linking against the library. It may be less intrusive to switch to the 23[link boost_test.adv_scenarios.shared_lib_customizations shared library usage variant] instead.] 24 25In one of the source files, you now have to define your custom entry point, and invoke the default 26[link boost_test.adv_scenarios.test_module_runner_overview test runner] `unit_test_main` manually with 27the default [link boost_test.adv_scenarios.test_module_init_overview initialization function] `init_unit_test` 28as the first argument. There is no need to define __BOOST_TEST_NO_MAIN__ in your source code, but you need 29to define __BOOST_TEST_ALTERNATIVE_INIT_API__ in the main file: 30 31[table 32[[In *exactly one* file][In all other files]] 33[[```#define BOOST_TEST_MODULE test module name 34#define BOOST_TEST_ALTERNATIVE_INIT_API 35#include <boost/test/unit_test.hpp> 36 37// entry point: 38int main(int argc, char* argv[], char* envp[]) 39{ 40 return utf::unit_test_main(init_unit_test, argc, argv); 41} 42```] 43[```#include <boost/test/unit_test.hpp> 44 45// 46// test cases 47// 48 49// 50// test cases 51// 52```]] 53] 54 55[note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described 56 [link boost_test.adv_scenarios.obsolete_init_func here].] 57 58 59[endsect] [/section:entry_point] 60 61[section:init_func Customizing the module's initialization function] 62 63In the static library variant, customizing the main entry point is quite troublesome, because the default test 64runner compiled into the static library uses the obsolete initialization function signature. This requires you 65to rebuild the __UTF__ static library with the defined symbol __BOOST_TEST_ALTERNATIVE_INIT_API__. In the Boost 66root directory you need to invoke command 67 68``` 69> b2 --with-test link=static define=__BOOST_TEST_ALTERNATIVE_INIT_API__ install 70``` 71 72[warning This alteration of the static library will affect everybody else who is linking against the 73library. Consider using the [link boost_test.adv_scenarios.obsolete_init_func obsolete test initialization function], 74which requires no rebuilding. Alternatively, it may be less intrusive to switch to the 75[link boost_test.adv_scenarios.shared_lib_customizations shared library usage variant] instead.] 76 77In one of the source files, you now have to define your custom initialization function with signature: 78 79``` 80bool init_unit_test(); 81``` 82 83The default [link boost_test.adv_scenarios.test_module_runner_overview test runner] will use it to initialize 84the test module. In your source code, you no longer define macro __BOOST_TEST_MODULE__; instead, you need to 85define __BOOST_TEST_ALTERNATIVE_INIT_API__ in the main file: 86 87[table 88[[In *exactly one* file][In all other files]] 89[[```#define BOOST_TEST_ALTERNATIVE_INIT_API 90#include <boost/test/unit_test.hpp> 91 92// init func: 93bool init_unit_test() 94{ 95 return true; 96} 97```] 98[```#include <boost/test/unit_test.hpp> 99 100// 101// test cases 102// 103 104// test cases 105// 106```]] 107] 108 109For reporting errors that may occur during the initialization, 110 111* either you return `false` (valid only for the new API only, see __BOOST_TEST_ALTERNATIVE_INIT_API__) 112* or you raise an exception such as `std::runtime_error` or [classref boost::unit_test::framework::setup_error] 113 114An error reported in this function aborts the execution of the test module. 115 116 117[note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described 118 [link boost_test.adv_scenarios.obsolete_init_func here].] 119 120 121[endsect] [/section:init_func] 122 123[endsect] [/section:static_lib_customizations] 124