libs/test/doc/adv_scenarios/link_reference.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
   9 [section:link_references Build scenarios and behaviors]
  10
  11 [/-----------------------------------------------------------------]
  12 [section:link_boost_test_main_macro `BOOST_TEST_MAIN`]
  13
  14 When defined, this macro creates a stub for the test module initialization (the main entry part). This
  15 macro also expands properly into a `main` function in case the shared library variant of the __UTF__ is used.
  16
  17
  18 [caution This macro should
  19
  20 # be defined before any inclusion directive to __UTF__ headers
  21 # be defined exactly for one compilation unit of your test module
  22
  23 ]
  24
  25 [tip The macro __BOOST_TEST_MODULE__ should be preferred]
  26
  27 [endsect]
  28
  29 [/-----------------------------------------------------------------]
  30 [section:link_boost_test_module_macro `BOOST_TEST_MODULE`]
  31 Serves the same purpose as the macro __BOOST_TEST_MAIN__ but, in addition, defines the name of the master test suite.
  32
  33 [caution As __BOOST_TEST_MAIN__, this macro should
  34
  35 # be defined before any inclusion directive to __UTF__ headers
  36 # be defined exactly for one compilation unit of your test module
  37
  38 ]
  39
  40 An example may be found [link ref_BOOST_TEST_MODULE here].
  41
  42 [endsect]
  43
  44 [/-----------------------------------------------------------------]
  45 [section:link_boost_test_alternative_init_macro `BOOST_TEST_ALTERNATIVE_INIT_API`]
  46
  47 [warning This macro should be defined before any include directive to the __UTF__ headers and is
  48 mutually exclusive with the __BOOST_TEST_MODULE__ macro.]
  49
  50 In case of custom initialization of the test module entry point, this macro indicates the __UTF__ to
  51 use the new API. The differences between the new and old APIs are described in [link
  52 boost_test.adv_scenarios.obsolete_init_func this section].
  53
  54 The way to customize the entry point of the test-module depends on the variant of the __UTF__ in use.
  55 Several sections in the documentation are devoted to this:
  56
  57 * [link boost_test.adv_scenarios.single_header_customizations.entry_point this section] for single header variant,
  58 * [link boost_test.adv_scenarios.static_lib_customizations.init_func this section] for static link variant,
  59 * [link boost_test.adv_scenarios.shared_lib_customizations.init_func this section] for shared link variant
  60
  61 [endsect]
  62
  63 [/-----------------------------------------------------------------]
  64 [section:link_boost_test_no_lib `BOOST_TEST_NO_LIB`]
  65 Define this flag to prevent auto-linking.
  66 [note The same flag is used for the __UTF__ and the __PEM__ components.]
  67 [endsect]
  68
  69 [/-----------------------------------------------------------------]
  70 [section:link_boost_test_dyn_link `BOOST_TEST_DYN_LINK`]
  71 Define this flag to link against the __UTF__ shared library.
  72 [note The same flag is used for the __UTF__ and the __PEM__ components.]
  73 [endsect]
  74
  75 [/-----------------------------------------------------------------]
  76 [section:link_boost_test_no_main `BOOST_TEST_NO_MAIN`]
  77 Prevents the auto generation of the test module initialization functions. This macro is particularly relevant for
  78 manually registered tests in conjunction with dynamic variant of the __UTF__. When defined, a `main` function
  79 registering all the tests should be implemented.
  80
  81 An example of a module initialization would be
  82 ``
  83 #define __BOOST_TEST_NO_MAIN__
  84 #include <boost/test/unit_test.hpp>
  85
  86 // a function in another compilation unit registering tests under the master test suite.
  87 void register_some_tests_manually(test_suite* test);
  88
  89 bool registering_all_tests()
  90 {
  91   test_suite* test_master_suite = &boost::unit_test::framework::master_test_suite();
  92   register_some_tests_manually(test_master_suite);
  93
  94   // register any other tests function or test suite to the master test suite
  95   // ...
  96   return true;
  97 }
  98
  99 int main(int argc, char* argv[])
 100 {
 101   return ::boost::unit_test::unit_test_main(&registering_all_tests, argc, argv);
 102 }
 103 ``
 104 [endsect]
 105
 106 [/-----------------------------------------------------------------]
 107 [section:link_boost_test_global_configuration `BOOST_TEST_GLOBAL_CONFIGURATION`]
 108 Declares a class that will be constructed during the initialization of the test framework, and destructed afterwards.
 109 The framework will not call any other member function than the constructor and destructor.
 110 In particular the constructor and destructor will be called prior and after to the [link boost_test.tests_organization.fixtures.global global fixtures]
 111 setup and teardown.
 112
 113 This facility is provided to perform additional configuration, in particular programmatic configuration
 114 of the loggers and reporters. See [link boost_test.test_output.logging_api this section] for more details.
 115
 116 [warning No logging or any other call to the framework assertion is allowed in the constructor and destructor, as its purpose is
 117  to set-up the loggers/reporters, and the assertions are calling the logging/reporting facility.
 118  Any such assertion during the execution of the will result in the abortion of the test module .]
 119
 120 [endsect]
 121
 122 [/-----------------------------------------------------------------]
 123 [section:config_disable_alt_stack `BOOST_TEST_DISABLE_ALT_STACK`]
 124 Disables the support of the alternative stack.
 125
 126 Define this macro before the inclusion of any __UTF__ header to disable the support
 127 of the [@http://www.gnu.org/software/libc/manual/html_node/Signal-Stack.html alternative stack],
 128 in case your compiler does not support it and the __UTF__ cannot automatically guess the lack of support.
 129
 130 See [link boost_test.utf_reference.rt_param_reference.use_alt_stack `use_alt_stack`]
 131 and [macroref BOOST_TEST_DISABLE_ALT_STACK `BOOST_TEST_DISABLE_ALT_STACK`] for more details.
 132 [endsect]
 133
 134 [endsect]