diff --git a/doc/Build.md b/doc/Build.md index 1f7158d..3adaa3f 100644 --- a/doc/Build.md +++ b/doc/Build.md @@ -27,6 +27,8 @@ Building with Xcode or Visual Studio is explained in sections further down. ## How to test +### Executing tests + After building you can run tests from the `build` folder with this command: ctest @@ -50,6 +52,24 @@ The `[filesystem]` tag marks all tests that interact with the filesystem. To exc For more details see the [Catch2 documentation](https://github.com/catchorg/Catch2/blob/devel/docs/command-line.md). + +### Integrating Catch2 into the build + +The libsgfc++ build system integrates Catch2 by way of the CMake commands `find_package()` or `add_subdirectory()`. It attempts to locate the package in two steps: + +1. First the build system looks for a system-wide package in a series of likely installation paths. The search logic is exceedingly complicated and can be looked up in the CMake documentation of the `find_package()` command. +2. If there is no system-wide package the build system then looks for the package in a defined path where it expects to find a Catch2 source distribution. This can be either a Catch2 git repository clone or a a plain directory that is structurally identical to the repository layout. For this the build system uses the `add_subdirectory()` command. + +If both lookup attempts fail, the build fails. + +You can define the source distribution path where the build system should look for the package by defining the variable `CATCH2_SOURCEDISTRIBUTION_PREFIX`: + + cmake -DCMAKE_BUILD_TYPE=Release \ + -DCATCH2_SOURCEDISTRIBUTION_PREFIX=/path/to/folder \ + .. + +If you don't define a source distribution path, the build system assumes `test/Catch2` as the default source distribution path. This path points to the Catch2 Git submodule which you have initialized at the very beginning. + ## How to install After the tests have run successfully you install the build products to a destination folder of your choice. CMake 3.15 and newer include a command line option `--install` which can be used like this: diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt index a40cade..9148ddd 100644 --- a/test/CMakeLists.txt +++ b/test/CMakeLists.txt @@ -22,13 +22,13 @@ if ( ${${CATCH2_PACKAGE_FOUND_VARIABLE_NAME}} ) else() message ( STATUS "System-wide Catch2 CMake package not found." ) - if ( NOT DEFINED CATCH2_GITREPOSITORY_PREFIX ) - message ( STATUS "Using default git repository prefix to find Catch2 CMake package." ) - message ( STATUS "Define CATCH2_GITREPOSITORY_PREFIX to override this." ) + if ( NOT DEFINED CATCH2_SOURCEDISTRIBUTION_PREFIX ) + message ( STATUS "Using default source distribution prefix to find Catch2 CMake package." ) + message ( STATUS "Define CATCH2_SOURCEDISTRIBUTION_PREFIX to override this." ) # A well known path: The Catch2 Git submodule. - set ( CATCH2_GITREPOSITORY_PREFIX "${CMAKE_CURRENT_SOURCE_DIR}/Catch2" ) + set ( CATCH2_SOURCEDISTRIBUTION_PREFIX "${CMAKE_CURRENT_SOURCE_DIR}/Catch2" ) else() - message ( STATUS "Using user-provided git repository prefix to find Catch2 CMake package." ) + message ( STATUS "Using user-provided source distribution prefix to find Catch2 CMake package." ) endif() # Here we expect to find the Catch2 source distribution, either as Catch2 git @@ -37,9 +37,9 @@ else() # add_subdirectory. The advantage over find_package() is that the user does # not need to build/install the Catch2 library separately - Catch2 is simply # built as part of the test project without the need of installation. - message ( STATUS "Adding Catch2 CMake package as sub-directory from ${CATCH2_GITREPOSITORY_PREFIX}." ) + message ( STATUS "Adding Catch2 CMake package as sub-directory from ${CATCH2_SOURCEDISTRIBUTION_PREFIX}." ) add_subdirectory ( - ${CATCH2_GITREPOSITORY_PREFIX} + ${CATCH2_SOURCEDISTRIBUTION_PREFIX} ) endif()