Boost C++ Libraries

libs/test/doc/adv_scenarios/static_lib_customizations.qbk

[/
 / 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]