1[/ 2 / Copyright (c) 2003 Boost.Test team 3 / 4 / Distributed under the Boost Software License, Version 1.0. (See accompanying 5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 /] 7 8[section:usage_variants Usage variants] 9 10The __UTF__ supports three different usage variants: 11 12# [link boost_test.usage_variants.single_header The single-header variant] 13# [link boost_test.usage_variants.static_lib The static library variant] 14# [link boost_test.usage_variants.shared_lib The shared library variant] 15 16In most cases you shouldn't have problems deciding which one to use, since there are 17clear reasons why would you prefer each one. Following sections should help you with the decision. 18 19[/ ##################################################################### ] 20[h3:single_header Single-header usage variant] 21 22If you prefer to avoid the compilation of standalone library, you should use the 23single-header variant of the __UTF__. This variant only requires you to include, 24as it follows from its name, the single header: `#include <boost/test/included/unit_test.hpp>` 25and there is no need to link with any library. There are several ways to perform 26the initialization, but the simplest way is this: 27`` 28 #define __BOOST_TEST_MODULE__ test module name 29 #include <boost/test/included/unit_test.hpp> 30`` 31__BOOST_TEST_MODULE__ macro needs to be defined *before* the include and should be set to 32test module name. This name can include spaces and does not need to be wrapped in quotes. 33 34The limitation of single header variant is that you can only implement this way 35test modules with a single translation unit. 36 37For more details on customization for this usage variant you can check [link 38boost_test.adv_scenarios.single_header_customizations this section]. 39 40[/ ##################################################################### ] 41[h3:static_lib Static library usage variant] 42For most users, who has an access to pre-built static library [footnote these files are distributed 43with the packaging systems on Linux and OSX for instance] of the __UTF__ or can 44[link boost_test.adv_scenarios.build_utf build it] themselves, following usage can be most versatile 45 and simple approach. This usage variant entails two steps. 46 47# First you need to add following line to all translation units in a test module: 48 `` 49 #include <boost/test/unit_test.hpp> 50 `` 51 and *only one* translation unit should include following lines 52 `` 53 #define __BOOST_TEST_MODULE__ test module name 54 #include <boost/test/unit_test.hpp> 55 `` 56 __BOOST_TEST_MODULE__ macro needs to be defined *before* the include and should be set to 57 test module name. This name can include spaces and does not need to be wrapped in quotes. 58# The second step is to link with the __UTF__ static library. 59 60[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.] 61 62The flip side of this usage variant is that each test module following this usage variant is going 63to be statically linked with __UTF__, which might be something you interested to avoid (to save space 64for example). For more information about these configuration options check 65[link boost_test.adv_scenarios.static_lib_customizations this section]. 66 67[/ ##################################################################### ] 68[h3:shared_lib Shared library usage variant] 69In the project with large number of test modules the static library variant of the __UTF__ may 70cause you to waste a lot of disk space. The solution is to link test module dynamically with the 71__UTF__ built as a shared library. 72This usage variant entails two steps. 73 74# First you need to add following lines to all translation units in a test module: 75 `` 76 #define __BOOST_TEST_DYN_LINK__ 77 #include <boost/test/unit_test.hpp> 78 `` 79 and *only one* translation unit should include following lines 80 `` 81 #define __BOOST_TEST_MODULE__ test module name 82 #define __BOOST_TEST_DYN_LINK__ 83 #include <boost/test/unit_test.hpp> 84 `` 85 `BOOST_TEST_MODULE` and `BOOST_TEST_DYN_LINK` macros needs to be defined *before* the include. 86 `BOOST_TEST_MODULE` should be set to test module name. This name can include spaces and does 87 not need to be wrapped in quotes. 88 89# The second step is to link with the __UTF__ shared library. 90 91The flip side of this usage variant is that you will need to make sure the __UTF__ shared library 92is accessible at runtime to a test module. 93 94In addition shared library usage variant facilitates custom test runners. For more information about this 95check [link boost_test.adv_scenarios.shared_lib_customizations this section]. 96 97[caution On Windows, the test module and the __UTF__ shared library should link to the same CRT. Not doing 98 so (for instance __UTF__ shared library in /release/ mode while the test module is in /debug/) will 99 lead to crashes.] 100 101[endsect] [/Usage Variants] 102 103[/ EOF] 104