1<a id="top"></a> 2# CMake integration 3 4**Contents**<br> 5[CMake target](#cmake-target)<br> 6[Automatic test registration](#automatic-test-registration)<br> 7[CMake project options](#cmake-project-options)<br> 8[Installing Catch2 from git repository](#installing-catch2-from-git-repository)<br> 9 10Because we use CMake to build Catch2, we also provide a couple of 11integration points for our users. 12 131) Catch2 exports a (namespaced) CMake target 142) Catch2's repository contains CMake scripts for automatic registration 15of `TEST_CASE`s in CTest 16 17## CMake target 18 19Catch2's CMake build exports an interface target `Catch2::Catch2`. Linking 20against it will add the proper include path and all necessary capabilities 21to the resulting binary. 22 23This means that if Catch2 has been installed on the system, it should be 24enough to do: 25```cmake 26find_package(Catch2 REQUIRED) 27target_link_libraries(tests Catch2::Catch2) 28``` 29 30 31This target is also provided when Catch2 is used as a subdirectory. 32Assuming that Catch2 has been cloned to `lib/Catch2`: 33```cmake 34add_subdirectory(lib/Catch2) 35target_link_libraries(tests Catch2::Catch2) 36``` 37 38## Automatic test registration 39 40Catch2's repository also contains two CMake scripts that help users 41with automatically registering their `TEST_CASE`s with CTest. They 42can be found in the `contrib` folder, and are 43 441) `Catch.cmake` (and its dependency `CatchAddTests.cmake`) 452) `ParseAndAddCatchTests.cmake` 46 47If Catch2 has been installed in system, both of these can be used after 48doing `find_package(Catch2 REQUIRED)`. Otherwise you need to add them 49to your CMake module path. 50 51### `Catch.cmake` and `CatchAddTests.cmake` 52 53`Catch.cmake` provides function `catch_discover_tests` to get tests from 54a target. This function works by running the resulting executable with 55`--list-test-names-only` flag, and then parsing the output to find all 56existing tests. 57 58#### Usage 59```cmake 60cmake_minimum_required(VERSION 3.5) 61 62project(baz LANGUAGES CXX VERSION 0.0.1) 63 64find_package(Catch2 REQUIRED) 65add_executable(foo test.cpp) 66target_link_libraries(foo Catch2::Catch2) 67 68include(CTest) 69include(Catch) 70catch_discover_tests(foo) 71``` 72 73 74#### Customization 75`catch_discover_tests` can be given several extra argumets: 76```cmake 77catch_discover_tests(target 78 [TEST_SPEC arg1...] 79 [EXTRA_ARGS arg1...] 80 [WORKING_DIRECTORY dir] 81 [TEST_PREFIX prefix] 82 [TEST_SUFFIX suffix] 83 [PROPERTIES name1 value1...] 84 [TEST_LIST var] 85) 86``` 87 88* `TEST_SPEC arg1...` 89 90Specifies test cases, wildcarded test cases, tags and tag expressions to 91pass to the Catch executable alongside the `--list-test-names-only` flag. 92 93 94* `EXTRA_ARGS arg1...` 95 96Any extra arguments to pass on the command line to each test case. 97 98 99* `WORKING_DIRECTORY dir` 100 101Specifies the directory in which to run the discovered test cases. If this 102option is not provided, the current binary directory is used. 103 104 105* `TEST_PREFIX prefix` 106 107Specifies a _prefix_ to be added to the name of each discovered test case. 108This can be useful when the same test executable is being used in multiple 109calls to `catch_discover_tests()`, with different `TEST_SPEC` or `EXTRA_ARGS`. 110 111 112* `TEST_SUFFIX suffix` 113 114Same as `TEST_PREFIX`, except it specific the _suffix_ for the test names. 115Both `TEST_PREFIX` and `TEST_SUFFIX` can be specified at the same time. 116 117 118* `PROPERTIES name1 value1...` 119 120Specifies additional properties to be set on all tests discovered by this 121invocation of `catch_discover_tests`. 122 123 124* `TEST_LIST var` 125 126Make the list of tests available in the variable `var`, rather than the 127default `<target>_TESTS`. This can be useful when the same test 128executable is being used in multiple calls to `catch_discover_tests()`. 129Note that this variable is only available in CTest. 130 131 132### `ParseAndAddCatchTests.cmake` 133 134`ParseAndAddCatchTests` works by parsing all implementation files 135associated with the provided target, and registering them via CTest's 136`add_test`. This approach has some limitations, such as the fact that 137commented-out tests will be registered anyway. 138 139 140#### Usage 141 142```cmake 143cmake_minimum_required(VERSION 3.5) 144 145project(baz LANGUAGES CXX VERSION 0.0.1) 146 147find_package(Catch2 REQUIRED) 148add_executable(foo test.cpp) 149target_link_libraries(foo Catch2::Catch2) 150 151include(CTest) 152include(ParseAndAddCatchTests) 153ParseAndAddCatchTests(foo) 154``` 155 156 157#### Customization 158 159`ParseAndAddCatchTests` provides some customization points: 160* `PARSE_CATCH_TESTS_VERBOSE` -- When `ON`, the script prints debug 161messages. Defaults to `OFF`. 162* `PARSE_CATCH_TESTS_NO_HIDDEN_TESTS` -- When `ON`, hidden tests (tests 163tagged with any of `[!hide]`, `[.]` or `[.foo]`) will not be registered. 164Defaults to `OFF`. 165* `PARSE_CATCH_TESTS_ADD_FIXTURE_IN_TEST_NAME` -- When `ON`, adds fixture 166class name to the test name in CTest. Defaults to `ON`. 167* `PARSE_CATCH_TESTS_ADD_TARGET_IN_TEST_NAME` -- When `ON`, adds target 168name to the test name in CTest. Defaults to `ON`. 169* `PARSE_CATCH_TESTS_ADD_TO_CONFIGURE_DEPENDS` -- When `ON`, adds test 170file to `CMAKE_CONFIGURE_DEPENDS`. This means that the CMake configuration 171step will be re-ran when the test files change, letting new tests be 172automatically discovered. Defaults to `OFF`. 173 174 175Optionally, one can specify a launching command to run tests by setting the 176variable `OptionalCatchTestLauncher` before calling `ParseAndAddCatchTests`. For 177instance to run some tests using `MPI` and other sequentially, one can write 178```cmake 179set(OptionalCatchTestLauncher ${MPIEXEC} ${MPIEXEC_NUMPROC_FLAG} ${NUMPROC}) 180ParseAndAddCatchTests(mpi_foo) 181unset(OptionalCatchTestLauncher) 182ParseAndAddCatchTests(bar) 183``` 184 185## CMake project options 186 187Catch2's CMake project also provides some options for other projects 188that consume it. These are 189 190* `CATCH_BUILD_TESTING` -- When `ON`, Catch2's SelfTest project will be 191built. Defaults to `ON`. Note that Catch2 also obeys `BUILD_TESTING` CMake 192variable, so _both_ of them need to be `ON` for the SelfTest to be built, 193and either of them can be set to `OFF` to disable building SelfTest. 194* `CATCH_BUILD_EXAMPLES` -- When `ON`, Catch2's usage examples will be 195built. Defaults to `OFF`. 196* `CATCH_INSTALL_DOCS` -- When `ON`, Catch2's documentation will be 197included in the installation. Defaults to `ON`. 198* `CATCH_INSTALL_HELPERS` -- When `ON`, Catch2's contrib folder will be 199included in the installation. Defaults to `ON`. 200* `BUILD_TESTING` -- When `ON` and the project is not used as a subproject, 201Catch2's test binary will be built. Defaults to `ON`. 202 203 204## Installing Catch2 from git repository 205 206If you cannot install Catch2 from a package manager (e.g. Ubuntu 16.04 207provides catch only in version 1.2.0) you might want to install it from 208the repository instead. Assuming you have enough rights, you can just 209install it to the default location, like so: 210``` 211$ git clone https://github.com/catchorg/Catch2.git 212$ cd Catch2 213$ cmake -Bbuild -H. -DBUILD_TESTING=OFF 214$ sudo cmake --build build/ --target install 215``` 216 217If you do not have superuser rights, you will also need to specify 218[CMAKE_INSTALL_PREFIX](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) 219when configuring the build, and then modify your calls to 220[find_package](https://cmake.org/cmake/help/latest/command/find_package.html) 221accordingly. 222 223 224--- 225 226[Home](Readme.md#top) 227