docs/configuration.md

   1 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```).
   2
   3 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.
   4
   5 #  main()/ implementation
   6
   7         CATCH_CONFIG_MAIN       // Designates this as implementation file and defines main()
   8         CATCH_CONFIG_RUNNER     // Designates this as implementation file
   9
  10 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*.
  11
  12 #  Prefixing Catch macros
  13
  14         CATCH_CONFIG_PREFIX_ALL
  15
  16 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```).
  17
  18
  19 #  Terminal colour
  20
  21         CATCH_CONFIG_COLOUR_NONE        // completely disables all text colouring
  22         CATCH_CONFIG_COLOUR_WINDOWS     // forces the Win32 console API to be used
  23         CATCH_CONFIG_COLOUR_ANSI        // forces ANSI colour codes to be used
  24
  25 Yes, I am English, so I will continue to spell "colour" with a 'u'.
  26
  27 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.
  28
  29 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):
  30
  31 Note that when ANSI colour codes are used "unistd.h" must be includable - along with a definition of ```isatty()```
  32
  33 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.
  34
  35 #  Console width
  36
  37         CATCH_CONFIG_CONSOLE_WIDTH = x // where x is a number
  38
  39 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.
  40 By default a console width of 80 is assumed but this can be controlled by defining the above identifier to be a different value.
  41
  42 #  stdout
  43
  44         CATCH_CONFIG_NOSTDOUT
  45
  46 Catch does not use ```std::cout```, ```std::cerr``` and ```std::clog``` directly but gets them from ```Catch::cout()```, ```Catch::cerr()``` and ```Catch::clog``` respectively. If the above identifier is defined these functions are left unimplemented and you must implement them yourself. Their signatures are:
  47
  48     std::ostream& cout();
  49     std::ostream& cerr();
  50     std::ostream& clog();
  51
  52 This can be useful on certain platforms that do not provide the standard iostreams, such as certain embedded systems.
  53
  54 # Default reporter
  55
  56     CATCH_CONFIG_DEFAULT_REPORTER <reporter>
  57
  58 The default reporter (reporter used when no reporters are explicitly specified) can be overriden during compilation time by using the above macro. Note that desired value of the macro is a C string and quotes have to be escaped during compilation: `clang++ test.cpp -DCATCH_CONFIG_DEFAULT_REPORTER=\"xml\"`.
  59
  60 # C++ conformance toggles
  61
  62     CATCH_CONFIG_CPP11_NULLPTR                 // nullptr is supported?
  63     CATCH_CONFIG_CPP11_NOEXCEPT                // noexcept is supported?
  64     CATCH_CONFIG_CPP11_GENERATED_METHODS       // delete and default keywords for methods
  65     CATCH_CONFIG_CPP11_IS_ENUM                 // std::is_enum is supported?
  66     CATCH_CONFIG_CPP11_TUPLE                   // std::tuple is supported
  67     CATCH_CONFIG_VARIADIC_MACROS               // Usually pre-C++11 compiler extensions are sufficient
  68     CATCH_CONFIG_CPP11_LONG_LONG               // generates overloads for the long long type
  69     CATCH_CONFIG_CPP11_OVERRIDE                // CATCH_OVERRIDE expands to override (for virtual function implementations)
  70     CATCH_CONFIG_CPP11_UNIQUE_PTR              // Use std::unique_ptr instead of std::auto_ptr
  71     CATCH_CONFIG_CPP11_SHUFFLE                 // Use std::shuffle instead of std::random_shuffle
  72     CATCH_CONFIG_CPP11_TYPE_TRAITS             // Use std::enable_if and <type_traits>
  73     CATCH_CONFIG_CPP11_STREAM_INSERTABLE_CHECK // Use C++11 expression SFINAE to check if class can be inserted to std::ostream
  74
  75 Catch has some basic compiler detection that will attempt to select the appropriate mix of these macros. However being incomplete - and often without access to the respective compilers - this detection tends to be conservative.
  76 So overriding control is given to the user. If a compiler supports a feature (and Catch does not already detect it) then one or more of these may be defined to enable it (or suppress it, in some cases). If you do do this please raise an issue, specifying your compiler version (ideally with an idea of how to detect it) and stating that it has such support.
  77 You may also suppress any of these features by using the `_NO_` form, e.g. `CATCH_CONFIG_CPP11_NO_NULLPTR`.
  78
  79 All C++11 support can be disabled with `CATCH_CONFIG_NO_CPP11`
  80
  81 ## `CATCH_CONFIG_CPP11_STREAM_INSERTABLE_CHECK`
  82
  83 This flag is off by default, but allows you to resolve problems caused by types with private base class that are streamable, but the classes themselves are not. Without it, the following code will cause a compilation error:
  84 ```cpp
  85 #define CATCH_CONFIG_MAIN
  86 #include <catch.hpp>
  87 struct A {};
  88 std::ostream &operator<< (std::ostream &o, const A &v) { return o << 0; }
  89
  90 struct B : private A {
  91     bool operator==(int){ return true;}
  92 };
  93
  94 B f ();
  95 std::ostream g ();
  96
  97 TEST_CASE ("Error in streamable check") {
  98     B x;
  99     REQUIRE (x == 4);
 100 }
 101 ```
 102
 103 # Other toggles
 104
 105     CATCH_CONFIG_COUNTER                    // Use __COUNTER__ to generate unique names for test cases
 106     CATCH_CONFIG_WINDOWS_SEH                // Enable SEH handling on Windows
 107     CATCH_CONFIG_FAST_COMPILE               // Sacrifices some (rather minor) features for compilation speed
 108     CATCH_CONFIG_POSIX_SIGNALS              // Enable handling POSIX signals
 109     CATCH_CONFIG_WINDOWS_CRTDBG             // Enable leak checking using Windows's CRT Debug Heap
 110     CATCH_CONFIG_DISABLE_STRINGIFICATION    // Disable stringifying the original expression
 111
 112 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.
 113
 114 `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`).
 115
 116 `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.
 117
 118 Just as with the C++11 conformance toggles, these toggles can be disabled by using `_NO_` form of the toggle, e.g. `CATCH_CONFIG_NO_WINDOWS_SEH`.
 119
 120 ## `CATCH_CONFIG_FAST_COMPILE`
 121 Defining this flag speeds up compilation of test files by ~20%, by making 2 changes:
 122 * The `-b` (`--break`) flag no longer makes Catch break into debugger in the same stack frame as the failed test, but rather in a stack frame *below*.
 123 * The `REQUIRE` family of macros (`REQUIRE`, `REQUIRE_FALSE` and `REQUIRE_THAT`) no longer uses local try-catch block. This disables exception translation, but should not lead to false negatives.
 124
 125 `CATCH_CONFIG_FAST_COMPILE` has to be either defined, or not defined, in all translation units that are linked into single test binary, or the behaviour of setting `-b` flag and throwing unexpected exceptions will be unpredictable.
 126
 127 ## `CATCH_CONFIG_DISABLE_STRINGIFICATION`
 128 This toggle enables a workaround for VS 2017 bug. For details see
 129 [known limitations](limitations.md#visual-studio-2017----raw-string-literal-in-assert-fails-to-compile).
 130
 131 # Windows header clutter
 132
 133 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:
 134
 135     CATCH_CONFIG_NO_NOMINMAX            // Stops Catch from using NOMINMAX macro
 136     CATCH_CONFIG_NO_WIN32_LEAN_AND_MEAN // Stops Catch from using WIN32_LEAN_AND_MEAN macro
 137
 138 ---
 139
 140 [Home](Readme.md)