]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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:obsolete_init_func The obsolete initialization function] | |
9 | ||
10 | For backwards compatibility, the __UTF__ also allows the customization of an initialization function of a different type. | |
11 | This is called the ['obsolete initialization function]. Its signature is: | |
12 | ||
13 | ``` | |
14 | boost::unit_test::test_suite* init_unit_test_suite(int argc, char* argv[]); | |
15 | ``` | |
16 | ||
17 | The original design of the __UTF__ required of the programmer to implement it. It was intended to initialize and return | |
18 | the __master_test_suite__. No [link ref_BOOST_AUTO_TEST_CASE automatic test case registration] was available at that | |
19 | time. The null-pointer value was considered an initialization error. | |
20 | ||
21 | In the single-header usage variant, you fall back to the obsolete initialization function signature by omitting the | |
22 | definition of macro __BOOST_TEST_ALTERNATIVE_INIT_API__ in test module code. | |
23 | ||
24 | [bt_example custom_obsolete_init..using obsolete initialization function..run-fail] | |
25 | ||
26 | In the static-library usage variant, you need to omit the definition of macro __BOOST_TEST_ALTERNATIVE_INIT_API__ in test | |
27 | module and compile the __UTF__ static library without the compilation flag __BOOST_TEST_ALTERNATIVE_INIT_API__ (this is | |
28 | the default). | |
29 | ||
30 | In the shared-library usage variant, it is not possible to use the obsolete initialization function. | |
31 | ||
32 | Even if you decide to us the obsolete initialization function, it is recommended that: | |
33 | ||
34 | # You always return a null-pointer value and install the master test suite via | |
35 | [memberref boost::unit_test::test_suite::add `test_suite::add`] as illustrated | |
36 | [link ref_BOOST_TEST_CASE here]. The current framework does no longer treat the | |
37 | null-pointer value as failure. | |
38 | # You signal the failure by throwing [classref boost::unit_test::framework::setup_error] exception. | |
39 | # You access the command-line arguments through the interface of the __master_test_suite__, | |
40 | and ignore the function's arguments `argc` and `argv`. | |
41 | ||
42 | [caution The obsolete initialization function is deprecated. It is recommended, to move from the old initialization | |
43 | function API, and rely on the automated test unit registration and [link boost_test.tests_organization.fixtures | |
44 | fixtures] (including [link boost_test.tests_organization.fixtures.global global fixtures]) for other set-up. ] | |
45 | ||
46 | [endsect] [/section:obsolete_init_func] |