2017-08-24 15:21:36 +02:00
< a id = "top" > < / a >
2017-08-24 22:21:54 +02:00
# Compile-time configuration
2017-10-13 11:14:37 +02:00
**Contents**< br >
[main()/ implementation ](#main-implementation )< br >
2018-09-09 16:16:49 +02:00
[Reporter / Listener interfaces ](#reporter--listener-interfaces )< br >
2017-10-13 11:14:37 +02:00
[Prefixing Catch macros ](#prefixing-catch-macros )< br >
[Terminal colour ](#terminal-colour )< br >
[Console width ](#console-width )< br >
[stdout ](#stdout )< br >
2018-02-11 16:31:12 +01:00
[Fallback stringifier ](#fallback-stringifier )< br >
2018-02-11 18:10:28 +01:00
[Default reporter ](#default-reporter )< br >
2018-09-09 16:16:49 +02:00
[C++11 toggles ](#c11-toggles )< br >
[C++17 toggles ](#c17-toggles )< br >
2017-10-13 11:14:37 +02:00
[Other toggles ](#other-toggles )< br >
[Windows header clutter ](#windows-header-clutter )< br >
[Enabling stringification ](#enabling-stringification )< br >
2018-09-05 10:01:54 +02:00
[Disabling exceptions ](#disabling-exceptions )< br >
2017-08-28 22:42:26 +02:00
2014-10-21 19:25:57 +02:00
Catch is designed to "just work" as much as possible. For most people the only configuration needed is telling Catch which source file should host all the implementation code (```CATCH_CONFIG_MAIN```).
2017-02-06 01:43:53 +01:00
Nonetheless there are still some occasions where finer control is needed. For these occasions Catch exposes a set of macros for configuring how it is built.
2014-10-21 19:25:57 +02:00
2017-08-28 22:32:06 +02:00
## main()/ implementation
2014-10-21 19:25:57 +02:00
2018-08-28 16:17:37 +02:00
CATCH_CONFIG_MAIN // Designates this as implementation file and defines main()
CATCH_CONFIG_RUNNER // Designates this as implementation file
2014-10-21 19:25:57 +02:00
2014-12-17 19:16:24 +01:00
Although Catch is header only it still, internally, maintains a distinction between interface headers and headers that contain implementation. Only one source file in your test project should compile the implementation headers and this is controlled through the use of one of these macros - one of these identifiers should be defined before including Catch in *exactly one implementation file in your project* .
2018-09-09 16:16:49 +02:00
## Reporter / Listener interfaces
2017-08-17 22:29:04 +02:00
2018-03-07 10:08:35 +01:00
CATCH_CONFIG_EXTERNAL_INTERFACES // Brings in necessary headers for Reporter/Listener implementation
2017-08-17 22:29:04 +02:00
Brings in various parts of Catch that are required for user defined Reporters and Listeners. This means that new Reporters and Listeners can be defined in this file as well as in the main file.
Implied by both `CATCH_CONFIG_MAIN` and `CATCH_CONFIG_RUNNER` .
2017-08-28 22:32:06 +02:00
## Prefixing Catch macros
2014-12-17 19:16:24 +01:00
2018-08-28 16:17:37 +02:00
CATCH_CONFIG_PREFIX_ALL
2014-12-17 19:16:24 +01:00
To keep test code clean and uncluttered Catch uses short macro names (e.g. ```TEST_CASE``` and ```REQUIRE```). Occasionally these may conflict with identifiers from platform headers or the system under test. In this case the above identifier can be defined. This will cause all the Catch user macros to be prefixed with ```CATCH_``` (e.g. ```CATCH_TEST_CASE``` and ```CATCH_REQUIRE```).
2014-10-21 19:25:57 +02:00
2014-12-17 19:16:24 +01:00
2017-08-28 22:32:06 +02:00
## Terminal colour
2014-10-21 19:25:57 +02:00
2018-08-28 16:17:37 +02:00
CATCH_CONFIG_COLOUR_NONE // completely disables all text colouring
CATCH_CONFIG_COLOUR_WINDOWS // forces the Win32 console API to be used
CATCH_CONFIG_COLOUR_ANSI // forces ANSI colour codes to be used
2014-10-21 19:25:57 +02:00
2014-12-17 19:16:24 +01:00
Yes, I am English, so I will continue to spell "colour" with a 'u'.
When sending output to the terminal, if it detects that it can, Catch will use colourised text. On Windows the Win32 API, ```SetConsoleTextAttribute```, is used. On POSIX systems ANSI colour escape codes are inserted into the stream.
For finer control you can define one of the above identifiers (these are mutually exclusive - but that is not checked so may behave unexpectedly if you mix them):
2014-10-21 19:25:57 +02:00
Note that when ANSI colour codes are used "unistd.h" must be includable - along with a definition of ```isatty()```
Typically you should place the ```#define``` before #including "catch.hpp" in your main source file - but if you prefer you can define it for your whole project by whatever your IDE or build system provides for you to do so.
2017-08-28 22:32:06 +02:00
## Console width
2014-12-17 19:16:24 +01:00
2018-08-28 16:17:37 +02:00
CATCH_CONFIG_CONSOLE_WIDTH = x // where x is a number
2014-12-17 19:16:24 +01:00
Catch formats output intended for the console to fit within a fixed number of characters. This is especially important as indentation is used extensively and uncontrolled line wraps break this.
By default a console width of 80 is assumed but this can be controlled by defining the above identifier to be a different value.
2017-08-28 22:32:06 +02:00
## stdout
2014-12-17 19:16:24 +01:00
2018-08-28 16:17:37 +02:00
CATCH_CONFIG_NOSTDOUT
2014-12-17 19:16:24 +01:00
2018-07-08 13:58:44 +02:00
To support platforms that do not provide `std::cout` , `std::cerr` and
`std::clog` , Catch does not usem the directly, but rather calls
`Catch::cout` , `Catch::cerr` and `Catch::clog` . You can replace their
implementation by defining `CATCH_CONFIG_NOSTDOUT` and implementing
them yourself, their signatures are:
2014-12-17 19:16:24 +01:00
std::ostream& cout();
std::ostream& cerr();
2017-08-10 16:43:17 +02:00
std::ostream& clog();
2014-12-17 19:16:24 +01:00
2018-07-08 13:58:44 +02:00
[You can see an example of replacing these functions here.](
../examples/231-Cfg-OutputStreams.cpp)
2014-12-17 19:16:24 +01:00
2017-04-25 15:57:47 +02:00
2018-02-11 16:31:12 +01:00
## Fallback stringifier
2018-05-14 21:03:07 +02:00
By default, when Catch's stringification machinery has to stringify
a type that does not specialize `StringMaker` , does not overload `operator<<` ,
is not an enumeration and is not a range, it uses `"{?}"` . This can be
2019-04-08 23:30:28 +02:00
overridden by defining `CATCH_CONFIG_FALLBACK_STRINGIFIER` to name of a
2018-05-14 21:03:07 +02:00
function that should perform the stringification instead.
All types that do not provide `StringMaker` specialization or `operator<<`
overload will be sent to this function (this includes enums and ranges).
The provided function must return `std::string` and must accept any type,
e.g. via overloading.
2018-02-11 16:31:12 +01:00
_Note that if the provided function does not handle a type and this type
requires to be stringified, the compilation will fail._
2017-04-05 09:53:10 +02:00
2018-02-11 18:10:28 +01:00
## Default reporter
Catch's default reporter can be changed by defining macro
`CATCH_CONFIG_DEFAULT_REPORTER` to string literal naming the desired
default reporter.
This means that defining `CATCH_CONFIG_DEFAULT_REPORTER` to `"console"`
is equivalent with the out-of-the-box experience.
2018-05-09 20:16:27 +02:00
## C++11 toggles
CATCH_CONFIG_CPP11_TO_STRING // Use `std::to_string`
Because we support platforms whose standard library does not contain
`std::to_string` , it is possible to force Catch to use a workaround
based on `std::stringstream` . On platforms other than Android,
the default is to use `std::to_string` . On Android, the default is to
use the `stringstream` workaround. As always, it is possible to override
Catch's selection, by defining either `CATCH_CONFIG_CPP11_TO_STRING` or
`CATCH_CONFIG_NO_CPP11_TO_STRING` .
2018-02-25 21:22:38 +01:00
## C++17 toggles
CATCH_CONFIG_CPP17_UNCAUGHT_EXCEPTIONS // Use std::uncaught_exceptions instead of std::uncaught_exception
2019-07-26 21:40:58 +02:00
CATCH_CONFIG_CPP17_STRING_VIEW // Override std::string_view support detection(Catch provides a StringMaker specialization by default)
2019-07-26 21:35:35 +02:00
CATCH_CONFIG_CPP17_VARIANT // Override std::variant support detection (checked by CATCH_CONFIG_ENABLE_VARIANT_STRINGMAKER)
CATCH_CONFIG_CPP17_OPTIONAL // Override std::optional support detection (checked by CATCH_CONFIG_ENABLE_OPTIONAL_STRINGMAKER)
2019-07-26 21:40:58 +02:00
CATCH_CONFIG_CPP17_BYTE // Override std::byte support detection (Catch provides a StringMaker specialization by default)
2018-02-25 21:22:38 +01:00
2019-07-22 14:02:01 +02:00
> `CATCH_CONFIG_CPP17_STRING_VIEW` was [introduced](https://github.com/catchorg/Catch2/issues/1376) in Catch 2.4.1.
2018-02-25 21:22:38 +01:00
Catch contains basic compiler/standard detection and attempts to use
some C++17 features whenever appropriate. This automatic detection
can be manually overridden in both directions, that is, a feature
can be enabled by defining the macro in the table above, and disabled
by using `_NO_` in the macro, e.g. `CATCH_CONFIG_NO_CPP17_UNCAUGHT_EXCEPTIONS` .
2017-08-28 22:32:06 +02:00
## Other toggles
2017-02-06 01:43:53 +01:00
CATCH_CONFIG_COUNTER // Use __COUNTER__ to generate unique names for test cases
CATCH_CONFIG_WINDOWS_SEH // Enable SEH handling on Windows
2017-03-17 17:02:39 +01:00
CATCH_CONFIG_FAST_COMPILE // Sacrifices some (rather minor) features for compilation speed
2017-07-28 21:34:34 +02:00
CATCH_CONFIG_DISABLE_MATCHERS // Do not compile Matchers in this compilation unit
2017-02-15 17:57:22 +01:00
CATCH_CONFIG_POSIX_SIGNALS // Enable handling POSIX signals
2017-02-16 11:09:09 +01:00
CATCH_CONFIG_WINDOWS_CRTDBG // Enable leak checking using Windows's CRT Debug Heap
2017-08-26 15:14:27 +02:00
CATCH_CONFIG_DISABLE_STRINGIFICATION // Disable stringifying the original expression
2017-08-27 17:03:32 +02:00
CATCH_CONFIG_DISABLE // Disables assertions and test case registration
2018-03-01 18:41:17 +01:00
CATCH_CONFIG_WCHAR // Enables use of wchart_t
Add an experimental new way of capturing stdout/stderr
Unlike the relatively non-invasive old way of capturing stdout/stderr,
this new way is also able to capture output from C's stdlib functions
such as `printf`. This is done by redirecting stdout and stderr file
descriptors to a file, and then reading this file back.
This approach has two sizeable drawbacks:
1) Performance, obviously. Previously an installed capture made the
program run faster (as long as it was then discarded), because a call
to `std::cout` did not result in text output to the console. This new
capture method in fact forces disk IO. While it is likely that any
modern OS will keep this file in memory-cache and might never actually
issue the IO to the backing storage, it is still a possibility and
calls to the file system are not free.
2) Nonportability. While POSIX is usually assumed portable, and this
implementation relies only on a very common parts of it, it is no
longer standard C++ (or just plain C) and thus might not be available
on some obscure platforms. Different C libs might also implement the
relevant functions in a less-than-useful ways (e.g. MS's `tmpfile`
generates a temp file inside system folder, so it will not work
without elevated privileges and thus is useless).
These two drawbacks mean that, at least for now, the new capture is
opt-in. To opt-in, `CATCH_CONFIG_EXPERIMENTAL_REDIRECT` needs to be
defined in the implementation file.
Closes #1243
2018-04-29 22:14:41 +02:00
CATCH_CONFIG_EXPERIMENTAL_REDIRECT // Enables the new (experimental) way of capturing stdout/stderr
2019-05-19 20:54:44 +02:00
CATCH_CONFIG_ENABLE_BENCHMARKING // Enables the integrated benchmarking features (has a significant effect on compilation speed)
2019-06-15 12:50:36 +02:00
CATCH_CONFIG_USE_ASYNC // Force parallel statistical processing of samples during benchmarking
2019-09-06 12:41:42 +02:00
CATCH_CONFIG_ANDROID_LOGWRITE // Use android's logging system for debug output
2019-09-06 13:08:44 +02:00
CATCH_CONFIG_GLOBAL_NEXTAFTER // Use nextafter{,f,l} instead of std::nextafter
2019-09-06 12:41:42 +02:00
2019-09-06 13:08:44 +02:00
> `CATCH_CONFIG_ANDROID_LOGWRITE` and `CATCH_CONFIG_GLOBAL_NEXTAFTER` were [introduced](https://github.com/catchorg/Catch2/issues/1743) in Catch X.Y.Z
2017-02-06 01:43:53 +01:00
2017-02-15 17:57:22 +01:00
Currently Catch enables `CATCH_CONFIG_WINDOWS_SEH` only when compiled with MSVC, because some versions of MinGW do not have the necessary Win32 API support.
2017-02-06 01:43:53 +01:00
2017-02-15 17:57:22 +01:00
`CATCH_CONFIG_POSIX_SIGNALS` is on by default, except when Catch is compiled under `Cygwin` , where it is disabled by default (but can be force-enabled by defining `CATCH_CONFIG_POSIX_SIGNALS` ).
2017-02-15 10:42:11 +01:00
2017-02-18 17:24:31 +01:00
`CATCH_CONFIG_WINDOWS_CRTDBG` is off by default. If enabled, Windows's CRT is used to check for memory leaks, and displays them after the tests finish running.
2017-02-16 11:09:09 +01:00
2018-03-01 18:41:17 +01:00
`CATCH_CONFIG_WCHAR` is on by default, but can be disabled. Currently
it is only used in support for DJGPP cross-compiler.
Add an experimental new way of capturing stdout/stderr
Unlike the relatively non-invasive old way of capturing stdout/stderr,
this new way is also able to capture output from C's stdlib functions
such as `printf`. This is done by redirecting stdout and stderr file
descriptors to a file, and then reading this file back.
This approach has two sizeable drawbacks:
1) Performance, obviously. Previously an installed capture made the
program run faster (as long as it was then discarded), because a call
to `std::cout` did not result in text output to the console. This new
capture method in fact forces disk IO. While it is likely that any
modern OS will keep this file in memory-cache and might never actually
issue the IO to the backing storage, it is still a possibility and
calls to the file system are not free.
2) Nonportability. While POSIX is usually assumed portable, and this
implementation relies only on a very common parts of it, it is no
longer standard C++ (or just plain C) and thus might not be available
on some obscure platforms. Different C libs might also implement the
relevant functions in a less-than-useful ways (e.g. MS's `tmpfile`
generates a temp file inside system folder, so it will not work
without elevated privileges and thus is useless).
These two drawbacks mean that, at least for now, the new capture is
opt-in. To opt-in, `CATCH_CONFIG_EXPERIMENTAL_REDIRECT` needs to be
defined in the implementation file.
Closes #1243
2018-04-29 22:14:41 +02:00
With the exception of `CATCH_CONFIG_EXPERIMENTAL_REDIRECT` ,
these toggles can be disabled by using `_NO_` form of the toggle,
e.g. `CATCH_CONFIG_NO_WINDOWS_SEH` .
2017-02-06 01:43:53 +01:00
2017-08-28 22:32:06 +02:00
### `CATCH_CONFIG_FAST_COMPILE`
2018-06-30 12:31:46 +02:00
This compile-time flag speeds up compilation of assertion macros by ~20%,
by disabling the generation of assertion-local try-catch blocks for
non-exception family of assertion macros ({`REQUIRE`,`CHECK`}{``,`_FALSE`, `_THAT` }).
This disables translation of exceptions thrown under these assertions, but
should not lead to false negatives.
`CATCH_CONFIG_FAST_COMPILE` has to be either defined, or not defined,
in all translation units that are linked into single test binary.
2017-03-17 17:02:39 +01:00
2017-08-28 22:32:06 +02:00
### `CATCH_CONFIG_DISABLE_MATCHERS`
2017-07-28 21:34:34 +02:00
When `CATCH_CONFIG_DISABLE_MATCHERS` is defined, all mentions of Catch's Matchers are ifdef-ed away from the translation unit. Doing so will speed up compilation of that TU.
_Note: If you define `CATCH_CONFIG_DISABLE_MATCHERS` in the same file as Catch's main is implemented, your test executable will fail to link if you use Matchers anywhere._
2017-08-28 22:32:06 +02:00
### `CATCH_CONFIG_DISABLE_STRINGIFICATION`
2017-10-14 08:36:44 +02:00
This toggle enables a workaround for VS 2017 bug. For details see [known limitations ](limitations.md#visual-studio-2017----raw-string-literal-in-assert-fails-to-compile ).
2017-07-28 21:34:34 +02:00
2017-08-28 22:32:06 +02:00
### `CATCH_CONFIG_DISABLE`
2017-08-27 17:03:32 +02:00
This toggle removes most of Catch from given file. This means that `TEST_CASE` s are not registered and assertions are turned into no-ops. Useful for keeping tests within implementation files (ie for functions with internal linkage), instead of in external files.
This feature is considered experimental and might change at any point.
_Inspired by Doctest's `DOCTEST_CONFIG_DISABLE` _
2017-08-28 22:32:06 +02:00
## Windows header clutter
2016-12-16 14:46:26 +01:00
On Windows Catch includes `windows.h` . To minimize global namespace clutter in the implementation file, it defines `NOMINMAX` and `WIN32_LEAN_AND_MEAN` before including it. You can control this behaviour via two macros:
CATCH_CONFIG_NO_NOMINMAX // Stops Catch from using NOMINMAX macro
CATCH_CONFIG_NO_WIN32_LEAN_AND_MEAN // Stops Catch from using WIN32_LEAN_AND_MEAN macro
2017-10-09 12:31:22 +02:00
## Enabling stringification
By default, Catch does not stringify some types from the standard library. This is done to avoid dragging in various standard library headers by default. However, Catch does contain these and can be configured to provide them, using these macros:
2019-01-31 15:36:48 +01:00
CATCH_CONFIG_ENABLE_PAIR_STRINGMAKER // Provide StringMaker specialization for std::pair
CATCH_CONFIG_ENABLE_TUPLE_STRINGMAKER // Provide StringMaker specialization for std::tuple
CATCH_CONFIG_ENABLE_CHRONO_STRINGMAKER // Provide StringMaker specialization for std::chrono::duration, std::chrono::timepoint
CATCH_CONFIG_ENABLE_VARIANT_STRINGMAKER // Provide StringMaker specialization for std::variant, std::monostate (on C++17)
CATCH_CONFIG_ENABLE_OPTIONAL_STRINGMAKER // Provide StringMaker specialization for std::optional (on C++17)
CATCH_CONFIG_ENABLE_ALL_STRINGMAKERS // Defines all of the above
2017-10-09 12:31:22 +02:00
2019-07-22 14:02:01 +02:00
> `CATCH_CONFIG_ENABLE_VARIANT_STRINGMAKER` was [introduced](https://github.com/catchorg/Catch2/issues/1380) in Catch 2.4.1.
2019-07-22 13:31:33 +02:00
> `CATCH_CONFIG_ENABLE_OPTIONAL_STRINGMAKER` was [introduced](https://github.com/catchorg/Catch2/issues/1510) in Catch 2.6.0.
2017-10-09 12:31:22 +02:00
2018-09-03 18:41:20 +02:00
## Disabling exceptions
2019-07-22 14:20:25 +02:00
> Introduced in Catch 2.4.0.
2018-09-03 18:41:20 +02:00
By default, Catch2 uses exceptions to signal errors and to abort tests
when an assertion from the `REQUIRE` family of assertions fails. We also
provide an experimental support for disabling exceptions. Catch2 should
automatically detect when it is compiled with exceptions disabled, but
it can be forced to compile without exceptions by defining
CATCH_CONFIG_DISABLE_EXCEPTIONS
Note that when using Catch2 without exceptions, there are 2 major
limitations:
1) If there is an error that would normally be signalled by an exception,
the exception's message will instead be written to `Catch::cerr` and
`std::terminate` will be called.
2) If an assertion from the `REQUIRE` family of macros fails,
`std::terminate` will be called after the active reporter returns.
There is also a customization point for the exact behaviour of what
happens instead of exception being thrown. To use it, define
CATCH_CONFIG_DISABLE_EXCEPTIONS_CUSTOM_HANDLER
and provide a definition for this function:
```cpp
namespace Catch {
[[noreturn]]
void throw_exception(std::exception const&);
}
```
2014-10-21 19:25:57 +02:00
---
2017-08-24 15:33:38 +02:00
[Home ](Readme.md#top )