libs/test/doc/usage_variants.qbk

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