[/
 / 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]