libs/test/doc/adv_scenarios/shared_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:shared_lib_customizations Shared-library variant customizations]
   9
  10 [caution Macro __BOOST_TEST_DYN_LINK__ (which instructs the compiler/linker to dynamically link against a shared
  11 library variant) may be implicitly defined when macro `BOOST_ALL_DYN_LINK` is defined.]
  12
  13 [caution In order to be able to run a test built with the dynamic variant, the operating system should be able
  14  to find the dynamic library of the __UTF__. This means, for example on Linux and MacOSX respectively, setting the environment
  15  variable `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` properly prior to the execution of the test module.]
  16
  17 [section:entry_point Customizing the module's entry point]
  18
  19 In this variant, in one of the source files, you now have to define your custom entry point, and invoke the default
  20 [link boost_test.adv_scenarios.test_module_runner_overview test runner] `unit_test_main` manually with the default
  21 [link boost_test.adv_scenarios.test_module_init_overview initialization function] `init_unit_test` as argument.
  22 You need to define __BOOST_TEST_NO_MAIN__ (its value is irrelevant) in the main file:
  23
  24 [table
  25 [[In *exactly one* file][In all other files]]
  26 [[```#define BOOST_TEST_MODULE test module name
  27 #define BOOST_TEST_DYN_LINK
  28 #define BOOST_TEST_NO_MAIN
  29 #include <boost/test/unit_test.hpp>
  30
  31 // entry point:
  32 int main(int argc, char* argv[], char* envp[])
  33 {
  34   return boost::unit_test::unit_test_main( &init_unit_test, argc, argv );
  35 }
  36 ```]
  37 [```#define BOOST_TEST_DYN_LINK
  38 #include <boost/test/unit_test.hpp>
  39
  40 //
  41 // test cases
  42 //
  43
  44 //
  45 // test cases
  46 //
  47 ```]]
  48 ]
  49
  50 [endsect] [/section:entry_point]
  51
  52 [section:init_func Customizing the module's initialization function]
  53
  54 In the shared-library variant, it is impossible to customize the initialization function without
  55 [link boost_test.adv_scenarios.shared_lib_customizations.entry_point customizing the entry point]. We have
  56 to customize both. In one of the source files, you now have to define your custom entry point and
  57 [link boost_test.adv_scenarios.test_module_init_overview initialization function] `init_unit_test`; next invoke
  58 the default [link boost_test.adv_scenarios.test_module_runner_overview test runner] `unit_test_main` manually
  59 with `init_unit_test` as argument. You ['do not] define __BOOST_TEST_MODULE__ in the main file:
  60
  61 [table
  62 [[In *exactly one* file][In all other files]]
  63 [[```#define BOOST_TEST_DYN_LINK
  64 #include <boost/test/unit_test.hpp>
  65
  66 // initialization function:
  67 bool init_unit_test()
  68 {
  69   return true;
  70 }
  71
  72 // entry point:
  73 int main(int argc, char* argv[])
  74 {
  75   return boost::unit_test::unit_test_main( &init_unit_test, argc, argv );
  76 }
  77 ```]
  78 [```#define BOOST_TEST_DYN_LINK
  79 #include <boost/test/unit_test.hpp>
  80
  81 //
  82 // test cases
  83 //
  84
  85 //
  86 // test cases
  87 //
  88
  89 //
  90 // test cases
  91 //
  92 ```]]
  93 ]
  94
  95 For reporting errors that may occur during the initialization,
  96
  97 * either you return `false` (valid only for the new API only, see __BOOST_TEST_ALTERNATIVE_INIT_API__)
  98 * or you raise an exception such as `std::runtime_error` or [classref boost::unit_test::framework::setup_error]
  99
 100 An error reported in this function aborts the execution of the test module.
 101
 102 [endsect] [/section:init_func]
 103
 104 [endsect] [/section:shared_lib_customizations]