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