build: Add unit test build control through BUILD_TESTING and YSTDLIB_CPP_BUILD_TESTING flags; Support CTest through Catch2 functions. (#30)

Author: Bill-hbrhbr

.gitignore

@@ -1,3 +1,6 @@
 # Build-related directories and files
 .task
 build
+
+# CTest directories and files
+Testing

CMake/ystdlib-cpp-helpers.cmake

@@ -1,8 +1,8 @@
 # Adds a c++20 interface library in the subdirectory NAME with the target NAME and alias
 # NAMESPACE::NAME. Libraries with multiple levels of namespace nesting are currently not supported.
 #
-# If `BUILD_TESTING` is ON, build the unit tests specific to the current library, and link this
-# library against the unified unit test target for the entire `ystdlib-cpp`.
+# If `YSTDLIB_CPP_ENABLE_TESTS` is ON, builds the unit tests specific to the current library, and
+# links this library against the unified unit test target for the entire `ystdlib-cpp` project.
 #
 # @param NAME
 # @param NAMESPACE
@@ -41,7 +41,8 @@ function(cpp_library)
     target_compile_features(${arg_cpp_lib_NAME} INTERFACE cxx_std_20)
     add_library(${arg_cpp_lib_NAMESPACE}::${arg_cpp_lib_NAME} ALIAS ${arg_cpp_lib_NAME})
 
-    if(BUILD_TESTING)
+    if(YSTDLIB_CPP_ENABLE_TESTS)
+        # Build library-specific unit test target
         set(_UNIT_TEST_TARGET "unit-test-${arg_cpp_lib_NAME}")
         add_executable(${_UNIT_TEST_TARGET})
         target_sources(${_UNIT_TEST_TARGET} PRIVATE ${arg_cpp_lib_TESTS_SOURCES})

CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.16.3)
+cmake_minimum_required(VERSION 3.22.1)
 
 project(YSTDLIB_CPP LANGUAGES CXX)
 
@@ -33,25 +33,32 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS
     FORCE
 )
 
-option(BUILD_TESTING "If ON, unit tests will be built." ON)
-
-# Import CMake helper functions
-list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR}/CMake)
-
-if(PROJECT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
+if(YSTDLIB_CPP_IS_TOP_LEVEL)
     # Include dependency settings if the project isn't being included as a subproject.
     # NOTE: We mark the file optional because if the user happens to have the dependencies
     # installed, this file is not necessary.
     include(build/deps/settings.cmake OPTIONAL)
+
+    # If previously undefined, `BUILD_TESTING` will be set to ON.
+    include(CTest)
 endif()
 
-if(BUILD_TESTING)
+option(YSTDLIB_CPP_BUILD_TESTING "Build the testing tree for ystdlib-cpp." ON)
+if(BUILD_TESTING AND YSTDLIB_CPP_BUILD_TESTING)
+    set(YSTDLIB_CPP_ENABLE_TESTS ON)
+endif()
+
+# Import CMake helper functions
+list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR}/CMake)
+
+if(YSTDLIB_CPP_ENABLE_TESTS)
     find_package(Catch2 3.8.0 REQUIRED)
     if(Catch2_FOUND)
         message(STATUS "Found Catch2 ${Catch2_VERSION}.")
     else()
         message(FATAL_ERROR "Could not find libraries for Catch2.")
     endif()
+    include(Catch)
 
     # Set up the unified unit test target
     set(UNIFIED_UNIT_TEST_TARGET "unit-test-all")
@@ -65,6 +72,7 @@ if(BUILD_TESTING)
             RUNTIME_OUTPUT_DIRECTORY
                 ${CMAKE_BINARY_DIR}/testbin
     )
+    catch_discover_tests(${UNIFIED_UNIT_TEST_TARGET} WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/testbin)
 endif()
 
 include(ystdlib-cpp-helpers)

README.md

@@ -1,10 +1,13 @@
-ystdlib-cpp
-===================================
+# ystdlib-cpp
 An open-source C++ library developed and used at YScope.
 
 # Usage
+
+## Via CMake's add_subdirectory()
 Clone `ystdlib-cpp` into your project. Then, in your project's `CMakeLists.txt`, add the following:
 ```cmake
+# Set `YSTDLIB_CPP_BUILD_TESTING` to an accepted `FALSE` class value to skip building unit tests.
+# option(YSTDLIB_CPP_BUILD_TESTING "" OFF)
 add_subdirectory(/path/to/ystdlib-cpp EXCLUDE_FROM_ALL)
 target_link_libraries(<target_name> <link_options>
     ystdlib::<lib_1> ystdlib::<lib_2> ... ystdlib::<lib_N>
@@ -60,6 +63,10 @@ To build and run unit tests for a specific library:
 task test-<lib_name>
 ```
 
+When generating a testing target, the CMake variable `BUILD_TESTING` is followed (unless overruled
+by setting `YSTDLIB_CPP_BUILD_TESTING` to false). By default, if built as a top-level project,
+`BUILD_TESTING` is set to true and unit tests are built.
+
 ## Linting
 Before submitting a pull request, ensure you’ve run the linting commands below and have fixed all
 violations and suppressed all warnings.