feat(cmake): Enhance cpp_library() with argument validation, test-only linking, and improved docstrings.

CMake/ystdlib-cpp-helpers.cmake

@@ -1,6 +1,17 @@
-# @param SOURCE_LIST The list of source files to check.
-# @param IS_HEADER_ONLY Returns whether the list only contains header files.
-# @param NON_HEADER_FILE Returns the name of the first, if any, non-header file.
+# @param {string[]} REQUIRED_ARGS The list of arguments to check.
+# @param {string[]} ARG_KEYWORDS_MISSING_VALUES The list of arguments with missing values.
+# @param {string} LIB_NAME The library target on which to perform the check.
+function(require_argument_values REQUIRED_ARGS ARG_KEYWORDS_MISSING_VALUES LIB_NAME)
+    foreach(arg IN LISTS REQUIRED_ARGS)
+        if("${arg}" IN_LIST ARG_KEYWORDS_MISSING_VALUES)
+            message(FATAL_ERROR "Missing values for argument '${arg}' in target '${LIB_NAME}'.")
+        endif()
+    endforeach()
+endfunction()
+
+# @param {string[]} SOURCE_LIST The list of source files to check.
+# @param {bool} IS_HEADER_ONLY Returns whether the list only contains header files.
+# @param {string} NON_HEADER_FILE Returns the name of the first, if any, non-header file.
 function(check_if_header_only SOURCE_LIST IS_HEADER_ONLY NON_HEADER_FILE)
     set(_LOCAL_SOURCE_LIST "${${SOURCE_LIST}}")
     foreach(src_file IN LISTS _LOCAL_SOURCE_LIST)
@@ -20,16 +31,17 @@ endfunction()
 # 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
-# @param PUBLIC_HEADERS
-# @param PRIVATE_SOURCES
-# @param PUBLIC_LINK_LIBRARIES
-# @param PRIVATE_LINK_LIBRARIES
-# @parms TESTS_SOURCES
-# @param [BUILD_INCLUDE_DIR="${PROJECT_SOURCE_DIR}/src"] The list of include paths for building the
-# library and for external projects that builds `ystdlib-cpp` as a CMAKE subproject via the
-# add_subdirectory() function.
+# @param {string} NAME
+# @param {string} NAMESPACE
+# @param {string[]} PUBLIC_HEADERS
+# @parms {string[]} TESTS_SOURCES
+# @param {string[]} [PRIVATE_SOURCES]
+# @param {string[]} [PUBLIC_LINK_LIBRARIES]
+# @param {string[]} [PRIVATE_LINK_LIBRARIES]
+# @parms {string[]} [TESTS_LINK_LIBRARIES]
+# @param {string[]} [BUILD_INCLUDE_DIR="${PROJECT_SOURCE_DIR}/src"] The list of include paths for
+# building the library and for external projects that builds `ystdlib-cpp` as a CMAKE subproject via
+# the add_subdirectory() function.
 function(cpp_library)
     set(options "")
     set(oneValueArgs
@@ -42,16 +54,27 @@ function(cpp_library)
         PUBLIC_LINK_LIBRARIES
         PRIVATE_LINK_LIBRARIES
         TESTS_SOURCES
+        TESTS_LINK_LIBRARIES
+        BUILD_INCLUDE_DIR
+    )
+    set(requireValueArgs
+        NAME
+        NAMESPACE
+        PUBLIC_HEADERS
+        TESTS_SOURCES
         BUILD_INCLUDE_DIR
     )
     cmake_parse_arguments(arg_cpp_lib "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
 
     set(_ALIAS_TARGET_NAME "${arg_cpp_lib_NAMESPACE}::${arg_cpp_lib_NAME}")
 
-    # TODO: Turn this into a function for handling other optional params that have default values.
-    if("BUILD_INCLUDE_DIR" IN_LIST arg_cpp_lib_KEYWORDS_MISSING_VALUES)
-        message(FATAL_ERROR "Missing build interface list for ${_ALIAS_TARGET_NAME}.")
-    elseif(NOT DEFINED arg_cpp_lib_BUILD_INCLUDE_DIR)
+    require_argument_values(
+        "${requireValueArgs}"
+        "${arg_cpp_lib_KEYWORDS_MISSING_VALUES}"
+        "${_ALIAS_TARGET_NAME}"
+    )
+
+    if(NOT DEFINED arg_cpp_lib_BUILD_INCLUDE_DIR)
         set(arg_cpp_lib_BUILD_INCLUDE_DIR "${PROJECT_SOURCE_DIR}/src")
     endif()
 
@@ -109,6 +132,7 @@ function(cpp_library)
             PRIVATE
                 Catch2::Catch2WithMain
                 ${_ALIAS_TARGET_NAME}
+                ${arg_cpp_lib_TESTS_LINK_LIBRARIES}
         )
         target_compile_features(${_UNIT_TEST_TARGET} PRIVATE cxx_std_20)
         set_property(
@@ -121,6 +145,11 @@ function(cpp_library)
 
         # Link against unified unit test
         target_sources(${UNIFIED_UNIT_TEST_TARGET} PRIVATE ${arg_cpp_lib_TESTS_SOURCES})
-        target_link_libraries(${UNIFIED_UNIT_TEST_TARGET} PRIVATE ${_ALIAS_TARGET_NAME})
+        target_link_libraries(
+            ${UNIFIED_UNIT_TEST_TARGET}
+            PRIVATE
+                ${_ALIAS_TARGET_NAME}
+                ${arg_cpp_lib_TESTS_LINK_LIBRARIES}
+        )
     endif()
 endfunction()