ceph/src/boost/libs/test/doc/adv_scenarios/static_lib_customizations.qbk

   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
  12 In the static library variant, customizing the main entry point is quite troublesome, because the definition of function `main` is already compiled into the static library. This requires you to rebuild the __UTF__ static library with the defined symbol __BOOST_TEST_NO_MAIN__. In the Boost root directory you need to invoke command
  13
  14 ```
  15 > b2 --with-test link=static define=__BOOST_TEST_NO_MAIN__ define=__BOOST_TEST_ALTERNATIVE_INIT_API__ install
  16 ```
  17
  18 [warning This removal of entry point definition from the static library will affect everybody else who is linking against the library. It may be less intrusive to switch to the [link boost_test.adv_scenarios.shared_lib_customizations shared library usage variant] instead.]
  19
  20 In one of the source files, you now have to define your custom entry point, and invoke the default [link boost_test.adv_scenarios.test_module_runner_overview test runner] `unit_test_main` manually with the default [link boost_test.adv_scenarios.test_module_init_overview initialization function] `init_unit_test` as the first argument. There is no need to define __BOOST_TEST_NO_MAIN__ in your source code, but you need to define __BOOST_TEST_ALTERNATIVE_INIT_API__ in the main file:
  21
  22 [table
  23 [[In *exactly one* file][In all other files]]
  24 [[```#define BOOST_TEST_MODULE test module name
  25 #define BOOST_TEST_ALTERNATIVE_INIT_API
  26 #include <boost/test/unit_test.hpp>
  27
  28 // entry point:
  29 int main(int argc, char* argv[], char* envp[])
  30 {
  31   return utf::unit_test_main(init_unit_test, argc, argv);
  32 }
  33 ```]
  34 [```#include <boost/test/unit_test.hpp>
  35
  36 //
  37 // test cases
  38 //
  39
  40 //
  41 // test cases
  42 //
  43 ```]]
  44 ]
  45
  46 [note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described [link boost_test.adv_scenarios.obsolete_init_func here].]
  47
  48
  49 [endsect] [/section:entry_point]
  50
  51 [section:init_func Customizing the module's initialization function]
  52
  53 In the static library variant, customizing the main entry point is quite troublesome, because the default test runner compiled into the static library uses the obsolete initialization function signature. This requires you to rebuild the __UTF__ static library with the defined symbol __BOOST_TEST_ALTERNATIVE_INIT_API__. In the Boost root directory you need to invoke command
  54
  55 ```
  56 > b2 --with-test link=static define=__BOOST_TEST_ALTERNATIVE_INIT_API__ install
  57 ```
  58
  59 [warning This alteration of the static library will affect everybody else who is linking against the library. Consider using the [link boost_test.adv_scenarios.obsolete_init_func obsolete test initialization function], which requires no rebuilding. Alternatively, it may be less intrusive to switch to the [link boost_test.adv_scenarios.shared_lib_customizations shared library usage variant] instead.]
  60
  61 In one of the source files, you now have to define your custom initialization function with signature:
  62
  63 ```
  64 bool init_unit_test();
  65 ```
  66
  67 The default [link boost_test.adv_scenarios.test_module_runner_overview test runner] will use it to initialize the test module. In your source code, you no longer define macro __BOOST_TEST_MODULE__; instead, you need to define __BOOST_TEST_ALTERNATIVE_INIT_API__ in the main file:
  68
  69 [table
  70 [[In *exactly one* file][In all other files]]
  71 [[```#define BOOST_TEST_ALTERNATIVE_INIT_API
  72 #include <boost/test/unit_test.hpp>
  73
  74 // init func:
  75 bool init_unit_test()
  76 {
  77   return true;
  78 }
  79 ```]
  80 [```#include <boost/test/unit_test.hpp>
  81
  82 //
  83 // test cases
  84 //
  85
  86 // test cases
  87 //
  88 ```]]
  89 ]
  90
  91 [note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described [link boost_test.adv_scenarios.obsolete_init_func here].]
  92
  93
  94 [endsect] [/section:init_func]
  95
  96 [endsect] [/section:static_lib_customizations]