Usage variants

The Unit Test Framework supports three different usage variants:

In most cases you shouldn't have problems deciding which one to use, since there are clear reasons why would you prefer each one. Following sections should help you with the decision.

If you prefer to avoid the compilation of standalone library, you should use the single-header variant of the Unit Test Framework. This variant only requires you to include, as it follows from its name, the single header: #include <boost/test/included/unit_test.hpp> and there is no need to link with any library. There are several ways to perform the initialization, but the simplest way is this:

#define BOOST_TEST_MODULE test module name
#include <boost/test/included/unit_test.hpp>

BOOST_TEST_MODULE macro needs to be defined before the include and should be set to test module name. This name can include spaces and does not need to be wrapped in quotes.

The limitation of single header variant is that you can only implement this way test modules with a single translation unit.

For more details on customization for this usage variant you can check this section.

Static library usage variant

For most users, who has an access to pre-built static library ^[1] of the Unit Test Framework or can build it themselves, following usage can be most versatile and simple approach. This usage variant entails two steps.

First you need to add following line to all translation units in a test module:
```
#include <boost/test/unit_test.hpp>
```
and only one translation unit should include following lines
```
#define BOOST_TEST_MODULE test module name
#include <boost/test/unit_test.hpp>
```
BOOST_TEST_MODULE macro needs to be defined before the include and should be set to test module name. This name can include spaces and does not need to be wrapped in quotes.
The second step is to link with the Unit Test Framework static library.

	Note
	Header `<boost/test/unit_test.hpp>` is an 'aggregate' header: it includes most of the other headers that contains the Unit Test Framework definitions.

The flip side of this usage variant is that each test module following this usage variant is going to be statically linked with Unit Test Framework, which might be something you interested to avoid (to save space for example). For more information about these configuration options check this section.

Shared library usage variant

In the project with large number of test modules the static library variant of the Unit Test Framework may cause you to waste a lot of disk space. The solution is to link test module dynamically with the Unit Test Framework built as a shared library. This usage variant entails two steps.

First you need to add following lines to all translation units in a test module:
```
#define BOOST_TEST_DYN_LINK
#include <boost/test/unit_test.hpp>
```
and only one translation unit should include following lines
```
#define BOOST_TEST_MODULE test module name
#define BOOST_TEST_DYN_LINK
#include <boost/test/unit_test.hpp>
```
BOOST_TEST_MODULE and BOOST_TEST_DYN_LINK macros needs to be defined before the include. BOOST_TEST_MODULE should be set to test module name. This name can include spaces and does not need to be wrapped in quotes.
The second step is to link with the Unit Test Framework shared library.

The flip side of this usage variant is that you will need to make sure the Unit Test Framework shared library is accessible at runtime to a test module.

In addition shared library usage variant facilitates custom test runners. For more information about this check this section.

	Caution
	On Windows, the test module and the Unit Test Framework shared library should link to the same CRT. Not doing so (for instance Unit Test Framework shared library in release mode while the test module is in debug) will lead to crashes.

^[1] these files are distributed with the packaging systems on Linux and OSX for instance

Boost C++ Libraries

Usage variants

Single-header usage variant

Static library usage variant

Shared library usage variant