configuration.md
1 <a id="top"></a> 2 # Compile-time configuration 3 4 **Contents**<br> 5 [Prefixing Catch macros](#prefixing-catch-macros)<br> 6 [Terminal colour](#terminal-colour)<br> 7 [Console width](#console-width)<br> 8 [stdout](#stdout)<br> 9 [Fallback stringifier](#fallback-stringifier)<br> 10 [Default reporter](#default-reporter)<br> 11 [Bazel support](#bazel-support)<br> 12 [C++11 toggles](#c11-toggles)<br> 13 [C++17 toggles](#c17-toggles)<br> 14 [Other toggles](#other-toggles)<br> 15 [Enabling stringification](#enabling-stringification)<br> 16 [Disabling exceptions](#disabling-exceptions)<br> 17 [Overriding Catch's debug break (`-b`)](#overriding-catchs-debug-break--b)<br> 18 [Static analysis support](#static-analysis-support)<br> 19 20 Catch2 is designed to "just work" as much as possible, and most of the 21 configuration options below are changed automatically during compilation, 22 according to the detected environment. However, this detection can also 23 be overridden by users, using macros documented below, and/or CMake options 24 with the same name. 25 26 27 ## Prefixing Catch macros 28 29 CATCH_CONFIG_PREFIX_ALL // Prefix all macros with CATCH_ 30 CATCH_CONFIG_PREFIX_MESSAGES // Prefix only INFO, UNSCOPED_INFO, WARN and CAPTURE 31 32 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```). 33 34 35 ## Terminal colour 36 37 CATCH_CONFIG_COLOUR_WIN32 // Force enables compiling colouring impl based on Win32 console API 38 CATCH_CONFIG_NO_COLOUR_WIN32 // Force disables ... 39 40 Yes, Catch2 uses the british spelling of colour. 41 42 Catch2 attempts to autodetect whether the Win32 console colouring API, 43 `SetConsoleTextAttribute`, is available, and if it is available it compiles 44 in a console colouring implementation that uses it. 45 46 This option can be used to override Catch2's autodetection and force the 47 compilation either ON or OFF. 48 49 50 ## Console width 51 52 CATCH_CONFIG_CONSOLE_WIDTH = x // where x is a number 53 54 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. 55 By default a console width of 80 is assumed but this can be controlled by defining the above identifier to be a different value. 56 57 ## stdout 58 59 CATCH_CONFIG_NOSTDOUT 60 61 To support platforms that do not provide `std::cout`, `std::cerr` and 62 `std::clog`, Catch does not use them directly, but rather calls 63 `Catch::cout`, `Catch::cerr` and `Catch::clog`. You can replace their 64 implementation by defining `CATCH_CONFIG_NOSTDOUT` and implementing 65 them yourself, their signatures are: 66 67 std::ostream& cout(); 68 std::ostream& cerr(); 69 std::ostream& clog(); 70 71 [You can see an example of replacing these functions here.]( 72 ../examples/231-Cfg-OutputStreams.cpp) 73 74 75 ## Fallback stringifier 76 77 By default, when Catch's stringification machinery has to stringify 78 a type that does not specialize `StringMaker`, does not overload `operator<<`, 79 is not an enumeration and is not a range, it uses `"{?}"`. This can be 80 overridden by defining `CATCH_CONFIG_FALLBACK_STRINGIFIER` to name of a 81 function that should perform the stringification instead. 82 83 All types that do not provide `StringMaker` specialization or `operator<<` 84 overload will be sent to this function (this includes enums and ranges). 85 The provided function must return `std::string` and must accept any type, 86 e.g. via overloading. 87 88 _Note that if the provided function does not handle a type and this type 89 requires to be stringified, the compilation will fail._ 90 91 92 ## Default reporter 93 94 Catch's default reporter can be changed by defining macro 95 `CATCH_CONFIG_DEFAULT_REPORTER` to string literal naming the desired 96 default reporter. 97 98 This means that defining `CATCH_CONFIG_DEFAULT_REPORTER` to `"console"` 99 is equivalent with the out-of-the-box experience. 100 101 102 ## Bazel support 103 104 Compiling Catch2 with `CATCH_CONFIG_BAZEL_SUPPORT` force-enables Catch2's 105 support for Bazel's environment variables (normally Catch2 looks for 106 `BAZEL_TEST=1` env var first). 107 108 This can be useful if you are using older versions of Bazel, that do not 109 yet have `BAZEL_TEST` env var support. 110 111 > `CATCH_CONFIG_BAZEL_SUPPORT` was [introduced](https://github.com/catchorg/Catch2/pull/2399) in Catch2 3.0.1. 112 113 > `CATCH_CONFIG_BAZEL_SUPPORT` was [deprecated](https://github.com/catchorg/Catch2/pull/2459) in Catch2 3.1.0. 114 115 116 ## C++11 toggles 117 118 CATCH_CONFIG_CPP11_TO_STRING // Use `std::to_string` 119 120 Because we support platforms whose standard library does not contain 121 `std::to_string`, it is possible to force Catch to use a workaround 122 based on `std::stringstream`. On platforms other than Android, 123 the default is to use `std::to_string`. On Android, the default is to 124 use the `stringstream` workaround. As always, it is possible to override 125 Catch's selection, by defining either `CATCH_CONFIG_CPP11_TO_STRING` or 126 `CATCH_CONFIG_NO_CPP11_TO_STRING`. 127 128 129 ## C++17 toggles 130 131 CATCH_CONFIG_CPP17_UNCAUGHT_EXCEPTIONS // Override std::uncaught_exceptions (instead of std::uncaught_exception) support detection 132 CATCH_CONFIG_CPP17_STRING_VIEW // Override std::string_view support detection (Catch provides a StringMaker specialization by default) 133 CATCH_CONFIG_CPP17_VARIANT // Override std::variant support detection (checked by CATCH_CONFIG_ENABLE_VARIANT_STRINGMAKER) 134 CATCH_CONFIG_CPP17_OPTIONAL // Override std::optional support detection (checked by CATCH_CONFIG_ENABLE_OPTIONAL_STRINGMAKER) 135 CATCH_CONFIG_CPP17_BYTE // Override std::byte support detection (Catch provides a StringMaker specialization by default) 136 137 > `CATCH_CONFIG_CPP17_STRING_VIEW` was [introduced](https://github.com/catchorg/Catch2/issues/1376) in Catch2 2.4.1. 138 139 Catch contains basic compiler/standard detection and attempts to use 140 some C++17 features whenever appropriate. This automatic detection 141 can be manually overridden in both directions, that is, a feature 142 can be enabled by defining the macro in the table above, and disabled 143 by using `_NO_` in the macro, e.g. `CATCH_CONFIG_NO_CPP17_UNCAUGHT_EXCEPTIONS`. 144 145 146 ## Other toggles 147 148 CATCH_CONFIG_COUNTER // Use __COUNTER__ to generate unique names for test cases 149 CATCH_CONFIG_WINDOWS_SEH // Enable SEH handling on Windows 150 CATCH_CONFIG_FAST_COMPILE // Sacrifices some (rather minor) features for compilation speed 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_USE_ASYNC // Force parallel statistical processing of samples during benchmarking 158 CATCH_CONFIG_ANDROID_LOGWRITE // Use android's logging system for debug output 159 CATCH_CONFIG_GLOBAL_NEXTAFTER // Use nextafter{,f,l} instead of std::nextafter 160 CATCH_CONFIG_GETENV // System has a working `getenv` 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 Catch2 2.10.0 163 164 > `CATCH_CONFIG_GETENV` was [introduced](https://github.com/catchorg/Catch2/pull/2562) in Catch2 3.2.0 165 166 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. 167 168 `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`). 169 170 `CATCH_CONFIG_GETENV` is on by default, except when Catch2 is compiled for 171 platforms that lacks working `std::getenv` (currently Windows UWP and 172 Playstation). 173 174 `CATCH_CONFIG_WINDOWS_CRTDBG` is off by default. If enabled, Windows's 175 CRT is used to check for memory leaks, and displays them after the tests 176 finish running. This option only works when linking against the default 177 main, and must be defined for the whole library build. 178 179 `CATCH_CONFIG_WCHAR` is on by default, but can be disabled. Currently 180 it is only used in support for DJGPP cross-compiler. 181 182 With the exception of `CATCH_CONFIG_EXPERIMENTAL_REDIRECT`, 183 these toggles can be disabled by using `_NO_` form of the toggle, 184 e.g. `CATCH_CONFIG_NO_WINDOWS_SEH`. 185 186 ### `CATCH_CONFIG_FAST_COMPILE` 187 This compile-time flag speeds up compilation of assertion macros by ~20%, 188 by disabling the generation of assertion-local try-catch blocks for 189 non-exception family of assertion macros ({`REQUIRE`,`CHECK`}{``,`_FALSE`, `_THAT`}). 190 This disables translation of exceptions thrown under these assertions, but 191 should not lead to false negatives. 192 193 `CATCH_CONFIG_FAST_COMPILE` has to be either defined, or not defined, 194 in all translation units that are linked into single test binary. 195 196 ### `CATCH_CONFIG_DISABLE_STRINGIFICATION` 197 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). 198 199 ### `CATCH_CONFIG_DISABLE` 200 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. 201 202 This feature is considered experimental and might change at any point. 203 204 _Inspired by Doctest's `DOCTEST_CONFIG_DISABLE`_ 205 206 207 ## Enabling stringification 208 209 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: 210 211 CATCH_CONFIG_ENABLE_PAIR_STRINGMAKER // Provide StringMaker specialization for std::pair 212 CATCH_CONFIG_ENABLE_TUPLE_STRINGMAKER // Provide StringMaker specialization for std::tuple 213 CATCH_CONFIG_ENABLE_VARIANT_STRINGMAKER // Provide StringMaker specialization for std::variant, std::monostate (on C++17) 214 CATCH_CONFIG_ENABLE_OPTIONAL_STRINGMAKER // Provide StringMaker specialization for std::optional (on C++17) 215 CATCH_CONFIG_ENABLE_ALL_STRINGMAKERS // Defines all of the above 216 217 > `CATCH_CONFIG_ENABLE_VARIANT_STRINGMAKER` was [introduced](https://github.com/catchorg/Catch2/issues/1380) in Catch2 2.4.1. 218 219 > `CATCH_CONFIG_ENABLE_OPTIONAL_STRINGMAKER` was [introduced](https://github.com/catchorg/Catch2/issues/1510) in Catch2 2.6.0. 220 221 ## Disabling exceptions 222 223 > Introduced in Catch2 2.4.0. 224 225 By default, Catch2 uses exceptions to signal errors and to abort tests 226 when an assertion from the `REQUIRE` family of assertions fails. We also 227 provide an experimental support for disabling exceptions. Catch2 should 228 automatically detect when it is compiled with exceptions disabled, but 229 it can be forced to compile without exceptions by defining 230 231 CATCH_CONFIG_DISABLE_EXCEPTIONS 232 233 Note that when using Catch2 without exceptions, there are 2 major 234 limitations: 235 236 1) If there is an error that would normally be signalled by an exception, 237 the exception's message will instead be written to `Catch::cerr` and 238 `std::terminate` will be called. 239 2) If an assertion from the `REQUIRE` family of macros fails, 240 `std::terminate` will be called after the active reporter returns. 241 242 243 There is also a customization point for the exact behaviour of what 244 happens instead of exception being thrown. To use it, define 245 246 CATCH_CONFIG_DISABLE_EXCEPTIONS_CUSTOM_HANDLER 247 248 and provide a definition for this function: 249 250 ```cpp 251 namespace Catch { 252 [[noreturn]] 253 void throw_exception(std::exception const&); 254 } 255 ``` 256 257 ## Overriding Catch's debug break (`-b`) 258 259 > [Introduced](https://github.com/catchorg/Catch2/pull/1846) in Catch2 2.11.2. 260 261 You can override Catch2's break-into-debugger code by defining the 262 `CATCH_BREAK_INTO_DEBUGGER()` macro. This can be used if e.g. Catch2 does 263 not know your platform, or your platform is misdetected. 264 265 The macro will be used as is, that is, `CATCH_BREAK_INTO_DEBUGGER();` 266 must compile and must break into debugger. 267 268 269 ## Static analysis support 270 271 > Introduced in Catch2 3.4.0. 272 273 Some parts of Catch2, e.g. `SECTION`s, can be hard for static analysis 274 tools to reason about. Catch2 can change its internals to help static 275 analysis tools reason about the tests. 276 277 Catch2 automatically detects some static analysis tools (initial 278 implementation checks for clang-tidy and Coverity), but you can override 279 its detection (in either direction) via 280 281 ``` 282 CATCH_CONFIG_EXPERIMENTAL_STATIC_ANALYSIS_SUPPORT // force enables static analysis help 283 CATCH_CONFIG_NO_EXPERIMENTAL_STATIC_ANALYSIS_SUPPORT // force disables static analysis help 284 ``` 285 286 _As the name suggests, this is currently experimental, and thus we provide 287 no backwards compatibility guarantees._ 288 289 **DO NOT ENABLE THIS FOR BUILDS YOU INTEND TO RUN.** The changed internals 290 are not meant to be runnable, only "scannable". 291 292 293 294 --- 295 296 [Home](Readme.md#top)