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