test/doc/v2/compilation/module_initialization.qbk

[section:module_initialization Test module initialization]
There are two tasks should be performed before actual testing is able to start:

* The test tree needs to be built: unless you are using automated test units registration, the tests that should be run and their relationship
  should be indicated.
* Custom ['test module initialization] needs to be performed. This includes
  initialization of the code under test and custom tune-up of the __UTF__ parameters (for example the test log or the
  test results report output streams redirection, some command line parameters passed to the test module, etc.).

The function dedicated for this purpose is called ['the test module initialization function]. 

[note Alternatively you can
employ global fixtures, covered in details, including differences in two approaches, in the [link boost_test.tests_organization.fixtures fixtures]
section.
]

The __UTF__ requires you to implement the test module initialization function. The test runner supplied with the static
library or single-header variants of the __UTF__ requires the specific function specification. The test runner supplied
with the dynamic library variant of the __UTF__ requires the specific initialization function signature only. 

[warning TO FIX: specific specification]

For many [link ref_test_module test modules], no custom initialization is required 
and test tree construction is automated. In this case, these initialization functions are not needed as
the __UTF__ provides a way to automatically generate an empty one.

Original design of the __UTF__ supported the manual test tree construction only. Later versions introduced the
automated registration of test units. In later versions of the __UTF__ the original initialization function
specification became inconvenient and unnecessary unsafe. So the alternative initialization function specification
was introduced. This change is not backward compatible. The test runners supplied with the static library and
single-header variants of the __UTF__ by default still require original initialization function specification, but
support <link linkend="utf.compilation.flags">compilation flags</link> that switch to the alternative one. The test
runner supplied with dynamic library variant of the __UTF__ requires new specification and doesn't support
original one. The plan is to deprecate the original initialization function specification in one of the future
releases and ultimately to stop supporting it.

[important 
The initialization function invocation is monitored by the __UTF__ the same way as all the test cases. An unexpected 
exception or system error detected during initialization function invocation is treated as initialization error and 
is reported as such. 
]

[/ ###################################################################################################### ]
[section Legacy initialization function]
The original design of the __UTF__ initialization required you to implement the function with the following
specification:

``
  boost::unit_test::test_suite* init_unit_test_suite(int argc, char* argv[]);
``


This function was intended to initialize and return a master test suite. The null value was considered an initialization 
error. The current design of the __UTF__ maintains master test suite instance internally and does not treat the null result 
value as an initialization error. In fact it's recommended to return null value always and register test units in the 
master test suite using the regular test suite add interface. The only way to indicate an initialization error is to throw the
[classref boost::unit_test::framework::setup_error] exception.

The initialization function parameters argc, argv provide the command line arguments specified during test
module invocation. It's guarantied that any framework-specific command line arguments are excluded. To be
consisted with the alternative initialization function specification it's recommended though to access the
command line arguments using the master test suite interface.

[endsect] [/ legacy init function]


[/ ###################################################################################################### ]
[section Initialization function]
The alternative design of the __UTF__ initialization requires you to implement a function with the following
specification:
``
  bool init_unit_test();
``

The result value of this function indicates whether or not initialization was successful. To register test
units in a master test suite use the test suite add interface. To access command line arguments use the master
test suite interface. It's guarantied that any framework-specific command line arguments are excluded.
[endsect] [/ alternative init function]


[/ ###################################################################################################### ]
[heading Initialization function signature access]

The test runner interface needs to refer to the initialization function signature. The __UTF__ provides the typedef 
that resolves to proper signature in all configurations:

``
namespace boost {
  namespace unit_test {
#ifdef __BOOST_TEST_ALTERNATIVE_INIT_API__
    typedef bool        (*init_unit_test_func)();
#else
    typedef test_suite* (*init_unit_test_func)( int, char* [] );
#endif
  }
}
``

[/[endsect] [/ signatures]]


[/ ###################################################################################################### ]
[section Automated generation]

To automatically generate an empty test module initialization function you need to define 
__BOOST_TEST_MAIN__ before including the
``boost/test/unit_test.hpp`` header. The value of this define is ignored.
Alternatively you can define the macro __BOOST_TEST_MODULE__ to be equal to 
any string (not necessarily in quotes). This macro causes the same result as 
__BOOST_TEST_MAIN__, and in addition the macro value becomes the name of the 
master test suite.

[important
For a test module consisting of multiple source files you have to define these flags in a single test file only.
Otherwise you end up with multiple instances of the initialization function.
]
   
[endsect] [/ automated generation]

[endsect] [/ test module initialisation]