Improve dependency mapping and version override support

Updated dependency mapping logic to distinguish between internal cpp-library and external dependencies, ensuring package names are collision-safe and consistent. Added support for overriding the version using the CPP_LIBRARY_VERSION variable, which is useful for package managers and CI systems without git history. Improved documentation in README.md to clarify dependency handling, target naming patterns, and version management. Refactored CMake scripts to align with these changes and updated comments for clarity.

Author: sean-parent

README.md

@@ -149,17 +149,22 @@ When installed, the generated `my-libConfig.cmake` will include:
 include(CMakeFindDependencyMacro)
 
 # Find dependencies required by this package
-find_dependency(copy-on-write)
-find_dependency(enum-ops)
+find_dependency(stlab-copy-on-write)
+find_dependency(stlab-enum-ops)
 find_dependency(Threads)
 
 include("${CMAKE_CURRENT_LIST_DIR}/my-libTargets.cmake")
 ```
 
 **Default dependency handling:**
 
-- **cpp-library dependencies** (matching your project's `NAMESPACE`): Automatically mapped to their package names (e.g., `stlab::copy-on-write` → `find_dependency(copy-on-write)`)
-- **Other packages**: Uses the package name only by default (e.g., `PackageName::Target` → `find_dependency(PackageName)`)
+- **cpp-library dependencies** (matching your project's `NAMESPACE`):
+  - When namespace and component match: `namespace::namespace` → `find_dependency(namespace)`
+  - When they differ: `namespace::component` → `find_dependency(namespace-component)`
+  - Example: `stlab::copy-on-write` → `find_dependency(stlab-copy-on-write)`
+- **Other packages**: Uses the package name only by default
+  - Example: `Threads::Threads` → `find_dependency(Threads)`
+  - Example: `Boost::filesystem` → `find_dependency(Boost)`
 
 **Custom dependency mappings:**
 
@@ -222,6 +227,8 @@ git push origin v1.0.0
 
 Tags should follow [semantic versioning](https://semver.org/) (e.g., `v1.0.0`, `v2.1.3`).
 
+Alternatively, you can override the version using `-DCPP_LIBRARY_VERSION=x.y.z` (useful for package managers). See [Version Management](#version-management) for details.
+
 #### GitHub Pages Deployment
 
 To enable automatic documentation deployment to GitHub Pages:
@@ -257,30 +264,52 @@ cpp_library_setup(
 **Notes:**
 
 - The project name is automatically taken from `PROJECT_NAME` (set by the `project()` command). You must call `project(your-library)` before `cpp_library_setup()`.
-- Version is automatically detected from git tags (see [Version Tagging](#version-tagging)).
+- Version is automatically detected from git tags, or can be overridden with `-DCPP_LIBRARY_VERSION=x.y.z` (see [Version Management](#version-management)).
 - Examples using doctest should include `test` in the filename to be visible in the [C++ TestMate](https://marketplace.visualstudio.com/items?itemName=matepek.vscode-catch2-test-adapter) extension for VS Code test explorer.
 
 ### Target Naming
 
-For `project(your-library)`, `cpp_library_setup` will create a target called `your-library`.
-
-The utility will additionally create an alias target based on the `NAMESPACE` option: `your_namespace::your-library`.
+**Recommended Pattern** (collision-safe):
 
-If your project name starts with the namespace followed by a dash, the namespace in the project name is stripped from the alias target:
+Use the component name as your project name, and specify the organizational namespace separately:
 
 ```cmake
-cmake_minimum_required(VERSION 3.20)
-project(namespace-library)
+project(enum-ops)  # Component name only
+
+cpp_library_setup(
+    NAMESPACE stlab  # Organizational namespace
+    # ...
+)
+```
+
+This produces:
+
+- Target name: `enum-ops`
+- Package name: `stlab-enum-ops` (used in `find_package(stlab-enum-ops)`)
+- Target alias: `stlab::enum-ops` (used in `target_link_libraries()`)
+
+**Alternative Patterns:**
 
-# ... CPM setup ...
+You can also use `project(namespace-component)` - the namespace prefix will be detected and stripped from the target alias:
+
+```cmake
+project(stlab-enum-ops)  # Includes namespace prefix
 
 cpp_library_setup(
-    NAMESPACE namespace
+    NAMESPACE stlab
     # ...
 )
 ```
 
-Results in `namespace-library` and `namespace::library` targets.
+Produces the same result as above.
+
+**Single-component namespace** (e.g., `project(stlab)` with `NAMESPACE stlab`):
+
+- Target name: `stlab`
+- Package name: `stlab` (used in `find_package(stlab)`)
+- Target alias: `stlab::stlab` (used in `target_link_libraries()`)
+
+All package names include the namespace prefix for collision prevention.
 
 ### `cpp_library_map_dependency`
 
@@ -380,6 +409,15 @@ Version is automatically detected from git tags:
 - Falls back to `0.0.0` if no tag is found (with warning)
 - Version used in CMake package config files
 
+For package managers or CI systems building from source archives without git history, you can override the version using the `CPP_LIBRARY_VERSION` cache variable:
+
+```bash
+cmake -DCPP_LIBRARY_VERSION=1.2.3 -B build
+cmake --build build
+```
+
+This is particularly useful for vcpkg, Conan, or other package managers that don't have access to git tags.
+
 ### Testing
 
 - **Test framework**: [doctest](https://github.com/doctest/doctest)

cmake/cpp-library-install.cmake

@@ -16,6 +16,7 @@ include(CMakePackageConfigHelpers)
 # - Precondition: TARGET is a namespaced target (e.g., "Qt5::Core", "Qt5::Widgets")
 # - Postcondition: FIND_DEPENDENCY_CALL stored for TARGET, used in package config generation
 # - Example: cpp_library_map_dependency("Qt5::Core" "Qt5 COMPONENTS Core")
+# - Note: Most dependencies work automatically; only use for special syntax (COMPONENTS, etc.)
 function(cpp_library_map_dependency TARGET FIND_DEPENDENCY_CALL)
     set_property(GLOBAL PROPERTY _CPP_LIBRARY_DEPENDENCY_MAP_${TARGET} "${FIND_DEPENDENCY_CALL}")
 endfunction()
@@ -24,7 +25,8 @@ endfunction()
 # - Precondition: TARGET_NAME specifies existing target with INTERFACE_LINK_LIBRARIES
 # - Postcondition: OUTPUT_VAR contains newline-separated find_dependency() calls for public dependencies
 # - Uses cpp_library_map_dependency() mappings if registered, otherwise uses defaults
-# - Automatically handles cpp-library dependencies (namespace::package → find_dependency(package))
+# - cpp-library dependencies: namespace::namespace → find_dependency(namespace), namespace::component → find_dependency(namespace-component)
+# - External dependencies: name::name → find_dependency(name), name::component → find_dependency(name)
 function(_cpp_library_generate_dependencies OUTPUT_VAR TARGET_NAME NAMESPACE)
     get_target_property(LINK_LIBS ${TARGET_NAME} INTERFACE_LINK_LIBRARIES)
 
@@ -53,11 +55,17 @@ function(_cpp_library_generate_dependencies OUTPUT_VAR TARGET_NAME NAMESPACE)
                 # Use custom mapping (e.g., "Qt5 COMPONENTS Core" for Qt5::Core)
                 list(APPEND DEPENDENCY_LIST "find_dependency(${CUSTOM_MAPPING})")
             elseif(PKG_NAME STREQUAL NAMESPACE)
-                # Internal cpp-library dependency: use component as package name
-                # (e.g., stlab::copy-on-write → find_dependency(copy-on-write))
-                list(APPEND DEPENDENCY_LIST "find_dependency(${COMPONENT})")
+                # Internal cpp-library dependency
+                if(PKG_NAME STREQUAL COMPONENT)
+                    # Namespace and component match: namespace::namespace → find_dependency(namespace)
+                    list(APPEND DEPENDENCY_LIST "find_dependency(${PKG_NAME})")
+                else()
+                    # Different names: namespace::component → find_dependency(namespace-component)
+                    list(APPEND DEPENDENCY_LIST "find_dependency(${PKG_NAME}-${COMPONENT})")
+                endif()
             else()
-                # Default: use package name only (e.g., libdispatch::libdispatch → find_dependency(libdispatch))
+                # External dependency: use package name only
+                # (e.g., Threads::Threads → find_dependency(Threads), Boost::filesystem → find_dependency(Boost))
                 list(APPEND DEPENDENCY_LIST "find_dependency(${PKG_NAME})")
             endif()
         endif()
@@ -81,7 +89,7 @@ endfunction()
 function(_cpp_library_setup_install)
     set(oneValueArgs
         NAME            # Target name (e.g., "stlab-enum-ops")
-        PACKAGE_NAME    # Package name for find_package() (e.g., "enum-ops")
+        PACKAGE_NAME    # Package name for find_package() (e.g., "stlab-enum-ops")
         VERSION         # Version string (e.g., "1.2.3")
         NAMESPACE       # Namespace for alias (e.g., "stlab")
     )

cmake/cpp-library-setup.cmake

@@ -2,13 +2,13 @@
 #
 # cpp-library-setup.cmake - Core library setup functionality
 
-# Returns version string from PROJECT_VERSION (if set), git tag (with 'v' prefix removed), or 
+# Returns version string from CPP_LIBRARY_VERSION cache variable (if set), git tag (with 'v' prefix removed), or 
 #    "0.0.0" fallback
 function(_cpp_library_get_git_version OUTPUT_VAR)
-    # If PROJECT_VERSION is already set (e.g., by vcpkg or other package manager),
+    # If CPP_LIBRARY_VERSION is set (e.g., by vcpkg or other package manager via -DCPP_LIBRARY_VERSION=x.y.z),
     # use it instead of trying to query git (which may not be available in source archives)
-    if(DEFINED PROJECT_VERSION AND NOT PROJECT_VERSION STREQUAL "")
-        set(${OUTPUT_VAR} "${PROJECT_VERSION}" PARENT_SCOPE)
+    if(DEFINED CPP_LIBRARY_VERSION AND NOT CPP_LIBRARY_VERSION STREQUAL "")
+        set(${OUTPUT_VAR} "${CPP_LIBRARY_VERSION}" PARENT_SCOPE)
         return()
     endif()
 
@@ -33,15 +33,16 @@ function(_cpp_library_get_git_version OUTPUT_VAR)
 endfunction()
 
 # Creates library target (INTERFACE or compiled) with headers and proper configuration.
-# - Precondition: NAME, NAMESPACE, PACKAGE_NAME, and REQUIRES_CPP_VERSION specified
-# - Postcondition: library target created with alias NAMESPACE::PACKAGE_NAME, install configured if TOP_LEVEL
+# - Precondition: NAME, NAMESPACE, PACKAGE_NAME, CLEAN_NAME, and REQUIRES_CPP_VERSION specified
+# - Postcondition: library target created with alias NAMESPACE::CLEAN_NAME, install configured if TOP_LEVEL
 function(_cpp_library_setup_core)
     set(oneValueArgs
         NAME
         VERSION
         DESCRIPTION
         NAMESPACE
         PACKAGE_NAME
+        CLEAN_NAME
         REQUIRES_CPP_VERSION
         TOP_LEVEL
     )
@@ -64,7 +65,7 @@ function(_cpp_library_setup_core)
     if(ARG_SOURCES)
         # Create a library with sources (respects BUILD_SHARED_LIBS variable)
         add_library(${ARG_NAME} ${ARG_SOURCES})
-        add_library(${ARG_NAMESPACE}::${ARG_PACKAGE_NAME} ALIAS ${ARG_NAME})
+        add_library(${ARG_NAMESPACE}::${ARG_CLEAN_NAME} ALIAS ${ARG_NAME})
         target_include_directories(${ARG_NAME} PUBLIC
             $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
             $<INSTALL_INTERFACE:include>
@@ -81,7 +82,7 @@ function(_cpp_library_setup_core)
     else()
         # Header-only INTERFACE target
         add_library(${ARG_NAME} INTERFACE)
-        add_library(${ARG_NAMESPACE}::${ARG_PACKAGE_NAME} ALIAS ${ARG_NAME})
+        add_library(${ARG_NAMESPACE}::${ARG_CLEAN_NAME} ALIAS ${ARG_NAME})
         target_include_directories(${ARG_NAME} INTERFACE
             $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
             $<INSTALL_INTERFACE:include>

cpp-library.cmake

@@ -34,8 +34,8 @@ function(_cpp_library_setup_executables)
 
     cmake_parse_arguments(ARG "" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
 
-    # Extract the clean library name for linking
-    string(REPLACE "${ARG_NAMESPACE}-" "" CLEAN_NAME "${ARG_NAME}")
+    # Extract the clean library name for linking (strip namespace prefix if present)
+    string(REGEX REPLACE "^${ARG_NAMESPACE}-" "" CLEAN_NAME "${ARG_NAME}")
 
     # Download doctest dependency via CPM
     if(NOT TARGET doctest::doctest)
@@ -140,8 +140,17 @@ function(cpp_library_setup)
     endif()
     set(ARG_NAME "${PROJECT_NAME}")
 
-    # Calculate PACKAGE_NAME (clean name without namespace prefix) for template substitution
-    string(REPLACE "${ARG_NAMESPACE}-" "" PACKAGE_NAME "${ARG_NAME}")
+    # 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}")
+    
+    # Always prefix package name with namespace for collision prevention
+    # Special case: if namespace equals clean name, don't duplicate (e.g., stlab::stlab → stlab)
+    if(ARG_NAMESPACE STREQUAL CLEAN_NAME)
+        set(PACKAGE_NAME "${ARG_NAMESPACE}")
+    else()
+        set(PACKAGE_NAME "${ARG_NAMESPACE}-${CLEAN_NAME}")
+    endif()
 
     # Set defaults
     if(NOT ARG_REQUIRES_CPP_VERSION)
@@ -188,6 +197,7 @@ function(cpp_library_setup)
         DESCRIPTION "${ARG_DESCRIPTION}"
         NAMESPACE "${ARG_NAMESPACE}"
         PACKAGE_NAME "${PACKAGE_NAME}"
+        CLEAN_NAME "${CLEAN_NAME}"
         HEADERS "${GENERATED_HEADERS}"
         SOURCES "${GENERATED_SOURCES}"
         REQUIRES_CPP_VERSION "${ARG_REQUIRES_CPP_VERSION}"