v3.3.0

Fixes #2615

.bazelrc

@@ -1,4 +1,10 @@
+build --enable_platform_specific_config
+
 build:gcc9 --cxxopt=-std=c++2a
+build:gcc11 --cxxopt=-std=c++2a
 build:clang13 --cxxopt=-std=c++17
 build:vs2019 --cxxopt=/std:c++17
-build:vs2022 --cxxopt=/std:c++17
+build:vs2022 --cxxopt=/std:c++17
+
+build:windows --config=vs2022
+build:linux --config=gcc11

.clang-format

@@ -1,25 +1,45 @@
 ---
-AccessModifierOffset: '-4'
-AlignEscapedNewlines: Left
-AllowAllConstructorInitializersOnNextLine: 'true'
-BinPackArguments: 'false'
-BinPackParameters: 'false'
-BreakConstructorInitializers: AfterColon
-ConstructorInitializerAllOnOneLineOrOnePerLine: 'true'
-DerivePointerAlignment: 'false'
-FixNamespaceComments: 'true'
-IncludeBlocks: Regroup
-IndentCaseLabels: 'false'
-IndentPPDirectives: AfterHash
-IndentWidth: '4'
 Language: Cpp
+Standard: c++14
+
+# Note that we cannot use IncludeIsMainRegex functionality, because it
+# does not support includes in angle brackets (<>)
+SortIncludes: true
+IncludeBlocks: Regroup
+IncludeCategories:
+  - Regex: <catch2/.*\.hpp>
+    Priority: 1
+  - Regex: <.*/.*\.hpp>
+    Priority: 2
+  - Regex: <.*>
+    Priority: 3
+
+AllowShortBlocksOnASingleLine: Always
+AllowShortEnumsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: WithoutElse
+AllowShortLambdasOnASingleLine: Inline
+
+AccessModifierOffset: "-4"
+AlignEscapedNewlines: Left
+AllowAllConstructorInitializersOnNextLine: "true"
+BinPackArguments: "false"
+BinPackParameters: "false"
+BreakConstructorInitializers: AfterColon
+ConstructorInitializerAllOnOneLineOrOnePerLine: "true"
+DerivePointerAlignment: "false"
+FixNamespaceComments: "true"
+IndentCaseLabels: "false"
+IndentPPDirectives: AfterHash
+IndentWidth: "4"
 NamespaceIndentation: All
 PointerAlignment: Left
-SpaceBeforeCtorInitializerColon: 'false'
-SpaceInEmptyParentheses: 'false'
-SpacesInParentheses: 'true'
-Standard: Cpp11
-TabWidth: '4'
+SpaceBeforeCtorInitializerColon: "false"
+SpaceInEmptyParentheses: "false"
+SpacesInParentheses: "true"
+TabWidth: "4"
 UseTab: Never
-
-...
+AlwaysBreakTemplateDeclarations: Yes
+SpaceAfterTemplateKeyword: true
+SortUsingDeclarations: true
+ReflowComments: true

.github/workflows/linux-bazel-builds.yml

@@ -0,0 +1,24 @@
+name: Bazel build
+
+on: [push, pull_request]
+
+jobs:
+  build_and_test_ubuntu:
+    name: Linux Ubuntu 22.04 Bazel build <GCC 11.2.0>
+    runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        compilation_mode: [fastbuild, dbg, opt]
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Mount bazel cache
+      uses: actions/cache@v3
+      with:
+        path: "/home/runner/.cache/bazel"
+        key: bazel-ubuntu22-gcc11
+
+    - name: Build Catch2
+      run: |
+        bazelisk build --compilation_mode=${{matrix.compilation_mode}} //...

.github/workflows/linux-meson-builds.yml

@@ -0,0 +1,43 @@
+name: Linux builds (meson)
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    name: meson ${{matrix.cxx}}, C++${{matrix.std}}, ${{matrix.build_type}}
+    runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        cxx:
+          - g++-11
+          - clang++-11
+        build_type: [debug, release]
+        std: [14, 17]
+        include:
+          - cxx: clang++-11
+            other_pkgs: clang-11
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Prepare environment
+      run: sudo apt-get install -y meson ninja-build ${{matrix.other_pkgs}}
+
+    - name: Configure build
+      env:
+        CXX: ${{matrix.cxx}}
+        CXXFLAGS: -std=c++${{matrix.std}} ${{matrix.cxxflags}}
+      # Note: $GITHUB_WORKSPACE is distinct from ${{runner.workspace}}.
+      #       This is important
+      run: |
+        meson -Dbuildtype=${{matrix.build_type}} ${{runner.workspace}}/meson-build
+
+    - name: Build tests + lib
+      working-directory: ${{runner.workspace}}/meson-build
+      run: ninja
+
+    - name: Run tests
+      working-directory: ${{runner.workspace}}/meson-build
+      # Hardcode 2 cores we know are there
+      run: |
+        meson test --verbose

.github/workflows/linux-other-builds.yml

@@ -56,9 +56,18 @@ jobs:
             build_description: CMake configuration tests
             build_type: Debug
             std: 14
-            other_pks: clang-10
+            other_pkgs: clang-10
             cmake_configurations: -DCATCH_ENABLE_CONFIGURE_TESTS=ON
 
+          # Valgrind test Clang-10
+          - cxx: clang++-10
+            build_description: Valgrind tests
+            build_type: Debug
+            std: 14
+            other_pkgs: clang-10 valgrind
+            cmake_configurations: -DMEMORYCHECK_COMMAND=`which valgrind` -DMEMORYCHECK_COMMAND_OPTIONS="-q --track-origins=yes --leak-check=full --num-callers=50 --show-leak-kinds=definite --error-exitcode=1"
+            other_ctest_args: -T memcheck -LE uses-python
+
 
     steps:
     - uses: actions/checkout@v2
@@ -77,6 +86,7 @@ jobs:
         cmake -Bbuild -H$GITHUB_WORKSPACE \
               -DCMAKE_BUILD_TYPE=${{matrix.build_type}} \
               -DCMAKE_CXX_STANDARD=${{matrix.std}} \
+              -DCMAKE_CXX_STANDARD_REQUIRED=ON \
               -DCMAKE_CXX_EXTENSIONS=OFF \
               -DCATCH_DEVELOPMENT_BUILD=ON \
               ${{matrix.cmake_configurations}} \
@@ -91,4 +101,4 @@ jobs:
           CTEST_OUTPUT_ON_FAILURE: 1
       working-directory: ${{runner.workspace}}/build
       # Hardcode 2 cores we know are there
-      run: ctest -C ${{matrix.build_type}} -j 2
+      run: ctest -C ${{matrix.build_type}} -j 2 ${{matrix.other_ctest_args}}

.github/workflows/linux-simple-builds.yml

@@ -9,7 +9,8 @@ jobs:
     strategy:
       matrix:
         cxx:
-#          - g++-6
+          - g++-5
+          - g++-6
           - g++-7
           - g++-8
           - g++-9
@@ -22,9 +23,10 @@ jobs:
         build_type: [Debug, Release]
         std: [14]
         include:
-        # cannot be installed on ubuntu-20.04 be default?
-#          - cxx: g++-6
-#            other_pkgs: g++-6
+          - cxx: g++-5
+            other_pkgs: g++-5
+          - cxx: g++-6
+            other_pkgs: g++-6
           - cxx: g++-7
             other_pkgs: g++-7
           - cxx: g++-8
@@ -63,10 +65,32 @@ jobs:
             build_type: Release
             std: 17
             other_pkgs: clang-10
+          - cxx: clang++-10
+            build_type: Debug
+            std: 20
+            other_pkgs: clang-10
+          - cxx: clang++-10
+            build_type: Release
+            std: 20
+            other_pkgs: clang-10
+          - cxx: g++-10
+            build_type: Debug
+            std: 20
+            other_pkgs: g++-10
+          - cxx: g++-10
+            build_type: Release
+            std: 20
+            other_pkgs: g++-10
 
     steps:
     - uses: actions/checkout@v2
 
+    - name: Add repositories for older GCC
+      run: |
+        sudo apt-add-repository 'deb http://azure.archive.ubuntu.com/ubuntu/ bionic main'
+        sudo apt-add-repository 'deb http://azure.archive.ubuntu.com/ubuntu/ bionic universe'
+      if: ${{ matrix.cxx == 'g++-5' || matrix.cxx == 'g++-6' }}
+
     - name: Prepare environment
       run: sudo apt-get install -y ninja-build ${{matrix.other_pkgs}}
 
@@ -81,6 +105,7 @@ jobs:
         cmake -Bbuild -H$GITHUB_WORKSPACE \
               -DCMAKE_BUILD_TYPE=${{matrix.build_type}} \
               -DCMAKE_CXX_STANDARD=${{matrix.std}} \
+              -DCMAKE_CXX_STANDARD_REQUIRED=ON \
               -DCMAKE_CXX_EXTENSIONS=OFF \
               -DCATCH_DEVELOPMENT_BUILD=ON \
               -G Ninja

.github/workflows/mac-builds.yml

@@ -4,11 +4,15 @@ on: [push, pull_request]
 
 jobs:
   build:
-    runs-on: macos-10.15
+    # macos-12 updated to a toolchain that crashes when linking the
+    # test binary. This seems to be a known bug in that version,
+    # and will eventually get fixed in an update. After that, we can go
+    # back to newer macos images.
+    runs-on: macos-11
     strategy:
       matrix:
         cxx:
-          - g++-9
+          - g++-11
           - clang++
         build_type: [Debug, Release]
         std: [14, 17]
@@ -29,8 +33,11 @@ jobs:
       #       This is important
       run: |
         cmake -Bbuild -H$GITHUB_WORKSPACE \
-              -DCMAKE_BUILD_TYPE=${{matrix.build_type}} -DCMAKE_CXX_STANDARD=${{matrix.std}} \
-              -DCATCH_DEVELOPMENT_BUILD=ON -DCATCH_BUILD_EXAMPLES=${{matrix.examples}} \
+              -DCMAKE_BUILD_TYPE=${{matrix.build_type}} \
+              -DCMAKE_CXX_STANDARD=${{matrix.std}} \
+              -DCMAKE_CXX_STANDARD_REQUIRED=ON \
+              -DCATCH_DEVELOPMENT_BUILD=ON \
+              -DCATCH_BUILD_EXAMPLES=${{matrix.examples}} \
               -DCATCH_BUILD_EXTRA_TESTS=${{matrix.examples}}
 
     - name: Build tests + lib

.github/workflows/windows-simple-builds.yml

@@ -0,0 +1,37 @@
+name: Windows builds (basic)
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    name: ${{matrix.os}}, ${{matrix.std}}, ${{matrix.build_type}}, ${{matrix.platform}}
+    runs-on: ${{matrix.os}}
+    strategy:
+      matrix:
+        os: [windows-2019, windows-2022]
+        platform: [Win32, x64]
+        build_type: [Debug, Release]
+        std: [14, 17]
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Configure build
+        working-directory: ${{runner.workspace}}
+        run: |
+          cmake -S $Env:GITHUB_WORKSPACE               `
+                -B ${{runner.workspace}}/build         `
+                -DCMAKE_CXX_STANDARD=${{matrix.std}}   `
+                -A ${{matrix.platform}}                `
+                --preset all-tests
+
+      - name: Build tests
+        working-directory: ${{runner.workspace}}
+        run: cmake --build build --config ${{matrix.build_type}} --parallel %NUMBER_OF_PROCESSORS%
+        shell: cmd
+
+      - name: Run tests
+        working-directory: ${{runner.workspace}}/build
+        env:
+            CTEST_OUTPUT_ON_FAILURE: 1
+        run: ctest -C ${{matrix.build_type}} -j %NUMBER_OF_PROCESSORS%
+        shell: cmd

.gitignore

@@ -1,4 +1,5 @@
 *.build
+!meson.build
 *.pbxuser
 *.mode1v3
 *.ncb
@@ -11,11 +12,6 @@ Release
 xcuserdata
 CatchSelfTest.xcscheme
 Breakpoints.xcbkptlist
-projects/VS2010/TestCatch/_UpgradeReport_Files/
-projects/VS2010/TestCatch/TestCatch/TestCatch.vcxproj.filters
-projects/VisualStudio/TestCatch/UpgradeLog.XML
-projects/CMake/.idea
-projects/CMake/cmake-build-debug
 UpgradeLog.XML
 Resources/DWARF
 projects/Generated
@@ -25,6 +21,7 @@ DerivedData
 Build
 .idea
 .vs
+.vscode
 cmake-build-*
 benchmark-dir
 .conan/test_package/build
@@ -32,3 +29,9 @@ bazel-*
 build-fuzzers
 debug-build
 .vscode
+msvc-sln*
+# Currently we use Doxygen for dep graphs and the full docs are only slowly
+# being filled in, so we definitely do not want git to deal with the docs.
+docs/doxygen
+*.cache
+compile_commands.json

BUILD.bazel

@@ -1,14 +1,13 @@
-# Load the cc_library rule.
-load("@rules_cc//cc:defs.bzl", "cc_library")
 load("@bazel_skylib//rules:expand_template.bzl", "expand_template")
 
 expand_template(
     name = "catch_user_config",
     out = "catch2/catch_user_config.hpp",
     substitutions = {
+        "@CATCH_CONFIG_CONSOLE_WIDTH@": "80",
+        "@CATCH_CONFIG_DEFAULT_REPORTER@": "console",
         "#cmakedefine CATCH_CONFIG_ANDROID_LOGWRITE": "",
         "#cmakedefine CATCH_CONFIG_BAZEL_SUPPORT": "#define CATCH_CONFIG_BAZEL_SUPPORT",
-        "#cmakedefine CATCH_CONFIG_NO_COLOUR_WIN32": "",
         "#cmakedefine CATCH_CONFIG_COLOUR_WIN32": "",
         "#cmakedefine CATCH_CONFIG_COUNTER": "",
         "#cmakedefine CATCH_CONFIG_CPP11_TO_STRING": "",
@@ -29,7 +28,10 @@ expand_template(
         "#cmakedefine CATCH_CONFIG_EXPERIMENTAL_REDIRECT": "",
         "#cmakedefine CATCH_CONFIG_FALLBACK_STRINGIFIER @CATCH_CONFIG_FALLBACK_STRINGIFIER@": "",
         "#cmakedefine CATCH_CONFIG_FAST_COMPILE": "",
+        "#cmakedefine CATCH_CONFIG_GETENV": "",
         "#cmakedefine CATCH_CONFIG_GLOBAL_NEXTAFTER": "",
+        "#cmakedefine CATCH_CONFIG_NO_ANDROID_LOGWRITE": "",
+        "#cmakedefine CATCH_CONFIG_NO_COLOUR_WIN32": "",
         "#cmakedefine CATCH_CONFIG_NO_COUNTER": "",
         "#cmakedefine CATCH_CONFIG_NO_CPP11_TO_STRING": "",
         "#cmakedefine CATCH_CONFIG_NO_CPP17_BYTE": "",
@@ -37,6 +39,7 @@ expand_template(
         "#cmakedefine CATCH_CONFIG_NO_CPP17_STRING_VIEW": "",
         "#cmakedefine CATCH_CONFIG_NO_CPP17_UNCAUGHT_EXCEPTIONS": "",
         "#cmakedefine CATCH_CONFIG_NO_CPP17_VARIANT": "",
+        "#cmakedefine CATCH_CONFIG_NO_GETENV": "",
         "#cmakedefine CATCH_CONFIG_NO_GLOBAL_NEXTAFTER": "",
         "#cmakedefine CATCH_CONFIG_NO_POSIX_SIGNALS": "",
         "#cmakedefine CATCH_CONFIG_NO_USE_ASYNC": "",
@@ -45,13 +48,11 @@ expand_template(
         "#cmakedefine CATCH_CONFIG_NOSTDOUT": "",
         "#cmakedefine CATCH_CONFIG_POSIX_SIGNALS": "",
         "#cmakedefine CATCH_CONFIG_PREFIX_ALL": "",
+        "#cmakedefine CATCH_CONFIG_SHARED_LIBRARY": "",
         "#cmakedefine CATCH_CONFIG_USE_ASYNC": "",
         "#cmakedefine CATCH_CONFIG_WCHAR": "",
         "#cmakedefine CATCH_CONFIG_WINDOWS_CRTDBG": "",
         "#cmakedefine CATCH_CONFIG_WINDOWS_SEH": "",
-        "#cmakedefine CATCH_CONFIG_NO_ANDROID_LOGWRITE": "",
-        "@CATCH_CONFIG_DEFAULT_REPORTER@": "console",
-        "@CATCH_CONFIG_CONSOLE_WIDTH@": "80",
     },
     template = "src/catch2/catch_user_config.hpp.in",
 )
@@ -88,4 +89,4 @@ cc_library(
     linkstatic = True,
     visibility = ["//visibility:public"],
     deps = [":catch2"],
-)
+)

CMake/CatchConfigOptions.cmake

@@ -1,7 +1,7 @@
 
 #              Copyright Catch2 Authors
 # Distributed under the Boost Software License, Version 1.0.
-#   (See accompanying file LICENSE_1_0.txt or copy at
+#   (See accompanying file LICENSE.txt or copy at
 #        https://www.boost.org/LICENSE_1_0.txt)
 
 # SPDX-License-Identifier: BSL-1.0
@@ -40,6 +40,7 @@ set(_OverridableOptions
   "USE_ASYNC"
   "WCHAR"
   "WINDOWS_SEH"
+  "GETENV"
 )
 
 foreach(OptionName ${_OverridableOptions})
@@ -67,6 +68,7 @@ set(_OtherConfigOptions
 foreach(OptionName ${_OtherConfigOptions})
   AddConfigOption(${OptionName})
 endforeach()
+set(CATCH_CONFIG_SHARED_LIBRARY ${BUILD_SHARED_LIBS})
 
 set(CATCH_CONFIG_DEFAULT_REPORTER "console" CACHE STRING "Read docs/configuration.md for details. The name of the reporter should be without quotes.")
 set(CATCH_CONFIG_CONSOLE_WIDTH "80" CACHE STRING "Read docs/configuration.md for details. Must form a valid integer literal.")

CMake/CatchMiscFunctions.cmake

@@ -1,18 +1,19 @@
 
 #              Copyright Catch2 Authors
 # Distributed under the Boost Software License, Version 1.0.
-#   (See accompanying file LICENSE_1_0.txt or copy at
+#   (See accompanying file LICENSE.txt or copy at
 #        https://www.boost.org/LICENSE_1_0.txt)
 
 # SPDX-License-Identifier: BSL-1.0
 
 include(CheckCXXCompilerFlag)
 function(add_cxx_flag_if_supported_to_targets flagname targets)
-    check_cxx_compiler_flag("${flagname}" HAVE_FLAG_${flagname})
+    string(MAKE_C_IDENTIFIER ${flagname} flag_identifier )
+    check_cxx_compiler_flag("${flagname}" HAVE_FLAG_${flag_identifier})
 
-    if (HAVE_FLAG_${flagname})
+    if (HAVE_FLAG_${flag_identifier})
         foreach(target ${targets})
-            target_compile_options(${target} PUBLIC ${flagname})
+            target_compile_options(${target} PRIVATE ${flagname})
         endforeach()
     endif()
 endfunction()
@@ -43,35 +44,58 @@ function(add_warnings_to_targets targets)
 
     if (NOT MSVC)
         set(CHECKED_WARNING_FLAGS
-          "-Wall"
-          "-Wextra"
-          "-Wpedantic"
-          "-Wweak-vtables"
-          "-Wunreachable-code"
-          "-Wmissing-declarations"
-          "-Wexit-time-destructors"
-          "-Wglobal-constructors"
-          "-Wmissing-noreturn"
-          "-Wparentheses"
-          "-Wextra-semi"
-          "-Wunreachable-code"
-          "-Wstrict-aliasing"
-          "-Wreturn-std-move"
-          "-Wmissing-braces"
-          "-Wdeprecated"
-          "-Wvla"
-          "-Wundef"
-          "-Wmisleading-indentation"
-          "-Wcatch-value"
           "-Wabsolute-value"
-          "-Wreturn-std-move"
-          "-Wunused-parameter"
-          "-Wunused-function"
+          "-Wall"
+          "-Wc++20-compat"
           "-Wcall-to-pure-virtual-from-ctor-dtor"
+          "-Wcast-align"
+          "-Wcatch-value"
+          "-Wdangling"
+          "-Wdeprecated"
           "-Wdeprecated-register"
-          "-Wsuggest-override"
-          "-Wshadow"
+          "-Wexceptions"
+          "-Wexit-time-destructors"
+          "-Wextra"
+          "-Wextra-semi"
+          "-Wfloat-equal"
+          "-Wglobal-constructors"
+          "-Winit-self"
+          "-Wmisleading-indentation"
+          "-Wmismatched-new-delete"
+          "-Wmismatched-return-types"
+          "-Wmismatched-tags"
+          "-Wmissing-braces"
+          "-Wmissing-declarations"
+          "-Wmissing-noreturn"
+          "-Wmissing-prototypes"
+          "-Wmissing-variable-declarations"
+          "-Wnull-dereference"
           "-Wold-style-cast"
+          "-Woverloaded-virtual"
+          "-Wparentheses"
+          "-Wpedantic"
+          "-Wreorder"
+          "-Wreturn-std-move"
+          "-Wshadow"
+          "-Wstrict-aliasing"
+          "-Wsuggest-destructor-override"
+          "-Wsuggest-override"
+          "-Wundef"
+          "-Wuninitialized"
+          "-Wunneeded-internal-declaration"
+          "-Wunreachable-code"
+          "-Wunused"
+          "-Wunused-function"
+          "-Wunused-parameter"
+          "-Wvla"
+          "-Wweak-vtables"
+
+          # This is a useful warning, but our tests sometimes rely on
+          # functions being present, but not picked (e.g. various checks
+          # for stringification implementation ordering).
+          # Ergo, we should use it every now and then, but we cannot
+          # enable it by default.
+          # "-Wunused-member-function"
         )
         foreach(warning ${CHECKED_WARNING_FLAGS})
             add_cxx_flag_if_supported_to_targets(${warning} "${targets}")
@@ -89,9 +113,8 @@ endfunction()
 # Adds flags required for reproducible build to the target
 # Currently only supports GCC and Clang
 function(add_build_reproducibility_settings target)
-# Make the build reproducible on versions of g++ and clang that supports -ffile-prefix-map
-  if(("${CMAKE_CXX_COMPILER_ID}" STREQUAL "GNU" AND NOT ${CMAKE_CXX_COMPILER_VERSION} VERSION_LESS 8) OR
-     ("${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang" AND NOT ${CMAKE_CXX_COMPILER_VERSION} VERSION_LESS 10))
-    target_compile_options(${target} PRIVATE "-ffile-prefix-map=${CATCH_DIR}=.")
+  # Make the build reproducible on versions of g++ and clang that supports -ffile-prefix-map
+  if((CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR (CMAKE_CXX_COMPILER_ID MATCHES "Clang"))
+    add_cxx_flag_if_supported_to_targets("-ffile-prefix-map=${CATCH_DIR}/=" "${target}")
   endif()
 endfunction()

CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.5)
+cmake_minimum_required(VERSION 3.10)
 
 # detect if Catch is being bundled,
 # disable testsuite in that case
@@ -30,16 +30,26 @@ if (CMAKE_BINARY_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
     message(FATAL_ERROR "Building in-source is not supported! Create a build dir and remove ${CMAKE_SOURCE_DIR}/CMakeCache.txt")
 endif()
 
-if(CMAKE_VERSION VERSION_GREATER 3.8)
-  # Enable IPO for CMake versions that support it
-  cmake_policy(SET CMP0069 NEW)
+project(Catch2
+  VERSION 3.3.0 # CML version placeholder, don't delete
+  LANGUAGES CXX
+  # HOMEPAGE_URL is not supported until CMake version 3.12, which
+  # we do not target yet.
+  # HOMEPAGE_URL "https://github.com/catchorg/Catch2"
+  DESCRIPTION "A modern, C++-native, unit test framework."
+)
+
+
+# Provide path for scripts. We first add path to the scripts we don't use,
+# but projects including us might, and set the path up to parent scope.
+# Then we also add path that we use to configure the project, but is of
+# no use to top level projects.
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/extras")
+if (NOT NOT_SUBPROJECT)
+  set(CMAKE_MODULE_PATH "${CMAKE_MODULE_PATH}" PARENT_SCOPE)
 endif()
-
-
-project(Catch2 LANGUAGES CXX VERSION 3.0.0)
-
-# Provide path for scripts
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/CMake")
+
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)
 include(CatchConfigOptions)
@@ -95,13 +105,6 @@ if (CATCH_DEVELOPMENT_BUILD)
     add_warnings_to_targets("${CATCH_WARNING_TARGETS}")
 endif()
 
-
-#set_property(GLOBAL PROPERTY USE_FOLDERS ON)
-#
-#
-#
-#
-#
 # Only perform the installation steps when Catch is not being used as
 # a subproject via `add_subdirectory`, or the destinations will break,
 # see https://github.com/catchorg/Catch2/issues/1373
@@ -134,6 +137,7 @@ if (NOT_SUBPROJECT)
           docs/
         DESTINATION
           "${CMAKE_INSTALL_DOCDIR}"
+        PATTERN "doxygen" EXCLUDE
       )
     endif()
 

Doxyfile

@@ -1319,7 +1319,7 @@ CHM_FILE               =
 HHC_LOCATION           =
 
 # The GENERATE_CHI flag controls if a separate .chi index file is generated
-# (YES) or that it should be included in the master .chm file (NO).
+# (YES) or that it should be included in the main .chm file (NO).
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTMLHELP is set to YES.
 

README.md

@@ -1,5 +1,5 @@
 <a id="top"></a>
-![Catch2 logo](data/artwork/catch2-logo-small.png)
+![Catch2 logo](data/artwork/catch2-logo-small-with-background.png)
 
 [![Github Releases](https://img.shields.io/github/release/catchorg/catch2.svg)](https://github.com/catchorg/catch2/releases)
 [![Linux build status](https://github.com/catchorg/Catch2/actions/workflows/linux-simple-builds.yml/badge.svg)](https://github.com/catchorg/Catch2/actions/workflows/linux-simple-builds.yml)
@@ -7,35 +7,86 @@
 [![MacOS build status](https://github.com/catchorg/Catch2/actions/workflows/mac-builds.yml/badge.svg)](https://github.com/catchorg/Catch2/actions/workflows/mac-builds.yml)
 [![Build Status](https://ci.appveyor.com/api/projects/status/github/catchorg/Catch2?svg=true&branch=devel)](https://ci.appveyor.com/project/catchorg/catch2)
 [![Code Coverage](https://codecov.io/gh/catchorg/Catch2/branch/devel/graph/badge.svg)](https://codecov.io/gh/catchorg/Catch2)
-[![Try online](https://img.shields.io/badge/try-online-blue.svg)](https://godbolt.org/z/9x9qoM)
+[![Try online](https://img.shields.io/badge/try-online-blue.svg)](https://godbolt.org/z/EdoY15q9G)
 [![Join the chat in Discord: https://discord.gg/4CWS9zD](https://img.shields.io/badge/Discord-Chat!-brightgreen.svg)](https://discord.gg/4CWS9zD)
 
 
-## What's the Catch2?
+## What is Catch2?
 
 Catch2 is mainly a unit testing framework for C++, but it also
 provides basic micro-benchmarking features, and simple BDD macros.
 
 Catch2's main advantage is that using it is both simple and natural.
-Tests autoregister themselves and do not have to be named with valid
-identifiers, assertions look like normal C++ code, and sections provide
-a nice way to share set-up and tear-down code in tests.
+Test names do not have to be valid identifiers, assertions look like
+normal C++ boolean expressions, and sections provide a nice and local way
+to share set-up and tear-down code in tests.
+
+**Example unit test**
+```cpp
+#include <catch2/catch_test_macros.hpp>
+
+#include <cstdint>
+
+uint32_t factorial( uint32_t number ) {
+    return number <= 1 ? number : factorial(number-1) * number;
+}
+
+TEST_CASE( "Factorials are computed", "[factorial]" ) {
+    REQUIRE( factorial( 1) == 1 );
+    REQUIRE( factorial( 2) == 2 );
+    REQUIRE( factorial( 3) == 6 );
+    REQUIRE( factorial(10) == 3'628'800 );
+}
+```
+
+**Example microbenchmark**
+```cpp
+#include <catch2/catch_test_macros.hpp>
+#include <catch2/benchmark/catch_benchmark.hpp>
+
+#include <cstdint>
+
+uint64_t fibonacci(uint64_t number) {
+    return number < 2 ? number : fibonacci(number - 1) + fibonacci(number - 2);
+}
+
+TEST_CASE("Benchmark Fibonacci", "[!benchmark]") {
+    REQUIRE(fibonacci(5) == 5);
+
+    REQUIRE(fibonacci(20) == 6'765);
+    BENCHMARK("fibonacci 20") {
+        return fibonacci(20);
+    };
+
+    REQUIRE(fibonacci(25) == 75'025);
+    BENCHMARK("fibonacci 25") {
+        return fibonacci(25);
+    };
+}
+```
+
+_Note that benchmarks are not run by default, so you need to run it explicitly
+with the `[!benchmark]` tag._
 
 
-## Catch2 v3 is being developed!
+## Catch2 v3 has been released!
 
-You are on the `devel` branch, where the next major version, v3, of
-Catch2 is being developed. As it is a significant rework, you will
-find that parts of this documentation are likely still stuck on v2.
+You are on the `devel` branch, where the v3 version is being developed.
+v3 brings a bunch of significant changes, the big one being that Catch2
+is no longer a single-header library. Catch2 now behaves as a normal
+library, with multiple headers and separately compiled implementation.
 
-For stable (and documentation-matching) version of Catch2, [go to the
-`v2.x` branch](https://github.com/catchorg/Catch2/tree/v2.x).
+The documentation is slowly being updated to take these changes into
+account, but this work is currently still ongoing.
 
 For migrating from the v2 releases to v3, you should look at [our
 documentation](docs/migrate-v2-to-v3.md#top). It provides a simple
 guidelines on getting started, and collects most common migration
 problems.
 
+For the previous major version of Catch2 [look into the `v2.x` branch
+here on GitHub](https://github.com/catchorg/Catch2/tree/v2.x).
+
 
 ## How to use it
 This documentation comprises these three parts:

WORKSPACE

@@ -1,14 +0,0 @@
-load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
-
-http_archive(
-    name = "bazel_skylib",
-    strip_prefix = "bazel-skylib-2a87d4a62af886fb320883aba102255aba87275e",
-    urls = [
-        "https://github.com/bazelbuild/bazel-skylib/archive/2a87d4a62af886fb320883aba102255aba87275e.tar.gz",
-    ],
-    sha256 = "d847b08d6702d2779e9eb399b54ff8920fa7521dc45e3e53572d1d8907767de7",
-)
-
-load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
-
-bazel_skylib_workspace()

WORKSPACE.bazel

@@ -0,0 +1,15 @@
+workspace(name = "catch2")
+
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+
+http_archive(
+    name = "bazel_skylib",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/1.3.0/bazel-skylib-1.3.0.tar.gz",
+        "https://github.com/bazelbuild/bazel-skylib/releases/download/1.3.0/bazel-skylib-1.3.0.tar.gz",
+    ],
+    sha256 = "74d544d96f4a5bb630d465ca8bbcfe231e3594e5aae57e1edbf17a6eb3ca2506",
+)
+
+load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
+bazel_skylib_workspace()

appveyor.yml

@@ -51,18 +51,6 @@ test_script:
 # build explicitly.
 environment:
   matrix:
-    - FLAVOR: VS 2019 x64 Debug Surrogates Configure Tests
-      APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019
-      surrogates: 1
-      configure_tests: 1
-      platform: x64
-      configuration: Debug
-    
-    - FLAVOR: VS 2019 x64 Release
-      APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019
-      platform: x64
-      configuration: Release
-
     - FLAVOR: VS 2019 x64 Debug Coverage Examples
       APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019
       examples: 1
@@ -77,11 +65,6 @@ environment:
       platform: x64
       configuration: Debug
 
-    - FLAVOR: VS 2019 Win32 Debug
-      APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019
-      platform: Win32
-      configuration: Debug
-
     - FLAVOR: VS 2019 x64 Debug Latest Strict
       APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019
       additional_flags: "/permissive- /std:c++latest"
@@ -92,38 +75,9 @@ environment:
       APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
       platform: x64
       configuration: Debug
-    
-    - FLAVOR: VS 2017 x64 Release
-      APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
-      platform: x64
-      configuration: Release
 
     - FLAVOR: VS 2017 x64 Release Coverage
       APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
       coverage: 1
       platform: x64
-      configuration: Debug
-
-    - FLAVOR: VS 2017 Win32 Debug
-      APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
-      platform: Win32
-      configuration: Debug
-
-    - FLAVOR: VS 2017 Win32 Debug Examples
-      APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
-      examples: 1
-      platform: Win32
-      configuration: Debug
-
-    - FLAVOR: VS 2017 Win32 Debug WMain
-      APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
-      wmain: 1
-      additional_flags: "/D_UNICODE /DUNICODE"
-      platform: Win32
-      configuration: Debug
-
-    - FLAVOR: VS 2017 x64 Debug Latest Strict
-      APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
-      additional_flags: "/permissive- /std:c++latest"
-      platform: x64
-      configuration: Debug
+      configuration: Debug

conanfile.py

@@ -51,6 +51,7 @@ conan_basic_setup()'''.format(line_to_replace, self.install_folder.replace("\\",
         self.cpp_info.components["catch2base"].names["cmake_find_package_multi"] = "Catch2"
         self.cpp_info.components["catch2base"].names["pkg_config"] = "Catch2"
         self.cpp_info.components["catch2base"].libs = ["Catch2" + lib_suffix]
+        self.cpp_info.components["catch2base"].builddirs.append("lib/cmake/Catch2")
         # Catch2WithMain
         self.cpp_info.components["catch2main"].names["cmake_find_package"] = "Catch2WithMain"
         self.cpp_info.components["catch2main"].names["cmake_find_package_multi"] = "Catch2WithMain"

docs/Readme.md

@@ -4,33 +4,36 @@
 To get the most out of Catch2, start with the [tutorial](tutorial.md#top).
 Once you're up and running consider the following reference material.
 
-Writing tests:
+**Writing tests:**
 * [Assertion macros](assertions.md#top)
-* [Matchers](matchers.md#top)
+* [Matchers (asserting complex properties)](matchers.md#top)
+* [Comparing floating point numbers](comparing-floating-point-numbers.md#top)
 * [Logging macros](logging.md#top)
 * [Test cases and sections](test-cases-and-sections.md#top)
 * [Test fixtures](test-fixtures.md#top)
-* [Reporters](reporters.md#top)
+* [Explicitly skipping, passing, and failing tests at runtime](skipping-passing-failing.md#top)
+* [Reporters (output customization)](reporters.md#top)
 * [Event Listeners](event-listeners.md#top)
-* [Data Generators](generators.md#top)
+* [Data Generators (value parameterized tests)](generators.md#top)
 * [Other macros](other-macros.md#top)
 * [Micro benchmarking](benchmarks.md#top)
 
-Fine tuning:
+**Fine tuning:**
 * [Supplying your own main()](own-main.md#top)
 * [Compile-time configuration](configuration.md#top)
 * [String Conversions](tostring.md#top)
 
-Running:
+**Running:**
 * [Command line](command-line.md#top)
 
-Odds and ends:
+**Odds and ends:**
 * [Frequently Asked Questions (FAQ)](faq.md#top)
+* [Best practices and other tips](usage-tips.md#top)
 * [CMake integration](cmake-integration.md#top)
-* [CI and other miscellaneous pieces](ci-and-misc.md#top)
+* [Tooling integration (CI, test runners, other)](ci-and-misc.md#top)
 * [Known limitations](limitations.md#top)
- 
-Other:
+
+**Other:**
 * [Why Catch2?](why-catch.md#top)
 * [Migrating from v2 to v3](migrate-v2-to-v3.md#top)
 * [Open Source Projects using Catch2](opensource-users.md#top)

docs/assertions.md

@@ -3,6 +3,7 @@
 
 **Contents**<br>
 [Natural Expressions](#natural-expressions)<br>
+[Floating point comparisons](#floating-point-comparisons)<br>
 [Exceptions](#exceptions)<br>
 [Matcher expressions](#matcher-expressions)<br>
 [Thread Safety](#thread-safety)<br>
@@ -19,7 +20,7 @@ Most of these macros come in two forms:
 The ```REQUIRE``` family of macros tests an expression and aborts the test case if it fails.
 The ```CHECK``` family are equivalent but execution continues in the same test case even if the assertion fails. This is useful if you have a series of essentially orthogonal assertions and it is useful to see all the results rather than stopping at the first failure.
 
-* **REQUIRE(** _expression_ **)** and  
+* **REQUIRE(** _expression_ **)** and
 * **CHECK(** _expression_ **)**
 
 Evaluates the expression and records the result. If an exception is thrown, it is caught, reported, and counted as a failure. These are the macros you will use most of the time.
@@ -31,98 +32,78 @@ CHECK( thisReturnsTrue() );
 REQUIRE( i == 42 );
 ```
 
-* **REQUIRE_FALSE(** _expression_ **)** and  
+Expressions prefixed with `!` cannot be decomposed. If you have a type
+that is convertible to bool and you want to assert that it evaluates to
+false, use the two forms below:
+
+
+* **REQUIRE_FALSE(** _expression_ **)** and
 * **CHECK_FALSE(** _expression_ **)**
 
-Evaluates the expression and records the _logical NOT_ of the result. If an exception is thrown it is caught, reported, and counted as a failure.
-(these forms exist as a workaround for the fact that ! prefixed expressions cannot be decomposed).
+Note that there is no reason to use these forms for plain bool variables,
+because there is no added value in decomposing them.
 
 Example:
-```
-REQUIRE_FALSE( thisReturnsFalse() );
-```
-
-Do note that "overly complex" expressions cannot be decomposed and thus will not compile. This is done partly for practical reasons (to keep the underlying expression template machinery to minimum) and partly for philosophical reasons (assertions should be simple and deterministic).
-
-Examples:
-* `CHECK(a == 1 && b == 2);`
-This expression is too complex because of the `&&` operator. If you want to check that 2 or more properties hold, you can either put the expression into parenthesis, which stops decomposition from working, or you need to decompose the expression into two assertions: `CHECK( a == 1 ); CHECK( b == 2);`
-* `CHECK( a == 2 || b == 1 );`
-This expression is too complex because of the `||` operator. If you want to check that one of several properties hold, you can put the expression into parenthesis (unlike with `&&`, expression decomposition into several `CHECK`s is not possible).
-
-
-### Floating point comparisons
-
-When comparing floating point numbers - especially if at least one of them has been computed - great care must be taken to allow for rounding errors and inexact representations.
-
-Catch provides a way to perform tolerant comparisons of floating point values through use of a wrapper class called `Approx`. `Approx` can be used on either side of a comparison expression. It overloads the comparisons operators to take a tolerance into account. Here's a simple example:
-
 ```cpp
-REQUIRE( performComputation() == Approx( 2.1 ) );
+Status ret = someFunction();
+REQUIRE_FALSE(ret); // ret must evaluate to false, and Catch2 will print
+                    // out the value of ret if possibly
 ```
 
-Catch also provides a user-defined literal for `Approx`; `_a`. It resides in
-the `Catch::literals` namespace and can be used like so:
-```cpp
-using namespace Catch::literals;
-REQUIRE( performComputation() == 2.1_a );
-```
 
-`Approx` is constructed with defaults that should cover most simple cases.
-For the more complex cases, `Approx` provides 3 customization points:
+### Other limitations
 
-* __epsilon__ - epsilon serves to set the coefficient by which a result
-can differ from `Approx`'s value before it is rejected.
-_By default set to `std::numeric_limits<float>::epsilon()*100`._
-* __margin__ - margin serves to set the the absolute value by which
-a result can differ from `Approx`'s value before it is rejected.
-_By default set to `0.0`._
-* __scale__ - scale is used to change the magnitude of `Approx` for relative check.
-_By default set to `0.0`._
+Note that expressions containing either of the binary logical operators,
+`&&` or `||`, cannot be decomposed and will not compile. The reason behind
+this is that it is impossible to overload `&&` and `||` in a way that
+keeps their short-circuiting semantics, and expression decomposition
+relies on overloaded operators to work.
 
-#### epsilon example
-```cpp
-Approx target = Approx(100).epsilon(0.01);
-100.0 == target; // Obviously true
-200.0 == target; // Obviously still false
-100.5 == target; // True, because we set target to allow up to 1% difference
-```
+Simple example of an issue with overloading binary logical operators
+is a common pointer idiom, `p && p->foo == 2`. Using the built-in `&&`
+operator, `p` is only dereferenced if it is not null. With overloaded
+`&&`, `p` is always dereferenced, thus causing a segfault if
+`p == nullptr`.
 
-#### margin example
-```cpp
-Approx target = Approx(100).margin(5);
-100.0 == target; // Obviously true
-200.0 == target; // Obviously still false
-104.0 == target; // True, because we set target to allow absolute difference of at most 5
-```
+If you want to test expression that contains `&&` or `||`, you have two
+options.
 
-#### scale
-Scale can be useful if the computation leading to the result worked
-on different scale than is used by the results. Since allowed difference
-between Approx's value and compared value is based primarily on Approx's value
-(the allowed difference is computed as
-`(Approx::scale + Approx::value) * epsilon`), the resulting comparison could
-need rescaling to be correct.
+1) Enclose it in parentheses. Parentheses force evaluation of the expression
+   before the expression decomposition can touch it, and thus it cannot
+   be used.
+
+2) Rewrite the expression. `REQUIRE(a == 1 && b == 2)` can always be split
+   into `REQUIRE(a == 1); REQUIRE(b == 2);`. Alternatively, if this is a
+   common pattern in your tests, think about using [Matchers](#matcher-expressions).
+   instead. There is no simple rewrite rule for `||`, but I generally
+   believe that if you have `||` in your test expression, you should rethink
+   your tests.
+
+
+## Floating point comparisons
+
+Comparing floating point numbers is complex, and [so it has its own
+documentation page](comparing-floating-point-numbers.md#top).
 
 
 ## Exceptions
 
-* **REQUIRE_NOTHROW(** _expression_ **)** and  
+* **REQUIRE_NOTHROW(** _expression_ **)** and
 * **CHECK_NOTHROW(** _expression_ **)**
 
 Expects that no exception is thrown during evaluation of the expression.
 
-* **REQUIRE_THROWS(** _expression_ **)** and  
+* **REQUIRE_THROWS(** _expression_ **)** and
 * **CHECK_THROWS(** _expression_ **)**
 
 Expects that an exception (of any type) is be thrown during evaluation of the expression.
 
-* **REQUIRE_THROWS_AS(** _expression_, _exception type_ **)** and  
+* **REQUIRE_THROWS_AS(** _expression_, _exception type_ **)** and
 * **CHECK_THROWS_AS(** _expression_, _exception type_ **)**
 
 Expects that an exception of the _specified type_ is thrown during evaluation of the expression. Note that the _exception type_ is extended with `const&` and you should not include it yourself.
 
-* **REQUIRE_THROWS_WITH(** _expression_, _string or string matcher_ **)** and  
+* **REQUIRE_THROWS_WITH(** _expression_, _string or string matcher_ **)** and
 * **CHECK_THROWS_WITH(** _expression_, _string or string matcher_ **)**
 
 Expects that an exception is thrown that, when converted to a string, matches the _string_ or _string matcher_ provided (see next section for Matchers).
@@ -158,8 +139,8 @@ REQUIRE_NOTHROW([&](){
 
 To support Matchers a slightly different form is used. Matchers have [their own documentation](matchers.md#top).
 
-* **REQUIRE_THAT(** _lhs_, _matcher expression_ **)** and  
-* **CHECK_THAT(** _lhs_, _matcher expression_ **)**  
+* **REQUIRE_THAT(** _lhs_, _matcher expression_ **)** and
+* **CHECK_THAT(** _lhs_, _matcher expression_ **)**
 
 Matchers can be composed using `&&`, `||` and `!` operators.
 

docs/ci-and-misc.md

@@ -1,14 +1,15 @@
 <a id="top"></a>
-# CI and other odd pieces
+# Tooling integration (CI, test runners and so on)
 
 **Contents**<br>
 [Continuous Integration systems](#continuous-integration-systems)<br>
-[Other reporters](#other-reporters)<br>
+[Bazel test runner integration](#bazel-test-runner-integration)<br>
 [Low-level tools](#low-level-tools)<br>
 [CMake](#cmake)<br>
 
-This page talks about how Catch integrates with Continuous Integration 
-Build Systems may refer to low-level tools, like CMake, or larger systems that run on servers, like Jenkins or TeamCity. This page will talk about both.
+This page talks about Catch2's integration with other related tooling,
+like Continuous Integration and 3rd party test runners.
+
 
 ## Continuous Integration systems
 
@@ -17,9 +18,9 @@ Probably the most important aspect to using Catch with a build server is the use
 Two of these reporters are built in (XML and JUnit) and the third (TeamCity) is included as a separate header. It's possible that the other two may be split out in the future too - as that would make the core of Catch smaller for those that don't need them.
 
 ### XML Reporter
-```-r xml``` 
+```-r xml```
 
-The XML Reporter writes in an XML format that is specific to Catch. 
+The XML Reporter writes in an XML format that is specific to Catch.
 
 The advantage of this format is that it corresponds well to the way Catch works (especially the more unusual features, such as nested sections) and is a fully streaming format - that is it writes output as it goes, without having to store up all its results before it can start writing.
 
@@ -34,19 +35,6 @@ The advantage of this format is that the JUnit Ant schema is widely understood b
 
 The disadvantage is that this schema was designed to correspond to how JUnit works - and there is a significant mismatch with how Catch works. Additionally the format is not streamable (because opening elements hold counts of failed and passing tests as attributes) - so the whole test run must complete before it can be written.
 
-## Other reporters
-Other reporters are not part of the single-header distribution and need
-to be downloaded and included separately. All reporters are stored in
-`single_include` directory in the git repository, and are named
-`catch_reporter_*.hpp`. For example, to use the TeamCity reporter you
-need to download `single_include/catch_reporter_teamcity.hpp` and include
-it after Catch itself.
-
-```cpp
-#define CATCH_CONFIG_MAIN
-#include "catch.hpp"
-#include "catch_reporter_teamcity.hpp"
-```
 
 ### TeamCity Reporter
 ```-r teamcity```
@@ -69,19 +57,29 @@ Because of the incremental nature of Catch's test suites and ability to run spec
 ```-r sonarqube```
 [SonarQube Generic Test Data](https://docs.sonarqube.org/latest/analysis/generic-test/) XML format for tests metrics.
 
+
+## Bazel test runner integration
+
+Catch2 understands some of the environment variables Bazel uses to control
+test execution. Specifically it understands
+
+ * JUnit output path via `XML_OUTPUT_FILE`
+ * Test filtering via `TESTBRIDGE_TEST_ONLY`
+ * Test sharding via `TEST_SHARD_INDEX`, `TEST_TOTAL_SHARDS`, and `TEST_SHARD_STATUS_FILE`
+
+> Support for `XML_OUTPUT_FILE` was [introduced](https://github.com/catchorg/Catch2/pull/2399) in Catch2 3.0.1
+
+> Support for `TESTBRIDGE_TEST_ONLY` and sharding was introduced in Catch2 3.2.0
+
+This integration is enabled via either a [compile time configuration
+option](configuration.md#bazel-support), or via `BAZEL_TEST` environment
+variable set to "1".
+
+> Support for `BAZEL_TEST` was [introduced](https://github.com/catchorg/Catch2/pull/2459) in Catch2 3.1.0
+
+
 ## Low-level tools
 
-### Precompiled headers (PCHs)
-
-Catch offers prototypal support for being included in precompiled headers, but because of its single-header nature it does need some actions by the user:
-* The precompiled header needs to define `CATCH_CONFIG_ALL_PARTS`
-* The implementation file needs to
-  * undefine `TWOBLUECUBES_SINGLE_INCLUDE_CATCH_HPP_INCLUDED`
-  * define `CATCH_CONFIG_IMPL_ONLY`
-  * define `CATCH_CONFIG_MAIN` or `CATCH_CONFIG_RUNNER`
-  * include "catch.hpp" again
-
-
 ### CodeCoverage module (GCOV, LCOV...)
 
 If you are using GCOV tool to get testing coverage of your code, and are not sure how to integrate it with CMake and Catch, there should be an external example over at https://github.com/fkromer/catch_cmake_coverage

docs/cmake-integration.md

@@ -5,6 +5,7 @@
 [CMake targets](#cmake-targets)<br>
 [Automatic test registration](#automatic-test-registration)<br>
 [CMake project options](#cmake-project-options)<br>
+[`CATCH_CONFIG_*` customization options in CMake](#catch_config_-customization-options-in-cmake)<br>
 [Installing Catch2 from git repository](#installing-catch2-from-git-repository)<br>
 [Installing Catch2 from vcpkg](#installing-catch2-from-vcpkg)<br>
 
@@ -50,7 +51,7 @@ Include(FetchContent)
 FetchContent_Declare(
   Catch2
   GIT_REPOSITORY https://github.com/catchorg/Catch2.git
-  GIT_TAG        v3.0.0-preview3
+  GIT_TAG        v3.0.1 # or a later release
 )
 
 FetchContent_MakeAvailable(Catch2)
@@ -62,17 +63,19 @@ target_link_libraries(tests PRIVATE Catch2::Catch2WithMain)
 
 ## Automatic test registration
 
-Catch2's repository also contains two CMake scripts that help users
+Catch2's repository also contains three CMake scripts that help users
 with automatically registering their `TEST_CASE`s with CTest. They
 can be found in the `extras` folder, and are
 
 1) `Catch.cmake` (and its dependency `CatchAddTests.cmake`)
 2) `ParseAndAddCatchTests.cmake` (deprecated)
+3) `CatchShardTests.cmake` (and its dependency `CatchShardTestsImpl.cmake`)
 
 If Catch2 has been installed in system, both of these can be used after
 doing `find_package(Catch2 REQUIRED)`. Otherwise you need to add them
 to your CMake module path.
 
+<a id="catch_discover_tests"></a>
 ### `Catch.cmake` and `CatchAddTests.cmake`
 
 `Catch.cmake` provides function `catch_discover_tests` to get tests from
@@ -109,7 +112,7 @@ catch_discover_tests()
 ```
 
 #### Customization
-`catch_discover_tests` can be given several extra argumets:
+`catch_discover_tests` can be given several extra arguments:
 ```cmake
 catch_discover_tests(target
                      [TEST_SPEC arg1...]
@@ -256,6 +259,49 @@ unset(OptionalCatchTestLauncher)
 ParseAndAddCatchTests(bar)
 ```
 
+
+### `CatchShardTests.cmake`
+
+> `CatchShardTests.cmake` was introduced in Catch2 3.1.0.
+
+`CatchShardTests.cmake` provides a function
+`catch_add_sharded_tests(TEST_BINARY)` that splits tests from `TEST_BINARY`
+into multiple shards. The tests in each shard and their order is randomized,
+and the seed changes every invocation of CTest.
+
+Currently there are 3 customization points for this script:
+
+ * SHARD_COUNT - number of shards to split target's tests into
+ * REPORTER    - reporter spec to use for tests
+ * TEST_SPEC   - test spec used for filtering tests
+
+Example usage:
+
+```
+include(CatchShardTests)
+
+catch_add_sharded_tests(foo-tests
+  SHARD_COUNT 4
+  REPORTER "xml::out=-"
+  TEST_SPEC "A"
+)
+
+catch_add_sharded_tests(tests
+  SHARD_COUNT 8
+  REPORTER "xml::out=-"
+  TEST_SPEC "B"
+)
+```
+
+This registers total of 12 CTest tests (4 + 8 shards) to run shards
+from `foo-tests` test binary, filtered by a test spec.
+
+_Note that this script is currently a proof-of-concept for reseeding
+shards per CTest run, and thus does not support (nor does it currently
+aim to support) all customization points from
+[`catch_discover_tests`](#catch_discover_tests)._
+
+
 ## CMake project options
 
 Catch2's CMake project also provides some options for other projects
@@ -293,6 +339,31 @@ compiled separately to ensure that they are self-sufficient.
 Defaults to `OFF`.
 
 
+## `CATCH_CONFIG_*` customization options in CMake
+
+> CMake support for `CATCH_CONFIG_*` options was introduced in Catch2 3.0.1
+
+Due to the new separate compilation model, all the options from the
+[Compile-time configuration docs](configuration.md#top) can also be set
+through Catch2's CMake. To set them, define the option you want as `ON`,
+e.g. `-DCATCH_CONFIG_NOSTDOUT=ON`.
+
+Note that setting the option to `OFF` doesn't disable it. To force disable
+an option, you need to set the `_NO_` form of it to `ON`, e.g.
+`-DCATCH_CONFIG_NO_COLOUR_WIN32=ON`.
+
+
+To summarize the configuration option behaviour with an example:
+
+| `-DCATCH_CONFIG_COLOUR_WIN32` | `-DCATCH_CONFIG_NO_COLOUR_WIN32` |      Result |
+|-------------------------------|----------------------------------|-------------|
+|                          `ON` |                             `ON` |       error |
+|                          `ON` |                            `OFF` |    force-on |
+|                         `OFF` |                             `ON` |   force-off |
+|                         `OFF` |                            `OFF` | auto-detect |
+
+
+
 ## Installing Catch2 from git repository
 
 If you cannot install Catch2 from a package manager (e.g. Ubuntu 16.04

docs/command-line.md

@@ -19,6 +19,7 @@
 [Specify a seed for the Random Number Generator](#specify-a-seed-for-the-random-number-generator)<br>
 [Identify framework and version according to the libIdentify standard](#identify-framework-and-version-according-to-the-libidentify-standard)<br>
 [Wait for key before continuing](#wait-for-key-before-continuing)<br>
+[Skip all benchmarks](#skip-all-benchmarks)<br>
 [Specify the number of benchmark samples to collect](#specify-the-number-of-benchmark-samples-to-collect)<br>
 [Specify the number of resamples for bootstrapping](#specify-the-number-of-resamples-for-bootstrapping)<br>
 [Specify the confidence-interval for bootstrapping](#specify-the-confidence-interval-for-bootstrapping)<br>
@@ -58,10 +59,12 @@ Click one of the following links to take you straight to that option - or scroll
 <a href="#listing-available-tests-tags-or-reporters">   `    --list-tests`</a><br />
 <a href="#listing-available-tests-tags-or-reporters">   `    --list-tags`</a><br />
 <a href="#listing-available-tests-tags-or-reporters">   `    --list-reporters`</a><br />
+<a href="#listing-available-tests-tags-or-reporters">   `    --list-listeners`</a><br />
 <a href="#order">                                       `    --order`</a><br />
 <a href="#rng-seed">                                    `    --rng-seed`</a><br />
 <a href="#libidentify">                                 `    --libidentify`</a><br />
 <a href="#wait-for-keypress">                           `    --wait-for-keypress`</a><br />
+<a href="#skip-benchmarks">                             `    --skip-benchmarks`</a><br />
 <a href="#benchmark-samples">                           `    --benchmark-samples`</a><br />
 <a href="#benchmark-resamples">                         `    --benchmark-resamples`</a><br />
 <a href="#benchmark-confidence-interval">               `    --benchmark-confidence-interval`</a><br />
@@ -142,10 +145,10 @@ hardcoded into Catch2. Currently there are only 2,
 _Note that the reporter might still check the X-prefixed options for
 validity, and throw an error if they are wrong._
 
-> Support for passing arguments to reporters through the `-r`, `--reporter` flag was introduced in Catch2 X.Y.Z
+> Support for passing arguments to reporters through the `-r`, `--reporter` flag was introduced in Catch2 3.0.1
 
-There are multiple built-in reporters, you can see what they do by using the 
-[`--list-reporter`](command-line.md#listing-available-tests-tags-or-reporters)
+There are multiple built-in reporters, you can see what they do by using the
+[`--list-reporters`](command-line.md#listing-available-tests-tags-or-reporters)
 flag. If you need a reporter providing custom format outside of the already
 provided ones, look at the ["write your own reporter" part of the reporter
 documentation](reporters.md#writing-your-own-reporter).
@@ -157,7 +160,7 @@ reporter can be provided without the output-file part of reporter spec.
 This reporter will use the "default" output destination, based on
 the [`-o`, `--out`](#sending-output-to-a-file) option.
 
-> Support for using multiple different reporters at the same time was [introduced](https://github.com/catchorg/Catch2/pull/2183) in Catch2 X.Y.Z
+> Support for using multiple different reporters at the same time was [introduced](https://github.com/catchorg/Catch2/pull/2183) in Catch2 3.0.1
 
 
 _Note: There is currently no way to escape `::` in the reporter spec,
@@ -198,9 +201,12 @@ Sometimes this results in a flood of failure messages and you'd rather just see
 --list-tests
 --list-tags
 --list-reporters
+--list-listeners
 ```
 
-> The `--list*` options became customizable through reporters in Catch2 X.Y.Z
+> The `--list*` options became customizable through reporters in Catch2 3.0.1
+
+> The `--list-listeners` option was added in Catch2 3.0.1
 
 `--list-tests` lists all registered tests matching specified test spec.
 Usually this listing also includes tags, and potentially also other
@@ -212,6 +218,17 @@ similar information.
 
 `--list-reporters` lists all available reporters and their descriptions.
 
+`--list-listeners` lists all registered listeners and their descriptions.
+
+The [`--verbosity` argument](#output-verbosity) modifies the level of detail provided by the default `--list*` options
+as follows:
+
+| Option             | `normal` (default)              | `quiet`             | `high`                                  |
+|--------------------|---------------------------------|---------------------|-----------------------------------------|
+| `--list-tests`     | Test names and tags             | Test names only     | Same as `normal`, plus source code line |
+| `--list-tags`      | Tags and counts                 | Same as `normal`    | Same as `normal`                        |
+| `--list-reporters` | Reporter names and descriptions | Reporter names only | Same as `normal`                        |
+| `--list-listeners` | Listener names and descriptions | Same as `normal`    | Same as `normal`                        |
 
 <a id="sending-output-to-a-file"></a>
 ## Sending output to a file
@@ -222,7 +239,7 @@ Use this option to send all output to a file, instead of stdout. You can
 use `-` as the filename to explicitly send the output to stdout (this is
 useful e.g. when using multiple reporters).
 
-> Support for `-` as the filename was introduced in Catch2 X.Y.Z
+> Support for `-` as the filename was introduced in Catch2 3.0.1
 
 Filenames starting with "%" (percent symbol) are reserved by Catch2 for
 meta purposes, e.g. using `%debug` as the filename opens stream that
@@ -234,7 +251,7 @@ Catch2 currently recognizes 3 meta streams:
 * `%stdout` - writes to stdout
 * `%stderr` - writes to stderr
 
-> Support for `%stdout` and `%stderr` was introduced in Catch2 X.Y.Z
+> Support for `%stdout` and `%stderr` was introduced in Catch2 3.0.1
 
 
 <a id="naming-a-test-run"></a>
@@ -267,7 +284,7 @@ This option transforms tabs and newline characters into ```\t``` and ```\n``` re
 <pre>-w, --warn &lt;warning name></pre>
 
 You can think of Catch2's warnings as the equivalent of `-Werror` (`/WX`)
-flag for C++ compilers. It turns some suspicious occurences, like a section
+flag for C++ compilers. It turns some suspicious occurrences, like a section
 without assertions, into errors. Because these might be intended, warnings
 are not enabled by default, but user can opt in.
 
@@ -282,7 +299,7 @@ There are currently two warnings implemented:
                         // not match any tests.
 ```
 
-> `UnmatchedTestSpec` was introduced in Catch2 X.Y.Z.
+> `UnmatchedTestSpec` was introduced in Catch2 3.0.1.
 
 
 <a id="reporting-timings"></a>
@@ -296,7 +313,7 @@ When set to ```yes``` Catch will report the duration of each test case, in milli
 > `--min-duration` was [introduced](https://github.com/catchorg/Catch2/pull/1910) in Catch2 2.13.0
 
 When set, Catch will report the duration of each test case that took more
-than &lt;value> seconds, in milliseconds. This option is overriden by both
+than &lt;value> seconds, in milliseconds. This option is overridden by both
 `-d yes` and `-d no`, so that either all durations are reported, or none
 are.
 
@@ -322,8 +339,8 @@ Test cases are ordered one of three ways:
 
 ### decl
 Declaration order (this is the default order if no --order argument is provided).
-Tests in the same TU are sorted using their declaration orders, different
-TUs are in an implementation (linking) dependent order.
+Tests in the same translation unit are sorted using their declaration orders,
+different TUs are sorted in an implementation (linking) dependent order.
 
 
 ### lex
@@ -332,13 +349,19 @@ Lexicographic order. Tests are sorted by their name, their tags are ignored.
 
 ### rand
 
-Randomly sorted. The order is dependent on Catch2's random seed (see
+Randomly ordered. The order is dependent on Catch2's random seed (see
 [`--rng-seed`](#rng-seed)), and is subset invariant. What this means
 is that as long as the random seed is fixed, running only some tests
 (e.g. via tag) does not change their relative order.
 
 > The subset stability was introduced in Catch2 v2.12.0
 
+Since the random order was made subset stable, we promise that given
+the same random seed, the order of test cases will be the same across
+different platforms, as long as the tests were compiled against identical
+version of Catch2. We reserve the right to change the relative order
+of tests cases between Catch2 versions, but it is unlikely to happen often.
+
 
 <a id="rng-seed"></a>
 ## Specify a seed for the Random Number Generator
@@ -370,6 +393,16 @@ See [The LibIdentify repo for more information and examples](https://github.com/
 Will cause the executable to print a message and wait until the return/ enter key is pressed before continuing -
 either before running any tests, after running all tests - or both, depending on the argument.
 
+<a id="skip-benchmarks"></a>
+## Skip all benchmarks
+<pre>--skip-benchmarks</pre>
+
+> [Introduced](https://github.com/catchorg/Catch2/issues/2408) in Catch2 3.0.1.
+
+This flag tells Catch2 to skip running all benchmarks. Benchmarks in this
+case mean code blocks in `BENCHMARK` and `BENCHMARK_ADVANCED` macros, not
+test cases with the `[!benchmark]` tag.
+
 <a id="benchmark-samples"></a>
 ## Specify the number of benchmark samples to collect
 <pre>--benchmark-samples &lt;# of samples&gt;</pre>
@@ -483,7 +516,7 @@ So, for example,  tests within the file `~\Dev\MyProject\Ferrets.cpp` would be t
 ## Override output colouring
 <pre>--colour-mode &lt;ansi|win32|none|default&gt;</pre>
 
-> The `--colour-mode` option replaced the old `--colour` option in Catch2 X.Y.Z
+> The `--colour-mode` option replaced the old `--colour` option in Catch2 3.0.1
 
 
 Catch2 support two different ways of colouring terminal output, and by
@@ -507,32 +540,38 @@ when writing to a file
 ## Test Sharding
 <pre>--shard-count <#number of shards>, --shard-index <#shard index to run></pre>
 
-> [Introduced](https://github.com/catchorg/Catch2/pull/2257) in Catch2 X.Y.Z.
+> [Introduced](https://github.com/catchorg/Catch2/pull/2257) in Catch2 3.0.1.
 
-When `--shard-count <#number of shards>` is used, the tests to execute will be split evenly in to the given number of sets,
-identified by indicies starting at 0. The tests in the set given by `--shard-index <#shard index to run>` will be executed.
-The default shard count is `1`, and the default index to run is `0`. It is an error to specify a shard index greater than
-the number of shards.
+When `--shard-count <#number of shards>` is used, the tests to execute
+will be split evenly in to the given number of sets, identified by indices
+starting at 0. The tests in the set given by
+`--shard-index <#shard index to run>` will be executed. The default shard
+count is `1`, and the default index to run is `0`.
+
+_Shard index must be less than number of shards. As the name suggests,
+it is treated as an index of the shard to run._
+
+Sharding is useful when you want to split test execution across multiple
+processes, as is done with the [Bazel test sharding](https://docs.bazel.build/versions/main/test-encyclopedia.html#test-sharding).
 
-This is useful when you want to split test execution across multiple processes, as is done with [Bazel test sharding](https://docs.bazel.build/versions/main/test-encyclopedia.html#test-sharding). 
 
 <a id="no-tests-override"></a>
 ## Allow running the binary without tests
 <pre>--allow-running-no-tests</pre>
 
-> Introduced in Catch2 X.Y.Z.
+> Introduced in Catch2 3.0.1.
 
-By default, Catch2 test binaries return non-0 exit code if no tests were
-run, e.g. if the binary was compiled with no tests, or the provided test
-spec matched no tests. This flag overrides that, so a test run with no
-tests still returns 0.
+By default, Catch2 test binaries return non-0 exit code if no tests were run,
+e.g. if the binary was compiled with no tests, the provided test spec matched no
+tests, or all tests [were skipped at runtime](skipping-passing-failing.md#top). This flag
+overrides that, so a test run with no tests still returns 0.
 
 ## Output verbosity
 ```
 -v, --verbosity <quiet|normal|high>
 ```
 
-Changing verbosity might change how much details Catch2's reporters output.
+Changing verbosity might change how many details Catch2's reporters output.
 However, you should consider changing the verbosity level as a _suggestion_.
 Not all reporters support all verbosity levels, e.g. because the reporter's
 format cannot meaningfully change. In that case, the verbosity level is

docs/commercial-users.md

@@ -6,16 +6,17 @@ some of them that are willing to share this information.
 
 If you want to add your organisation, please check that there is no issue
 with you sharing this fact.
- 
+
  - Bloomberg
  - [Bloomlife](https://bloomlife.com)
  - [Inscopix Inc.](https://www.inscopix.com/)
  - Locksley.CZ
  - [Makimo](https://makimo.pl/)
  - NASA
+ - [Nexus Software Systems](https://nexwebsites.com)
  - [UX3D](https://ux3d.io)
  - [King](https://king.com)
- 
+
 
 ---
 

docs/comparing-floating-point-numbers.md

@@ -0,0 +1,192 @@
+<a id="top"></a>
+# Comparing floating point numbers with Catch2
+
+If you are not deeply familiar with them, floating point numbers can be
+unintuitive. This also applies to comparing floating point numbers for
+(in)equality.
+
+This page assumes that you have some understanding of both FP, and the
+meaning of different kinds of comparisons, and only goes over what
+functionality Catch2 provides to help you with comparing floating point
+numbers. If you do not have this understanding, we recommend that you first
+study up on floating point numbers and their comparisons, e.g. by [reading
+this blog post](https://codingnest.com/the-little-things-comparing-floating-point-numbers/).
+
+
+## Floating point matchers
+
+```
+#include <catch2/matchers/catch_matchers_floating_point.hpp>
+```
+
+[Matchers](matchers.md#top) are the preferred way of comparing floating
+point numbers in Catch2. We provide 3 of them:
+
+* `WithinAbs(double target, double margin)`,
+* `WithinRel(FloatingPoint target, FloatingPoint eps)`, and
+* `WithinULP(FloatingPoint target, uint64_t maxUlpDiff)`.
+
+> `WithinRel` matcher was introduced in Catch2 2.10.0
+
+As with all matchers, you can combine multiple floating point matchers
+in a single assertion. For example, to check that some computation matches
+a known good value within 0.1% or is close enough (no different to 5
+decimal places) to zero, we would write this assertion:
+
+```cpp
+    REQUIRE_THAT( computation(input),
+        Catch::Matchers::WithinRel(expected, 0.001)
+     || Catch::Matchers::WithinAbs(0, 0.000001) );
+```
+
+
+### WithinAbs
+
+`WithinAbs` creates a matcher that accepts floating point numbers whose
+difference with `target` is less-or-equal to the `margin`. Since `float`
+can be converted to `double` without losing precision, only `double`
+overload exists.
+
+```cpp
+REQUIRE_THAT(1.0, WithinAbs(1.2, 0.2));
+REQUIRE_THAT(0.f, !WithinAbs(1.0, 0.5));
+// Notice that infinity == infinity for WithinAbs
+REQUIRE_THAT(INFINITY, WithinAbs(INFINITY, 0));
+```
+
+
+### WithinRel
+
+`WithinRel` creates a matcher that accepts floating point numbers that
+are _approximately equal_ to the `target` with a tolerance of `eps.`
+Specifically, it matches if
+`|arg - target| <= eps * max(|arg|, |target|)` holds. If you do not
+specify `eps`, `std::numeric_limits<FloatingPoint>::epsilon * 100`
+is used as the default.
+
+```cpp
+// Notice that WithinRel comparison is symmetric, unlike Approx's.
+REQUIRE_THAT(1.0, WithinRel(1.1, 0.1));
+REQUIRE_THAT(1.1, WithinRel(1.0, 0.1));
+// Notice that inifnity == infinity for WithinRel
+REQUIRE_THAT(INFINITY, WithinRel(INFINITY));
+```
+
+
+### WithinULP
+
+`WithinULP` creates a matcher that accepts floating point numbers that
+are no more than `maxUlpDiff`
+[ULPs](https://en.wikipedia.org/wiki/Unit_in_the_last_place)
+away from the `target` value. The short version of what this means
+is that there is no more than `maxUlpDiff - 1` representable floating
+point numbers between the argument for matching and the `target` value.
+
+When using the ULP matcher in Catch2, it is important to keep in mind
+that Catch2 interprets ULP distance slightly differently than
+e.g. `std::nextafter` does.
+
+Catch2's ULP calculation obeys these relations:
+  * `ulpDistance(-x, x) == 2 * ulpDistance(x, 0)`
+  * `ulpDistance(-0, 0) == 0` (due to the above)
+  * `ulpDistance(DBL_MAX, INFINITY) == 1`
+  * `ulpDistancE(NaN, x) == infinity`
+
+
+**Important**: The WithinULP matcher requires the platform to use the
+[IEEE-754](https://en.wikipedia.org/wiki/IEEE_754) representation for
+floating point numbers.
+
+```cpp
+REQUIRE_THAT( -0.f, WithinULP( 0.f, 0 ) );
+```
+
+
+## `Approx`
+
+```
+#include <catch2/catch_approx.hpp>
+```
+
+**We strongly recommend against using `Approx` when writing new code.**
+You should be using floating point matchers instead.
+
+Catch2 provides one more way to handle floating point comparisons. It is
+`Approx`, a special type with overloaded comparison operators, that can
+be used in standard assertions, e.g.
+
+```cpp
+REQUIRE(0.99999 == Catch::Approx(1));
+```
+
+`Approx` supports four comparison operators, `==`, `!=`, `<=`, `>=`, and can
+also be used with strong typedefs over `double`s. It can be used for both
+relative and margin comparisons by using its three customization points.
+Note that the semantics of this is always that of an _or_, so if either
+the relative or absolute margin comparison passes, then the whole comparison
+passes.
+
+The downside to `Approx` is that it has a couple of issues that we cannot
+fix without breaking backwards compatibility. Because Catch2 also provides
+complete set of matchers that implement different floating point comparison
+methods, `Approx` is left as-is, is considered deprecated, and should
+not be used in new code.
+
+The issues are
+  * All internal computation is done in `double`s, leading to slightly
+    different results if the inputs were floats.
+  * `Approx`'s relative margin comparison is not symmetric. This means
+    that `Approx( 10 ).epsilon(0.1) != 11.1` but `Approx( 11.1 ).epsilon(0.1) == 10`.
+  * By default, `Approx` only uses relative margin comparison. This means
+    that `Approx(0) == X` only passes for `X == 0`.
+
+
+### Approx details
+
+If you still want/need to know more about `Approx`, read on.
+
+Catch2 provides a UDL for `Approx`; `_a`. It resides in the `Catch::literals`
+namespace, and can be used like this:
+
+```cpp
+using namespace Catch::literals;
+REQUIRE( performComputation() == 2.1_a );
+```
+
+`Approx` has three customization points for the comparison:
+
+* **epsilon** - epsilon sets the coefficient by which a result
+can differ from `Approx`'s value before it is rejected.
+_Defaults to `std::numeric_limits<float>::epsilon()*100`._
+
+```cpp
+Approx target = Approx(100).epsilon(0.01);
+100.0 == target; // Obviously true
+200.0 == target; // Obviously still false
+100.5 == target; // True, because we set target to allow up to 1% difference
+```
+
+
+* **margin** - margin sets the absolute value by which
+a result can differ from `Approx`'s value before it is rejected.
+_Defaults to `0.0`._
+
+```cpp
+Approx target = Approx(100).margin(5);
+100.0 == target; // Obviously true
+200.0 == target; // Obviously still false
+104.0 == target; // True, because we set target to allow absolute difference of at most 5
+```
+
+* **scale** - scale is used to change the magnitude of `Approx` for the relative check.
+_By default, set to `0.0`._
+
+Scale could be useful if the computation leading to the result worked
+on a different scale than is used by the results. Approx's scale is added
+to Approx's value when computing the allowed relative margin from the
+Approx's value.
+
+
+---
+
+[Home](Readme.md#top)

docs/configuration.md

@@ -19,7 +19,7 @@
 Catch2 is designed to "just work" as much as possible, and most of the
 configuration options below are changed automatically during compilation,
 according to the detected environment. However, this detection can also
-be overriden by users, using macros documented below, and/or CMake options
+be overridden by users, using macros documented below, and/or CMake options
 with the same name.
 
 
@@ -98,10 +98,18 @@ is equivalent with the out-of-the-box experience.
 
 
 ## Bazel support
-When `CATCH_CONFIG_BAZEL_SUPPORT` is defined, Catch2 will register a `JUnit`
-reporter writing to a path pointed by `XML_OUTPUT_FILE` provided by Bazel.
 
-> `CATCH_CONFIG_BAZEL_SUPPORT` was [introduced](https://github.com/catchorg/Catch2/pull/2399) in Catch2 X.Y.Z.
+Compiling Catch2 with `CATCH_CONFIG_BAZEL_SUPPORT` force-enables Catch2's
+support for Bazel's environment variables (normally Catch2 looks for
+`BAZEL_TEST=1` env var first).
+
+This can be useful if you are using older versions of Bazel, that do not
+yet have `BAZEL_TEST` env var support.
+
+> `CATCH_CONFIG_BAZEL_SUPPORT` was [introduced](https://github.com/catchorg/Catch2/pull/2399) in Catch2 3.0.1.
+
+> `CATCH_CONFIG_BAZEL_SUPPORT` was [deprecated](https://github.com/catchorg/Catch2/pull/2459) in Catch2 3.1.0.
+
 
 ## C++11 toggles
 
@@ -147,13 +155,20 @@ by using `_NO_` in the macro, e.g. `CATCH_CONFIG_NO_CPP17_UNCAUGHT_EXCEPTIONS`.
     CATCH_CONFIG_USE_ASYNC                  // Force parallel statistical processing of samples during benchmarking
     CATCH_CONFIG_ANDROID_LOGWRITE           // Use android's logging system for debug output
     CATCH_CONFIG_GLOBAL_NEXTAFTER           // Use nextafter{,f,l} instead of std::nextafter
+    CATCH_CONFIG_GETENV                     // System has a working `getenv`
 
 > [`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
 
+> `CATCH_CONFIG_GETENV` was [introduced](https://github.com/catchorg/Catch2/pull/2562) in Catch2 3.2.0
+
 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.
 
 `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_GETENV` is on by default, except when Catch2 is compiled for
+platforms that lacks working `std::getenv` (currently Windows UWP and
+Playstation).
+
 `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. This option only works when linking against the default

docs/contributing.md

@@ -125,7 +125,7 @@ information that you will need for updating Catch2's documentation, and
 possibly some generic advise as well.
 
 
-### Technicalities 
+### Technicalities
 
 First, the technicalities:
 
@@ -136,6 +136,8 @@ should use. It provides you with the top anchor mentioned to link to
 <a id="top"></a>
 # Cool feature
 
+> [Introduced](https://github.com/catchorg/Catch2/pull/123456) in Catch2 X.Y.Z
+
 Text that explains how to use the cool feature.
 
 
@@ -201,7 +203,7 @@ and so on.
 
 Catch2 currently targets C++14 as the minimum supported C++ version.
 Features from higher language versions should be used only sparingly,
-when the benefits from using them outweight the maintenance overhead.
+when the benefits from using them outweigh the maintenance overhead.
 
 Example of good use of polyfilling features is our use of `conjunction`,
 where if available we use `std::conjunction` and otherwise provide our
@@ -289,16 +291,30 @@ Specifically, every source file should start with the licence header:
 
     //              Copyright Catch2 Authors
     // Distributed under the Boost Software License, Version 1.0.
-    //   (See accompanying file LICENSE_1_0.txt or copy at
+    //   (See accompanying file LICENSE.txt or copy at
     //        https://www.boost.org/LICENSE_1_0.txt)
 
     // SPDX-License-Identifier: BSL-1.0
 ```
 
 The include guards for header files should follow the pattern `{FILENAME}_INCLUDED`.
-This means that for file `catch_matchers_foo`, the include guard should
-be `CATCH_MATCHERS_FOO_INCLUDED`, for `catch_generators_bar`, the include
-guard should be `CATCH_GENERATORS_BAR_INCLUDED`, and so on.
+This means that for file `catch_matchers_foo.hpp`, the include guard should
+be `CATCH_MATCHERS_FOO_HPP_INCLUDED`, for `catch_generators_bar.hpp`, the include
+guard should be `CATCH_GENERATORS_BAR_HPP_INCLUDED`, and so on.
+
+
+### Adding new `CATCH_CONFIG` option
+
+When adding new `CATCH_CONFIG` option, there are multiple places to edit:
+  * `CMake/CatchConfigOptions.cmake` - this is used to generate the
+    configuration options in CMake, so that CMake frontends know about them.
+  * `docs/configuration.md` - this is where the options are documented
+  * `src/catch2/catch_user_config.hpp.in` - this is template for generating
+    `catch_user_config.hpp` which contains the materialized configuration
+  * `BUILD.bazel` - Bazel does not have configuration support like CMake,
+    and all expansions need to be done manually
+  * other files as needed, e.g. `catch2/internal/catch_config_foo.hpp`
+    for the logic that guards the configuration
 
 
 ## CoC

docs/deprecations.md

@@ -17,13 +17,23 @@ as it can be replaced by `Catch.cmake` that provides the function
 command line interface instead of parsing C++ code with regular expressions.
 
 
-## Planned changes
+### `CATCH_CONFIG_BAZEL_SUPPORT`
 
-### Console Colour API
+Catch2 supports writing the Bazel JUnit XML output file when it is aware
+that is within a bazel testing environment. Originally there was no way
+to accurately probe the environment for this information so the flag
+`CATCH_CONFIG_BAZEL_SUPPORT` was added. This now deprecated. Bazel has now had a change
+where it will export `BAZEL_TEST=1` for purposes like the above. Catch2
+will now instead inspect the environment instead of relying on build configuration.
 
-The API for Catch2's console colour will be changed to take an extra
-argument, the stream to which the colour code should be applied.
+### `IEventLister::skipTest( TestCaseInfo const& testInfo )`
 
+This event (including implementations in derived classes such as `ReporterBase`)
+is deprecated and will be removed in the next major release. It is currently
+invoked for all test cases that are not going to be executed due to the test run
+being aborted (when using `--abort` or `--abortx`). It is however
+**NOT** invoked for test cases that are [explicitly skipped using the `SKIP`
+macro](skipping-passing-failing.md#top).
 
 ---
 

docs/event-listeners.md

@@ -33,7 +33,7 @@ public:
 CATCH_REGISTER_LISTENER(testRunListener)
 ```
 
-_Note that you should not use any assertion macros within a Listener!_ 
+_Note that you should not use any assertion macros within a Listener!_
 
 [You can find the list of events that the listeners can react to on its
 own page](reporter-events.md#top).

docs/faq.md

@@ -1,6 +1,17 @@
 <a id="top"></a>
 # Frequently Asked Questions (FAQ)
 
+**Contents**<br>
+[How do I run global setup/teardown only if tests will be run?](#how-do-i-run-global-setupteardown-only-if-tests-will-be-run)<br>
+[How do I clean up global state between running different tests?](#how-do-i-clean-up-global-state-between-running-different-tests)<br>
+[Why cannot I derive from the built-in reporters?](#why-cannot-i-derive-from-the-built-in-reporters)<br>
+[What is Catch2's ABI stability policy?](#what-is-catch2s-abi-stability-policy)<br>
+[What is Catch2's API stability policy?](#what-is-catch2s-api-stability-policy)<br>
+[Does Catch2 support running tests in parallel?](#does-catch2-support-running-tests-in-parallel)<br>
+[Can I compile Catch2 into a dynamic library?](#can-i-compile-catch2-into-a-dynamic-library)<br>
+[What repeatability guarantees does Catch2 provide?](#what-repeatability-guarantees-does-catch2-provide)<br>
+
+
 ## How do I run global setup/teardown only if tests will be run?
 
 Write a custom [event listener](event-listeners.md#top) and place the
@@ -16,12 +27,68 @@ depending on how often the cleanup needs to happen.
 
 ## Why cannot I derive from the built-in reporters?
 
-They are not made to be overriden, in that we do not attempt to maintain
+They are not made to be overridden, in that we do not attempt to maintain
 a consistent internal state if a member function is overriden, and by
 forbidding users from using them as a base class, we can refactor them
 as needed later.
 
 
+## What is Catch2's ABI stability policy?
+
+Catch2 provides no ABI stability guarantees whatsoever. Catch2 provides
+rich C++ interface, and trying to freeze its ABI would take a lot of
+pointless work.
+
+Catch2 is not designed to be distributed as dynamic library, and you
+should really be able to compile everything with the same compiler binary.
+
+
+## What is Catch2's API stability policy?
+
+Catch2 follows [semver](https://semver.org/) to the best of our ability.
+This means that we will not knowingly make backwards-incompatible changes
+without incrementing the major version number.
+
+
+## Does Catch2 support running tests in parallel?
+
+Not natively, no. We see running tests in parallel as the job of an
+external test runner, that can also run them in separate processes,
+support test execution timeouts and so on.
+
+However, Catch2 provides some tools that make the job of external test
+runners easier. [See the relevant section in our page on best
+practices](usage-tips.md#parallel-tests).
+
+
+## Can I compile Catch2 into a dynamic library?
+
+Yes, Catch2 supports the [standard CMake `BUILD_SHARED_LIBS`
+option](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html).
+However, the dynamic library support is provided as-is. Catch2 does not
+provide API export annotations, and so you can only use it as a dynamic
+library on platforms that default to public visibility, or with tooling
+support to force export Catch2's API.
+
+
+## What repeatability guarantees does Catch2 provide?
+
+There are two places where it is meaningful to talk about Catch2's
+repeatability guarantees without taking into account user-provided
+code. First one is in the test case shuffling, and the second one is
+the output from random generators.
+
+Test case shuffling is repeatable across different platforms since v2.12.0,
+and it is also generally repeatable across versions, but we might break
+it from time to time. E.g. we broke repeatability with previous versions
+in v2.13.4 so that test cases with similar names are shuffled better.
+
+Random generators currently rely on platform's stdlib, specifically
+the distributions from `<random>`. We thus provide no extra guarantee
+above what your platform does. **Important: `<random>`'s distributions
+are not specified to be repeatable across different platforms.**
+
+
 ---
 
 [Home](Readme.md#top)

docs/generators.md

@@ -205,13 +205,17 @@ struct IGenerator : GeneratorUntypedBase {
     // Precondition:
     // The generator is either freshly constructed or the last call to next() returned true
     virtual T const& get() const = 0;
+
+    // Returns user-friendly string showing the current generator element
+    // Does not have to be overridden, IGenerator provides default implementation
+    virtual std::string stringifyImpl() const;
 };
 ```
 
 However, to be able to use your custom generator inside `GENERATE`, it
 will need to be wrapped inside a `GeneratorWrapper<T>`.
 `GeneratorWrapper<T>` is a value wrapper around a
-`std::unique_ptr<IGenerator<T>>`.
+`Catch::Detail::unique_ptr<IGenerator<T>>`.
 
 For full example of implementing your own generator, look into Catch2's
 examples, specifically

docs/limitations.md

@@ -99,7 +99,7 @@ Catch does not support running tests in isolated (forked) processes. While this
 
 Catch2 keeps test execution in one process strictly serial, and there
 are no plans to change this. If you find yourself with a test suite
-that takes too long to run and yo uwant to make it parallel, you have
+that takes too long to run and you want to make it parallel, you have
 to run multiple processes side by side.
 
 There are 2 basic ways to do that,
@@ -155,7 +155,7 @@ with expansion:
 
 
 ### Clang/G++ -- skipping leaf sections after an exception
-Some versions of `libc++` and `libstdc++` (or their runtimes) have a bug with `std::uncaught_exception()` getting stuck returning `true` after rethrow, even if there are no active exceptions. One such case is this snippet, which skipped the sections "a" and "b", when compiled against `libcxxrt` from master
+Some versions of `libc++` and `libstdc++` (or their runtimes) have a bug with `std::uncaught_exception()` getting stuck returning `true` after rethrow, even if there are no active exceptions. One such case is this snippet, which skipped the sections "a" and "b", when compiled against `libcxxrt` from the master branch
 ```cpp
 #include <catch2/catch_test_macros.hpp>
 
@@ -171,7 +171,7 @@ TEST_CASE("b") {
 }
 ```
 
-If you are seeing a problem like this, i.e. a weird test paths that trigger only under Clang with `libc++`, or only under very specific version of `libstdc++`, it is very likely you are seeing this. The only known workaround is to use a fixed version of your standard library.
+If you are seeing a problem like this, i.e. weird test paths that trigger only under Clang with `libc++`, or only under very specific version of `libstdc++`, it is very likely you are seeing this. The only known workaround is to use a fixed version of your standard library.
 
 
 ### libstdc++, `_GLIBCXX_DEBUG` macro and random ordering of tests

docs/matchers.md

@@ -150,49 +150,8 @@ are:
 
 > `WithinRel` matcher was introduced in Catch2 2.10.0
 
-
-`WithinAbs` creates a matcher that accepts floating point numbers whose
-difference with `target` is less than the `margin`.
-
-`WithinULP` creates a matcher that accepts floating point numbers that
-are no more than `maxUlpDiff`
-[ULPs](https://en.wikipedia.org/wiki/Unit_in_the_last_place)
-away from the `target` value. The short version of what this means
-is that there is no more than `maxUlpDiff - 1` representeable floating
-point numbers between the argument for matching and the `target` value.
-
-**Important**: The WithinULP matcher requires the platform to use the
-[IEEE-754](https://en.wikipedia.org/wiki/IEEE_754) representation for
-floating point numbers.
-
-
-`WithinRel` creates a matcher that accepts floating point numbers that
-are _approximately equal_ with the `target` with tolerance of `eps.`
-Specifically, it matches if
-`|arg - target| <= eps * max(|arg|, |target|)` holds. If you do not
-specify `eps`, `std::numeric_limits<FloatingPoint>::epsilon * 100`
-is used as the default.
-
-
-In practice, you will often want to combine multiple of these matchers,
-together for an assertion, because all 3 options have edge cases where
-they behave differently than you would expect. As an example, under
-the `WithinRel` matcher, a `0.` only ever matches a `0.` (or `-0.`),
-regardless of the relative tolerance specified. Thus, if you want to
-handle numbers that are "close enough to 0 to be 0", you have to combine
-it with the `WithinAbs` matcher.
-
-For example, to check that our computation matches known good value
-within 0.1%, or is close enough (no different to 5 decimal places)
-to zero, we would write this assertion:
-```cpp
-    REQUIRE_THAT( computation(input),
-        Catch::Matchers::WithinRel(expected, 0.001)
-     || Catch::Matchers::WithinAbs(0, 0.000001) );
-```
-
-
-> floating point matchers live in `catch2/matchers/catch_matchers_floating.hpp`
+For more details, read [the docs on comparing floating point
+numbers](comparing-floating-point-numbers.md#floating-point-matchers).
 
 
 ### Miscellaneous matchers
@@ -224,20 +183,30 @@ The other miscellaneous matcher utility is exception matching.
 
 #### Matching exceptions
 
-Catch2 provides an utility macro for asserting that an expression
+Catch2 provides a utility macro for asserting that an expression
 throws exception of specific type, and that the exception has desired
 properties. The macro is `REQUIRE_THROWS_MATCHES(expr, ExceptionType, Matcher)`.
 
 > `REQUIRE_THROWS_MATCHES` macro lives in `catch2/matchers/catch_matchers.hpp`
 
 
-Catch2 currently provides only one matcher for exceptions,
-`Message(std::string message)`. `Message` checks that the exception's
+Catch2 currently provides two matchers for exceptions.
+These are:
+* `Message(std::string message)`.
+* `MessageMatches(Matcher matcher)`.
+
+> `MessageMatches` was [introduced](https://github.com/catchorg/Catch2/pull/2570) in Catch2 3.3.0
+
+`Message` checks that the exception's
 message, as returned from `what` is exactly equal to `message`.
 
+`MessageMatches` applies the provided matcher on the exception's
+message, as returned from `what`. This is useful in conjunctions with the `std::string` matchers (e.g. `StartsWith`)
+
 Example use:
 ```cpp
 REQUIRE_THROWS_MATCHES(throwsDerivedException(),  DerivedException,  Message("DerivedException::what"));
+REQUIRE_THROWS_MATCHES(throwsDerivedException(),  DerivedException,  MessageMatches(StartsWith("DerivedException")));
 ```
 
 Note that `DerivedException` in the example above has to derive from
@@ -248,7 +217,7 @@ Note that `DerivedException` in the example above has to derive from
 
 ### Generic range Matchers
 
-> Generic range matchers were introduced in Catch2 X.Y.Z
+> Generic range matchers were introduced in Catch2 3.0.1
 
 Catch2 also provides some matchers that use the new style matchers
 definitions to handle generic range-like types. These are:
@@ -258,6 +227,20 @@ definitions to handle generic range-like types. These are:
 * `SizeIs(Matcher size_matcher)`
 * `Contains(T&& target_element, Comparator = std::equal_to<>{})`
 * `Contains(Matcher element_matcher)`
+* `AllMatch(Matcher element_matcher)`
+* `AnyMatch(Matcher element_matcher)`
+* `NoneMatch(Matcher element_matcher)`
+* `AllTrue()`, `AnyTrue()`, `NoneTrue()`
+* `RangeEquals(TargetRangeLike&&, Comparator = std::equal_to<>{})`
+* `UnorderedRangeEquals(TargetRangeLike&&, Comparator = std::equal_to<>{})`
+
+> `IsEmpty`, `SizeIs`, `Contains` were introduced in Catch2 3.0.1
+
+> `All/Any/NoneMatch` were introduced in Catch2 3.0.1
+
+> `All/Any/NoneTrue` were introduced in Catch2 3.1.0
+
+> `RangeEquals` and `UnorderedRangeEquals` matchers were [introduced](https://github.com/catchorg/Catch2/pull/2377) in Catch2 3.3.0
 
 `IsEmpty` should be self-explanatory. It successfully matches objects
 that are empty according to either `std::empty`, or ADL-found `empty`
@@ -275,6 +258,33 @@ the target element. The other variant is constructed from a matcher,
 in which case a range is accepted if any of its elements is accepted
 by the provided matcher.
 
+`AllMatch`, `NoneMatch`, and `AnyMatch` match ranges for which either
+all, none, or any of the contained elements matches the given matcher,
+respectively.
+
+`AllTrue`, `NoneTrue`, and `AnyTrue` match ranges for which either
+all, none, or any of the contained elements are `true`, respectively.
+It works for ranges of `bool`s and ranges of elements (explicitly)
+convertible to `bool`.
+
+`RangeEquals` compares the range that the matcher is constructed with
+(the "target range") against the range to be tested, element-wise. The
+match succeeds if all elements from the two ranges compare equal (using
+`operator==` by default). The ranges do not need to be the same type,
+and the element types do not need to be the same, as long as they are
+comparable. (e.g. you may compare `std::vector<int>` to `std::array<char>`).
+
+`UnorderedRangeEquals` is similar to `RangeEquals`, but the order
+does not matter. For example "1, 2, 3" would match "3, 2, 1", but not
+"1, 1, 2, 3" As with `RangeEquals`, `UnorderedRangeEquals` compares
+the individual elements using using `operator==` by default.
+
+Both `RangeEquals` and `UnorderedRangeEquals` optionally accept a
+predicate which can be used to compare the containers element-wise.
+
+To check a container elementwise against a given matcher, use
+`AllMatch`.
+
 
 ## Writing custom matchers (old style)
 
@@ -350,11 +360,11 @@ style matchers arbitrarily.
 
 ## Writing custom matchers (new style)
 
-> New style matchers were introduced in Catch2 X.Y.Z
+> New style matchers were introduced in Catch2 3.0.1
 
 To create a new-style matcher, you have to create your own type that
 derives from `Catch::Matchers::MatcherGenericBase`. Your type has to
-also provide two methods, `bool match( ... ) const` and overriden
+also provide two methods, `bool match( ... ) const` and overridden
 `std::string describe() const`.
 
 Unlike with old-style matchers, there are no requirements on how

docs/migrate-v2-to-v3.md

@@ -21,9 +21,10 @@ reduced by roughly 80%. The improved ease of maintenance also led to
 various runtime performance improvements and the introduction of new features.
 For details, look at [the release notes of 3.0.1](release-notes.md#301).
 
-_Note that we still provide one header + one TU distribution but do
-not consider it the primarily supported option. You should also expect
-that the compilation times will be worse if you use this option._
+_Note that we still provide one header + one translation unit (TU)
+distribution but do not consider it the primarily supported option. You
+should also expect that the compilation times will be worse if you use
+this option._
 
 
 ## How to migrate projects from v2 to v3
@@ -50,7 +51,8 @@ compilation times in the v3 version. The basic steps to do so are:
 
 1. Change your CMakeLists.txt to link against `Catch2WithMain` target if
 you use Catch2's default main. (If you do not, keep linking against
-the `Catch2` target.)
+the `Catch2` target.). If you use pkg-config, change `pkg-config catch2` to
+`pkg-config catch2-with-main`.
 2. Delete TU with `CATCH_CONFIG_RUNNER` or `CATCH_CONFIG_MAIN` defined,
 as it is no longer needed.
 3. Change `#include <catch2/catch.hpp>` to `#include <catch2/catch_all.hpp>`
@@ -64,7 +66,9 @@ to piecemeal includes. You will likely want to start by including
 [other notes](#other-notes) for further ideas)
 
 ## Other notes
+
 * The main test include is now `<catch2/catch_test_macros.hpp>`
+
 * Big "subparts" like Matchers, or Generators, have their own folder, and
 also their own "big header", so if you just want to include all matchers,
 you can include `<catch2/matchers/catch_matchers_all.hpp>`,
@@ -72,11 +76,21 @@ or `<catch2/generators/catch_generators_all.hpp>`
 
 
 ## Things that can break during porting
-* The namespace on Matchers were cleaned up, they are no longer first declared
-deep within an internal namespace and then brought up. All Matchers now live
-in `Catch::Matchers`.
-* The reporter interfaces changed in a breaking manner. If you wrote custom
-reporter or listener, you might need to modify them a bit.
+
+* The namespaces of Matchers were flattened and cleaned up.
+
+Matchers are no longer declared deep within an internal namespace and
+then brought up into `Catch` namespace. All Matchers now live in the
+`Catch::Matchers` namespace.
+
+* The `Contains` string matcher was renamed to `ContainsSubstring`.
+
+* The reporter interfaces changed in a breaking manner.
+
+If you are using a custom reporter or listener, you will likely need to
+modify them to conform to the new interfaces. Unlike before in v2,
+the [interfaces](reporters.md#top) and the [events](reporter-events.md#top)
+are now documented.
 
 
 ---

docs/opensource-users.md

@@ -72,7 +72,7 @@ A header-only template engine for modern C++.
 A C++17 template header-only library for the abstraction of memory access patterns.
 
 ### [libcluon](https://github.com/chrberger/libcluon)
-A single-header-only library written in C++14 to glue distributed software components (UDP, TCP, shared memory) supporting natively Protobuf, LCM/ZCM, MsgPack, and JSON for dynamic message transformations in-between. 
+A single-header-only library written in C++14 to glue distributed software components (UDP, TCP, shared memory) supporting natively Protobuf, LCM/ZCM, MsgPack, and JSON for dynamic message transformations in-between.
 
 ### [MNMLSTC Core](https://github.com/mnmlstc/core)
 A small and easy to use C++11 library that adds a functionality set that will be available in C++14 and later, as well as some useful additions.
@@ -118,6 +118,9 @@ A high available cloud native micro-service application management platform impl
 ### [ArangoDB](https://github.com/arangodb/arangodb)
 ArangoDB is a native multi-model database with flexible data models for documents, graphs, and key-values.
 
+### [Cytopia](https://github.com/CytopiaTeam/Cytopia)
+Cytopia is a free, open source retro pixel-art city building game with a big focus on mods. It utilizes a custom isometric rendering engine based on SDL2.
+
 ### [d-SEAMS](https://github.com/d-SEAMS/seams-core)
 Open source molecular dynamics simulation structure analysis suite of tools in modern C++.
 

docs/other-macros.md

@@ -15,7 +15,7 @@ stringification machinery to the _expr_ and records the result. As with
 evaluates to `true`. `CHECKED_ELSE( expr )` work similarly, but the block
 is entered only if the _expr_ evaluated to `false`.
 
-> `CHECKED_X` macros were changed to not count as failure in Catch2 X.Y.Z.
+> `CHECKED_X` macros were changed to not count as failure in Catch2 3.0.1.
 
 Example:
 ```cpp
@@ -77,7 +77,7 @@ TEST_CASE("STATIC_REQUIRE showcase", "[traits]") {
 }
 ```
 
-> `STATIC_CHECK` was [introduced](https://github.com/catchorg/Catch2/pull/2318) in Catch2 X.Y.Z.
+> `STATIC_CHECK` was [introduced](https://github.com/catchorg/Catch2/pull/2318) in Catch2 3.0.1.
 
 `STATIC_CHECK( expr )` is equivalent to `STATIC_REQUIRE( expr )`, with the
 difference that when `CATCH_CONFIG_RUNTIME_STATIC_REQUIRE` is defined, it

docs/release-notes.md

@@ -2,7 +2,12 @@
 
 # Release notes
 **Contents**<br>
-[3.0.1 (in progress)](#301-in-progress)<br>
+[3.3.0](#330)<br>
+[3.2.1](#321)<br>
+[3.2.0](#320)<br>
+[3.1.1](#311)<br>
+[3.1.0](#310)<br>
+[3.0.1](#301)<br>
 [2.13.7](#2137)<br>
 [2.13.6](#2136)<br>
 [2.13.5](#2135)<br>
@@ -49,7 +54,151 @@
 [Even Older versions](#even-older-versions)<br>
 
 
-## 3.0.1 (in progress)
+
+## 3.3.0
+
+### Improvements
+
+* Added `MessageMatches` exception matcher (#2570)
+* Added `RangeEquals` and `UnorderedRangeEquals` generic range matchers (#2377)
+* Added `SKIP` macro for skipping tests from within the test body (#2360)
+  * All built-in reporters have been extended to handle it properly, whether your custom reporter needs changes depends on how it was written
+  * `skipTest` reporter event **is unrelated** to this, and has been deprecated since it has practically no uses
+* Restored support for PPC Macs in the break-into-debugger functionality (#2619)
+* Made our warning suppression compatible with CUDA toolkit pre 11.5 (#2626)
+* Cleaned out some static analysis complaints
+
+
+### Fixes
+
+* Fixed macro redefinition warning when NVCC was reporting as MSVC (#2603)
+* Fixed throws in generator constructor causing the whole binary to abort (#2615)
+  * Now it just fails the test
+* Fixed missing transitive include with libstdc++13 (#2611)
+
+
+### Miscellaneous
+
+* Improved support for dynamic library build with non-MSVC compilers on Windows (#2630)
+* When used as a subproject, Catch2 keeps its generated header in a separate directory from the main project (#2604)
+
+
+
+## 3.2.1
+
+### Improvements
+* Fix the reworked decomposer to work with older (pre 9) GCC versions (#2571)
+  * **This required more significant changes to properly support C++20, there might be bugs.**
+
+
+## 3.2.0
+
+### Improvements
+* Catch2 now compiles on PlayStation (#2562)
+* Added `CATCH_CONFIG_GETENV` compile-time toggle (#2562)
+  * This toggle guards whether Catch2 calls `std::getenv` when reading env variables
+* Added support for more Bazel test environment variables
+  * `TESTBRIDGE_TEST_ONLY` is now supported (#2490)
+  * Sharding variables, `TEST_SHARD_INDEX`, `TEST_TOTAL_SHARDS`, `TEST_SHARD_STATUS_FILE`, are now all supported (#2491)
+* Bunch of small tweaks and improvements in reporters
+  * The TAP and SonarQube reporters output the used test filters
+  * The XML reporter now also reports the version of its output format
+  * The compact reporter now uses the same summary output as the console reporter (#878, #2554)
+* Added support for asserting on types that can only be compared with literal 0 (#2555)
+  * A canonical example is C++20's `std::*_ordering` types, which cannot be compared with an `int` variable, only `0`
+  * The support extends to any type with this property, not just the ones in stdlib
+  * This change imposes 2-3% slowdown on compiling files that are heavy on `REQUIRE` and friends
+  * **This required significant rewrite of decomposition, there might be bugs**
+* Simplified internals of matcher related macros
+  * This provides about ~2% speed up compiling files that are heavy on `REQUIRE_THAT` and friends
+
+
+### Fixes
+* Cleaned out some warnings and static analysis issues
+  * Suppressed `-Wcomma` warning rarely occuring in templated test cases (#2543)
+  * Constified implementation details in `INFO` (#2564)
+  * Made `MatcherGenericBase` copy constructor const (#2566)
+* Fixed serialization of test filters so the output roundtrips
+  * This means that e.g. `./tests/SelfTest "aaa bbb", [approx]` outputs `Filters: "aaa bbb",[approx]`
+
+
+### Miscellaneous
+* Catch2's build no longer leaks `-ffile-prefix-map` setting  to dependees (#2533)
+
+
+
+## 3.1.1
+
+### Improvements
+* Added `Catch::getSeed` function that user code can call to retrieve current rng-seed
+* Better detection of compiler support for `-ffile-prefix-map` (#2517)
+* Catch2's shared libraries now have `SOVERSION` set (#2516)
+* `catch2/catch_all.hpp` convenience header no longer transitively includes `windows.h` (#2432, #2526)
+
+
+### Fixes
+* Fixed compilation on Universal Windows Platform
+* Fixed compilation on VxWorks (#2515)
+* Fixed compilation on Cygwin (#2540)
+* Remove unused variable in reporter registration (#2538)
+* Fixed some symbol visibility issues with dynamic library on Windows (#2527)
+* Suppressed `-Wuseless-cast` warnings in `REQUIRE_THROWS*` macros (#2520, #2521)
+  * This was triggered when the potentially throwing expression evaluates to `void`
+* Fixed "warning: storage class is not first" with `nvc++` (#2533)
+* Fixed handling of `DL_PATHS` argument to `catch_discover_tests` on MacOS (#2483)
+* Suppressed `*-avoid-c-arrays` clang-tidy warning in `TEMPLATE_TEST_CASE` (#2095, #2536)
+
+
+### Miscellaneous
+* Fixed CMake install step for Catch2 build as dynamic library (#2485)
+* Raised minimum CMake version to 3.10 (#2523)
+  * Expect the minimum CMake version to increase once more in next few releases.
+* Whole bunch of doc updates and fixes
+  * #1444, #2497, #2547, #2549, and more
+* Added support for building Catch2 with Meson (#2530, #2539)
+
+
+
+## 3.1.0
+
+### Improvements
+* Improved suppression of `-Wparentheses` for older GCCs
+  * Turns out that even GCC 9 does not properly handle `_Pragma`s in the C++ frontend.
+* Added type constraints onto `random` generator (#2433)
+  * These constraints copy what the standard says for the underlying `std::uniform_int_distribution`
+* Suppressed -Wunused-variable from nvcc (#2306, #2427)
+* Suppressed -Wunused-variable from MinGW (#2132)
+* Added All/Any/NoneTrue range matchers (#2319)
+  * These check that all/any/none of boolean values in a range are true.
+* The JUnit reporter now normalizes classnames from C++ namespaces to Java-like namespaces (#2468)
+  * This provides better support for other JUnit based tools.
+* The Bazel support now understands `BAZEL_TEST` environment variable (#2459)
+  * The `CATCH_CONFIG_BAZEL_SUPPORT` configuration option is also still supported.
+* Returned support for compiling Catch2 with GCC 5 (#2448)
+  * This required removing inherited constructors from Catch2's internals.
+  * I recommend updating to a newer GCC anyway.
+* `catch_discover_tests` now has a new options for setting library load path(s) when running the Catch2 binary (#2467)
+
+
+### Fixes
+* Fixed crash when listing listeners without any registered listeners (#2442)
+* Fixed nvcc compilation error in constructor benchmarking helper (#2477)
+* Catch2's CMakeList supports pre-3.12 CMake again (#2428)
+  * The gain from requiring CMake 3.12 was very minor, but y'all should really update to newer CMake
+
+
+### Miscellaneous
+* Fixed SelfTest build on MinGW (#2447)
+* The in-repo conan recipe exports the CMake helper (#2460)
+* Added experimental CMake script to showcase using test case sharding together with CTest
+  * Compared to `catch_discover_tests`, it supports very limited number of options and customization
+* Added documentation page on best practices when running Catch2 tests
+* Catch2 can be built as a dynamic library (#2397, #2398)
+  * Note that Catch2 does not have visibility annotations, and you are responsible for ensuring correct visibility built into the resulting library.
+
+
+
+## 3.0.1
 
 **Catch2 now uses statically compiled library as its distribution model.
 This also means that to get all of Catch2's functionality in a test file,
@@ -191,6 +340,8 @@ v3 releases.
     * For details see the docs for command-line and compile-time Catch2 configuration
 * Added a support for Bazel integration with `XML_OUTPUT_FILE` env var (#2399)
   * This has to be enabled during compilation.
+* Added `--skip-benchmarks` flag to run tests without any `BENCHMARK`s (#2392, #2408)
+* Added option to list all listeners in the binary via `--list-listeners`
 
 
 ### Fixes
@@ -204,6 +355,7 @@ v3 releases.
 * The cumulative reporter base stores benchmark results alongside assertion results
 * Catch2's SE handling should no longer interferes with ASan on Windows (#2334)
 * Fixed Windows console colour handling for tests that redirect stdout (#2345)
+* Fixed issue with the `random` generators returning the same value over and over again
 
 
 ### Other changes
@@ -228,6 +380,7 @@ v3 releases.
     * `-DCATCH_CONFIG_ANDROID_LOGWRITE=OFF` does nothing (the define will not exist)
 
 
+
 ## 2.13.7
 
 ### Fixes
@@ -371,7 +524,7 @@ v3 releases.
 ### Improvements
 * `std::result_of` is not used if `std::invoke_result` is available (#1934)
 * JUnit reporter writes out `status` attribute for tests (#1899)
-* Suppresed clang-tidy's `hicpp-vararg` warning (#1921)
+* Suppressed clang-tidy's `hicpp-vararg` warning (#1921)
   * Catch2 was already suppressing the `cppcoreguidelines-pro-type-vararg` alias of the warning
 
 

docs/reporter-events.md

@@ -56,7 +56,7 @@ are handled by a different event.
 
 ### `testCasePartial` events
 
-> Introduced in Catch2 X.Y.Z
+> Introduced in Catch2 3.0.1
 
 ```cpp
 void testCasePartialStarting( TestCaseInfo const& testInfo, uint64_t partNumber );
@@ -135,10 +135,10 @@ benchmarking itself fails.
 
 ## Listings events
 
-> Introduced in Catch2 X.Y.Z.
+> Introduced in Catch2 3.0.1.
 
 Listings events are events that correspond to the test binary being
-invoked with `--list-foo` flag. 
+invoked with `--list-foo` flag.
 
 There are currently 3 listing events, one for reporters, one for tests,
 and one for tags. Note that they are not exclusive to each other.

docs/reporters.md

@@ -30,7 +30,7 @@ reporters](#multiple-reporters) to avoid any surprises from doing so.
 <a id="multiple-reporters"></a>
 ## Using multiple reporters
 
-> Support for having multiple parallel reporters was [introduced](https://github.com/catchorg/Catch2/pull/2183) in Catch2 X.Y.Z
+> Support for having multiple parallel reporters was [introduced](https://github.com/catchorg/Catch2/pull/2183) in Catch2 3.0.1
 
 Catch2 supports using multiple reporters at the same time while having
 them write into different destinations. The two main uses of this are
@@ -169,7 +169,7 @@ Currently there are two customization options:
 
 ### Per-reporter configuration
 
-> Per-reporter configuration was introduced in Catch2 X.Y.Z
+> Per-reporter configuration was introduced in Catch2 3.0.1
 
 Catch2 supports some configuration to happen per reporter. The configuration
 options fall into one of two categories:

docs/skipping-passing-failing.md

@@ -0,0 +1,129 @@
+<a id="top"></a>
+# Explicitly skipping, passing, and failing tests at runtime
+
+## Skipping Test Cases at Runtime
+
+> [Introduced](https://github.com/catchorg/Catch2/pull/2360) in Catch2 3.3.0.
+
+In some situations it may not be possible to meaningfully execute a test case,
+for example when the system under test is missing certain hardware capabilities.
+If the required conditions can only be determined at runtime, it often
+doesn't make sense to consider such a test case as either passed or failed,
+because it simply can not run at all.
+
+To properly express such scenarios, Catch2 provides a way to explicitly
+_skip_ test cases, using the `SKIP` macro:
+
+```
+SKIP( [streamable expression] )
+```
+
+Example usage:
+
+```c++
+TEST_CASE("copy files between drives") {
+    if(getNumberOfHardDrives() < 2) {
+        SKIP("at least two hard drives required");
+    }
+    // ...
+}
+```
+
+This test case is then reported as _skipped_ instead of _passed_ or _failed_.
+
+The `SKIP` macro behaves similarly to an explicit [`FAIL`](#passing-and-failing-test-cases),
+in that it is the last expression that will be executed:
+
+```c++
+TEST_CASE("my test") {
+    printf("foo");
+    SKIP();
+    printf("bar"); // not printed
+}
+```
+
+However a failed assertion _before_ a `SKIP` still causes the entire
+test case to fail:
+
+```c++
+TEST_CASE("failing test") {
+    CHECK(1 == 2);
+    SKIP();
+}
+```
+
+### Interaction with Sections and Generators
+
+Sections, nested sections as well as specific outputs from [generators](generators.md#top)
+can all be individually skipped, with the rest executing as usual:
+
+```c++
+TEST_CASE("complex test case") {
+  int value = GENERATE(2, 4, 6);
+  SECTION("a") {
+    SECTION("a1") { CHECK(value < 8); }
+    SECTION("a2") {
+      if (value == 4) {
+        SKIP();
+      }
+      CHECK(value % 2 == 0);
+    }
+  }
+}
+```
+
+This test case will report 5 passing assertions; one for each of the three
+values in section `a1`, and then two in section `a2`, from values 2 and 4.
+
+Note that as soon as one section is skipped, the entire test case will
+be reported as _skipped_ (unless there is a failing assertion, in which
+case the test is handled as _failed_ instead).
+
+Note that if all test cases in a run are skipped, Catch2 returns a non-zero
+exit code, same as it does if no test cases have run. This behaviour can
+be overridden using the [--allow-running-no-tests](command-line.md#no-tests-override)
+flag.
+
+
+## Passing and failing test cases
+
+Test cases can also be explicitly passed or failed, without the use of
+assertions, and with a specific message. This can be useful to handle
+complex preconditions/postconditions and give useful error messages
+when they fail.
+
+* `SUCCEED( [streamable expression] )`
+
+`SUCCEED` is morally equivalent with `INFO( [streamable expression] ); REQUIRE( true );`.
+Note that it does not stop further test execution, so it cannot be used
+to guard failing assertions from being executed.
+
+_In practice, `SUCCEED` is usually used as a test placeholder, to avoid
+[failing a test case due to missing assertions](command-line.md#warnings)._
+
+```cpp
+TEST_CASE( "SUCCEED showcase" ) {
+    int I = 1;
+    SUCCEED( "I is " << I );
+    // ... execution continues here ...
+}
+```
+
+* `FAIL( [streamable expression] )`
+
+`FAIL` is morally equivalent with `INFO( [streamable expression] ); REQUIRE( false );`.
+
+_In practice, `FAIL` is usually used to stop executing test that is currently
+known to be broken, but has to be fixed later._
+
+```cpp
+TEST_CASE( "FAIL showcase" ) {
+    FAIL( "This test case causes segfault, which breaks CI." );
+    // ... this will not be executed ...
+}
+```
+
+
+---
+
+[Home](Readme.md#top)

docs/test-cases-and-sections.md

@@ -25,7 +25,8 @@ _section description_ can be used to provide long form description
 of a section while keeping the _section name_ short for use with the
 [`-c` command line parameter](command-line.md#specify-the-section-to-run).
 
-**Test names must be unique within the Catch executable.**
+**The combination of test names and tags must be unique within the Catch2
+executable.**
 
 For examples see the [Tutorial](tutorial.md#top)
 
@@ -72,7 +73,8 @@ All tag names beginning with non-alphanumeric characters are reserved by Catch.
 
 * `[@<alias>]` - tag aliases all begin with `@` (see below).
 
-* `[!benchmark]` - this test case is actually a benchmark. This is an experimental feature, and currently has no documentation. If you want to try it out, look at `projects/SelfTest/Benchmark.tests.cpp` for details.
+* `[!benchmark]` - this test case is actually a benchmark. Currently this only serves to hide the test case by default, to avoid the execution time costs.
+
 
 ## Tag aliases
 
@@ -153,7 +155,7 @@ Scenario : vector can be sized and resized
   Then   : The size changes
 ```
 
-See also [runnable example on godbolt](https://godbolt.org/z/e5vPPM),
+See also [runnable example on godbolt](https://godbolt.org/z/eY5a64r99),
 with a more complicated (and failing) example.
 
 > `AND_GIVEN` was [introduced](https://github.com/catchorg/Catch2/issues/1360) in Catch2 2.4.0.
@@ -166,7 +168,11 @@ Other than the additional prefixes and the formatting in the console reporter th
 
 In addition to `TEST_CASE`s, Catch2 also supports test cases parametrised
 by types, in the form of `TEMPLATE_TEST_CASE`,
-`TEMPLATE_PRODUCT_TEST_CASE` and `TEMPLATE_LIST_TEST_CASE`.
+`TEMPLATE_PRODUCT_TEST_CASE` and `TEMPLATE_LIST_TEST_CASE`. These macros
+are defined in the `catch_template_test_macros.hpp` header, so compiling
+the code examples below also requires
+`#include <catch2/catch_template_test_macros.hpp>`.
+
 
 * **TEMPLATE_TEST_CASE(** _test name_ , _tags_,  _type1_, _type2_, ..., _typen_ **)**
 
@@ -288,7 +294,9 @@ TEMPLATE_LIST_TEST_CASE("Template test case with test types specified inside std
 In addition to [type parametrised test cases](#type-parametrised-test-cases) Catch2 also supports
 signature base parametrised test cases, in form of `TEMPLATE_TEST_CASE_SIG` and `TEMPLATE_PRODUCT_TEST_CASE_SIG`.
 These test cases have similar syntax like [type parametrised test cases](#type-parametrised-test-cases), with one
-additional positional argument which specifies the signature.
+additional positional argument which specifies the signature. These macros are defined in the
+`catch_template_test_macros.hpp` header, so compiling the code examples below also requires
+`#include <catch2/catch_template_test_macros.hpp>`.
 
 ### Signature
 Signature has some strict rules for these tests cases to work properly:

docs/test-fixtures.md

@@ -3,7 +3,7 @@
 
 ## Defining test fixtures
 
-Although Catch allows you to group tests together as sections within a test case, it can still be convenient, sometimes, to group them using a more traditional test fixture. Catch fully supports this too. You define the test fixture as a simple structure:
+Although Catch allows you to group tests together as [sections within a test case](test-cases-and-sections.md), it can still be convenient, sometimes, to group them using a more traditional test fixture. Catch fully supports this too. You define the test fixture as a simple structure:
 
 ```c++
 class UniqueTestsFixture {
@@ -59,7 +59,10 @@ struct Template_Fixture {
     T m_a;
 };
 
-TEMPLATE_TEST_CASE_METHOD(Template_Fixture,"A TEMPLATE_TEST_CASE_METHOD based test run that succeeds", "[class][template]", int, float, double) {
+TEMPLATE_TEST_CASE_METHOD(Template_Fixture,
+                          "A TEMPLATE_TEST_CASE_METHOD based test run that succeeds",
+                          "[class][template]",
+                          int, float, double) {
     REQUIRE( Template_Fixture<TestType>::m_a == 1 );
 }
 
@@ -77,7 +80,11 @@ struct Foo_class {
     }
 };
 
-TEMPLATE_PRODUCT_TEST_CASE_METHOD(Template_Template_Fixture, "A TEMPLATE_PRODUCT_TEST_CASE_METHOD based test succeeds", "[class][template]", (Foo_class, std::vector), int) {
+TEMPLATE_PRODUCT_TEST_CASE_METHOD(Template_Template_Fixture,
+                                  "A TEMPLATE_PRODUCT_TEST_CASE_METHOD based test succeeds",
+                                  "[class][template]",
+                                  (Foo_class, std::vector),
+                                  int) {
     REQUIRE( Template_Template_Fixture<TestType>::m_a.size() == 0 );
 }
 ```
@@ -101,7 +108,12 @@ struct Nttp_Fixture{
     int value = V;
 };
 
-TEMPLATE_TEST_CASE_METHOD_SIG(Nttp_Fixture, "A TEMPLATE_TEST_CASE_METHOD_SIG based test run that succeeds", "[class][template][nttp]",((int V), V), 1, 3, 6) {
+TEMPLATE_TEST_CASE_METHOD_SIG(
+    Nttp_Fixture,
+    "A TEMPLATE_TEST_CASE_METHOD_SIG based test run that succeeds",
+    "[class][template][nttp]",
+    ((int V), V),
+    1, 3, 6) {
     REQUIRE(Nttp_Fixture<V>::value > 0);
 }
 
@@ -117,8 +129,13 @@ struct Template_Foo_2 {
     size_t size() { return V; }
 };
 
-TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG(Template_Fixture_2, "A TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG based test run that succeeds", "[class][template][product][nttp]", ((typename T, size_t S), T, S),(std::array, Template_Foo_2), ((int,2), (float,6)))
-{
+TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG(
+    Template_Fixture_2,
+    "A TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG based test run that succeeds",
+    "[class][template][product][nttp]",
+    ((typename T, size_t S), T, S),
+    (std::array, Template_Foo_2),
+    ((int,2), (float,6))) {
     REQUIRE(Template_Fixture_2<TestType>{}.m_a.size() >= 2);
 }
 ```
@@ -132,8 +149,10 @@ only difference is the source of types. This allows you to reuse the template ty
 Example:
 ```cpp
 using MyTypes = std::tuple<int, char, double>;
-TEMPLATE_LIST_TEST_CASE_METHOD(Template_Fixture, "Template test case method with test types specified inside std::tuple", "[class][template][list]", MyTypes)
-{
+TEMPLATE_LIST_TEST_CASE_METHOD(Template_Fixture,
+                               "Template test case method with test types specified inside std::tuple",
+                               "[class][template][list]",
+                               MyTypes) {
     REQUIRE( Template_Fixture<TestType>::m_a == 1 );
 }
 ```

docs/tutorial.md

@@ -13,9 +13,10 @@
 ## Getting Catch2
 
 Ideally you should be using Catch2 through its [CMake integration](cmake-integration.md#top).
-Catch2 also provides pkg-config files and single TU distribution, but this
-documentation will assume you are using CMake. If you are using single-TU
-distribution instead, remember to replace the included header with `catch_amalgamated.hpp`.
+Catch2 also provides pkg-config files and two file (header + cpp)
+distribution, but this documentation will assume you are using CMake. If
+you are using the two file distribution instead, remember to replace
+the included header with `catch_amalgamated.hpp`.
 
 
 ## Writing tests
@@ -94,12 +95,12 @@ before we move on.
 * The test automatically self-registers with the test runner, and user
   does not have do anything more to ensure that it is picked up by the test
   framework. _Note that you can run specific test, or set of tests,
-  through the [command line](command-line#top)._
+  through the [command line](command-line.md#top)._
 * The individual test assertions are written using the `REQUIRE` macro.
   It accepts a boolean expression, and uses expression templates to
   internally decompose it, so that it can be individually stringified
   on test failure.
-  
+
 On the last point, note that there are more testing macros available,
 because not all useful checks can be expressed as a simple boolean
 expression. As an example, checking that an expression throws an exception
@@ -177,7 +178,7 @@ To continue on the vector example above, you could add a check that
     }
 ```
 
-Another way to look at sections is that they are a way to define a tree 
+Another way to look at sections is that they are a way to define a tree
 of paths through the test. Each section represents a node, and the final
 tree is walked in depth-first manner, with each path only visiting only
 one leaf node.

docs/usage-tips.md

@@ -0,0 +1,100 @@
+<a id="top"></a>
+# Best practices and other tips on using Catch2
+
+## Running tests
+
+Your tests should be run in a manner roughly equivalent with:
+
+```
+./tests --order rand --warn NoAssertions
+```
+
+Notice that all the tests are run in a large batch, their relative order
+is randomized, and that you ask Catch2 to fail test whose leaf-path
+does not contain an assertion.
+
+The reason I recommend running all your tests in the same process is that
+this exposes your tests to interference from their runs. This can be both
+positive interference, where the changes in global state from previous
+test allow later tests to pass, but also negative interference, where
+changes in global state from previous test causes later tests to fail.
+
+In my experience, interference, especially destructive interference,
+usually comes from errors in the code under test, rather than the tests
+themselves. This means that by allowing interference to happen, our tests
+can find these issues. Obviously, to shake out interference coming from
+different orderings of tests, the test order also need to be shuffled
+between runs.
+
+However, running all tests in a single batch eventually becomes impractical
+as they will take too long to run, and you will want to run your tests
+in parallel.
+
+
+<a id="parallel-tests"></a>
+## Running tests in parallel
+
+There are multiple ways of running tests in parallel, with various level
+of structure. If you are using CMake and CTest, then we provide a helper
+function [`catch_discover_tests`](cmake-integration.md#automatic-test-registration)
+that registers each Catch2 `TEST_CASE` as a single CTest test, which
+is then run in a separate process. This is an easy way to set up parallel
+tests if you are already using CMake & CTest to run your tests, but you
+will lose the advantage of running tests in batches.
+
+
+Catch2 also supports [splitting tests in a binary into multiple
+shards](command-line.md#test-sharding). This can be used by any test
+runner to run batches of tests in parallel. Do note that when selecting
+on the number of shards, you should have more shards than there are cores,
+to avoid issues with long-running tests getting accidentally grouped in
+the same shard, and causing long-tailed execution time.
+
+**Note that naively composing sharding and random ordering of tests will break.**
+
+Invoking Catch2 test executable like this
+
+```text
+./tests --order rand --shard-index 0 --shard-count 3
+./tests --order rand --shard-index 1 --shard-count 3
+./tests --order rand --shard-index 2 --shard-count 3
+```
+
+does not guarantee covering all tests inside the executable, because
+each invocation will have its own random seed, thus it will have its own
+random order of tests and thus the partitioning of tests into shards will
+be different as well.
+
+To do this properly, you need the individual shards to share the random
+seed, e.g.
+```text
+./tests --order rand --shard-index 0 --shard-count 3 --rng-seed 0xBEEF
+./tests --order rand --shard-index 1 --shard-count 3 --rng-seed 0xBEEF
+./tests --order rand --shard-index 2 --shard-count 3 --rng-seed 0xBEEF
+```
+
+Catch2 actually provides a helper to automatically register multiple shards
+as CTest tests, with shared random seed that changes each CTest invocation.
+For details look at the documentation of
+[`CatchShardTests.cmake` CMake script](cmake-integration.md#catchshardtestscmake).
+
+
+## Organizing tests into binaries
+
+Both overly large and overly small test binaries can cause issues. Overly
+large test binaries have to be recompiled and relinked often, and the
+link times are usually also long. Overly small test binaries in turn pay
+significant overhead from linking against Catch2 more often per compiled
+test case, and also make it hard/impossible to run tests in batches.
+
+Because there is no hard and fast rule for the right size of a test binary,
+I recommend having 1:1 correspondence between libraries in project and test
+binaries. (At least if it is possible, in some cases it is not.) Having
+a test binary for each library in project keeps related tests together,
+and makes tests easy to navigate by reflecting the project's organizational
+structure.
+
+
+---
+
+[Home](Readme.md#top)

docs/why-catch.md

@@ -41,7 +41,7 @@ So what does Catch2 bring to the party that differentiates it from these? Apart
 
 ## Who else is using Catch2?
 
-A whole lot of people. According to the 2021 Jetbrains C++ ecosystem survey,
+A whole lot of people. According to the 2021 JetBrains C++ ecosystem survey,
 about 11% of C++ programmers use Catch2 for unit testing, making it the
 second most popular unit testing framework.
 

examples/010-TestCase.cpp

@@ -19,7 +19,7 @@ TEST_CASE( "Factorials of 1 and higher are computed (pass)", "[single-file]" ) {
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 010-TestCase 010-TestCase.cpp && 010-TestCase --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 010-TestCase 010-TestCase.cpp && 010-TestCase --success
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 010-TestCase.cpp && 010-TestCase --success
 
 // Expected compact output (all assertions):

examples/020-TestCase-1.cpp

@@ -10,8 +10,8 @@ TEST_CASE( "1: All test cases reside in other .cpp files (empty)", "[multi-file:
 // Here just to show there are two source files via option --list-tests.
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -c 020-TestCase-1.cpp
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 020-TestCase TestCase-1.o 020-TestCase-2.cpp && 020-TestCase --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -c 020-TestCase-1.cpp
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 020-TestCase TestCase-1.o 020-TestCase-2.cpp && 020-TestCase --success
 //
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% -c 020-TestCase-1.cpp
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% -Fe020-TestCase.exe 020-TestCase-1.obj 020-TestCase-2.cpp && 020-TestCase --success

examples/030-Asn-Require-Check.cpp

@@ -53,7 +53,7 @@ TEST_CASE( "Assert that something is false (continue after failure)", "[check-fa
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 030-Asn-Require-Check 030-Asn-Require-Check.cpp && 030-Asn-Require-Check --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 030-Asn-Require-Check 030-Asn-Require-Check.cpp && 030-Asn-Require-Check --success
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 030-Asn-Require-Check.cpp && 030-Asn-Require-Check --success
 
 // Expected compact output (all assertions):

examples/100-Fix-Section.cpp

@@ -45,7 +45,7 @@ TEST_CASE( "vectors can be sized and resized", "[vector]" ) {
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 100-Fix-Section 100-Fix-Section.cpp && 100-Fix-Section --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 100-Fix-Section 100-Fix-Section.cpp && 100-Fix-Section --success
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 100-Fix-Section.cpp && 100-Fix-Section --success
 
 // Expected compact output (all assertions):

examples/110-Fix-ClassFixture.cpp

@@ -52,8 +52,11 @@ TEST_CASE_METHOD( UniqueTestsFixture, "Create Employee/Normal", "[create]" ) {
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 110-Fix-ClassFixture 110-Fix-ClassFixture.cpp && 110-Fix-ClassFixture --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 110-Fix-ClassFixture 110-Fix-ClassFixture.cpp && 110-Fix-ClassFixture --success
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 110-Fix-ClassFixture.cpp && 110-Fix-ClassFixture --success
+//
+// Compile with pkg-config:
+// - g++ -std=c++14 -Wall $(pkg-config catch2-with-main --cflags)  -o 110-Fix-ClassFixture 110-Fix-ClassFixture.cpp $(pkg-config catch2-with-main --libs)
 
 // Expected compact output (all assertions):
 //

examples/120-Bdd-ScenarioGivenWhenThen.cpp

@@ -48,7 +48,7 @@ SCENARIO( "vectors can be sized and resized", "[vector]" ) {
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 120-Bdd-ScenarioGivenWhenThen 120-Bdd-ScenarioGivenWhenThen.cpp && 120-Bdd-ScenarioGivenWhenThen --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 120-Bdd-ScenarioGivenWhenThen 120-Bdd-ScenarioGivenWhenThen.cpp && 120-Bdd-ScenarioGivenWhenThen --success
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 120-Bdd-ScenarioGivenWhenThen.cpp && 120-Bdd-ScenarioGivenWhenThen --success
 
 // Expected compact output (all assertions):

examples/210-Evt-EventListeners.cpp

@@ -308,7 +308,7 @@ struct MyListener : Catch::EventListenerBase {
     using EventListenerBase::EventListenerBase; // inherit constructor
 
     // Get rid of Wweak-tables
-    ~MyListener();
+    ~MyListener() override;
 
     // The whole test run starting
     void testRunStarting( Catch::TestRunInfo const& testRunInfo ) override {
@@ -420,7 +420,7 @@ TEST_CASE_METHOD( Fixture, "3: Testcase with class-based fixture", "[tag-C][tag-
 }
 
 // Compile & run:
-// - g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 210-Evt-EventListeners 210-Evt-EventListeners.cpp && 210-Evt-EventListeners --success
+// - g++ -std=c++14 -Wall -I$(CATCH_SINGLE_INCLUDE) -o 210-Evt-EventListeners 210-Evt-EventListeners.cpp && 210-Evt-EventListeners --success
 // - cl -EHsc -I%CATCH_SINGLE_INCLUDE% 210-Evt-EventListeners.cpp && 210-Evt-EventListeners --success
 
 // Expected compact output (all assertions):

examples/CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required( VERSION 3.5 )
+cmake_minimum_required( VERSION 3.10 )
 
 project( Catch2Examples LANGUAGES CXX )
 
@@ -54,8 +54,6 @@ set(ALL_EXAMPLE_TARGETS
 
 foreach( name ${ALL_EXAMPLE_TARGETS} )
     target_link_libraries( ${name} Catch2 Catch2WithMain )
-    set_property(TARGET ${name} PROPERTY CXX_STANDARD 14)
-    set_property(TARGET ${name} PROPERTY CXX_EXTENSIONS OFF)
 endforeach()
 
 

extras/Catch.cmake

@@ -116,6 +116,13 @@ same as the Catch name; see also ``TEST_PREFIX`` and ``TEST_SUFFIX``.
     ``--out dir/<test_name>suffix``. This can be used to add a file extension to
     the output e.g. ".xml".
 
+  ``DL_PATHS path...``
+    Specifies paths that need to be set for the dynamic linker to find shared
+    libraries/DLLs when running the test executable (PATH/LD_LIBRARY_PATH respectively).
+    These paths will both be set when retrieving the list of test cases from the
+    test executable and when the tests are executed themselves. This requires
+    cmake/ctest >= 3.22.
+
 #]=======================================================================]
 
 #------------------------------------------------------------------------------
@@ -124,7 +131,7 @@ function(catch_discover_tests TARGET)
     ""
     ""
     "TEST_PREFIX;TEST_SUFFIX;WORKING_DIRECTORY;TEST_LIST;REPORTER;OUTPUT_DIR;OUTPUT_PREFIX;OUTPUT_SUFFIX"
-    "TEST_SPEC;EXTRA_ARGS;PROPERTIES"
+    "TEST_SPEC;EXTRA_ARGS;PROPERTIES;DL_PATHS"
     ${ARGN}
   )
 
@@ -135,6 +142,12 @@ function(catch_discover_tests TARGET)
     set(_TEST_LIST ${TARGET}_TESTS)
   endif()
 
+  if (_DL_PATHS)
+    if(${CMAKE_VERSION} VERSION_LESS "3.22.0")
+        message(FATAL_ERROR "The DL_PATHS option requires at least cmake 3.22")
+    endif()
+  endif()
+
   ## Generate a unique name based on the extra arguments
   string(SHA1 args_hash "${_TEST_SPEC} ${_EXTRA_ARGS} ${_REPORTER} ${_OUTPUT_DIR} ${_OUTPUT_PREFIX} ${_OUTPUT_SUFFIX}")
   string(SUBSTRING ${args_hash} 0 7 args_hash)
@@ -164,6 +177,7 @@ function(catch_discover_tests TARGET)
             -D "TEST_OUTPUT_DIR=${_OUTPUT_DIR}"
             -D "TEST_OUTPUT_PREFIX=${_OUTPUT_PREFIX}"
             -D "TEST_OUTPUT_SUFFIX=${_OUTPUT_SUFFIX}"
+            -D "TEST_DL_PATHS=${_DL_PATHS}"
             -D "CTEST_FILE=${ctest_tests_file}"
             -P "${_CATCH_DISCOVER_TESTS_SCRIPT}"
     VERBATIM

extras/CatchAddTests.cmake

@@ -10,10 +10,19 @@ set(reporter ${TEST_REPORTER})
 set(output_dir ${TEST_OUTPUT_DIR})
 set(output_prefix ${TEST_OUTPUT_PREFIX})
 set(output_suffix ${TEST_OUTPUT_SUFFIX})
+set(dl_paths ${TEST_DL_PATHS})
 set(script)
 set(suite)
 set(tests)
 
+if(WIN32)
+  set(dl_paths_variable_name PATH)
+elseif(APPLE)
+  set(dl_paths_variable_name DYLD_LIBRARY_PATH)
+else()
+  set(dl_paths_variable_name LD_LIBRARY_PATH)
+endif()
+
 function(add_command NAME)
   set(_args "")
   # use ARGV* instead of ARGN, because ARGN splits arrays into multiple arguments
@@ -35,6 +44,12 @@ if(NOT EXISTS "${TEST_EXECUTABLE}")
     "Specified test executable '${TEST_EXECUTABLE}' does not exist"
   )
 endif()
+
+if(dl_paths)
+  cmake_path(CONVERT "${dl_paths}" TO_NATIVE_PATH_LIST paths)
+  set(ENV{${dl_paths_variable_name}} "${paths}")
+endif()
+
 execute_process(
   COMMAND ${TEST_EXECUTOR} "${TEST_EXECUTABLE}" ${spec} --list-tests --verbosity quiet
   OUTPUT_VARIABLE output
@@ -85,6 +100,13 @@ if(output_dir AND NOT IS_ABSOLUTE ${output_dir})
   endif()
 endif()
 
+if(dl_paths)
+  foreach(path ${dl_paths})
+    cmake_path(NATIVE_PATH path native_path)
+    list(APPEND environment_modifications "${dl_paths_variable_name}=path_list_prepend:${native_path}")
+  endforeach()
+endif()
+
 # Parse output
 foreach(line ${output})
   set(test ${line})
@@ -115,6 +137,14 @@ foreach(line ${output})
     WORKING_DIRECTORY "${TEST_WORKING_DIR}"
     ${properties}
   )
+
+   if(environment_modifications)
+     add_command(set_tests_properties
+       "${prefix}${test}${suffix}"
+       PROPERTIES
+       ENVIRONMENT_MODIFICATION "${environment_modifications}")
+   endif()
+
   list(APPEND tests "${prefix}${test}${suffix}")
 endforeach()
 

extras/CatchShardTests.cmake

@@ -0,0 +1,66 @@
+
+#              Copyright Catch2 Authors
+# Distributed under the Boost Software License, Version 1.0.
+#   (See accompanying file LICENSE.txt or copy at
+#        https://www.boost.org/LICENSE_1_0.txt)
+
+# SPDX-License-Identifier: BSL-1.0
+
+# Supported optional args:
+#  * SHARD_COUNT - number of shards to split target's tests into
+#  * REPORTER    - reporter spec to use for tests
+#  * TEST_SPEC   - test spec used for filtering tests
+function(catch_add_sharded_tests TARGET)
+  if (${CMAKE_VERSION} VERSION_LESS "3.10.0")
+    message(FATAL_ERROR "add_sharded_catch_tests only supports CMake versions 3.10.0 and up")
+  endif()
+
+  cmake_parse_arguments(
+    ""
+    ""
+    "SHARD_COUNT;REPORTER;TEST_SPEC"
+    ""
+    ${ARGN}
+  )
+  
+  if (NOT DEFINED _SHARD_COUNT)
+    set(_SHARD_COUNT 2)
+  endif()
+
+  # Generate a unique name based on the extra arguments
+  string(SHA1 args_hash "${_TEST_SPEC} ${_EXTRA_ARGS} ${_REPORTER} ${_OUTPUT_DIR} ${_OUTPUT_PREFIX} ${_OUTPUT_SUFFIX} ${_SHARD_COUNT}")
+  string(SUBSTRING ${args_hash} 0 7 args_hash)
+
+  set(ctest_include_file "${CMAKE_CURRENT_BINARY_DIR}/${TARGET}-sharded-tests-include-${args_hash}.cmake")
+  set(ctest_tests_file "${CMAKE_CURRENT_BINARY_DIR}/${TARGET}-sharded-tests-impl-${args_hash}.cmake")
+
+  file(WRITE "${ctest_include_file}"
+    "if(EXISTS \"${ctest_tests_file}\")\n"
+    "  include(\"${ctest_tests_file}\")\n"
+    "else()\n"
+    "  add_test(${TARGET}_NOT_BUILT-${args_hash} ${TARGET}_NOT_BUILT-${args_hash})\n"
+    "endif()\n"
+  )
+
+  set_property(DIRECTORY
+    APPEND PROPERTY TEST_INCLUDE_FILES "${ctest_include_file}"
+  )
+
+  set(shard_impl_script_file "${CMAKE_CURRENT_LIST_DIR}/CatchShardTestsImpl.cmake")
+
+  add_custom_command(
+    TARGET ${TARGET} POST_BUILD
+    BYPRODUCTS "${ctest_tests_file}"
+    COMMAND "${CMAKE_COMMAND}"
+            -D "TARGET_NAME=${TARGET}"
+            -D "TEST_BINARY=$<TARGET_FILE:${TARGET}>"
+            -D "CTEST_FILE=${ctest_tests_file}"
+            -D "SHARD_COUNT=${_SHARD_COUNT}"
+            -D "REPORTER_SPEC=${_REPORTER}"
+            -D "TEST_SPEC=${_TEST_SPEC}"
+            -P "${shard_impl_script_file}"
+    VERBATIM
+  )
+
+
+endfunction()

extras/CatchShardTestsImpl.cmake

@@ -0,0 +1,52 @@
+
+#              Copyright Catch2 Authors
+# Distributed under the Boost Software License, Version 1.0.
+#   (See accompanying file LICENSE.txt or copy at
+#        https://www.boost.org/LICENSE_1_0.txt)
+
+# SPDX-License-Identifier: BSL-1.0
+
+# Indirection for CatchShardTests that allows us to delay the script
+# file generation until build time.
+
+# Expected args:
+#  * TEST_BINARY - full path to the test binary to run sharded
+#  * CTEST_FILE  - full path to ctest script file to write to
+#  * TARGET_NAME - name of the target to shard (used for test names)
+#  * SHARD_COUNT - number of shards to split the binary into
+# Optional args:
+#  * REPORTER_SPEC - reporter specs to be passed down to the binary
+#  * TEST_SPEC     - test spec to pass down to the test binary
+
+if(NOT EXISTS "${TEST_BINARY}")
+  message(FATAL_ERROR
+    "Specified test binary '${TEST_BINARY}' does not exist"
+  )
+endif()
+
+set(other_args "")
+if (TEST_SPEC)
+  set(other_args "${other_args} ${TEST_SPEC}")
+endif()
+if (REPORTER_SPEC)
+  set(other_args "${other_args} --reporter ${REPORTER_SPEC}")
+endif()
+
+# foreach RANGE in cmake is inclusive of the end, so we have to adjust it
+math(EXPR adjusted_shard_count "${SHARD_COUNT} - 1")
+
+file(WRITE "${CTEST_FILE}"
+  "string(RANDOM LENGTH 8 ALPHABET \"0123456789abcdef\" rng_seed)\n"
+  "\n"
+  "foreach(shard_idx RANGE ${adjusted_shard_count})\n"
+  "  add_test(${TARGET_NAME}-shard-" [[${shard_idx}]] "/${adjusted_shard_count}\n"
+  "    ${TEST_BINARY}"
+  " --shard-index " [[${shard_idx}]]
+  " --shard-count ${SHARD_COUNT}"
+  " --rng-seed " [[0x${rng_seed}]]
+  " --order rand"
+  "${other_args}"
+  "\n"
+  "  )\n"
+  "endforeach()\n"
+)

meson.build

@@ -0,0 +1,17 @@
+#              Copyright Catch2 Authors
+# Distributed under the Boost Software License, Version 1.0.
+#   (See accompanying file LICENSE.txt or copy at
+#        https://www.boost.org/LICENSE_1_0.txt)
+
+# SPDX-License-Identifier: BSL-1.0
+
+project(
+  'catch2',
+  'cpp',
+  version: '3.3.0', # CML version placeholder, don't delete
+  license: 'BSL-1.0',
+  meson_version: '>=0.50.0',
+)
+
+subdir('src/catch2')
+subdir('tests')

src/CMakeLists.txt

@@ -7,267 +7,333 @@ include(CatchMiscFunctions)
 set(Catch2_GUID_CMAKE "8d538cbe-01bf-4a2e-a98a-6c368fdf13d7" CACHE INTERNAL "Project GUID")
 set(Catch2WithMain_GUID_CMAKE "8bd3552a-2cfb-4a59-ab15-2031b97ada1e" CACHE INTERNAL "Project GUID")
 
-# Please keep these ordered alphabetically
 set(BENCHMARK_HEADERS
-    ${SOURCES_DIR}/benchmark/catch_benchmark.hpp
-    ${SOURCES_DIR}/benchmark/catch_benchmark_all.hpp
-    ${SOURCES_DIR}/benchmark/catch_chronometer.hpp
-    ${SOURCES_DIR}/benchmark/catch_clock.hpp
-    ${SOURCES_DIR}/benchmark/catch_constructor.hpp
-    ${SOURCES_DIR}/benchmark/catch_environment.hpp
-    ${SOURCES_DIR}/benchmark/catch_estimate.hpp
-    ${SOURCES_DIR}/benchmark/catch_execution_plan.hpp
-    ${SOURCES_DIR}/benchmark/catch_optimizer.hpp
-    ${SOURCES_DIR}/benchmark/catch_outlier_classification.hpp
-    ${SOURCES_DIR}/benchmark/catch_sample_analysis.hpp
-    ${SOURCES_DIR}/benchmark/detail/catch_analyse.hpp
-    ${SOURCES_DIR}/benchmark/detail/catch_benchmark_function.hpp
-    ${SOURCES_DIR}/benchmark/detail/catch_complete_invoke.hpp
-    ${SOURCES_DIR}/benchmark/detail/catch_estimate_clock.hpp
-    ${SOURCES_DIR}/benchmark/detail/catch_measure.hpp
-    ${SOURCES_DIR}/benchmark/detail/catch_repeat.hpp
-    ${SOURCES_DIR}/benchmark/detail/catch_run_for_at_least.hpp
-    ${SOURCES_DIR}/benchmark/detail/catch_stats.hpp
-    ${SOURCES_DIR}/benchmark/detail/catch_timing.hpp
+  ${SOURCES_DIR}/benchmark/catch_benchmark.hpp
+  ${SOURCES_DIR}/benchmark/catch_benchmark_all.hpp
+  ${SOURCES_DIR}/benchmark/catch_chronometer.hpp
+  ${SOURCES_DIR}/benchmark/catch_clock.hpp
+  ${SOURCES_DIR}/benchmark/catch_constructor.hpp
+  ${SOURCES_DIR}/benchmark/catch_environment.hpp
+  ${SOURCES_DIR}/benchmark/catch_estimate.hpp
+  ${SOURCES_DIR}/benchmark/catch_execution_plan.hpp
+  ${SOURCES_DIR}/benchmark/catch_optimizer.hpp
+  ${SOURCES_DIR}/benchmark/catch_outlier_classification.hpp
+  ${SOURCES_DIR}/benchmark/catch_sample_analysis.hpp
+  ${SOURCES_DIR}/benchmark/detail/catch_analyse.hpp
+  ${SOURCES_DIR}/benchmark/detail/catch_benchmark_function.hpp
+  ${SOURCES_DIR}/benchmark/detail/catch_complete_invoke.hpp
+  ${SOURCES_DIR}/benchmark/detail/catch_estimate_clock.hpp
+  ${SOURCES_DIR}/benchmark/detail/catch_measure.hpp
+  ${SOURCES_DIR}/benchmark/detail/catch_repeat.hpp
+  ${SOURCES_DIR}/benchmark/detail/catch_run_for_at_least.hpp
+  ${SOURCES_DIR}/benchmark/detail/catch_stats.hpp
+  ${SOURCES_DIR}/benchmark/detail/catch_timing.hpp
 )
 set(BENCHMARK_SOURCES
-    ${SOURCES_DIR}/benchmark/internal/catch_benchmark_combined_tu.cpp
-    ${SOURCES_DIR}/benchmark/detail/catch_stats.cpp
+  ${SOURCES_DIR}/benchmark/catch_chronometer.cpp
+  ${SOURCES_DIR}/benchmark/detail/catch_benchmark_function.cpp
+  ${SOURCES_DIR}/benchmark/detail/catch_run_for_at_least.cpp
+  ${SOURCES_DIR}/benchmark/detail/catch_stats.cpp
 )
+set(BENCHMARK_FILES ${BENCHMARK_HEADERS} ${BENCHMARK_SOURCES})
 
-SOURCE_GROUP("benchmark" FILES ${BENCHMARK_HEADERS} ${BENCHMARK_SOURCES})
 
-set(INTERNAL_HEADERS
-   "${CMAKE_BINARY_DIR}/generated-includes/catch2/catch_user_config.hpp"
-   "${SOURCES_DIR}/catch_user_config.hpp.in"
-    ${SOURCES_DIR}/catch_all.hpp
-    ${SOURCES_DIR}/matchers/catch_matchers_all.hpp
-    ${SOURCES_DIR}/generators/catch_generators_all.hpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_all.hpp
-    ${SOURCES_DIR}/matchers/internal/catch_matchers_impl.hpp
-    ${SOURCES_DIR}/internal/catch_case_insensitive_comparisons.hpp
-    ${SOURCES_DIR}/internal/catch_console_width.hpp
-    ${SOURCES_DIR}/internal/catch_container_nonmembers.hpp
-    ${SOURCES_DIR}/internal/catch_noncopyable.hpp
-    ${SOURCES_DIR}/catch_approx.hpp
-    ${SOURCES_DIR}/internal/catch_assertion_handler.hpp
-    ${SOURCES_DIR}/catch_assertion_info.hpp
-    ${SOURCES_DIR}/catch_assertion_result.hpp
-    ${SOURCES_DIR}/internal/catch_test_macro_impl.hpp
-    ${SOURCES_DIR}/internal/catch_test_failure_exception.hpp
-    ${SOURCES_DIR}/internal/catch_case_sensitive.hpp
-    ${SOURCES_DIR}/internal/catch_clara.hpp
-    ${SOURCES_DIR}/internal/catch_commandline.hpp
-    ${SOURCES_DIR}/internal/catch_source_line_info.hpp
-    ${SOURCES_DIR}/internal/catch_compiler_capabilities.hpp
-    ${SOURCES_DIR}/catch_config.hpp
-    ${SOURCES_DIR}/internal/catch_config_android_logwrite.hpp
-    ${SOURCES_DIR}/internal/catch_config_counter.hpp
-    ${SOURCES_DIR}/internal/catch_config_uncaught_exceptions.hpp
-    ${SOURCES_DIR}/internal/catch_config_wchar.hpp
-    ${SOURCES_DIR}/internal/catch_console_colour.hpp
-    ${SOURCES_DIR}/internal/catch_context.hpp
-    ${SOURCES_DIR}/internal/catch_debug_console.hpp
-    ${SOURCES_DIR}/internal/catch_debugger.hpp
-    ${SOURCES_DIR}/internal/catch_decomposer.hpp
-    ${SOURCES_DIR}/internal/catch_enforce.hpp
-    ${SOURCES_DIR}/internal/catch_enum_values_registry.hpp
-    ${SOURCES_DIR}/internal/catch_errno_guard.hpp
-    ${SOURCES_DIR}/internal/catch_exception_translator_registry.hpp
-    ${SOURCES_DIR}/internal/catch_fatal_condition_handler.hpp
-    ${SOURCES_DIR}/internal/catch_floating_point_helpers.hpp
-    ${SOURCES_DIR}/internal/catch_istream.hpp
-    ${SOURCES_DIR}/internal/catch_unique_name.hpp
-    ${SOURCES_DIR}/internal/catch_sharding.hpp
-    ${SOURCES_DIR}/generators/catch_generator_exception.hpp
-    ${SOURCES_DIR}/generators/catch_generators.hpp
-    ${SOURCES_DIR}/generators/catch_generators_adapters.hpp
-    ${SOURCES_DIR}/generators/catch_generators_random.hpp
-    ${SOURCES_DIR}/generators/catch_generators_range.hpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_capture.hpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_config.hpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_enum_values_registry.hpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_exception.hpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_generatortracker.hpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_registry_hub.hpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_reporter.hpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_reporter_factory.hpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_reporter_registry.hpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_tag_alias_registry.hpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_testcase.hpp
-    ${SOURCES_DIR}/internal/catch_lazy_expr.hpp
-    ${SOURCES_DIR}/internal/catch_leak_detector.hpp
-    ${SOURCES_DIR}/internal/catch_list.hpp
-    ${SOURCES_DIR}/matchers/catch_matchers.hpp
-    ${SOURCES_DIR}/matchers/catch_matchers_container_properties.hpp
-    ${SOURCES_DIR}/matchers/catch_matchers_contains.hpp
-    ${SOURCES_DIR}/matchers/catch_matchers_exception.hpp
-    ${SOURCES_DIR}/matchers/catch_matchers_floating_point.hpp
-    ${SOURCES_DIR}/matchers/catch_matchers_predicate.hpp
-    ${SOURCES_DIR}/matchers/catch_matchers_quantifiers.hpp
-    ${SOURCES_DIR}/matchers/catch_matchers_string.hpp
-    ${SOURCES_DIR}/matchers/catch_matchers_templated.hpp
-    ${SOURCES_DIR}/matchers/catch_matchers_vector.hpp
-    ${SOURCES_DIR}/catch_message.hpp
-    ${SOURCES_DIR}/internal/catch_message_info.hpp
-    ${SOURCES_DIR}/internal/catch_meta.hpp
-    ${SOURCES_DIR}/internal/catch_move_and_forward.hpp
-    ${SOURCES_DIR}/internal/catch_optional.hpp
-    ${SOURCES_DIR}/internal/catch_output_redirect.hpp
-    ${SOURCES_DIR}/internal/catch_platform.hpp
-    ${SOURCES_DIR}/internal/catch_polyfills.hpp
-    ${SOURCES_DIR}/internal/catch_preprocessor.hpp
-    ${SOURCES_DIR}/internal/catch_preprocessor_remove_parens.hpp
-    ${SOURCES_DIR}/internal/catch_random_number_generator.hpp
-    ${SOURCES_DIR}/internal/catch_random_seed_generation.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_registrars.hpp
-    ${SOURCES_DIR}/internal/catch_reporter_registry.hpp
-    ${SOURCES_DIR}/internal/catch_reporter_spec_parser.hpp
-    ${SOURCES_DIR}/internal/catch_result_type.hpp
-    ${SOURCES_DIR}/internal/catch_run_context.hpp
-    ${SOURCES_DIR}/internal/catch_section.hpp
-    ${SOURCES_DIR}/internal/catch_stdstreams.hpp
-    ${SOURCES_DIR}/catch_section_info.hpp
-    ${SOURCES_DIR}/catch_session.hpp
-    ${SOURCES_DIR}/internal/catch_singletons.hpp
-    ${SOURCES_DIR}/internal/catch_startup_exception_registry.hpp
-    ${SOURCES_DIR}/internal/catch_reusable_string_stream.hpp
-    ${SOURCES_DIR}/internal/catch_stream_end_stop.hpp
-    ${SOURCES_DIR}/internal/catch_string_manip.hpp
-    ${SOURCES_DIR}/internal/catch_stringref.hpp
-    ${SOURCES_DIR}/catch_tag_alias.hpp
-    ${SOURCES_DIR}/catch_tag_alias_autoregistrar.hpp
-    ${SOURCES_DIR}/internal/catch_tag_alias_registry.hpp
-    ${SOURCES_DIR}/catch_test_case_info.hpp
-    ${SOURCES_DIR}/internal/catch_test_case_registry_impl.hpp
-    ${SOURCES_DIR}/internal/catch_test_case_tracker.hpp
-    ${SOURCES_DIR}/catch_template_test_macros.hpp
-    ${SOURCES_DIR}/catch_test_macros.hpp
-    ${SOURCES_DIR}/internal/catch_template_test_registry.hpp
-    ${SOURCES_DIR}/internal/catch_test_registry.hpp
-    ${SOURCES_DIR}/catch_test_spec.hpp
-    ${SOURCES_DIR}/internal/catch_test_spec_parser.hpp
-    ${SOURCES_DIR}/internal/catch_textflow.hpp
-    ${SOURCES_DIR}/catch_timer.hpp
-    ${SOURCES_DIR}/internal/catch_to_string.hpp
-    ${SOURCES_DIR}/catch_tostring.hpp
-    ${SOURCES_DIR}/catch_totals.hpp
-    ${SOURCES_DIR}/catch_translate_exception.hpp
-    ${SOURCES_DIR}/internal/catch_uncaught_exceptions.hpp
-    ${SOURCES_DIR}/internal/catch_unique_ptr.hpp
-    ${SOURCES_DIR}/internal/catch_void_type.hpp
-    ${SOURCES_DIR}/catch_version.hpp
-    ${SOURCES_DIR}/catch_version_macros.hpp
-    ${SOURCES_DIR}/internal/catch_wildcard_pattern.hpp
-    ${SOURCES_DIR}/internal/catch_windows_h_proxy.hpp
-    ${SOURCES_DIR}/internal/catch_xmlwriter.hpp
-    ${SOURCES_DIR}/internal/catch_test_case_info_hasher.hpp
+set(IMPL_HEADERS
+ "${PROJECT_BINARY_DIR}/generated-includes/catch2/catch_user_config.hpp"
+  ${SOURCES_DIR}/catch_user_config.hpp.in
+  ${SOURCES_DIR}/catch_all.hpp
+  ${SOURCES_DIR}/catch_approx.hpp
+  ${SOURCES_DIR}/catch_assertion_info.hpp
+  ${SOURCES_DIR}/catch_assertion_result.hpp
+  ${SOURCES_DIR}/catch_config.hpp
+  ${SOURCES_DIR}/catch_get_random_seed.hpp
+  ${SOURCES_DIR}/catch_message.hpp
+  ${SOURCES_DIR}/catch_section_info.hpp
+  ${SOURCES_DIR}/catch_session.hpp
+  ${SOURCES_DIR}/catch_tag_alias.hpp
+  ${SOURCES_DIR}/catch_tag_alias_autoregistrar.hpp
+  ${SOURCES_DIR}/catch_template_test_macros.hpp
+  ${SOURCES_DIR}/catch_test_case_info.hpp
+  ${SOURCES_DIR}/catch_test_macros.hpp
+  ${SOURCES_DIR}/catch_test_spec.hpp
+  ${SOURCES_DIR}/catch_timer.hpp
+  ${SOURCES_DIR}/catch_tostring.hpp
+  ${SOURCES_DIR}/catch_totals.hpp
+  ${SOURCES_DIR}/catch_translate_exception.hpp
+  ${SOURCES_DIR}/catch_version.hpp
+  ${SOURCES_DIR}/catch_version_macros.hpp
+  ${SOURCES_DIR}/internal/catch_assertion_handler.hpp
+  ${SOURCES_DIR}/internal/catch_case_insensitive_comparisons.hpp
+  ${SOURCES_DIR}/internal/catch_case_sensitive.hpp
+  ${SOURCES_DIR}/internal/catch_clara.hpp
+  ${SOURCES_DIR}/internal/catch_commandline.hpp
+  ${SOURCES_DIR}/internal/catch_compare_traits.hpp
+  ${SOURCES_DIR}/internal/catch_compiler_capabilities.hpp
+  ${SOURCES_DIR}/internal/catch_config_android_logwrite.hpp
+  ${SOURCES_DIR}/internal/catch_config_counter.hpp
+  ${SOURCES_DIR}/internal/catch_config_uncaught_exceptions.hpp
+  ${SOURCES_DIR}/internal/catch_config_wchar.hpp
+  ${SOURCES_DIR}/internal/catch_console_colour.hpp
+  ${SOURCES_DIR}/internal/catch_console_width.hpp
+  ${SOURCES_DIR}/internal/catch_container_nonmembers.hpp
+  ${SOURCES_DIR}/internal/catch_context.hpp
+  ${SOURCES_DIR}/internal/catch_debug_console.hpp
+  ${SOURCES_DIR}/internal/catch_debugger.hpp
+  ${SOURCES_DIR}/internal/catch_decomposer.hpp
+  ${SOURCES_DIR}/internal/catch_enforce.hpp
+  ${SOURCES_DIR}/internal/catch_enum_values_registry.hpp
+  ${SOURCES_DIR}/internal/catch_errno_guard.hpp
+  ${SOURCES_DIR}/internal/catch_exception_translator_registry.hpp
+  ${SOURCES_DIR}/internal/catch_fatal_condition_handler.hpp
+  ${SOURCES_DIR}/internal/catch_floating_point_helpers.hpp
+  ${SOURCES_DIR}/internal/catch_getenv.hpp
+  ${SOURCES_DIR}/internal/catch_istream.hpp
+  ${SOURCES_DIR}/internal/catch_lazy_expr.hpp
+  ${SOURCES_DIR}/internal/catch_leak_detector.hpp
+  ${SOURCES_DIR}/internal/catch_list.hpp
+  ${SOURCES_DIR}/internal/catch_logical_traits.hpp
+  ${SOURCES_DIR}/internal/catch_message_info.hpp
+  ${SOURCES_DIR}/internal/catch_meta.hpp
+  ${SOURCES_DIR}/internal/catch_move_and_forward.hpp
+  ${SOURCES_DIR}/internal/catch_noncopyable.hpp
+  ${SOURCES_DIR}/internal/catch_optional.hpp
+  ${SOURCES_DIR}/internal/catch_output_redirect.hpp
+  ${SOURCES_DIR}/internal/catch_parse_numbers.hpp
+  ${SOURCES_DIR}/internal/catch_platform.hpp
+  ${SOURCES_DIR}/internal/catch_polyfills.hpp
+  ${SOURCES_DIR}/internal/catch_preprocessor.hpp
+  ${SOURCES_DIR}/internal/catch_preprocessor_remove_parens.hpp
+  ${SOURCES_DIR}/internal/catch_random_number_generator.hpp
+  ${SOURCES_DIR}/internal/catch_random_seed_generation.hpp
+  ${SOURCES_DIR}/internal/catch_reporter_registry.hpp
+  ${SOURCES_DIR}/internal/catch_reporter_spec_parser.hpp
+  ${SOURCES_DIR}/internal/catch_result_type.hpp
+  ${SOURCES_DIR}/internal/catch_reusable_string_stream.hpp
+  ${SOURCES_DIR}/internal/catch_run_context.hpp
+  ${SOURCES_DIR}/internal/catch_section.hpp
+  ${SOURCES_DIR}/internal/catch_sharding.hpp
+  ${SOURCES_DIR}/internal/catch_singletons.hpp
+  ${SOURCES_DIR}/internal/catch_source_line_info.hpp
+  ${SOURCES_DIR}/internal/catch_startup_exception_registry.hpp
+  ${SOURCES_DIR}/internal/catch_stdstreams.hpp
+  ${SOURCES_DIR}/internal/catch_stream_end_stop.hpp
+  ${SOURCES_DIR}/internal/catch_string_manip.hpp
+  ${SOURCES_DIR}/internal/catch_stringref.hpp
+  ${SOURCES_DIR}/internal/catch_tag_alias_registry.hpp
+  ${SOURCES_DIR}/internal/catch_template_test_registry.hpp
+  ${SOURCES_DIR}/internal/catch_test_case_info_hasher.hpp
+  ${SOURCES_DIR}/internal/catch_test_case_registry_impl.hpp
+  ${SOURCES_DIR}/internal/catch_test_case_tracker.hpp
+  ${SOURCES_DIR}/internal/catch_test_failure_exception.hpp
+  ${SOURCES_DIR}/internal/catch_test_macro_impl.hpp
+  ${SOURCES_DIR}/internal/catch_test_registry.hpp
+  ${SOURCES_DIR}/internal/catch_test_spec_parser.hpp
+  ${SOURCES_DIR}/internal/catch_textflow.hpp
+  ${SOURCES_DIR}/internal/catch_to_string.hpp
+  ${SOURCES_DIR}/internal/catch_uncaught_exceptions.hpp
+  ${SOURCES_DIR}/internal/catch_unique_name.hpp
+  ${SOURCES_DIR}/internal/catch_unique_ptr.hpp
+  ${SOURCES_DIR}/internal/catch_void_type.hpp
+  ${SOURCES_DIR}/internal/catch_wildcard_pattern.hpp
+  ${SOURCES_DIR}/internal/catch_windows_h_proxy.hpp
+  ${SOURCES_DIR}/internal/catch_xmlwriter.hpp
 )
 set(IMPL_SOURCES
-    ${SOURCES_DIR}/catch_approx.cpp
-    ${SOURCES_DIR}/internal/catch_assertion_handler.cpp
-    ${SOURCES_DIR}/catch_assertion_result.cpp
-    ${SOURCES_DIR}/matchers/internal/catch_matchers_combined_tu.cpp
-    ${SOURCES_DIR}/internal/catch_clara.cpp
-    ${SOURCES_DIR}/internal/catch_commandline.cpp
-    ${SOURCES_DIR}/internal/catch_source_line_info.cpp
-    ${SOURCES_DIR}/catch_config.cpp
-    ${SOURCES_DIR}/internal/catch_case_insensitive_comparisons.cpp
-    ${SOURCES_DIR}/internal/catch_console_colour.cpp
-    ${SOURCES_DIR}/internal/catch_context.cpp
-    ${SOURCES_DIR}/internal/catch_debug_console.cpp
-    ${SOURCES_DIR}/internal/catch_debugger.cpp
-    ${SOURCES_DIR}/internal/catch_enforce.cpp
-    ${SOURCES_DIR}/internal/catch_enum_values_registry.cpp
-    ${SOURCES_DIR}/internal/catch_exception_translator_registry.cpp
-    ${SOURCES_DIR}/internal/catch_fatal_condition_handler.cpp
-    ${SOURCES_DIR}/internal/catch_floating_point_helpers.cpp
-    ${SOURCES_DIR}/internal/catch_istream.cpp
-    ${SOURCES_DIR}/generators/internal/catch_generators_combined_tu.cpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_combined_tu.cpp
-    ${SOURCES_DIR}/interfaces/catch_interfaces_reporter.cpp
-    ${SOURCES_DIR}/internal/catch_list.cpp
-    ${SOURCES_DIR}/matchers/catch_matchers_floating_point.cpp
-    ${SOURCES_DIR}/matchers/catch_matchers_string.cpp
-    ${SOURCES_DIR}/matchers/catch_matchers_templated.cpp
-    ${SOURCES_DIR}/catch_message.cpp
-    ${SOURCES_DIR}/internal/catch_output_redirect.cpp
-    ${SOURCES_DIR}/catch_registry_hub.cpp
-    ${SOURCES_DIR}/internal/catch_combined_tu.cpp
-    ${SOURCES_DIR}/internal/catch_random_number_generator.cpp
-    ${SOURCES_DIR}/internal/catch_random_seed_generation.cpp
-    ${SOURCES_DIR}/internal/catch_reporter_registry.cpp
-    ${SOURCES_DIR}/internal/catch_reporter_spec_parser.cpp
-    ${SOURCES_DIR}/internal/catch_result_type.cpp
-    ${SOURCES_DIR}/internal/catch_run_context.cpp
-    ${SOURCES_DIR}/internal/catch_section.cpp
-    ${SOURCES_DIR}/internal/catch_stdstreams.cpp
-    ${SOURCES_DIR}/catch_session.cpp
-    ${SOURCES_DIR}/internal/catch_singletons.cpp
-    ${SOURCES_DIR}/internal/catch_reusable_string_stream.cpp
-    ${SOURCES_DIR}/internal/catch_stringref.cpp
-    ${SOURCES_DIR}/internal/catch_string_manip.cpp
-    ${SOURCES_DIR}/internal/catch_tag_alias_registry.cpp
-    ${SOURCES_DIR}/catch_test_case_info.cpp
-    ${SOURCES_DIR}/internal/catch_test_case_registry_impl.cpp
-    ${SOURCES_DIR}/internal/catch_test_case_tracker.cpp
-    ${SOURCES_DIR}/internal/catch_test_registry.cpp
-    ${SOURCES_DIR}/internal/catch_textflow.cpp
-    ${SOURCES_DIR}/catch_test_spec.cpp
-    ${SOURCES_DIR}/internal/catch_test_spec_parser.cpp
-    ${SOURCES_DIR}/catch_timer.cpp
-    ${SOURCES_DIR}/catch_tostring.cpp
-    ${SOURCES_DIR}/catch_totals.cpp
-    ${SOURCES_DIR}/catch_version.cpp
-    ${SOURCES_DIR}/internal/catch_wildcard_pattern.cpp
-    ${SOURCES_DIR}/internal/catch_xmlwriter.cpp
-    ${SOURCES_DIR}/internal/catch_test_case_info_hasher.cpp
+  ${SOURCES_DIR}/catch_approx.cpp
+  ${SOURCES_DIR}/catch_assertion_result.cpp
+  ${SOURCES_DIR}/catch_config.cpp
+  ${SOURCES_DIR}/catch_get_random_seed.cpp
+  ${SOURCES_DIR}/catch_message.cpp
+  ${SOURCES_DIR}/catch_registry_hub.cpp
+  ${SOURCES_DIR}/catch_session.cpp
+  ${SOURCES_DIR}/catch_tag_alias_autoregistrar.cpp
+  ${SOURCES_DIR}/catch_test_case_info.cpp
+  ${SOURCES_DIR}/catch_test_spec.cpp
+  ${SOURCES_DIR}/catch_timer.cpp
+  ${SOURCES_DIR}/catch_tostring.cpp
+  ${SOURCES_DIR}/catch_totals.cpp
+  ${SOURCES_DIR}/catch_version.cpp
+  ${SOURCES_DIR}/internal/catch_assertion_handler.cpp
+  ${SOURCES_DIR}/internal/catch_case_insensitive_comparisons.cpp
+  ${SOURCES_DIR}/internal/catch_clara.cpp
+  ${SOURCES_DIR}/internal/catch_commandline.cpp
+  ${SOURCES_DIR}/internal/catch_console_colour.cpp
+  ${SOURCES_DIR}/internal/catch_context.cpp
+  ${SOURCES_DIR}/internal/catch_debug_console.cpp
+  ${SOURCES_DIR}/internal/catch_debugger.cpp
+  ${SOURCES_DIR}/internal/catch_decomposer.cpp
+  ${SOURCES_DIR}/internal/catch_enforce.cpp
+  ${SOURCES_DIR}/internal/catch_enum_values_registry.cpp
+  ${SOURCES_DIR}/internal/catch_errno_guard.cpp
+  ${SOURCES_DIR}/internal/catch_exception_translator_registry.cpp
+  ${SOURCES_DIR}/internal/catch_fatal_condition_handler.cpp
+  ${SOURCES_DIR}/internal/catch_floating_point_helpers.cpp
+  ${SOURCES_DIR}/internal/catch_getenv.cpp
+  ${SOURCES_DIR}/internal/catch_istream.cpp
+  ${SOURCES_DIR}/internal/catch_lazy_expr.cpp
+  ${SOURCES_DIR}/internal/catch_leak_detector.cpp
+  ${SOURCES_DIR}/internal/catch_list.cpp
+  ${SOURCES_DIR}/internal/catch_message_info.cpp
+  ${SOURCES_DIR}/internal/catch_output_redirect.cpp
+  ${SOURCES_DIR}/internal/catch_parse_numbers.cpp
+  ${SOURCES_DIR}/internal/catch_polyfills.cpp
+  ${SOURCES_DIR}/internal/catch_random_number_generator.cpp
+  ${SOURCES_DIR}/internal/catch_random_seed_generation.cpp
+  ${SOURCES_DIR}/internal/catch_reporter_registry.cpp
+  ${SOURCES_DIR}/internal/catch_reporter_spec_parser.cpp
+  ${SOURCES_DIR}/internal/catch_result_type.cpp
+  ${SOURCES_DIR}/internal/catch_reusable_string_stream.cpp
+  ${SOURCES_DIR}/internal/catch_run_context.cpp
+  ${SOURCES_DIR}/internal/catch_section.cpp
+  ${SOURCES_DIR}/internal/catch_singletons.cpp
+  ${SOURCES_DIR}/internal/catch_source_line_info.cpp
+  ${SOURCES_DIR}/internal/catch_startup_exception_registry.cpp
+  ${SOURCES_DIR}/internal/catch_stdstreams.cpp
+  ${SOURCES_DIR}/internal/catch_string_manip.cpp
+  ${SOURCES_DIR}/internal/catch_stringref.cpp
+  ${SOURCES_DIR}/internal/catch_tag_alias_registry.cpp
+  ${SOURCES_DIR}/internal/catch_test_case_info_hasher.cpp
+  ${SOURCES_DIR}/internal/catch_test_case_registry_impl.cpp
+  ${SOURCES_DIR}/internal/catch_test_case_tracker.cpp
+  ${SOURCES_DIR}/internal/catch_test_failure_exception.cpp
+  ${SOURCES_DIR}/internal/catch_test_registry.cpp
+  ${SOURCES_DIR}/internal/catch_test_spec_parser.cpp
+  ${SOURCES_DIR}/internal/catch_textflow.cpp
+  ${SOURCES_DIR}/internal/catch_uncaught_exceptions.cpp
+  ${SOURCES_DIR}/internal/catch_wildcard_pattern.cpp
+  ${SOURCES_DIR}/internal/catch_xmlwriter.cpp
 )
-set(INTERNAL_FILES ${IMPL_SOURCES} ${INTERNAL_HEADERS})
+set(INTERNAL_FILES ${IMPL_SOURCES} ${IMPL_HEADERS})
+
+set(INTERFACE_HEADERS
+  ${SOURCES_DIR}/interfaces/catch_interfaces_all.hpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_capture.hpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_config.hpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_enum_values_registry.hpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_exception.hpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_generatortracker.hpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_registry_hub.hpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_reporter.hpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_reporter_factory.hpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_reporter_registry.hpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_tag_alias_registry.hpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_testcase.hpp
+)
+set(INTERFACE_SOURCES
+  ${SOURCES_DIR}/interfaces/catch_interfaces_capture.cpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_config.cpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_exception.cpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_generatortracker.cpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_registry_hub.cpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_reporter.cpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_reporter_factory.cpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_reporter_registry.cpp
+  ${SOURCES_DIR}/interfaces/catch_interfaces_testcase.cpp
+)
+set(INTERFACE_FILES ${INTERFACE_HEADERS} ${INTERFACE_SOURCES})
+
+set(GENERATOR_HEADERS
+  ${SOURCES_DIR}/generators/catch_generator_exception.hpp
+  ${SOURCES_DIR}/generators/catch_generators.hpp
+  ${SOURCES_DIR}/generators/catch_generators_adapters.hpp
+  ${SOURCES_DIR}/generators/catch_generators_all.hpp
+  ${SOURCES_DIR}/generators/catch_generators_random.hpp
+  ${SOURCES_DIR}/generators/catch_generators_range.hpp
+)
+set(GENERATOR_SOURCES
+  ${SOURCES_DIR}/generators/catch_generator_exception.cpp
+  ${SOURCES_DIR}/generators/catch_generators.cpp
+  ${SOURCES_DIR}/generators/catch_generators_random.cpp
+)
+set(GENERATOR_FILES ${GENERATOR_HEADERS} ${GENERATOR_SOURCES})
+
+set(MATCHER_HEADERS
+  ${SOURCES_DIR}/matchers/catch_matchers.hpp
+  ${SOURCES_DIR}/matchers/catch_matchers_all.hpp
+  ${SOURCES_DIR}/matchers/catch_matchers_container_properties.hpp
+  ${SOURCES_DIR}/matchers/catch_matchers_contains.hpp
+  ${SOURCES_DIR}/matchers/catch_matchers_range_equals.hpp
+  ${SOURCES_DIR}/matchers/catch_matchers_exception.hpp
+  ${SOURCES_DIR}/matchers/catch_matchers_floating_point.hpp
+  ${SOURCES_DIR}/matchers/catch_matchers_predicate.hpp
+  ${SOURCES_DIR}/matchers/catch_matchers_quantifiers.hpp
+  ${SOURCES_DIR}/matchers/catch_matchers_string.hpp
+  ${SOURCES_DIR}/matchers/catch_matchers_templated.hpp
+  ${SOURCES_DIR}/matchers/catch_matchers_vector.hpp
+  ${SOURCES_DIR}/matchers/internal/catch_matchers_impl.hpp
+)
+set(MATCHER_SOURCES
+  ${SOURCES_DIR}/matchers/catch_matchers.cpp
+  ${SOURCES_DIR}/matchers/catch_matchers_container_properties.cpp
+  ${SOURCES_DIR}/matchers/catch_matchers_exception.cpp
+  ${SOURCES_DIR}/matchers/catch_matchers_floating_point.cpp
+  ${SOURCES_DIR}/matchers/catch_matchers_predicate.cpp
+  ${SOURCES_DIR}/matchers/catch_matchers_quantifiers.cpp
+  ${SOURCES_DIR}/matchers/catch_matchers_string.cpp
+  ${SOURCES_DIR}/matchers/catch_matchers_templated.cpp
+  ${SOURCES_DIR}/matchers/internal/catch_matchers_impl.cpp
+)
+set(MATCHER_FILES ${MATCHER_HEADERS} ${MATCHER_SOURCES})
 
-# Please keep these ordered alphabetically
 set(REPORTER_HEADERS
-    ${SOURCES_DIR}/reporters/catch_reporters_all.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_automake.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_common_base.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_compact.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_console.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_cumulative_base.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_event_listener.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_helpers.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_junit.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_multi.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_sonarqube.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_streaming_base.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_tap.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_teamcity.hpp
-    ${SOURCES_DIR}/reporters/catch_reporter_xml.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_automake.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_common_base.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_compact.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_console.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_cumulative_base.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_event_listener.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_helpers.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_junit.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_multi.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_registrars.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_sonarqube.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_streaming_base.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_tap.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_teamcity.hpp
+  ${SOURCES_DIR}/reporters/catch_reporter_xml.hpp
+  ${SOURCES_DIR}/reporters/catch_reporters_all.hpp
 )
 set(REPORTER_SOURCES
-    ${SOURCES_DIR}/reporters/catch_reporter_automake.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_combined_tu.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_common_base.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_compact.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_console.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_cumulative_base.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_junit.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_multi.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_sonarqube.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_streaming_base.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_tap.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_teamcity.cpp
-    ${SOURCES_DIR}/reporters/catch_reporter_xml.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_automake.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_common_base.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_compact.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_console.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_cumulative_base.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_event_listener.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_helpers.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_junit.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_multi.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_registrars.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_sonarqube.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_streaming_base.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_tap.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_teamcity.cpp
+  ${SOURCES_DIR}/reporters/catch_reporter_xml.cpp
 )
 set(REPORTER_FILES ${REPORTER_HEADERS} ${REPORTER_SOURCES})
 
-# Fixme: STATIC because for dynamic, we would need to handle visibility
-# and I don't want to do the annotations right now
-add_library(Catch2 STATIC
+set(ALL_FILES
+  ${BENCHMARK_FILES}
+  ${GENERATOR_FILES}
   ${REPORTER_FILES}
+  ${INTERFACE_FILES}
   ${INTERNAL_FILES}
-  ${BENCHMARK_HEADERS}
-  ${BENCHMARK_SOURCES}
+  ${MATCHER_FILES}
 )
+
+set(FILTERED_FILES ${ALL_FILES})
+list(REMOVE_ITEM FILTERED_FILES "${PROJECT_BINARY_DIR}/generated-includes/catch2/catch_user_config.hpp")
+source_group(
+  TREE ${SOURCES_DIR}
+  PREFIX sources
+  FILES ${FILTERED_FILES}
+)
+source_group("generated headers"
+  FILES
+    "${PROJECT_BINARY_DIR}/generated-includes/catch2/catch_user_config.hpp"
+)
+
+add_library(Catch2 ${ALL_FILES})
 add_build_reproducibility_settings(Catch2)
 add_library(Catch2::Catch2 ALIAS Catch2)
 
@@ -275,7 +341,10 @@ if (ANDROID)
     target_link_libraries(Catch2 INTERFACE log)
 endif()
 
-set_target_properties(Catch2 PROPERTIES DEBUG_POSTFIX "d")
+set_target_properties(Catch2 PROPERTIES
+                          DEBUG_POSTFIX "d"
+                                VERSION ${PROJECT_VERSION}
+                              SOVERSION ${PROJECT_VERSION})
 
 # depend on bunch of C++11 and C++14 features to have C++14 enabled by default
 target_compile_features(Catch2
@@ -304,18 +373,18 @@ target_compile_features(Catch2
 
 configure_file(
   "${SOURCES_DIR}/catch_user_config.hpp.in"
-  "${CMAKE_BINARY_DIR}/generated-includes/catch2/catch_user_config.hpp"
+  "${PROJECT_BINARY_DIR}/generated-includes/catch2/catch_user_config.hpp"
 )
 
 target_include_directories(Catch2
   PUBLIC
     $<BUILD_INTERFACE:${SOURCES_DIR}/..>
-    $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/generated-includes>
+    $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}/generated-includes>
     $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
 )
 
 
-add_library(Catch2WithMain STATIC
+add_library(Catch2WithMain
     ${SOURCES_DIR}/internal/catch_main.cpp
 )
 add_build_reproducibility_settings(Catch2WithMain)
@@ -324,6 +393,8 @@ target_link_libraries(Catch2WithMain PUBLIC Catch2)
 set_target_properties(Catch2WithMain
   PROPERTIES
     OUTPUT_NAME "Catch2Main"
+        VERSION ${PROJECT_VERSION}
+      SOVERSION ${PROJECT_VERSION}
 )
 set_target_properties(Catch2WithMain PROPERTIES DEBUG_POSTFIX "d")
 
@@ -335,8 +406,12 @@ if (NOT_SUBPROJECT)
         Catch2WithMain
       EXPORT
         Catch2Targets
-      DESTINATION
+      LIBRARY DESTINATION
         ${CMAKE_INSTALL_LIBDIR}
+      ARCHIVE DESTINATION
+        ${CMAKE_INSTALL_LIBDIR}
+      RUNTIME DESTINATION
+        ${CMAKE_INSTALL_BINDIR}
     )
 
 
@@ -352,7 +427,7 @@ if (NOT_SUBPROJECT)
     install(
       DIRECTORY
         "${SOURCES_DIR}"
-        "${CMAKE_BINARY_DIR}/generated-includes/catch2" # Also install the generated header
+        "${PROJECT_BINARY_DIR}/generated-includes/catch2" # Also install the generated header
       DESTINATION
         "${CMAKE_INSTALL_INCLUDEDIR}"
       FILES_MATCHING
@@ -366,19 +441,20 @@ endif()
 if (CATCH_BUILD_EXAMPLES OR CATCH_BUILD_EXTRA_TESTS)
     add_library(Catch2_buildall_interface INTERFACE)
     target_sources(Catch2_buildall_interface INTERFACE
-      ${REPORTER_FILES}
-      ${INTERNAL_FILES}
-      ${BENCHMARK_HEADERS}
-      ${BENCHMARK_SOURCES}
+      ${ALL_FILES}
       # Also include main entry point
       ${SOURCES_DIR}/internal/catch_main.cpp
     )
     target_include_directories(Catch2_buildall_interface
       INTERFACE
         $<BUILD_INTERFACE:${SOURCES_DIR}/..>
-        $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/generated-includes>
+        $<BUILD_INTERFACE:${PROJECT_BINARY_DIR}/generated-includes>
         $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
     )
+    target_compile_definitions(Catch2_buildall_interface
+      INTERFACE
+        CATCH_CONFIG_STATIC
+    )
     target_compile_features(Catch2_buildall_interface
       INTERFACE
         cxx_alignas
@@ -406,3 +482,25 @@ endif()
 
 list(APPEND CATCH_WARNING_TARGETS Catch2 Catch2WithMain)
 set(CATCH_WARNING_TARGETS ${CATCH_WARNING_TARGETS} PARENT_SCOPE)
+
+
+# We still do not support building dynamic library with hidden visibility
+# so we want to check & warn users if they do this. However, we won't abort
+# the configuration step so that we don't have to also provide an override.
+if (BUILD_SHARED_LIBS)
+    set_target_properties(Catch2 Catch2WithMain
+      PROPERTIES
+        WINDOWS_EXPORT_ALL_SYMBOLS ON
+    )
+
+    get_target_property(_VisPreset Catch2 CXX_VISIBILITY_PRESET)
+    if (NOT MSVC AND _VisPreset STREQUAL "hidden")
+        set_target_properties(Catch2 Catch2WithMain
+          PROPERTIES
+            CXX_VISIBILITY_PRESET "default"
+            VISIBILITY_INLINES_HIDDEN OFF
+        )
+        message(WARNING "Setting Catch2's visibility to default."
+                        " Hidden visibility is not supported.")
+    endif()
+endif()

src/catch2/benchmark/catch_benchmark.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0
@@ -95,8 +95,11 @@ namespace Catch {
             // sets lambda to be used in fun *and* executes benchmark!
             template <typename Fun, std::enable_if_t<!Detail::is_related<Fun, Benchmark>::value, int> = 0>
                 Benchmark & operator=(Fun func) {
-                fun = Detail::BenchmarkFunction(func);
-                run();
+                auto const* cfg = getCurrentContext().getConfig();
+                if (!cfg->skipBenchmarks()) {
+                    fun = Detail::BenchmarkFunction(func);
+                    run();
+                }
                 return *this;
             }
 

src/catch2/benchmark/catch_benchmark_all.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/catch_chronometer.cpp

@@ -0,0 +1,17 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/benchmark/catch_chronometer.hpp>
+
+namespace Catch {
+    namespace Benchmark {
+        namespace Detail {
+            ChronometerConcept::~ChronometerConcept() = default;
+        } // namespace Detail
+    } // namespace Benchmark
+} // namespace Catch

src/catch2/benchmark/catch_chronometer.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/catch_clock.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/catch_constructor.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0
@@ -20,9 +20,7 @@ namespace Catch {
             template <typename T, bool Destruct>
             struct ObjectStorage
             {
-                using TStorage = std::aligned_storage_t<sizeof(T), std::alignment_of<T>::value>;
-
-                ObjectStorage() : data() {}
+                ObjectStorage() = default;
 
                 ObjectStorage(const ObjectStorage& other)
                 {
@@ -31,7 +29,7 @@ namespace Catch {
 
                 ObjectStorage(ObjectStorage&& other)
                 {
-                    new(&data) T(CATCH_MOVE(other.stored_object()));
+                    new(data) T(CATCH_MOVE(other.stored_object()));
                 }
 
                 ~ObjectStorage() { destruct_on_exit<T>(); }
@@ -39,7 +37,7 @@ namespace Catch {
                 template <typename... Args>
                 void construct(Args&&... args)
                 {
-                    new (&data) T(CATCH_FORWARD(args)...);
+                    new (data) T(CATCH_FORWARD(args)...);
                 }
 
                 template <bool AllowManualDestruction = !Destruct>
@@ -51,21 +49,25 @@ namespace Catch {
             private:
                 // If this is a constructor benchmark, destruct the underlying object
                 template <typename U>
-                void destruct_on_exit(std::enable_if_t<Destruct, U>* = 0) { destruct<true>(); }
+                void destruct_on_exit(std::enable_if_t<Destruct, U>* = nullptr) { destruct<true>(); }
                 // Otherwise, don't
                 template <typename U>
-                void destruct_on_exit(std::enable_if_t<!Destruct, U>* = 0) { }
+                void destruct_on_exit(std::enable_if_t<!Destruct, U>* = nullptr) { }
 
-                T& stored_object() {
-                    return *static_cast<T*>(static_cast<void*>(&data));
-                }
+#if defined( __GNUC__ ) && __GNUC__ <= 6
+#    pragma GCC diagnostic push
+#    pragma GCC diagnostic ignored "-Wstrict-aliasing"
+#endif
+                T& stored_object() { return *reinterpret_cast<T*>( data ); }
 
                 T const& stored_object() const {
-                    return *static_cast<T*>(static_cast<void*>(&data));
+                    return *reinterpret_cast<T const*>( data );
                 }
+#if defined( __GNUC__ ) && __GNUC__ <= 6
+#    pragma GCC diagnostic pop
+#endif
 
-
-                TStorage data;
+                alignas( T ) unsigned char data[sizeof( T )]{};
             };
         } // namespace Detail
 

src/catch2/benchmark/catch_environment.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/catch_estimate.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/catch_execution_plan.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/catch_optimizer.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/catch_outlier_classification.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/catch_sample_analysis.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/detail/catch_analyse.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/detail/catch_benchmark_function.cpp

@@ -0,0 +1,17 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/benchmark/detail/catch_benchmark_function.hpp>
+
+namespace Catch {
+    namespace Benchmark {
+        namespace Detail {
+            BenchmarkFunction::callable::~callable() = default;
+        } // namespace Detail
+    } // namespace Benchmark
+} // namespace Catch

src/catch2/benchmark/detail/catch_benchmark_function.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/detail/catch_complete_invoke.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/detail/catch_estimate_clock.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/detail/catch_measure.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/detail/catch_repeat.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/detail/catch_run_for_at_least.cpp

@@ -0,0 +1,30 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/benchmark/detail/catch_run_for_at_least.hpp>
+#include <exception>
+#include <catch2/internal/catch_enforce.hpp>
+
+namespace Catch {
+    namespace Benchmark {
+        namespace Detail {
+            struct optimized_away_error : std::exception {
+                const char* what() const noexcept override;
+            };
+
+            const char* optimized_away_error::what() const noexcept {
+                return "could not measure benchmark, maybe it was optimized away";
+            }
+
+            void throw_optimized_away_error() {
+                Catch::throw_exception(optimized_away_error{});
+            }
+
+        } // namespace Detail
+    } // namespace Benchmark
+} // namespace Catch

src/catch2/benchmark/detail/catch_run_for_at_least.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/detail/catch_stats.cpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0
@@ -137,6 +137,15 @@ namespace Catch {
     namespace Benchmark {
         namespace Detail {
 
+#if defined( __GNUC__ ) || defined( __clang__ )
+#    pragma GCC diagnostic push
+#    pragma GCC diagnostic ignored "-Wfloat-equal"
+#endif
+            bool directCompare( double lhs, double rhs ) { return lhs == rhs; }
+#if defined( __GNUC__ ) || defined( __clang__ )
+#    pragma GCC diagnostic pop
+#endif
+
             double weighted_average_quantile(int k, int q, std::vector<double>::iterator first, std::vector<double>::iterator last) {
                 auto count = last - first;
                 double idx = (count - 1) * k / static_cast<double>(q);
@@ -144,7 +153,9 @@ namespace Catch {
                 double g = idx - j;
                 std::nth_element(first, first + j, last);
                 auto xj = first[j];
-                if (g == 0) return xj;
+                if ( directCompare( g, 0 ) ) {
+                    return xj;
+                }
 
                 auto xj1 = *std::min_element(first + (j + 1), last);
                 return xj + g * (xj1 - xj);

src/catch2/benchmark/detail/catch_stats.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0
@@ -24,6 +24,10 @@ namespace Catch {
         namespace Detail {
             using sample = std::vector<double>;
 
+            // Used when we know we want == comparison of two doubles
+            // to centralize warning suppression
+            bool directCompare( double lhs, double rhs );
+
             double weighted_average_quantile(int k, int q, std::vector<double>::iterator first, std::vector<double>::iterator last);
 
             template <typename Iterator>
@@ -54,7 +58,7 @@ namespace Catch {
             double mean(Iterator first, Iterator last) {
                 auto count = last - first;
                 double sum = std::accumulate(first, last, 0.);
-                return sum / count;
+                return sum / static_cast<double>(count);
             }
 
             template <typename Estimator, typename Iterator>
@@ -100,23 +104,25 @@ namespace Catch {
                 });
 
                 double accel = sum_cubes / (6 * std::pow(sum_squares, 1.5));
-                int n = static_cast<int>(resample.size());
+                long n = static_cast<long>(resample.size());
                 double prob_n = std::count_if(resample.begin(), resample.end(), [point](double x) { return x < point; }) / static_cast<double>(n);
                 // degenerate case with uniform samples
-                if (prob_n == 0) return { point, point, point, confidence_level };
+                if ( directCompare( prob_n, 0. ) ) {
+                    return { point, point, point, confidence_level };
+                }
 
                 double bias = normal_quantile(prob_n);
                 double z1 = normal_quantile((1. - confidence_level) / 2.);
 
-                auto cumn = [n]( double x ) -> int {
-                    return std::lround( normal_cdf( x ) * n );
+                auto cumn = [n]( double x ) -> long {
+                    return std::lround( normal_cdf( x ) * static_cast<double>(n) );
                 };
                 auto a = [bias, accel](double b) { return bias + b / (1. - accel * b); };
                 double b1 = bias + z1;
                 double b2 = bias - z1;
                 double a1 = a(b1);
                 double a2 = a(b2);
-                auto lo = static_cast<size_t>((std::max)(cumn(a1), 0));
+                auto lo = static_cast<size_t>((std::max)(cumn(a1), 0l));
                 auto hi = static_cast<size_t>((std::min)(cumn(a2), n - 1));
 
                 return { point, resample[lo], resample[hi], confidence_level };

src/catch2/benchmark/detail/catch_timing.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/benchmark/internal/catch_benchmark_combined_tu.cpp

@@ -1,75 +0,0 @@
-
-//              Copyright Catch2 Authors
-// Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
-//        https://www.boost.org/LICENSE_1_0.txt)
-
-// SPDX-License-Identifier: BSL-1.0
-/** \file
- * This is a special TU that combines what would otherwise be a very
- * small benchmarking-related TUs into one bigger TU.
- *
- * The reason for this is compilation performance improvements by
- * avoiding reparsing headers for many small TUs, instead having this
- * one TU include bit more, but having it all parsed only once.
- *
- * To avoid heavy-tail problem with compilation times, each "subpart"
- * of Catch2 has its own combined TU like this.
- */
-
-////////////////////////////////////////////
-// vvv formerly catch_chronometer.cpp vvv //
-////////////////////////////////////////////
-
-#include <catch2/benchmark/catch_chronometer.hpp>
-
-namespace Catch {
-    namespace Benchmark {
-        namespace Detail {
-            ChronometerConcept::~ChronometerConcept() = default;
-        } // namespace Detail
-    } // namespace Benchmark
-} // namespace Catch
-
-
-///////////////////////////////////////////////////
-// vvv formerly catch_benchmark_function.cpp vvv //
-///////////////////////////////////////////////////
-
-#include <catch2/benchmark/detail/catch_benchmark_function.hpp>
-
-namespace Catch {
-    namespace Benchmark {
-        namespace Detail {
-            BenchmarkFunction::callable::~callable() = default;
-            } // namespace Detail
-    } // namespace Benchmark
-} // namespace Catch
-
-
-/////////////////////////////////////////////////
-// vvv formerly catch_run_for_at_least.cpp vvv //
-/////////////////////////////////////////////////
-
-#include <catch2/benchmark/detail/catch_run_for_at_least.hpp>
-#include <exception>
-#include <catch2/internal/catch_enforce.hpp>
-
-namespace Catch {
-    namespace Benchmark {
-        namespace Detail {
-            struct optimized_away_error : std::exception {
-                const char* what() const noexcept override;
-            };
-
-            const char* optimized_away_error::what() const noexcept {
-                return "could not measure benchmark, maybe it was optimized away";
-            }
-
-            void throw_optimized_away_error() {
-                Catch::throw_exception(optimized_away_error{});
-            }
-
-        } // namespace Detail
-    } // namespace Benchmark
-} // namespace Catch

src/catch2/catch_all.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0
@@ -27,6 +27,7 @@
 #include <catch2/catch_assertion_info.hpp>
 #include <catch2/catch_assertion_result.hpp>
 #include <catch2/catch_config.hpp>
+#include <catch2/catch_get_random_seed.hpp>
 #include <catch2/catch_message.hpp>
 #include <catch2/catch_section_info.hpp>
 #include <catch2/catch_session.hpp>
@@ -49,6 +50,7 @@
 #include <catch2/internal/catch_case_sensitive.hpp>
 #include <catch2/internal/catch_clara.hpp>
 #include <catch2/internal/catch_commandline.hpp>
+#include <catch2/internal/catch_compare_traits.hpp>
 #include <catch2/internal/catch_compiler_capabilities.hpp>
 #include <catch2/internal/catch_config_android_logwrite.hpp>
 #include <catch2/internal/catch_config_counter.hpp>
@@ -67,16 +69,19 @@
 #include <catch2/internal/catch_exception_translator_registry.hpp>
 #include <catch2/internal/catch_fatal_condition_handler.hpp>
 #include <catch2/internal/catch_floating_point_helpers.hpp>
+#include <catch2/internal/catch_getenv.hpp>
 #include <catch2/internal/catch_istream.hpp>
 #include <catch2/internal/catch_lazy_expr.hpp>
 #include <catch2/internal/catch_leak_detector.hpp>
 #include <catch2/internal/catch_list.hpp>
+#include <catch2/internal/catch_logical_traits.hpp>
 #include <catch2/internal/catch_message_info.hpp>
 #include <catch2/internal/catch_meta.hpp>
 #include <catch2/internal/catch_move_and_forward.hpp>
 #include <catch2/internal/catch_noncopyable.hpp>
 #include <catch2/internal/catch_optional.hpp>
 #include <catch2/internal/catch_output_redirect.hpp>
+#include <catch2/internal/catch_parse_numbers.hpp>
 #include <catch2/internal/catch_platform.hpp>
 #include <catch2/internal/catch_polyfills.hpp>
 #include <catch2/internal/catch_preprocessor.hpp>
@@ -113,7 +118,6 @@
 #include <catch2/internal/catch_unique_ptr.hpp>
 #include <catch2/internal/catch_void_type.hpp>
 #include <catch2/internal/catch_wildcard_pattern.hpp>
-#include <catch2/internal/catch_windows_h_proxy.hpp>
 #include <catch2/internal/catch_xmlwriter.hpp>
 #include <catch2/matchers/catch_matchers_all.hpp>
 #include <catch2/reporters/catch_reporters_all.hpp>

src/catch2/catch_approx.cpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/catch_approx.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/catch_assertion_info.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/catch_assertion_result.cpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/catch_assertion_result.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/catch_config.cpp

@@ -1,20 +1,89 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0
 #include <catch2/catch_config.hpp>
 #include <catch2/catch_user_config.hpp>
 #include <catch2/internal/catch_enforce.hpp>
+#include <catch2/internal/catch_parse_numbers.hpp>
+#include <catch2/internal/catch_stdstreams.hpp>
 #include <catch2/internal/catch_stringref.hpp>
 #include <catch2/internal/catch_string_manip.hpp>
 #include <catch2/internal/catch_test_spec_parser.hpp>
 #include <catch2/interfaces/catch_interfaces_tag_alias_registry.hpp>
+#include <catch2/internal/catch_getenv.hpp>
+
+#include <fstream>
 
 namespace Catch {
 
+    namespace {
+        static bool enableBazelEnvSupport() {
+#if defined( CATCH_CONFIG_BAZEL_SUPPORT )
+            return true;
+#else
+            return Detail::getEnv( "BAZEL_TEST" ) != nullptr;
+#endif
+        }
+
+        struct bazelShardingOptions {
+            unsigned int shardIndex, shardCount;
+            std::string shardFilePath;
+        };
+
+        static Optional<bazelShardingOptions> readBazelShardingOptions() {
+            const auto bazelShardIndex = Detail::getEnv( "TEST_SHARD_INDEX" );
+            const auto bazelShardTotal = Detail::getEnv( "TEST_TOTAL_SHARDS" );
+            const auto bazelShardInfoFile = Detail::getEnv( "TEST_SHARD_STATUS_FILE" );
+
+
+            const bool has_all =
+                bazelShardIndex && bazelShardTotal && bazelShardInfoFile;
+            if ( !has_all ) {
+                // We provide nice warning message if the input is
+                // misconfigured.
+                auto warn = []( const char* env_var ) {
+                    Catch::cerr()
+                        << "Warning: Bazel shard configuration is missing '"
+                        << env_var << "'. Shard configuration is skipped.\n";
+                };
+                if ( !bazelShardIndex ) {
+                    warn( "TEST_SHARD_INDEX" );
+                }
+                if ( !bazelShardTotal ) {
+                    warn( "TEST_TOTAL_SHARDS" );
+                }
+                if ( !bazelShardInfoFile ) {
+                    warn( "TEST_SHARD_STATUS_FILE" );
+                }
+                return {};
+            }
+
+            auto shardIndex = parseUInt( bazelShardIndex );
+            if ( !shardIndex ) {
+                Catch::cerr()
+                    << "Warning: could not parse 'TEST_SHARD_INDEX' ('" << bazelShardIndex
+                    << "') as unsigned int.\n";
+                return {};
+            }
+            auto shardTotal = parseUInt( bazelShardTotal );
+            if ( !shardTotal ) {
+                Catch::cerr()
+                    << "Warning: could not parse 'TEST_TOTAL_SHARD' ('"
+                    << bazelShardTotal << "') as unsigned int.\n";
+                return {};
+            }
+
+            return bazelShardingOptions{
+                *shardIndex, *shardTotal, bazelShardInfoFile };
+
+        }
+    } // end namespace
+
+
     bool operator==( ProcessedReporterSpec const& lhs,
                      ProcessedReporterSpec const& rhs ) {
         return lhs.name == rhs.name &&
@@ -36,17 +105,6 @@ namespace Catch {
             elem = trim(elem);
         }
 
-
-        TestSpecParser parser(ITagAliasRegistry::get());
-        if (!m_data.testsOrTags.empty()) {
-            m_hasTestFilters = true;
-            for (auto const& testOrTags : m_data.testsOrTags) {
-                parser.parse(testOrTags);
-            }
-        }
-        m_testSpec = parser.testSpec();
-
-
         // Insert the default reporter if user hasn't asked for a specfic one
         if ( m_data.reporterSpecifications.empty() ) {
             m_data.reporterSpecifications.push_back( {
@@ -59,27 +117,20 @@ namespace Catch {
             } );
         }
 
-#if defined( CATCH_CONFIG_BAZEL_SUPPORT )
-        // Register a JUnit reporter for Bazel. Bazel sets an environment
-        // variable with the path to XML output. If this file is written to
-        // during test, Bazel will not generate a default XML output.
-        // This allows the XML output file to contain higher level of detail
-        // than what is possible otherwise.
-#    if defined( _MSC_VER )
-        // On Windows getenv throws a warning as there is no input validation,
-        // since the key is hardcoded, this should not be an issue.
-#        pragma warning( push )
-#        pragma warning( disable : 4996 )
-#    endif
-        const auto bazelOutputFilePtr = std::getenv( "XML_OUTPUT_FILE" );
-#    if defined( _MSC_VER )
-#        pragma warning( pop )
-#    endif
-        if ( bazelOutputFilePtr != nullptr ) {
-            m_data.reporterSpecifications.push_back(
-                { "junit", std::string( bazelOutputFilePtr ), {}, {} } );
+        if ( enableBazelEnvSupport() ) {
+            readBazelEnvVars();
         }
-#endif
+
+        // Bazel support can modify the test specs, so parsing has to happen
+        // after reading Bazel env vars.
+        TestSpecParser parser( ITagAliasRegistry::get() );
+        if ( !m_data.testsOrTags.empty() ) {
+            m_hasTestFilters = true;
+            for ( auto const& testOrTags : m_data.testsOrTags ) {
+                parser.parse( testOrTags );
+            }
+        }
+        m_testSpec = parser.testSpec();
 
 
         // We now fixup the reporter specs to handle default output spec,
@@ -111,6 +162,7 @@ namespace Catch {
     bool Config::listTests() const          { return m_data.listTests; }
     bool Config::listTags() const           { return m_data.listTags; }
     bool Config::listReporters() const      { return m_data.listReporters; }
+    bool Config::listListeners() const      { return m_data.listListeners; }
 
     std::vector<std::string> const& Config::getTestsOrTags() const { return m_data.testsOrTags; }
     std::vector<std::string> const& Config::getSectionsToRun() const { return m_data.sectionsToRun; }
@@ -152,10 +204,44 @@ namespace Catch {
     bool Config::showInvisibles() const                { return m_data.showInvisibles; }
     Verbosity Config::verbosity() const                { return m_data.verbosity; }
 
+    bool Config::skipBenchmarks() const                           { return m_data.skipBenchmarks; }
     bool Config::benchmarkNoAnalysis() const                      { return m_data.benchmarkNoAnalysis; }
     unsigned int Config::benchmarkSamples() const                 { return m_data.benchmarkSamples; }
     double Config::benchmarkConfidenceInterval() const            { return m_data.benchmarkConfidenceInterval; }
     unsigned int Config::benchmarkResamples() const               { return m_data.benchmarkResamples; }
     std::chrono::milliseconds Config::benchmarkWarmupTime() const { return std::chrono::milliseconds(m_data.benchmarkWarmupTime); }
 
+    void Config::readBazelEnvVars() {
+        // Register a JUnit reporter for Bazel. Bazel sets an environment
+        // variable with the path to XML output. If this file is written to
+        // during test, Bazel will not generate a default XML output.
+        // This allows the XML output file to contain higher level of detail
+        // than what is possible otherwise.
+        const auto bazelOutputFile = Detail::getEnv( "XML_OUTPUT_FILE" );
+
+        if ( bazelOutputFile ) {
+            m_data.reporterSpecifications.push_back(
+                { "junit", std::string( bazelOutputFile ), {}, {} } );
+        }
+
+        const auto bazelTestSpec = Detail::getEnv( "TESTBRIDGE_TEST_ONLY" );
+        if ( bazelTestSpec ) {
+            // Presumably the test spec from environment should overwrite
+            // the one we got from CLI (if we got any)
+            m_data.testsOrTags.clear();
+            m_data.testsOrTags.push_back( bazelTestSpec );
+        }
+
+        const auto bazelShardOptions = readBazelShardingOptions();
+        if ( bazelShardOptions ) {
+            std::ofstream f( bazelShardOptions->shardFilePath,
+                             std::ios_base::out | std::ios_base::trunc );
+            if ( f.is_open() ) {
+                f << "";
+                m_data.shardIndex = bazelShardOptions->shardIndex;
+                m_data.shardCount = bazelShardOptions->shardCount;
+            }
+        }
+    }
+
 } // end namespace Catch

src/catch2/catch_config.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0
@@ -48,6 +48,7 @@ namespace Catch {
         bool listTests = false;
         bool listTags = false;
         bool listReporters = false;
+        bool listListeners = false;
 
         bool showSuccessfulTests = false;
         bool shouldDebugBreak = false;
@@ -64,6 +65,7 @@ namespace Catch {
         unsigned int shardCount = 1;
         unsigned int shardIndex = 0;
 
+        bool skipBenchmarks = false;
         bool benchmarkNoAnalysis = false;
         unsigned int benchmarkSamples = 100;
         double benchmarkConfidenceInterval = 0.95;
@@ -98,6 +100,7 @@ namespace Catch {
         bool listTests() const;
         bool listTags() const;
         bool listReporters() const;
+        bool listListeners() const;
 
         std::vector<ReporterSpec> const& getReporterSpecs() const;
         std::vector<ProcessedReporterSpec> const&
@@ -129,6 +132,7 @@ namespace Catch {
         int abortAfter() const override;
         bool showInvisibles() const override;
         Verbosity verbosity() const override;
+        bool skipBenchmarks() const override;
         bool benchmarkNoAnalysis() const override;
         unsigned int benchmarkSamples() const override;
         double benchmarkConfidenceInterval() const override;
@@ -136,6 +140,9 @@ namespace Catch {
         std::chrono::milliseconds benchmarkWarmupTime() const override;
 
     private:
+        // Reads Bazel env vars and applies them to the config
+        void readBazelEnvVars();
+
         ConfigData m_data;
         std::vector<ProcessedReporterSpec> m_processedReporterSpecs;
         TestSpec m_testSpec;

src/catch2/catch_get_random_seed.cpp

@@ -0,0 +1,18 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/catch_get_random_seed.hpp>
+
+#include <catch2/internal/catch_context.hpp>
+#include <catch2/catch_config.hpp>
+
+namespace Catch {
+    std::uint32_t getSeed() {
+        return getCurrentContext().getConfig()->rngSeed();
+    }
+}

src/catch2/catch_get_random_seed.hpp

@@ -0,0 +1,18 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+#ifndef CATCH_GET_RANDOM_SEED_HPP_INCLUDED
+#define CATCH_GET_RANDOM_SEED_HPP_INCLUDED
+
+#include <cstdint>
+
+namespace Catch {
+    //! Returns Catch2's current RNG seed.
+    std::uint32_t getSeed();
+}
+
+#endif // CATCH_GET_RANDOM_SEED_HPP_INCLUDED

src/catch2/catch_message.cpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0

src/catch2/catch_message.hpp

@@ -1,7 +1,7 @@
 
 //              Copyright Catch2 Authors
 // Distributed under the Boost Software License, Version 1.0.
-//   (See accompanying file LICENSE_1_0.txt or copy at
+//   (See accompanying file LICENSE.txt or copy at
 //        https://www.boost.org/LICENSE_1_0.txt)
 
 // SPDX-License-Identifier: BSL-1.0
@@ -103,7 +103,7 @@ namespace Catch {
 
 ///////////////////////////////////////////////////////////////////////////////
 #define INTERNAL_CATCH_INFO( macroName, log ) \
-    Catch::ScopedMessage INTERNAL_CATCH_UNIQUE_NAME( scopedMessage )( Catch::MessageBuilder( macroName##_catch_sr, CATCH_INTERNAL_LINEINFO, Catch::ResultWas::Info ) << log )
+    const Catch::ScopedMessage INTERNAL_CATCH_UNIQUE_NAME( scopedMessage )( Catch::MessageBuilder( macroName##_catch_sr, CATCH_INTERNAL_LINEINFO, Catch::ResultWas::Info ) << log )
 
 ///////////////////////////////////////////////////////////////////////////////
 #define INTERNAL_CATCH_UNSCOPED_INFO( macroName, log ) \