Enhance CMake functionality and improve error messaging

- Updated regex handling in cpp_library_setup to correctly escape namespace prefixes when calculating clean names.
- Refined version extraction logic in dependency provider to enforce semantic versioning format.
- Improved error messages in dependency resolution to clarify common issues and provide guidance on correct usage.
- Expanded unit test documentation to reflect the interaction between dependency tracking and custom mappings.

These changes enhance the clarity and robustness of the CMake configuration for the cpp-library.

Author: sean-parent

cmake/cpp-library-dependency-provider.cmake

@@ -62,9 +62,10 @@ function(_cpp_library_track_find_package package_name)
     cmake_parse_arguments(FP "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
 
     # Extract version if present (first unparsed argument that looks like a version)
+    # Pattern requires at least major.minor format (e.g., "1.2", "1.23", "1.2.3")
     set(VERSION "")
     foreach(arg IN LISTS FP_UNPARSED_ARGUMENTS)
-        if(arg MATCHES "^[0-9]+\\.[0-9]")
+        if(arg MATCHES "^[0-9]+\\.[0-9]+")
             set(VERSION "${arg}")
             break()
         endif()

cmake/cpp-library-install.cmake

@@ -140,12 +140,18 @@ function(_cpp_library_resolve_dependency LIB NAMESPACE OUTPUT_VAR)
                     # Provider is installed but dependency wasn't tracked
                     message(FATAL_ERROR 
                         "cpp-library: Dependency ${LIB} (package: ${FIND_PACKAGE_NAME}) was not tracked.\n"
-                        "This may happen if:\n"
-                        "  - The dependency was added after cpp_library_setup()\n"
-                        "  - The dependency was added in a subdirectory\n"
                         "\n"
-                        "Make sure all CPMAddPackage() and find_package() calls happen AFTER project()\n"
-                        "and BEFORE cpp_library_setup().\n"
+                        "The dependency provider is installed, but this dependency was not captured.\n"
+                        "Common causes:\n"
+                        "  - find_package() or CPMAddPackage() was called AFTER cpp_library_setup()\n"
+                        "  - Dependency was added in a subdirectory with separate scope\n"
+                        "\n"
+                        "Solution: Ensure all dependencies are declared AFTER project() and BEFORE cpp_library_setup().\n"
+                        "\n"
+                        "Correct order:\n"
+                        "    project(my-library)\n"
+                        "    find_package(SomePackage)  # or CPMAddPackage(...)\n"
+                        "    cpp_library_setup(...)     # Must come after all dependencies\n"
                     )
                 endif()
             endif()
@@ -186,9 +192,9 @@ function(_cpp_library_add_dependency FIND_DEP_ARGS)
         set(REMAINING_ARGS "")
     endif()
 
-    # Extract version (first token that looks like a version number)
+    # Extract version (first token that looks like a semantic version number: major.minor[.patch]...)
     set(VERSION "")
-    if(REMAINING_ARGS MATCHES "^([0-9][0-9.]*)")
+    if(REMAINING_ARGS MATCHES "^([0-9]+\\.[0-9]+(?:\\.[0-9]+)*)")
         set(VERSION "${CMAKE_MATCH_1}")
         # Remove version from args - use substring to avoid regex issues with dots
         string(LENGTH "${VERSION}" VERSION_LEN)

cpp-library.cmake

@@ -170,7 +170,8 @@ function(cpp_library_setup)
 
     # Calculate clean name (without namespace prefix) for target alias
     # If PROJECT_NAME starts with NAMESPACE-, strip it; otherwise use PROJECT_NAME as-is
-    string(REGEX REPLACE "^${ARG_NAMESPACE}-" "" CLEAN_NAME "${ARG_NAME}")
+    string(REGEX ESCAPE "${ARG_NAMESPACE}" ESCAPED_NAMESPACE)
+    string(REGEX REPLACE "^${ESCAPED_NAMESPACE}-" "" CLEAN_NAME "${ARG_NAME}")
 
     # Always prefix package name with namespace for collision prevention
     # Special case: if namespace equals clean name, don't duplicate (e.g., stlab::stlab → stlab)

templates/.github/workflows/ci.yml.in

@@ -119,8 +119,9 @@ jobs:
     steps:
       - uses: actions/checkout@v5
 
+      # ssciwr/doxygen-install@1.6.4
       - name: Install Doxygen
-        uses: ssciwr/doxygen-install@v1
+        uses: ssciwr/doxygen-install@501e53b879da7648ab392ee226f5b90e42148449
 
       - name: Configure CMake
         run: cmake --preset=docs

tests/install/test_dependency_provider.cmake

@@ -1,8 +1,9 @@
 # SPDX-License-Identifier: BSL-1.0
 #
-# Unit tests for dependency provider tracking
-# These tests verify that the dependency provider correctly tracks dependencies
-
+# Unit tests for dependency provider tracking and its interaction with dependency mapping
+# These tests verify that the dependency provider correctly tracks dependencies and that
+# tracked dependencies interact properly with custom mappings and system packages.
+#
 # Note: We can't actually test the provider installation itself in these unit tests
 # since that requires being called during project(). Instead, we test the tracking
 # functions directly and simulate tracked dependencies.