diff options
Diffstat (limited to 'docs/cmake-integration.md')
| -rw-r--r-- | docs/cmake-integration.md | 226 |
1 files changed, 0 insertions, 226 deletions
diff --git a/docs/cmake-integration.md b/docs/cmake-integration.md deleted file mode 100644 index 57073c40..00000000 --- a/docs/cmake-integration.md +++ /dev/null @@ -1,226 +0,0 @@ -<a id="top"></a> -# CMake integration - -**Contents**<br> -[CMake target](#cmake-target)<br> -[Automatic test registration](#automatic-test-registration)<br> -[CMake project options](#cmake-project-options)<br> -[Installing Catch2 from git repository](#installing-catch2-from-git-repository)<br> - -Because we use CMake to build Catch2, we also provide a couple of -integration points for our users. - -1) Catch2 exports a (namespaced) CMake target -2) Catch2's repository contains CMake scripts for automatic registration -of `TEST_CASE`s in CTest - -## CMake target - -Catch2's CMake build exports an interface target `Catch2::Catch2`. Linking -against it will add the proper include path and all necessary capabilities -to the resulting binary. - -This means that if Catch2 has been installed on the system, it should be -enough to do: -```cmake -find_package(Catch2 REQUIRED) -target_link_libraries(tests Catch2::Catch2) -``` - - -This target is also provided when Catch2 is used as a subdirectory. -Assuming that Catch2 has been cloned to `lib/Catch2`: -```cmake -add_subdirectory(lib/Catch2) -target_link_libraries(tests Catch2::Catch2) -``` - -## Automatic test registration - -Catch2's repository also contains two CMake scripts that help users -with automatically registering their `TEST_CASE`s with CTest. They -can be found in the `contrib` folder, and are - -1) `Catch.cmake` (and its dependency `CatchAddTests.cmake`) -2) `ParseAndAddCatchTests.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. - -### `Catch.cmake` and `CatchAddTests.cmake` - -`Catch.cmake` provides function `catch_discover_tests` to get tests from -a target. This function works by running the resulting executable with -`--list-test-names-only` flag, and then parsing the output to find all -existing tests. - -#### Usage -```cmake -cmake_minimum_required(VERSION 3.5) - -project(baz LANGUAGES CXX VERSION 0.0.1) - -find_package(Catch2 REQUIRED) -add_executable(foo test.cpp) -target_link_libraries(foo Catch2::Catch2) - -include(CTest) -include(Catch) -catch_discover_tests(foo) -``` - - -#### Customization -`catch_discover_tests` can be given several extra argumets: -```cmake -catch_discover_tests(target - [TEST_SPEC arg1...] - [EXTRA_ARGS arg1...] - [WORKING_DIRECTORY dir] - [TEST_PREFIX prefix] - [TEST_SUFFIX suffix] - [PROPERTIES name1 value1...] - [TEST_LIST var] -) -``` - -* `TEST_SPEC arg1...` - -Specifies test cases, wildcarded test cases, tags and tag expressions to -pass to the Catch executable alongside the `--list-test-names-only` flag. - - -* `EXTRA_ARGS arg1...` - -Any extra arguments to pass on the command line to each test case. - - -* `WORKING_DIRECTORY dir` - -Specifies the directory in which to run the discovered test cases. If this -option is not provided, the current binary directory is used. - - -* `TEST_PREFIX prefix` - -Specifies a _prefix_ to be added to the name of each discovered test case. -This can be useful when the same test executable is being used in multiple -calls to `catch_discover_tests()`, with different `TEST_SPEC` or `EXTRA_ARGS`. - - -* `TEST_SUFFIX suffix` - -Same as `TEST_PREFIX`, except it specific the _suffix_ for the test names. -Both `TEST_PREFIX` and `TEST_SUFFIX` can be specified at the same time. - - -* `PROPERTIES name1 value1...` - -Specifies additional properties to be set on all tests discovered by this -invocation of `catch_discover_tests`. - - -* `TEST_LIST var` - -Make the list of tests available in the variable `var`, rather than the -default `<target>_TESTS`. This can be useful when the same test -executable is being used in multiple calls to `catch_discover_tests()`. -Note that this variable is only available in CTest. - - -### `ParseAndAddCatchTests.cmake` - -`ParseAndAddCatchTests` works by parsing all implementation files -associated with the provided target, and registering them via CTest's -`add_test`. This approach has some limitations, such as the fact that -commented-out tests will be registered anyway. - - -#### Usage - -```cmake -cmake_minimum_required(VERSION 3.5) - -project(baz LANGUAGES CXX VERSION 0.0.1) - -find_package(Catch2 REQUIRED) -add_executable(foo test.cpp) -target_link_libraries(foo Catch2::Catch2) - -include(CTest) -include(ParseAndAddCatchTests) -ParseAndAddCatchTests(foo) -``` - - -#### Customization - -`ParseAndAddCatchTests` provides some customization points: -* `PARSE_CATCH_TESTS_VERBOSE` -- When `ON`, the script prints debug -messages. Defaults to `OFF`. -* `PARSE_CATCH_TESTS_NO_HIDDEN_TESTS` -- When `ON`, hidden tests (tests -tagged with any of `[!hide]`, `[.]` or `[.foo]`) will not be registered. -Defaults to `OFF`. -* `PARSE_CATCH_TESTS_ADD_FIXTURE_IN_TEST_NAME` -- When `ON`, adds fixture -class name to the test name in CTest. Defaults to `ON`. -* `PARSE_CATCH_TESTS_ADD_TARGET_IN_TEST_NAME` -- When `ON`, adds target -name to the test name in CTest. Defaults to `ON`. -* `PARSE_CATCH_TESTS_ADD_TO_CONFIGURE_DEPENDS` -- When `ON`, adds test -file to `CMAKE_CONFIGURE_DEPENDS`. This means that the CMake configuration -step will be re-ran when the test files change, letting new tests be -automatically discovered. Defaults to `OFF`. - - -Optionally, one can specify a launching command to run tests by setting the -variable `OptionalCatchTestLauncher` before calling `ParseAndAddCatchTests`. For -instance to run some tests using `MPI` and other sequentially, one can write -```cmake -set(OptionalCatchTestLauncher ${MPIEXEC} ${MPIEXEC_NUMPROC_FLAG} ${NUMPROC}) -ParseAndAddCatchTests(mpi_foo) -unset(OptionalCatchTestLauncher) -ParseAndAddCatchTests(bar) -``` - -## CMake project options - -Catch2's CMake project also provides some options for other projects -that consume it. These are - -* `CATCH_BUILD_TESTING` -- When `ON`, Catch2's SelfTest project will be -built. Defaults to `ON`. Note that Catch2 also obeys `BUILD_TESTING` CMake -variable, so _both_ of them need to be `ON` for the SelfTest to be built, -and either of them can be set to `OFF` to disable building SelfTest. -* `CATCH_BUILD_EXAMPLES` -- When `ON`, Catch2's usage examples will be -built. Defaults to `OFF`. -* `CATCH_INSTALL_DOCS` -- When `ON`, Catch2's documentation will be -included in the installation. Defaults to `ON`. -* `CATCH_INSTALL_HELPERS` -- When `ON`, Catch2's contrib folder will be -included in the installation. Defaults to `ON`. -* `BUILD_TESTING` -- When `ON` and the project is not used as a subproject, -Catch2's test binary will be built. Defaults to `ON`. - - -## Installing Catch2 from git repository - -If you cannot install Catch2 from a package manager (e.g. Ubuntu 16.04 -provides catch only in version 1.2.0) you might want to install it from -the repository instead. Assuming you have enough rights, you can just -install it to the default location, like so: -``` -$ git clone https://github.com/catchorg/Catch2.git -$ cd Catch2 -$ cmake -Bbuild -H. -DBUILD_TESTING=OFF -$ sudo cmake --build build/ --target install -``` - -If you do not have superuser rights, you will also need to specify -[CMAKE_INSTALL_PREFIX](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) -when configuring the build, and then modify your calls to -[find_package](https://cmake.org/cmake/help/latest/command/find_package.html) -accordingly. - - ---- - -[Home](Readme.md#top) |