add documentation how to integrate Catch2 into the build

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:

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()