Test module initialization

Legacy initialization function
Initialization function
Automated generation

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 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 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.

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
  }
}