skip to content

When migrating a CMake project from Catch2 v2's single catch.hpp to Catch2 v3, what changes in the includes, the main function and the link targets?

level: seniorimportance: should knowfreq 30%

answer

  1. a compiled library now
  2. headers per feature
  3. the main lives in a second library
  4. CATCH_CONFIG_MAIN no longer works

basics

~10 s

Catch2 v3 is a compiled static library with per-feature headers. Replace catch.hpp with catch_test_macros.hpp and the feature headers you use, delete the CATCH_CONFIG_MAIN file, and link Catch2::Catch2WithMain, or Catch2::Catch2 plus your own main.

solid answer

~40 s

Catch2 v3 stopped being a single header: it is a **static library** with **per-feature headers** and a C++14 minimum. The include `<catch2/catch.hpp>` no longer exists; `<catch2/catch_all.hpp>` is a stepping stone, and the target is per-feature includes such as `<catch2/catch_test_macros.hpp>`, `<catch2/matchers/catch_matchers_floating_point.hpp>` or `<catch2/generators/catch_generators.hpp>`. The `main` moved into a second library: `find_package(Catch2 3 REQUIRED)` provides `Catch2::Catch2WithMain`, which links both, and `Catch2::Catch2`, which you link when you write your own `main` around `Catch::Session`. In v3, defining `CATCH_CONFIG_MAIN` no longer creates `main`, so a leftover definition linked against `Catch2::Catch2` alone fails with an undefined `main`. Expect a few renames, such as the string matcher `Contains` becoming `ContainsSubstring`. The documentation reports roughly 80% less inclusion overhead.

code

cmake · 12 lines
cmake
cmake_minimum_required(VERSION 3.16)
project(shapes_tests LANGUAGES CXX)

find_package(Catch2 3 REQUIRED)

# Uses the main that Catch2 provides
add_executable(tests test_area.cpp)
target_link_libraries(tests PRIVATE Catch2::Catch2WithMain)

# Supplies its own main in test_main.cpp
add_executable(tests_own_main test_area.cpp test_main.cpp)
target_link_libraries(tests_own_main PRIVATE Catch2::Catch2)

go deeper

for a junior

Recall that Catch2 v3 is a library with separate headers, that the main comes from Catch2WithMain, and that catch.hpp is gone.

for a middle

Walk through the documented migration steps, explain the two CMake targets, and say why CATCH_CONFIG_MAIN leaves a v3 build without main.

for a senior

Plan the migration for compile-time gains: catch_all.hpp as a short bridge, then per-feature headers, fixing renamed matchers and custom reporters on the way.

for a principal

Weigh the library model against the amalgamated files for a codebase: build-system effort and package management versus slower compilation, and schedule the move rather than letting v2 linger.

## What changed between v2 and v3 The migration guide names three significant changes in Catch2 v3: - Catch2 is **split into multiple headers**, one per feature area. - Catch2 is **compiled as a static library** rather than compiled into every test translation unit. - **C++14** is the minimum C++ version. The stated motivation is compile time: the guide reports that the inclusion overhead in the common case dropped by roughly 80%. It also makes Catch2 friendlier to package managers. ## The recommended path The guide recommends building Catch2 as a proper library and moving to piecewise headers: 1. Link against `Catch2WithMain` if you used Catch2's default main; otherwise keep linking against `Catch2`. With pkg-config, use `catch2-with-main`. 2. Delete the translation unit that defined `CATCH_CONFIG_MAIN` or `CATCH_CONFIG_RUNNER`; it is no longer needed. 3. Change `#include <catch2/catch.hpp>` to `#include <catch2/catch_all.hpp>`. 4. Fix what breaks: matchers now live directly in `Catch::Matchers`, the string matcher `Contains` is now `ContainsSubstring`, and custom reporters face a changed interface. 5. Replace `catch_all.hpp` with the headers each file needs, starting from `<catch2/catch_test_macros.hpp>`. Step 5 is where the compile-time win comes from; `catch_all.hpp` alone keeps much of the old cost. ## CMake for the migrated project ```cmake cmake_minimum_required(VERSION 3.16) project(shapes_tests LANGUAGES CXX) find_package(Catch2 3 REQUIRED) add_executable(tests test_area.cpp) target_link_libraries(tests PRIVATE Catch2::Catch2WithMain) add_executable(tests_own_main test_area.cpp test_main.cpp) target_link_libraries(tests_own_main PRIVATE Catch2::Catch2) ``` `Catch2::Catch2WithMain` adds the include paths and links **two** static libraries, the framework and its main. `Catch2::Catch2` alone is for a project that supplies `main`. The same targets exist when Catch2 is added with `add_subdirectory` or `FetchContent`. How `find_package` locates the package is a CMake subject; here the point is which target to name. ## The main that is no longer generated In v2, one file did `#define CATCH_CONFIG_MAIN` before including `catch.hpp`, and that translation unit received a `main`. The v3 release notes state that defining `CATCH_CONFIG_MAIN` no longer creates `main`. A leftover definition is harmless when linking `Catch2WithMain`, but linked against `Catch2` alone the link fails. the macOS linker reported: ```plaintext Undefined symbols for architecture arm64: "_main", referenced from: <initial-undefines> ``` ## Your own main When code must run before or after the tests, link `Catch2::Catch2` and write: ```cpp #include <catch2/catch_session.hpp> int main(int argc, char* argv[]) { // global set-up int result = Catch::Session().run(argc, argv); // global tear-down return result; } ``` `Session` parses the command line and runs the tests, and its return value is the exit code. For set-up alone, the documentation suggests event listeners as a simpler option. ## What breaks during porting | v2 habit | v3 reality | |---|---| | `#include <catch2/catch.hpp>` | file not found; use `catch_all.hpp`, then feature headers | | `#define CATCH_CONFIG_MAIN` | no `main` generated; link `Catch2WithMain` | | `Contains("text")` on a string | `ContainsSubstring`; `Contains` is now the range matcher and fails to compile on a string | | matchers in nested namespaces | all in `Catch::Matchers` | | custom reporter classes | new, documented reporter interface | ## Ordering the work in a large suite 1. Upgrade the dependency and switch the link target first, with `catch_all.hpp` everywhere, so the whole suite compiles and passes before any header work. 2. Fix the renamed matchers and namespaces that the compiler reports; the error points into the matcher headers, so search for the old names rather than reading the diagnostic line by line. 3. Run the suite in the new default random order, which Catch2 3.9.0 introduced, and fix any test that depended on running after another one. 4. Replace `catch_all.hpp` file by file with the specific headers, measuring the build time as you go. 5. Register the tests with CTest through Catch2's discovery script, so CI sees each test case. Each step leaves a green suite behind it, so the migration can stop and resume between releases without a long-lived branch. ## The amalgamated alternative The guide also offers `catch_amalgamated.hpp` and `catch_amalgamated.cpp` from the `extras` directory: one header and one source file added to the test project, with includes rewritten to `"catch_amalgamated.hpp"`. It avoids consuming a library through the build system, at the price of slower compilation, and the project does not consider it the primarily supported option.

  • Why does a migrated Catch2 v3 test that calls Contains on a std::string fail to compile?
    In v3 the string matcher was renamed `ContainsSubstring`, and `Contains` now names the generic range matcher, which checks whether a range holds an element. Applied to a `std::string` with a string argument, it tries to compare each `char` with the argument and fails inside `catch_matchers_contains.hpp`. Renaming the call to `ContainsSubstring` and including `catch_matchers_string.hpp` fixes it.
  • When would you link Catch2::Catch2 instead of Catch2::Catch2WithMain?
    When the test binary needs its own `main`: global set-up and tear-down around the run, adjusting the configuration programmatically, or adding custom command-line options. You then write `main` around `Catch::Session`. Linking `Catch2WithMain` as well does not cause a duplicate-symbol error with these static libraries: in a run with the macOS linker the project's own `main` won and the library's was never pulled in. Linking only `Catch2::Catch2` makes that intent explicit instead of relying on archive resolution.

  • Catch2 v3 is still header-only; just include catch_all.hpp everywhere.
  • Defining CATCH_CONFIG_MAIN in one file still gives a v3 binary its main.
  • Link Catch2::Catch2WithMain even when the project defines its own main.
  • The v2 matcher names all carry over unchanged to v3.
  • Catch2 v3 requires C++17.

Assumes Catch2 3 (checked against 3.16.1): a static library with per-feature headers, the Catch2::Catch2 and Catch2::Catch2WithMain targets, and no main from CATCH_CONFIG_MAIN.