ae01c8387c
- section about command line argument filtering for template test cases - many typos fixes - remove reference to bjam
124 lines
4.2 KiB
Plaintext
124 lines
4.2 KiB
Plaintext
[/
|
|
/ Copyright (c) 2003 Boost.Test contributors
|
|
/
|
|
/ Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
/]
|
|
|
|
[section:static_lib_customizations Static-library variant customizations]
|
|
|
|
[section:entry_point Customizing the module's entry point]
|
|
|
|
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
|
|
|
|
```
|
|
> b2 --with-test link=static define=__BOOST_TEST_NO_MAIN__ define=__BOOST_TEST_ALTERNATIVE_INIT_API__ install
|
|
```
|
|
|
|
[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.]
|
|
|
|
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:
|
|
|
|
[table
|
|
[[In *exactly one* file][In all other files]]
|
|
[[```#define BOOST_TEST_MODULE test module name
|
|
#define BOOST_TEST_ALTERNATIVE_INIT_API
|
|
#include <boost/test/unit_test.hpp>
|
|
|
|
// entry point:
|
|
int main(int argc, char* argv[], char* envp[])
|
|
{
|
|
return utf::unit_test_main(init_unit_test, argc, argv);
|
|
}
|
|
```]
|
|
[```#include <boost/test/unit_test.hpp>
|
|
|
|
//
|
|
// test cases
|
|
//
|
|
|
|
//
|
|
// test cases
|
|
//
|
|
```]]
|
|
]
|
|
|
|
[note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described
|
|
[link boost_test.adv_scenarios.obsolete_init_func here].]
|
|
|
|
|
|
[endsect] [/section:entry_point]
|
|
|
|
[section:init_func Customizing the module's initialization function]
|
|
|
|
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
|
|
|
|
```
|
|
> b2 --with-test link=static define=__BOOST_TEST_ALTERNATIVE_INIT_API__ install
|
|
```
|
|
|
|
[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.]
|
|
|
|
In one of the source files, you now have to define your custom initialization function with signature:
|
|
|
|
```
|
|
bool init_unit_test();
|
|
```
|
|
|
|
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:
|
|
|
|
[table
|
|
[[In *exactly one* file][In all other files]]
|
|
[[```#define BOOST_TEST_ALTERNATIVE_INIT_API
|
|
#include <boost/test/unit_test.hpp>
|
|
|
|
// init func:
|
|
bool init_unit_test()
|
|
{
|
|
return true;
|
|
}
|
|
```]
|
|
[```#include <boost/test/unit_test.hpp>
|
|
|
|
//
|
|
// test cases
|
|
//
|
|
|
|
// test cases
|
|
//
|
|
```]]
|
|
]
|
|
|
|
For reporting errors that may occur during the initialization,
|
|
|
|
* either you return `false` (valid only for the new API only, see __BOOST_TEST_ALTERNATIVE_INIT_API__)
|
|
* or you raise an exception such as `std::runtime_error` or [classref boost::unit_test::framework::setup_error]
|
|
|
|
An error reported in this function aborts the execution of the test module.
|
|
|
|
|
|
[note The reason for defining __BOOST_TEST_ALTERNATIVE_INIT_API__ is described
|
|
[link boost_test.adv_scenarios.obsolete_init_func here].]
|
|
|
|
|
|
[endsect] [/section:init_func]
|
|
|
|
[endsect] [/section:static_lib_customizations]
|