CXX-3094 Upgrade Catch2 from v2 to v3 (#1200)

* clang-format: separate system and third-party headers from driver headers

* Remove obsolete MONGO_CXX_DRIVER_COMPILING compile definition

* Do not build or run tests on VS 2015 distros

* Upgrade to Catch2 v3 via FetchCatch2.cmake

* Format catch_helpers.hh

* Conditionally pass SYSTEM to FetchContent_Declare

* Disable tests in RPM snapshot builds

* Address -Wextra-semi* warnings

* Update Catch2 license in THIRD-PARTY-NOTICES to match v3.7.0

Author: eramongodb

.clang-format

@@ -10,14 +10,20 @@ Cpp11BracedListStyle: true
 DerivePointerAlignment: false
 IncludeBlocks: Regroup
 IncludeCategories:
-  - Regex: 'prelude\.(hpp|hh)' # preludes
-    Priority: 4
+  - Regex: '".*"' # relative headers
+    Priority: 10
+  - Regex: '(bsoncxx|mongocxx)/config(/private)?/prelude\.(hpp|hh)' # v_noabi preludes
+    Priority: 50
+  - Regex: '(bsoncxx|mongocxx)/test/.*' # test headers
+    Priority: 60
   - Regex: '<[[:alnum:]_.]+>' # system headers
-    Priority: 1
-  - Regex: '.*(-|\/)fwd\.(hpp|hh)' # forwarding headers
-    Priority: 2
-  - Regex: '.*' # driver headers
-    Priority: 3
+    Priority: 20
+  - Regex: '(bsoncxx|mongocxx)/.*(-|\/)fwd\.(hpp|hh)' # all driver forwarding headers
+    Priority: 30
+  - Regex: '(bsoncxx|mongocxx)/.*' # all remaining (normal) driver headers
+    Priority: 40
+  - Regex: '.*' # all other headers (third party)
+    Priority: 90
 IndentWidth: 4
 MaxEmptyLinesToKeep: 1
 NamespaceIndentation: None

.evergreen/build_snapshot_rpm.sh

@@ -105,7 +105,7 @@ sudo mock -r ${config} --use-bootstrap-image --isolation=simple --copyout "/tmp/
 sudo mock -r ${config} --use-bootstrap-image --isolation=simple --cwd "/tmp/${build_dir}" --chroot -- /bin/sh -c "(
   [ -d build ] || mkdir build ;
   cd build ;
-  /usr/bin/cmake -DCMAKE_BUILD_TYPE=Release -DBSONCXX_POLY_USE_BOOST=1 -DENABLE_UNINSTALL=OFF .. ;
+  /usr/bin/cmake -DCMAKE_BUILD_TYPE=Release -DBSONCXX_POLY_USE_BOOST=1 -DENABLE_UNINSTALL=OFF -DENABLE_TESTS=OFF .. ;
   make -j 8 dist
   )"
 

.evergreen/test.sh

@@ -60,6 +60,7 @@ PATH="${working_dir:?}/build/src/mongocxx/test/${build_type:?}:${PATH:-}"
 PATH="${working_dir:?}/build/src/bsoncxx/test/${build_type:?}:${PATH:-}"
 PATH="${working_dir:?}/build/src/mongocxx/${build_type:?}:${PATH:-}"
 PATH="${working_dir:?}/build/src/bsoncxx/${build_type:?}:${PATH:-}"
+PATH="${working_dir:?}/build/_deps/ep_catch2-build/src/${build_type:?}:${PATH:-}"
 PATH="${mongoc_dir:?}/bin:${PATH:-}"
 PATH="${working_dir:?}/build/install/bin:${PATH:-}"
 

.mci.yml

@@ -1001,6 +1001,8 @@ tasks:
       - func: "setup"
       - func: "fetch_c_driver_source"
       - func: "compile"
+        vars:
+          ENABLE_TESTS: OFF
       - command: shell.exec
         type: test
         params:
@@ -1015,6 +1017,8 @@ tasks:
       - func: "setup"
       - func: "fetch_c_driver_source"
       - func: "compile"
+        vars:
+          ENABLE_TESTS: OFF
       - command: shell.exec
         type: test
         params:
@@ -2156,10 +2160,7 @@ buildvariants:
       run_on:
           - windows-64-vs2015-compile
       tasks:
-          - name: compile_and_test_with_shared_libs
-          - name: compile_and_test_with_shared_libs_extra_alignment
-          - name: compile_and_test_with_static_libs
-          - name: compile_and_test_with_static_libs_extra_alignment
+          - name: compile_without_tests
           - name: uninstall_check_windows
 
     - name: windows-2k8-debug
@@ -2172,9 +2173,8 @@ buildvariants:
       run_on:
           - windows-64-vs2015-compile
       tasks:
-          # The debug shared lib is tested in the "integration tests" matrix
-          - name: compile_and_test_with_static_libs
-          - name: compile_and_test_with_static_libs_extra_alignment
+          - name: compile_without_tests
+          - name: uninstall_check_windows
 
     - name: windows-msvc2015-debug
       display_name: "Windows (VS 2015) Debug (MongoDB 4.2)"
@@ -2186,8 +2186,8 @@ buildvariants:
       run_on:
          - windows-64-vs2015-compile
       tasks:
-         - name: compile_with_shared_libs
-         - name: compile_and_test_auth_with_shared_libs
+         - name: compile_without_tests
+         - name: uninstall_check_windows
 
     - name: packaging
       display_name: Linux Distro Packaging

CHANGELOG.md

@@ -11,8 +11,10 @@ Changes prior to 3.9.0 are documented as [release notes on GitHub](https://githu
 
 ### Changed
 
-- `FetchContent_MakeAvailable()` is used to populate dependencies instead of `FetchContent_Populate()` for the Mongo C Driver (when not provided by `CMAKE_PREFIX_PATH`) and mnmlstc/core (when automatically selected or `BSONCXX_POLY_USE_MNMLSTC=ON`).
+- `FetchContent_MakeAvailable()` is used to populate dependencies instead of `FetchContent_Populate()` for the Mongo C Driver (when not provided by `CMAKE_PREFIX_PATH`) and mnmlstc/core (when automatically selected or when `BSONCXX_POLY_USE_MNMLSTC=ON`).
   - Note: `FetchContent_Populate()` is still used for mnmlstc/core for CMake versions prior to 3.18 to avoid `add_subdirectory()` behavior.
+- Test suite now uses Catch2 v3 via FetchContent instead of the bundled Catch2 v2 standalone header.
+  - C++14 or newer is now required to build tests when enabled with `ENABLE_TESTS=ON`.
 
 ### Deprecated
 

THIRD-PARTY-NOTICES

@@ -15,7 +15,7 @@ https://github.com/mongodb/mongo-cxx-driver.
 ---------------------------------------
 [Note: Catch is used only for testing.]
 
-Copyright (c) 2012 Two Blue Cubes Ltd. All rights reserved.
+Copyright Catch2 Authors
 
 Distributed under the Boost Software License, Version 1.0.
 See http://www.boost.org/LICENSE_1_0.txt

cmake/CMakeLists.txt

@@ -16,6 +16,7 @@ add_subdirectory(make_dist)
 
 set(cmake_MODULES
     BsoncxxUtil.cmake
+    FetchCatch2.cmake
     FetchMnmlstcCore.cmake
     FetchMongoC.cmake
     MacroGuardTest.cmake

cmake/FetchCatch2.cmake

@@ -0,0 +1,46 @@
+# Use FetchContent to obtain Catch2.
+
+include(FetchContent)
+
+message(STATUS "Downloading Catch2...")
+
+function(fetch_catch2)
+    set(fetch_args "")
+    if (CMAKE_VERSION VERSION_GREATER_EQUAL "3.25.0")
+        set(fetch_args "SYSTEM")
+    endif()
+
+    FetchContent_Declare(
+        EP_Catch2
+
+        GIT_REPOSITORY https://github.com/catchorg/Catch2
+        GIT_TAG v3.7.0
+        GIT_SHALLOW TRUE
+        LOG_DOWNLOAD ON
+
+        ${fetch_args}
+
+        FETCHCONTENT_UPDATES_DISCONNECTED ON
+    )
+
+    FetchContent_GetProperties(EP_Catch2)
+
+    if(NOT ep_catch2_POPULATED)
+        # Avoid Catch2 compile warnings from being treated as errors.
+        string(REPLACE " -Werror" "" CMAKE_C_FLAGS "${CMAKE_C_FLAGS}")
+        string(REPLACE " -Werror" "" CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
+
+        FetchContent_MakeAvailable(EP_Catch2)
+
+        # Avoid building unnecessary targets. Use FetchContent_Declare(EXCLUDE_FROM_ALL) in CMake 3.28 and newer.
+        set_property(DIRECTORY "${ep_catch2_SOURCE_DIR}" PROPERTY EXCLUDE_FROM_ALL ON)
+
+        # Catch2 config vars.
+        set_property(CACHE CATCH_INSTALL_DOCS PROPERTY VALUE OFF)
+        set_property(CACHE CATCH_INSTALL_EXTRAS PROPERTY VALUE OFF)
+    endif()
+endfunction()
+
+fetch_catch2()
+
+message (STATUS "Downloading Catch2... done.")

cmake/FetchMnmlstcCore.cmake

@@ -7,6 +7,11 @@ set(core-subbuild "${CMAKE_CURRENT_BINARY_DIR}/_deps/core-subbuild")
 set(core-build "${CMAKE_CURRENT_BINARY_DIR}/_deps/core-build")
 set(core-install "${CMAKE_CURRENT_BINARY_DIR}/_deps/core-install")
 
+set(fetch_args "")
+if (CMAKE_VERSION VERSION_GREATER_EQUAL "3.25.0")
+    set(fetch_args "SYSTEM")
+endif()
+
 # Also update etc/purls.txt.
 FetchContent_Declare(
     EP_mnmlstc_core
@@ -22,6 +27,8 @@ FetchContent_Declare(
     GIT_SHALLOW TRUE
     LOG_DOWNLOAD ON
 
+    ${fetch_args}
+
     FETCHCONTENT_UPDATES_DISCONNECTED ON
 )
 FetchContent_GetProperties(EP_mnmlstc_core)
@@ -33,7 +40,7 @@ if(core_FOUND AND "$CACHE{INTERNAL_MONGOC_MNMLSTC_CORE_FOUND}")
 else()
     if(NOT ep_mnmlstc_core_POPULATED)
         message(STATUS "Downloading mnmlstc/core...")
-        if("${CMAKE_VERSION}" VERSION_LESS "3.18.0")
+        if(CMAKE_VERSION VERSION_LESS "3.18.0")
             # SOURCE_SUBDIR is not yet supported.
             FetchContent_Populate(EP_mnmlstc_core)
         else()

cmake/FetchMongoC.cmake

@@ -4,11 +4,18 @@ include(FetchContent)
 
 message(STATUS "Download and configure C driver version ${LIBMONGOC_DOWNLOAD_VERSION} ... begin")
 
+set(fetch_args "")
+if (CMAKE_VERSION VERSION_GREATER_EQUAL "3.25.0")
+    set(fetch_args "SYSTEM")
+endif()
+
 # Declare mongo-c-driver as a dependency
 FetchContent_Declare(
     mongo-c-driver
     GIT_REPOSITORY https://github.com/mongodb/mongo-c-driver.git
     GIT_TAG ${LIBMONGOC_DOWNLOAD_VERSION}
+
+    ${fetch_args}
 )
 
 FetchContent_GetProperties(mongo-c-driver)

src/CMakeLists.txt

@@ -12,15 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-add_definitions(-DMONGO_CXX_DRIVER_COMPILING)
 add_subdirectory(bsoncxx)
 add_subdirectory(mongocxx)
 
 set_local_dist(src_DIST_local
     CMakeLists.txt
-    third_party/catch/main.cpp
-    third_party/catch/include/catch.hpp
-    third_party/catch/include/helpers.hpp
 )
 
 set(src_DIST

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/list.hpp

@@ -160,7 +160,7 @@ class document : public list {
     ///
     /// Creates an empty document.
     ///
-    document() : list({}, false, false){};
+    document() : list({}, false, false) {}
 
     ///
     /// Creates a BSON document.
@@ -184,7 +184,7 @@ class array : public list {
     ///
     /// Creates an empty array.
     ///
-    array() : list({}, false, true){};
+    array() : list({}, false, true) {}
 
     ///
     /// Creates a BSON array.

src/bsoncxx/test/CMakeLists.txt

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+include(FetchCatch2)
+
 if(NOT BUILD_TESTING)
     set_property(DIRECTORY PROPERTY EXCLUDE_FROM_ALL TRUE)
 endif()
@@ -46,25 +48,28 @@ add_executable(test_bson
 
 # Common target properties for test executables.
 add_library(bsoncxx_test_properties INTERFACE)
+
+target_link_libraries(bsoncxx_test_properties INTERFACE Catch2::Catch2)
+target_compile_features(bsoncxx_test_properties INTERFACE cxx_std_14)
+
 target_link_libraries(bsoncxx_test_properties INTERFACE bsoncxx_testing ${libbson_target})
 target_include_directories(bsoncxx_test_properties INTERFACE
 
     # Allow `#include <bson/bson.h>`
     ${libbson_include_directories}
 
-    # Allow `#include <bsoncxx/test/...>` and `#include <third_party/...>`.
+    # Allow `#include <bsoncxx/test/...>`.
     ${CMAKE_CURRENT_SOURCE_DIR}/../..
 )
 target_compile_definitions(bsoncxx_test_properties INTERFACE ${libbson_definitions})
 add_library(bsoncxx::test_properties ALIAS bsoncxx_test_properties)
 
 # Avoid redundant recompilation of catch/main.cpp.
-add_library(bsoncxx_test_properties_with_main STATIC EXCLUDE_FROM_ALL ${THIRD_PARTY_SOURCE_DIR}/catch/main.cpp)
-target_link_libraries(bsoncxx_test_properties_with_main PUBLIC bsoncxx::test_properties)
+add_library(bsoncxx_test_properties_with_main INTERFACE)
+target_link_libraries(bsoncxx_test_properties_with_main INTERFACE bsoncxx::test_properties Catch2::Catch2WithMain)
 add_library(bsoncxx::test_properties_with_main ALIAS bsoncxx_test_properties_with_main)
 
-set_property(TARGET test_bson APPEND PROPERTY LINK_LIBRARIES bsoncxx::test_properties_with_main)
-
+target_link_libraries (test_bson PRIVATE bsoncxx::test_properties_with_main)
 add_test(NAME bson COMMAND test_bson)
 
 # Generate test to ensure macro guards behave properly.

src/bsoncxx/test/array.cpp

@@ -14,10 +14,11 @@
 
 #include <bsoncxx/array/view.hpp>
 #include <bsoncxx/builder/basic/array.hpp>
-#include <bsoncxx/test/catch.hh>
 #include <bsoncxx/types.hpp>
 #include <bsoncxx/types/bson_value/make_value.hpp>
 
+#include <bsoncxx/test/catch.hh>
+
 namespace {
 
 using namespace bsoncxx;

src/bsoncxx/test/bson_b_date.cpp

@@ -14,9 +14,10 @@
 
 #include <chrono>
 
-#include <bsoncxx/test/catch.hh>
 #include <bsoncxx/types.hpp>
 
+#include <bsoncxx/test/catch.hh>
+
 namespace {
 TEST_CASE("time_point is converted to b_date and back", "[bsoncxx::types::b_date]") {
     using bsoncxx::types::b_date;

src/bsoncxx/test/bson_builder.cpp

@@ -24,10 +24,14 @@
 #include <bsoncxx/json.hpp>
 #include <bsoncxx/private/libbson.hh>
 #include <bsoncxx/string/to_string.hpp>
-#include <bsoncxx/test/catch.hh>
 #include <bsoncxx/types.hpp>
 #include <bsoncxx/types/bson_value/view.hpp>
 
+#include <bsoncxx/test/catch.hh>
+
+#include <catch2/catch_case_sensitive.hpp>
+#include <catch2/matchers/catch_matchers_string.hpp>
+
 namespace {
 
 using namespace bsoncxx;
@@ -1711,12 +1715,12 @@ TEST_CASE("list builder with explicit type deduction", "[bsoncxx::builder::list]
 
     SECTION("document") {
         builder::list b;
-        auto kvp_regex =
-            Catch::Matches("(.*)must be list of key-value pairs(.*)", Catch::CaseSensitive::No);
+        auto kvp_regex = Catch::Matchers::Matches("(.*)must be list of key-value pairs(.*)",
+                                                  Catch::CaseSensitive::No);
         REQUIRE_THROWS_WITH((b = builder::document{"foo", 1, 2}), kvp_regex);
 
-        auto type_regex =
-            Catch::Matches("(.*)must be string type(.*)int32(.*)", Catch::CaseSensitive::No);
+        auto type_regex = Catch::Matchers::Matches("(.*)must be string type(.*)int32(.*)",
+                                                   Catch::CaseSensitive::No);
         REQUIRE_THROWS_WITH((b = builder::document{"foo", 1, 2, 4}), type_regex);
     }
 }

src/bsoncxx/test/bson_get_values.cpp

@@ -17,6 +17,7 @@
 #include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/builder/basic/document.hpp>
 #include <bsoncxx/builder/basic/sub_array.hpp>
+
 #include <bsoncxx/test/catch.hh>
 
 namespace {

src/bsoncxx/test/bson_serialization.cpp

@@ -17,9 +17,10 @@
 #include <bsoncxx/builder/basic/document.hpp>
 #include <bsoncxx/document/value.hpp>
 #include <bsoncxx/string/to_string.hpp>
-#include <bsoncxx/test/catch.hh>
 #include <bsoncxx/types/bson_value/view.hpp>
 
+#include <bsoncxx/test/catch.hh>
+
 namespace {
 using namespace bsoncxx;