libs/test/doc/usage_variants.qbk
[/ / Copyright (c) 2003 Boost.Test contributors / / Distributed under the Boost Software License, Version 1.0. (See accompanying / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) /] [section:usage_variants Usage variants] The __UTF__ supports three different usage variants: # [link boost_test.usage_variants.single_header The header-only variant] # [link boost_test.usage_variants.static_lib The static library variant] # [link boost_test.usage_variants.shared_lib 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. [/ ##################################################################### ] [h3:single_header Header-only usage variant] If you prefer to avoid the compilation of standalone library, you should use the header-only variant of the __UTF__. 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> `` __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. [link boost_test.adv_scenarios.single_header_customizations 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 [link boost_test.adv_scenarios.single_header_customizations.multiple_translation_units Header-only with multiple translation units]. [/ ##################################################################### ] [h3:static_lib Static library usage variant] For most users, who has an access to pre-built static library [footnote these files are distributed with the packaging systems on Linux and OSX for instance] of the __UTF__ or can [link boost_test.adv_scenarios.build_utf build it] themselves, following usage can be most versatile and simple approach. This usage variant entails two steps. # 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. # The second step is to link with the __UTF__ *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 __UTF__, which might be something you want to avoid (to save space for example). For more information about these configuration options check [link boost_test.adv_scenarios.static_lib_customizations this section]. [/ ##################################################################### ] [h3:shared_lib Shared library usage variant] In the project with large number of test modules the static library variant of the __UTF__ may cause you to waste a lot of disk space. The solution is to link test module dynamically with the __UTF__ 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 __UTF__ *shared* library. The flip side of this usage variant is that you will need to make sure the __UTF__ 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 [link boost_test.adv_scenarios.shared_lib_customizations this section]. [caution On Windows, the test module and the __UTF__ shared library should link to the same CRT. Not doing so (for instance __UTF__ shared library in /release/ mode while the test module is in /debug/) will lead to crashes.] [endsect] [/Usage Variants] [/ EOF]