103 lines
4.9 KiB
Plaintext
103 lines
4.9 KiB
Plaintext
[/
|
|
/ 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]
|