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