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