1<a id="top"></a> 2# Compile-time configuration 3 4**Contents**<br> 5[main()/ implementation](#main-implementation)<br> 6[Reporter / Listener interfaces](#reporter--listener-interfaces)<br> 7[Prefixing Catch macros](#prefixing-catch-macros)<br> 8[Terminal colour](#terminal-colour)<br> 9[Console width](#console-width)<br> 10[stdout](#stdout)<br> 11[Fallback stringifier](#fallback-stringifier)<br> 12[Default reporter](#default-reporter)<br> 13[C++11 toggles](#c11-toggles)<br> 14[C++17 toggles](#c17-toggles)<br> 15[Other toggles](#other-toggles)<br> 16[Windows header clutter](#windows-header-clutter)<br> 17[Enabling stringification](#enabling-stringification)<br> 18[Disabling exceptions](#disabling-exceptions)<br> 19[Overriding Catch's debug break (`-b`)](#overriding-catchs-debug-break--b)<br> 20 21Catch 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```). 22 23Nonetheless 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. 24 25## main()/ implementation 26 27 CATCH_CONFIG_MAIN // Designates this as implementation file and defines main() 28 CATCH_CONFIG_RUNNER // Designates this as implementation file 29 30Although 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*. 31 32## Reporter / Listener interfaces 33 34 CATCH_CONFIG_EXTERNAL_INTERFACES // Brings in necessary headers for Reporter/Listener implementation 35 36Brings 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. 37 38Implied by both `CATCH_CONFIG_MAIN` and `CATCH_CONFIG_RUNNER`. 39 40## Prefixing Catch macros 41 42 CATCH_CONFIG_PREFIX_ALL 43 44To 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```). 45 46 47## Terminal colour 48 49 CATCH_CONFIG_COLOUR_NONE // completely disables all text colouring 50 CATCH_CONFIG_COLOUR_WINDOWS // forces the Win32 console API to be used 51 CATCH_CONFIG_COLOUR_ANSI // forces ANSI colour codes to be used 52 53Yes, I am English, so I will continue to spell "colour" with a 'u'. 54 55When 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. 56 57For 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): 58 59Note that when ANSI colour codes are used "unistd.h" must be includable - along with a definition of ```isatty()``` 60 61Typically 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. 62 63## Console width 64 65 CATCH_CONFIG_CONSOLE_WIDTH = x // where x is a number 66 67Catch 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. 68By default a console width of 80 is assumed but this can be controlled by defining the above identifier to be a different value. 69 70## stdout 71 72 CATCH_CONFIG_NOSTDOUT 73 74To support platforms that do not provide `std::cout`, `std::cerr` and 75`std::clog`, Catch does not usem the directly, but rather calls 76`Catch::cout`, `Catch::cerr` and `Catch::clog`. You can replace their 77implementation by defining `CATCH_CONFIG_NOSTDOUT` and implementing 78them yourself, their signatures are: 79 80 std::ostream& cout(); 81 std::ostream& cerr(); 82 std::ostream& clog(); 83 84[You can see an example of replacing these functions here.]( 85../examples/231-Cfg-OutputStreams.cpp) 86 87 88## Fallback stringifier 89 90By default, when Catch's stringification machinery has to stringify 91a type that does not specialize `StringMaker`, does not overload `operator<<`, 92is not an enumeration and is not a range, it uses `"{?}"`. This can be 93overridden by defining `CATCH_CONFIG_FALLBACK_STRINGIFIER` to name of a 94function that should perform the stringification instead. 95 96All types that do not provide `StringMaker` specialization or `operator<<` 97overload will be sent to this function (this includes enums and ranges). 98The provided function must return `std::string` and must accept any type, 99e.g. via overloading. 100 101_Note that if the provided function does not handle a type and this type 102requires to be stringified, the compilation will fail._ 103 104 105## Default reporter 106 107Catch's default reporter can be changed by defining macro 108`CATCH_CONFIG_DEFAULT_REPORTER` to string literal naming the desired 109default reporter. 110 111This means that defining `CATCH_CONFIG_DEFAULT_REPORTER` to `"console"` 112is equivalent with the out-of-the-box experience. 113 114 115## C++11 toggles 116 117 CATCH_CONFIG_CPP11_TO_STRING // Use `std::to_string` 118 119Because we support platforms whose standard library does not contain 120`std::to_string`, it is possible to force Catch to use a workaround 121based on `std::stringstream`. On platforms other than Android, 122the default is to use `std::to_string`. On Android, the default is to 123use the `stringstream` workaround. As always, it is possible to override 124Catch's selection, by defining either `CATCH_CONFIG_CPP11_TO_STRING` or 125`CATCH_CONFIG_NO_CPP11_TO_STRING`. 126 127 128## C++17 toggles 129 130 CATCH_CONFIG_CPP17_UNCAUGHT_EXCEPTIONS // Use std::uncaught_exceptions instead of std::uncaught_exception 131 CATCH_CONFIG_CPP17_STRING_VIEW // Override std::string_view support detection(Catch provides a StringMaker specialization by default) 132 CATCH_CONFIG_CPP17_VARIANT // Override std::variant support detection (checked by CATCH_CONFIG_ENABLE_VARIANT_STRINGMAKER) 133 CATCH_CONFIG_CPP17_OPTIONAL // Override std::optional support detection (checked by CATCH_CONFIG_ENABLE_OPTIONAL_STRINGMAKER) 134 CATCH_CONFIG_CPP17_BYTE // Override std::byte support detection (Catch provides a StringMaker specialization by default) 135 136> `CATCH_CONFIG_CPP17_STRING_VIEW` was [introduced](https://github.com/catchorg/Catch2/issues/1376) in Catch 2.4.1. 137 138Catch contains basic compiler/standard detection and attempts to use 139some C++17 features whenever appropriate. This automatic detection 140can be manually overridden in both directions, that is, a feature 141can be enabled by defining the macro in the table above, and disabled 142by using `_NO_` in the macro, e.g. `CATCH_CONFIG_NO_CPP17_UNCAUGHT_EXCEPTIONS`. 143 144 145## Other toggles 146 147 CATCH_CONFIG_COUNTER // Use __COUNTER__ to generate unique names for test cases 148 CATCH_CONFIG_WINDOWS_SEH // Enable SEH handling on Windows 149 CATCH_CONFIG_FAST_COMPILE // Sacrifices some (rather minor) features for compilation speed 150 CATCH_CONFIG_DISABLE_MATCHERS // Do not compile Matchers in this compilation unit 151 CATCH_CONFIG_POSIX_SIGNALS // Enable handling POSIX signals 152 CATCH_CONFIG_WINDOWS_CRTDBG // Enable leak checking using Windows's CRT Debug Heap 153 CATCH_CONFIG_DISABLE_STRINGIFICATION // Disable stringifying the original expression 154 CATCH_CONFIG_DISABLE // Disables assertions and test case registration 155 CATCH_CONFIG_WCHAR // Enables use of wchart_t 156 CATCH_CONFIG_EXPERIMENTAL_REDIRECT // Enables the new (experimental) way of capturing stdout/stderr 157 CATCH_CONFIG_ENABLE_BENCHMARKING // Enables the integrated benchmarking features (has a significant effect on compilation speed) 158 CATCH_CONFIG_USE_ASYNC // Force parallel statistical processing of samples during benchmarking 159 CATCH_CONFIG_ANDROID_LOGWRITE // Use android's logging system for debug output 160 CATCH_CONFIG_GLOBAL_NEXTAFTER // Use nextafter{,f,l} instead of std::nextafter 161 162> [`CATCH_CONFIG_ANDROID_LOGWRITE`](https://github.com/catchorg/Catch2/issues/1743) and [`CATCH_CONFIG_GLOBAL_NEXTAFTER`](https://github.com/catchorg/Catch2/pull/1739) were introduced in Catch 2.10.0 163 164Currently Catch enables `CATCH_CONFIG_WINDOWS_SEH` only when compiled with MSVC, because some versions of MinGW do not have the necessary Win32 API support. 165 166`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`). 167 168`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. 169 170`CATCH_CONFIG_WCHAR` is on by default, but can be disabled. Currently 171it is only used in support for DJGPP cross-compiler. 172 173With the exception of `CATCH_CONFIG_EXPERIMENTAL_REDIRECT`, 174these toggles can be disabled by using `_NO_` form of the toggle, 175e.g. `CATCH_CONFIG_NO_WINDOWS_SEH`. 176 177### `CATCH_CONFIG_FAST_COMPILE` 178This compile-time flag speeds up compilation of assertion macros by ~20%, 179by disabling the generation of assertion-local try-catch blocks for 180non-exception family of assertion macros ({`REQUIRE`,`CHECK`}{``,`_FALSE`, `_THAT`}). 181This disables translation of exceptions thrown under these assertions, but 182should not lead to false negatives. 183 184`CATCH_CONFIG_FAST_COMPILE` has to be either defined, or not defined, 185in all translation units that are linked into single test binary. 186 187### `CATCH_CONFIG_DISABLE_MATCHERS` 188When `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. 189 190_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._ 191 192### `CATCH_CONFIG_DISABLE_STRINGIFICATION` 193This 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). 194 195### `CATCH_CONFIG_DISABLE` 196This 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. 197 198This feature is considered experimental and might change at any point. 199 200_Inspired by Doctest's `DOCTEST_CONFIG_DISABLE`_ 201 202## Windows header clutter 203 204On 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: 205 206 CATCH_CONFIG_NO_NOMINMAX // Stops Catch from using NOMINMAX macro 207 CATCH_CONFIG_NO_WIN32_LEAN_AND_MEAN // Stops Catch from using WIN32_LEAN_AND_MEAN macro 208 209 210## Enabling stringification 211 212By 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: 213 214 CATCH_CONFIG_ENABLE_PAIR_STRINGMAKER // Provide StringMaker specialization for std::pair 215 CATCH_CONFIG_ENABLE_TUPLE_STRINGMAKER // Provide StringMaker specialization for std::tuple 216 CATCH_CONFIG_ENABLE_CHRONO_STRINGMAKER // Provide StringMaker specialization for std::chrono::duration, std::chrono::timepoint 217 CATCH_CONFIG_ENABLE_VARIANT_STRINGMAKER // Provide StringMaker specialization for std::variant, std::monostate (on C++17) 218 CATCH_CONFIG_ENABLE_OPTIONAL_STRINGMAKER // Provide StringMaker specialization for std::optional (on C++17) 219 CATCH_CONFIG_ENABLE_ALL_STRINGMAKERS // Defines all of the above 220 221> `CATCH_CONFIG_ENABLE_VARIANT_STRINGMAKER` was [introduced](https://github.com/catchorg/Catch2/issues/1380) in Catch 2.4.1. 222 223> `CATCH_CONFIG_ENABLE_OPTIONAL_STRINGMAKER` was [introduced](https://github.com/catchorg/Catch2/issues/1510) in Catch 2.6.0. 224 225## Disabling exceptions 226 227> Introduced in Catch 2.4.0. 228 229By default, Catch2 uses exceptions to signal errors and to abort tests 230when an assertion from the `REQUIRE` family of assertions fails. We also 231provide an experimental support for disabling exceptions. Catch2 should 232automatically detect when it is compiled with exceptions disabled, but 233it can be forced to compile without exceptions by defining 234 235 CATCH_CONFIG_DISABLE_EXCEPTIONS 236 237Note that when using Catch2 without exceptions, there are 2 major 238limitations: 239 2401) If there is an error that would normally be signalled by an exception, 241the exception's message will instead be written to `Catch::cerr` and 242`std::terminate` will be called. 2432) If an assertion from the `REQUIRE` family of macros fails, 244`std::terminate` will be called after the active reporter returns. 245 246 247There is also a customization point for the exact behaviour of what 248happens instead of exception being thrown. To use it, define 249 250 CATCH_CONFIG_DISABLE_EXCEPTIONS_CUSTOM_HANDLER 251 252and provide a definition for this function: 253 254```cpp 255namespace Catch { 256 [[noreturn]] 257 void throw_exception(std::exception const&); 258} 259``` 260 261## Overriding Catch's debug break (`-b`) 262 263> [Introduced](https://github.com/catchorg/Catch2/pull/1846) in Catch 2.11.2. 264 265You can override Catch2's break-into-debugger code by defining the 266`CATCH_BREAK_INTO_DEBUGGER()` macro. This can be used if e.g. Catch2 does 267not know your platform, or your platform is misdetected. 268 269The macro will be used as is, that is, `CATCH_BREAK_INTO_DEBUGGER();` 270must compile and must break into debugger. 271 272 273--- 274 275[Home](Readme.md#top) 276