Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

Usage variants

The Unit Test Framework supports three different usage variants:

  1. The header-only variant
  2. The static library variant
  3. The shared library variant

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.

Header-only usage variant

If you prefer to avoid the compilation of standalone library, you should use the header-only variant of the Unit Test Framework. This variant only requires you to include the unique 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 the following:

#define BOOST_TEST_MODULE test module name
#include <boost/test/included/unit_test.hpp> /* path is different than the other variants! */

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

This section gives additional details on how to customize this usage variant. In particular, it is possible to have several compilation units with this variant, as explained in the section Header-only with multiple translation units.

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.

  1. First, the following line needs to be added to all translation units in the test module:

    #include <boost/test/unit_test.hpp>
    

    One 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 indicate the name of the test module. This name can include spaces and does not need to be wrapped in quotes.

  2. The second step is to link with the Unit Test Framework static library.
[Note] 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 want 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.

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

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


PrevUpHomeNext