From 6a009fabcb0686a0bee5a66211e72d98cfcc34f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Ho=C5=99e=C5=88ovsk=C3=BD?= Date: Fri, 17 Mar 2017 17:02:39 +0100 Subject: [PATCH] Documented REQUIRE under CATCH_CONFIG_FAST_COMPILE --- docs/configuration.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 99b7ff2fa0..3d3d5fcc7e 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -74,20 +74,33 @@ All C++11 support can be disabled with `CATCH_CONFIG_NO_CPP11` CATCH_CONFIG_COUNTER // Use __COUNTER__ to generate unique names for test cases CATCH_CONFIG_WINDOWS_SEH // Enable SEH handling on Windows - CATCH_CONFIG_FAST_COMPILE // Sacrifices some (extremely minor) features for compilation speed + CATCH_CONFIG_FAST_COMPILE // Sacrifices some (rather minor) features for compilation speed CATCH_CONFIG_POSIX_SIGNALS // Enable handling POSIX signals CATCH_CONFIG_WINDOWS_CRTDBG // Enable leak checking using Windows's CRT Debug Heap 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. -At this moment, `CATCH_CONFIG_FAST_COMPILE` changes only the behaviour of the `-b` (`--break`) flag, making it break into debugger in a stack frame *below* the actual test, unlike the default behaviour, where the break into debugger occurs in the same stack frame as the actual test. `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 will be unpredictable. - `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`). `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. 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`. +## `CATCH_CONFIG_FAST_COMPILE` +Defining this flag speeds up compilation of test files by ~20%, by making 2 changes: +* 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*. +* The `REQUIRE` family of macros (`REQUIRE`, `REQUIRE_FALSE` and `REQUIRE_THAT`) no longer uses local try-catch block. This creates minor chance for false negative under certain conditions, when expression tested inside `REQUIRE` throws exception, that is then caught by user's code before it gets to the test runner. Example: +```cpp +TEST_CASE("False negative") { + try { + REQUIRE(throws() == ""); + } catch (...) {} +} +``` +This test case will succeed, reporting no assertions checked, instead of failing as it would without `CATCH_CONFIG_FAST_COMPILE`. + +`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 will be unpredictable. + # Windows header clutter 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: