mirror of
https://github.com/boostorg/test.git
synced 2026-01-29 20:12:09 +00:00
159 lines
9.1 KiB
XML
159 lines
9.1 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../../tools/boostbook/dtd/boostbook.dtd" [
|
|
<!ENTITY utf "<acronym>UTF</acronym>">
|
|
]>
|
|
<section id="utf.user-guide.usage-variants">
|
|
<title>The &utf; usage variants … or the <ulink url="http://en.wikipedia.org/wiki/Buridan's_ass">Buridan's donkey</ulink> parable</title>
|
|
<titleabbrev>Usage variants</titleabbrev>
|
|
|
|
<para role="first-line-indented">
|
|
The &utf; presents you with 4 different variants how it can be used.
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara><link linkend="utf.user-guide.static-lib-variant">The static library variant</link></simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><link linkend="utf.user-guide.dynamic-lib-variant">The dynamic library variant</link></simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><link linkend="utf.user-guide.single-header-variant">The single-header variant</link></simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><link linkend="utf.user-guide.extern-test-runner-variant">The external test runner variant</link></simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para role="first-line-indented">
|
|
Unlike the Buridan's donkey though, you shouldn't have problems deciding which one to use, since there are
|
|
clear reasons why would you prefer each one.
|
|
</para>
|
|
|
|
<para role="first-line-indented">
|
|
In most cases to compile a test module based on the &utf; all you need to include is just the single header
|
|
<filename class="headerfile">boost/test/unit_test.hpp</filename>. This header includes internally most of the other
|
|
headers that contains the &utf; definitions. Some advanced features, like the floating point comparison or the
|
|
logged expectations testing, are defined in independent headers and need to be included explicitly.
|
|
</para>
|
|
|
|
<section id="utf.user-guide.static-lib-variant">
|
|
<title>The static library variant of the &utf;</title><titleabbrev>Static library</titleabbrev>
|
|
<para role="first-line-indented">
|
|
The &utf; can be built into a static library. If you opt to link a test module with the
|
|
<link linkend="utf.compilation.standalone">standalone static library</link>, this usage is called the static library
|
|
variant of the &utf;.
|
|
</para>
|
|
|
|
<para role="first-line-indented">
|
|
The test runner supplied with this variant required you to implement the <link linkend="test-module.def">test
|
|
module</link> initialization function that matches one of the two specifications depending on the compilation flag
|
|
<xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/>. If flag isn't defined you are required
|
|
to match the original specification. If you define the flag <xref linkend="utf.flag.alt-init-api"
|
|
endterm="utf.flag.alt-init-api"/> during a test module compilation you are required to use the alternative
|
|
initialization function specification. The &utf; provides an ability to
|
|
<link linkend="utf.user-guide.initialization.auto-generation">automatically generate</link> an empty test module
|
|
initialization function with correct specification if no custom initialization is required by a test module.
|
|
</para>
|
|
|
|
<important>
|
|
<simpara>
|
|
If you opted to use an alternative initialization API, for a test module to be able to link with prebuilt library,
|
|
the flag <xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/> has to be defined both during
|
|
library and a test module compilation.
|
|
</simpara>
|
|
</important>
|
|
</section>
|
|
|
|
<section id="utf.user-guide.dynamic-lib-variant">
|
|
<title>The dynamic library variant of the &utf;</title>
|
|
<titleabbrev>Dynamic library</titleabbrev>
|
|
|
|
<para role="first-line-indented">
|
|
In the project with large number of test modules <link linkend="utf.user-guide.dynamic-lib-variant">the static
|
|
library</link> variant of the &utf; may cause you to waste a lot of disk space, since the &utf; is linked
|
|
statically with every test module. The solution is to link with the &utf; built into a dynamic library. If you opt
|
|
to link a test module with the prebuilt dynamic library, this usage is called the dynamic library variant of the
|
|
&utf;. This variant requires you to define the flag <xref linkend="utf.flag.dyn-link" endterm="utf.flag.dyn-link"/>
|
|
either in a makefile or before the header <filename class="headerfile">boost/test/unit_test.hpp</filename>
|
|
inclusion.
|
|
</para>
|
|
|
|
<para role="first-line-indented">
|
|
The test runner supplied with this variant requires you to implement the <link linkend="test-module.def">test
|
|
module</link> initialization function that matches the alternative initialization function signature. The &utf;
|
|
provides an ability to <link linkend="utf.user-guide.initialization.auto-generation">automatically generate</link>
|
|
an empty test module initialization function with correct signature if no custom initialization is required by a
|
|
test module.
|
|
</para>
|
|
|
|
<note>
|
|
<simpara>
|
|
The name of the test module initialization function is not enforced, since the function is passed as an argument
|
|
to the test runner.
|
|
</simpara>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="utf.user-guide.single-header-variant">
|
|
<title>The single-header variant of the &utf;</title>
|
|
<titleabbrev>Single header</titleabbrev>
|
|
|
|
<para role="first-line-indented">
|
|
If you prefer to avoid the <link linkend="utf.compilation.standalone">standalone library compilation</link>, you
|
|
should use the single-header variant of the &utf;. This variant is implemented, as it follows from its name, in
|
|
the single header <filename class="headerfile">boost/test/included/unit_test.hpp</filename>. An inclusion of
|
|
the header causes the complete implementation of the &utf; to be included as a part of a test module's
|
|
source file. The header <filename class="headerfile">boost/test/unit_test.hpp</filename> doesn't have to be
|
|
included anymore. You don't have to worry about disabling <link linkend="utf.compilation.auto-linking">
|
|
auto-linking</link> feature either. It's done in the implementation header already. This variant
|
|
can't be used with the <xref linkend="multi-file-test-module.def" endterm="multi-file-test-module.def"/>.
|
|
Otherwise it's almost identical from the usage prospective to the static library variant of the &utf;.
|
|
In fact the only difference is the name of the include file:
|
|
<filename class="headerfile">boost/test/included/unit_test.hpp</filename> instead of
|
|
<filename class="headerfile">boost/test/unit_test.hpp</filename>.
|
|
</para>
|
|
|
|
<para role="first-line-indented">
|
|
The test runner supplied with this variant requires you to implement the <link linkend="test-module.def">test
|
|
module</link> initialization function that matches one of the two specifications depending on the compilation flag
|
|
<xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/>. If flag isn't defined you are required to
|
|
match the original specification. If you define the flag
|
|
<xref linkend="utf.flag.alt-init-api" endterm="utf.flag.alt-init-api"/> during a test module compilation you are
|
|
required to use the alternative initialization function specification. The &utf; provides an ability to
|
|
<link linkend="utf.user-guide.initialization.auto-generation">automatically generate</link> an empty test module
|
|
initialization function with correct specification if no custom initialization is required by a test module.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="utf.user-guide.extern-test-runner-variant">
|
|
<title>The external test runner variant of the &utf;</title>
|
|
<titleabbrev>External test runner</titleabbrev>
|
|
|
|
<para role="first-line-indented">
|
|
All other usage variants employ the build-in test runners. If you plan to use an external test runner with your
|
|
test module you need to build it as a dynamic library. This usage of the &utf; is called the external test runner
|
|
variant of the &utf;. The variant requires you to define the flag
|
|
<xref linkend="utf.flag.dyn-link" endterm="utf.flag.dyn-link"/> either in a makefile or before the header
|
|
<filename class="headerfile">boost/test/unit_test.hpp</filename> inclusion. An external test runner utility is
|
|
required to link with dynamic library.
|
|
</para>
|
|
|
|
<para role="first-line-indented">
|
|
If an external test runner is based on the test runner built in to the dynamic library (like the standalone
|
|
boost_test_runner utility supplied by the &utf;), it requires you to implement the <link linkend="test-module.def">
|
|
test module</link> initialization function that matches the alternative initialization function signature. The
|
|
&utf; provides an ability to <link linkend="utf.user-guide.initialization.auto-generation">automatically generate
|
|
</link> an empty test module initialization function with correct signature if no custom initialization is required
|
|
by a test module.
|
|
</para>
|
|
|
|
<note>
|
|
<simpara>
|
|
An advanced test runner doesn't have to be based on the build-in one and may require a different
|
|
test module initialization function signature and/or name.
|
|
</simpara>
|
|
</note>
|
|
</section>
|
|
</section>
|