Gitiles
Code Review Sign In
gerrit.cesnet.cz / github / onqtam / doctest / 7cd2fabc778b9e7c968acfcd0f26a48e449c3f97 / . / doc / html_generated / configuration.html
blob: 62f8863e6456b717cb1e2ad09b14a1e333b4df3a [file] [log] [blame]
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]1<!DOCTYPE html>
2<html>
3<title>configuration</title>
4<xmp theme="united" style="display:none;">
5
6## Configuration
7
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]8**doctest** is designed to "just work" as much as possible. It also allows configuring how it is built with a set of identifiers.
9
10The identifiers should be defined before the inclusion of the framework header.
11
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]12Defining something ```globally``` means for every source file of the binary (executable / shared object).
13
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]14- [**```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**](#doctest_config_implement_with_main)
15- [**```DOCTEST_CONFIG_IMPLEMENT```**](#doctest_config_implement)
16- [**```DOCTEST_CONFIG_DISABLE```**](#doctest_config_disable)
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]17- [**```DOCTEST_CONFIG_IMPLEMENTATION_IN_DLL```**](#doctest_config_implementation_in_dll)
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]18- [**```DOCTEST_CONFIG_NO_SHORT_MACRO_NAMES```**](#doctest_config_no_short_macro_names)
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]19- [**```DOCTEST_CONFIG_NUM_CAPTURES_ON_STACK```**](#doctest_config_num_captures_on_stack)
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]20- [**```DOCTEST_CONFIG_TREAT_CHAR_STAR_AS_STRING```**](#doctest_config_treat_char_star_as_string)
21- [**```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**](#doctest_config_super_fast_asserts)
22- [**```DOCTEST_CONFIG_USE_IOSFWD```**](#doctest_config_use_iosfwd)
23- [**```DOCTEST_CONFIG_NO_COMPARISON_WARNING_SUPPRESSION```**](#doctest_config_no_comparison_warning_suppression)
24- [**```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```**](#doctest_config_no_unprefixed_options)
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame]25- [**```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**](#doctest_config_no_try_catch_in_asserts)
26- [**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions)
27- [**```DOCTEST_CONFIG_NO_EXCEPTIONS_BUT_WITH_ALL_ASSERTS```**](#doctest_config_no_exceptions_but_with_all_asserts)
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]28- [**```DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE```**](#doctest_config_assertion_parameters_by_value)
29- [**```DOCTEST_CONFIG_COLORS_NONE```**](#doctest_config_colors_none)
30- [**```DOCTEST_CONFIG_COLORS_WINDOWS```**](#doctest_config_colors_windows)
31- [**```DOCTEST_CONFIG_COLORS_ANSI```**](#doctest_config_colors_ansi)
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]32- [**```DOCTEST_CONFIG_WINDOWS_SEH```**](#doctest_config_windows_seh)
33- [**```DOCTEST_CONFIG_NO_WINDOWS_SEH```**](#doctest_config_no_windows_seh)
34- [**```DOCTEST_CONFIG_POSIX_SIGNALS```**](#doctest_config_posix_signals)
35- [**```DOCTEST_CONFIG_NO_POSIX_SIGNALS```**](#doctest_config_no_posix_signals)
36
37Detection of modern C++ features:
38
39- [**```DOCTEST_CONFIG_WITH_DELETED_FUNCTIONS```**](#doctest_config_with_deleted_functions)
40- [**```DOCTEST_CONFIG_WITH_RVALUE_REFERENCES```**](#doctest_config_with_rvalue_references)
41- [**```DOCTEST_CONFIG_WITH_VARIADIC_MACROS```**](#doctest_config_with_variadic_macros)
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]42- [**```DOCTEST_CONFIG_WITH_NULLPTR```**](#doctest_config_with_nullptr)
43- [**```DOCTEST_CONFIG_WITH_LONG_LONG```**](#doctest_config_with_long_long)
44- [**```DOCTEST_CONFIG_WITH_STATIC_ASSERT```**](#doctest_config_with_static_assert)
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]45- [**```DOCTEST_CONFIG_NO_DELETED_FUNCTIONS```**](#doctest_config_no_deleted_functions)
46- [**```DOCTEST_CONFIG_NO_RVALUE_REFERENCES```**](#doctest_config_no_rvalue_references)
47- [**```DOCTEST_CONFIG_NO_VARIADIC_MACROS```**](#doctest_config_no_variadic_macros)
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]48- [**```DOCTEST_CONFIG_NO_NULLPTR```**](#doctest_config_no_nullptr)
49- [**```DOCTEST_CONFIG_NO_LONG_LONG```**](#doctest_config_no_long_long)
50- [**```DOCTEST_CONFIG_NO_STATIC_ASSERT```**](#doctest_config_no_static_assert)
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]51
52For most people the only configuration needed is telling **doctest** which source file should host all the implementation code:
53
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]54### **```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]55
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]56```
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]57#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN
58#include "doctest.h"
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]59```
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]60
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]61This should be defined only in the source file where the library is implemented.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]62
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]63### **```DOCTEST_CONFIG_IMPLEMENT```**
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]64
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]65If the client wants to [**supply the ```main()``` function**](main.html) (either to set an option with some value from the code or to integrate the framework into his existing project codebase) this identifier should be used.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]66
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]67This should be defined only in the source file where the library is implemented. It also creates a ```main()``` entry point.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]68
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]69### **```DOCTEST_CONFIG_DISABLE```**
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]70
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]71One of the most most important configuration option - everything testing-related is removed from the binary - including most of the framework implementation and every test case written anywhere! This is one of the most unique features of **doctest**.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]72
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]73This should be defined globally.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]74
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]75### **```DOCTEST_CONFIG_IMPLEMENTATION_IN_DLL```**
76
77This will affect the public interface of doctest - all necessary forward declarations for writing tests will be turned into imported symbols. That way the test runner doesn't have to be implemented in the binary (executable / shared object) and can be reused from another binary where it is built and exported.
78
79To export the test runner from a binary simply use [**```DOCTEST_CONFIG_IMPLEMENTATION_IN_DLL```**](#doctest_config_implementation_in_dll) together with [**```DOCTEST_CONFIG_IMPLEMENT```**](#doctest_config_implement) (or [**```DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN```**](#doctest_config_implement_with_main) but then the other binaries will have to link to the executable) in whatever source file the test runner gets implemented into. Note that this identifier should not be defined in the other source files of the binary which exports the doctest test runner - or there will be linker conflicts - having the same symbols as both imported and exported within the same binary.
80
81Checkout the [**example**](../../examples/executable_dll_and_plugin/) - it shows how to have the test runner implemented in a dll (and there are even tests in a plugin which is dynamically loaded).
82
83This should be defined globally in binaries that import the symbols.
84
85This should be defined only in the source file where the library is implemented for binaries that export the test runner.
86
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]87### **```DOCTEST_CONFIG_NO_SHORT_MACRO_NAMES```**
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]88
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]89This will remove all macros from **doctest** that don't have the **```DOCTEST_```** prefix - like **```CHECK```**, **```TEST_CASE```** and **```SUBCASE```**. Then only the full macro names will be available - **```DOCTEST_CHECK```**, **```DOCTEST_TEST_CASE```** and **```DOCTEST_SUBCASE```**. The user is free to make his own short versions of these macros - [**example**](../../examples/all_features/alternative_macros.cpp).
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]90
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]91This can be defined both globally and in specific source files only.
92
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]93### **```DOCTEST_CONFIG_NUM_CAPTURES_ON_STACK```**
94
95With this identifier the user may configure the number of captures on the stack by the ```INFO()``` [**logging macros**](logging.html) (read there for more info). The default is ```5``` - which means that for a call like this: ```INFO(var1 << "la la" << var2);``` all 3 logged variables will be captured on the stack (with the ability to hold 2 more - so no heap allocation unless an assert fails later in the same scope) - and a total of ```5 * (sizeof(void*) * 2))``` bytes are used on the stack for captures. A subsequent call to ```INFO()``` will have it's own stack space. Note that ```0``` is an invalid value. Examples:
96
97```
98#define DOCTEST_CONFIG_NUM_CAPTURES_ON_STACK 10
99#include <doctest.h>
100```
101
102or through the command line: ```-DDOCTEST_CONFIG_NUM_CAPTURES_ON_STACK=10```
103
104This should be defined globally.
105
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]106### **```DOCTEST_CONFIG_TREAT_CHAR_STAR_AS_STRING```**
107
108By default ```char*``` is being treated as a pointer. With this option comparing ```char*``` pointers will switch to using ```strcmp()``` for comparisons and when stringified the string will be printed instead of the pointer value.
109
110This should be defined globally.
111
112### **```DOCTEST_CONFIG_SUPER_FAST_ASSERTS```**
113
114This makes the fast assert macros (```FAST_CHECK_EQ(a,b)``` - with a ```FAST_``` prefix) compile [**even faster**](benchmarks.html#cost-of-an-assertion-macro)! (35-80%)
115
116Each fast assert is turned into a single function call - the only downside of this is: if an assert fails and a debugger is attached - when it breaks it will be in an internal function - the user will have to go 1 level up in the callstack to see the actual assert.
117
118This can be defined both globally and in specific source files only.
119
120### **```DOCTEST_CONFIG_USE_IOSFWD```**
121
122The library by default provides a forward declaration of ```std::ostream``` in order to support the ```operator<<``` [**stringification**](stringification.html) mechanism. This is forbidden by the standard (even though it works everywhere on all tested compilers). However if the user wishes to be 100% standards compliant - then this configuration option can be used to force the inclusion of ```<iosfwd>```.
123
124Also it is possible that some STL implementation of a compiler with niche usage defines them differently - then there will be compilation errors in STL headers and using this option should fix the problem.
125
126This should be defined globally.
127
128### **```DOCTEST_CONFIG_NO_COMPARISON_WARNING_SUPPRESSION```**
129
130By default the library suppresses warnings about comparing signed and unsigned types, etc.
131
132- g++/clang ```-Wsign-conversion```
133- g++/clang ```-Wsign-compare```
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]134- msvc ```C4389``` 'operator' : signed/unsigned mismatch
135- msvc ```C4018``` 'expression' : signed/unsigned mismatch
136
137You can checkout [**this**](https://github.com/onqtam/doctest/issues/16#issuecomment-246803303) issue to better understand why I suppress these warnings by default.
138
139This can be defined both globally and in specific source files only.
140
141### **```DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS```**
142
143This will disable the short versions of the [**command line**](commandline.html) options and only the versions with ```--dt-``` prefix will be parsed by **doctest** - this is possible for easy interoperability with client command line option handling when the testing framework is integrated within a client codebase - so there are no clashes and so that the user can exclude everything starting with ```--dt-``` from their option parsing.
144
145This should be defined only in the source file where the library is implemented (it's relevant only there).
146
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame]147### **```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**
148
149This will remove all ```try``` / ```catch``` sections from:
150
151- the [normal asserts](assertions.html#expression-decomposing-asserts)
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]152- the [binary and unary asserts](assertions.html#binary-and-unary-asserts) - making them functionally the same as the [**fast asserts**](assertions.html#fast-asserts) (but not for compile time speed)
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame]153
154so exceptions thrown while evaluating the expression in an assert will terminate the current test case.
155
156This can be defined both globally and in specific source files only.
157
158### **```DOCTEST_CONFIG_NO_EXCEPTIONS```**
159
160This will remove everything that uses exceptions from the framework - it is also auto detectable for some compilers (GCC, Clang) if exceptions are disabled with ```-fno-exceptions```. For MSVC ```_HAS_EXCEPTIONS``` cannot be used for auto detecting because it is defined in system headers instead of as a project define - and doctest will not include a header just for that.
161
162What gets changed:
163
164- asserts that evaluate the expression in a ```try``` / ```catch``` section no longer evaluate in such a context
165- ```REQUIRE``` macros are gone (undefined)
166- [exception macros](assertions.html#exceptions) are gone (undefined)
167- the ```abort-after``` option won't be fully working because an exception is used to terminate test cases
168
169The ```REQUIRE``` family of asserts uses exceptions to terminate the current test case when they fail. An exception is used instead of a simple ```return;``` because asserts can be used not only in a test case but also in functions called by a test case.
170
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]171Also some of the [**logging macros**](logging.html#messages-which-can-optionally-fail-test-cases) which act like a ```REQUIRE``` assert (terminating the test case) - like ```FAIL()``` - start to work differently - like a ```FAIL_CHECK()```.
172
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame]173[**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions) implies [**```DOCTEST_CONFIG_NO_TRY_CATCH_IN_ASSERTS```**](#doctest_config_no_try_catch_in_asserts)
174
175If you wish to use asserts that deal with exceptions and only sometimes build without exceptions - check the [**```DOCTEST_CONFIG_NO_EXCEPTIONS_BUT_WITH_ALL_ASSERTS```**](#doctest_config_no_exceptions_but_with_all_asserts) config option.
176
177This should be defined globally.
178
onqtame34600e2016-11-15 02:16:56 +0200[diff] [blame]179### **```DOCTEST_CONFIG_NO_EXCEPTIONS_BUT_WITH_ALL_ASSERTS```**
180
181When building with no exceptions (see [**```DOCTEST_CONFIG_NO_EXCEPTIONS```**](#doctest_config_no_exceptions)) ```REQUIRE``` asserts and the ones about dealing with exceptions are gone.
182
183If however you want your code to use these assertions and only sometimes build without exceptions - then using this config will be of help. The effects of using it are the following:
184
185- ```REQUIRE``` asserts are not gone - but they act like ```CHECK``` asserts - when one of them fails the whole test case will be marked as failed but will not be exited immediately
186- the [asserts for dealing with exceptions](assertions.html#exceptions) are turned into a no-op (instead of being totally undefined)
187
188This can be defined both globally and in specific source files only.
189
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]190### **```DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE```**
191
192This option forces all doctest asserts to copy by value the expressions they are given instead of binding them to const references. This might be useful to avoid ODR-usage of static constants (which might lead to linker errors with g++/clang):
193
194```
195template<typename T> struct type_traits { static const bool value = false; };
196
197// unless DOCTEST_CONFIG_ASSERTION_PARAMETERS_BY_VALUE is defined the following assertion
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]198// will lead to a linker error if type_traits<int>::value isn't defined in a translation unit
199CHECK(type_traits<int>::value == false);
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]200```
201
202This can be defined both globally and in specific source files only.
203
204### **```DOCTEST_CONFIG_COLORS_NONE```**
205
206This will remove support for colors in the console output of the framework.
207
208This should be defined only in the source file where the library is implemented (it's relevant only there).
209
210### **```DOCTEST_CONFIG_COLORS_WINDOWS```**
211
212This will force the support for colors in the console output to use the Windows APIs and headers.
213
214This should be defined only in the source file where the library is implemented (it's relevant only there).
215
216### **```DOCTEST_CONFIG_COLORS_ANSI```**
217
218This will force the support for colors in the console output to use ANSI escape codes.
219
220This should be defined only in the source file where the library is implemented (it's relevant only there).
221
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]222### **```DOCTEST_CONFIG_WINDOWS_SEH```**
223
224This will enable SEH handling on Windows. Currently enabled only when compiled with MSVC, because some versions of MinGW do not have the necessary Win32 API support. The user may choose to enable this explicitly - it is known to work with the MinGW-w64 project.
225
226This should be defined only in the source file where the library is implemented (it's relevant only there).
227
228### **```DOCTEST_CONFIG_NO_WINDOWS_SEH```**
229
230This can be used to disable **```DOCTEST_CONFIG_WINDOWS_SEH```** when it is auto-selected by the library.
231
232This should be defined only in the source file where the library is implemented (it's relevant only there).
233
234### **```DOCTEST_CONFIG_POSIX_SIGNALS```**
235
236This will enable the use of signals under UNIX for handling crashes. On by default.
237
238This should be defined only in the source file where the library is implemented (it's relevant only there).
239
240### **```DOCTEST_CONFIG_NO_POSIX_SIGNALS```**
241
242This can be used to disable **```DOCTEST_CONFIG_POSIX_SIGNALS```** when it is auto-selected by the library.
243
244This should be defined only in the source file where the library is implemented (it's relevant only there).
245
246### **```DOCTEST_CONFIG_WITH_DELETED_FUNCTIONS```**
247
248doctest tries to detect if c++11 deleted functions are available but if it doesn't detect it - the user might define this.
249
250This should be defined globally.
251
252### **```DOCTEST_CONFIG_WITH_RVALUE_REFERENCES```**
253
254doctest tries to detect if c++11 rvalue references are available but if it doesn't detect it - the user might define this.
255
256This should be defined globally.
257
258### **```DOCTEST_CONFIG_WITH_VARIADIC_MACROS```**
259
260doctest tries to detect if c++11 variadic macros are available but if it doesn't detect it - the user might define this.
261
262This can be defined both globally and in specific source files only.
263
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]264### **```DOCTEST_CONFIG_WITH_NULLPTR```**
265
266doctest tries to detect if c++11 ```nullptr``` is available but if it doesn't detect it - the user might define this.
267
268This should be defined globally.
269
270### **```DOCTEST_CONFIG_WITH_LONG_LONG```**
271
272doctest tries to detect if c++11 ```long long``` is available but if it doesn't detect it - the user might define this.
273
274This should be defined globally.
275
276### **```DOCTEST_CONFIG_WITH_STATIC_ASSERT```**
277
278doctest tries to detect if c++11 ```static_assert()``` is available but if it doesn't detect it - the user might define this.
279
280This should be defined globally.
281
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]282### **```DOCTEST_CONFIG_NO_DELETED_FUNCTIONS```**
283
284If doctest detects c++11 deleted functions support as available but the user knows better - this can be defined to disable it.
285
286This should be defined globally.
287
288### **```DOCTEST_CONFIG_NO_RVALUE_REFERENCES```**
289
290If doctest detects c++11 rvalue references support as available but the user knows better - this can be defined to disable it.
291
292This should be defined globally.
293
294### **```DOCTEST_CONFIG_NO_VARIADIC_MACROS```**
295
296If doctest detects c++11 variadic macros support as available but the user knows better - this can be defined to disable it.
297
298This can be defined both globally and in specific source files only.
299
onqtam1435c012016-09-21 15:29:11 +0300[diff] [blame]300### **```DOCTEST_CONFIG_NO_NULLPTR```**
301
302If doctest detects c++11 ```nullptr``` support as available but the user knows better - this can be defined to disable it.
303
304This should be defined globally.
305
306### **```DOCTEST_CONFIG_NO_LONG_LONG```**
307
308If doctest detects c++11 ```long long``` support as available but the user knows better - this can be defined to disable it.
309
310This should be defined globally.
311
312### **```DOCTEST_CONFIG_NO_STATIC_ASSERT```**
313
314If doctest detects c++11 ```static_assert()``` support as available but the user knows better - this can be defined to disable it.
315
316This should be defined globally.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]317
318---------------
319
320[Home](readme.html#reference)
321
322
323</xmp>
324<script src="strapdown.js/strapdown.js"></script>
325</html>