Add custom dependency mapping for CMake package generation

Introduces the cpp_library_map_dependency() function to allow custom find_dependency() calls for specific targets, such as Qt components requiring COMPONENTS syntax. Updates documentation and dependency generation logic to prioritize custom mappings, improving flexibility for complex dependencies in installed CMake package config files.

Author: sean-parent

README.md

@@ -156,12 +156,35 @@ find_dependency(Threads)
 include("${CMAKE_CURRENT_LIST_DIR}/my-libTargets.cmake")
 ```
 
-**Supported dependency patterns:**
+**Default dependency handling:**
 
-- **CPM/Internal dependencies** (`namespace::target`): Automatically mapped to their package names (e.g., `stlab::copy-on-write` → `find_dependency(copy-on-write)`)
-- **Threading** (`Threads::Threads`): Generates `find_dependency(Threads)`
-- **Qt libraries** (`Qt5::Core`, `Qt6::Widgets`): Generates `find_dependency(Qt5 COMPONENTS Core)` with proper components
-- **Generic packages** (`PackageName::Target`): Generates `find_dependency(PackageName)`
+- **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)`)
+
+**Custom dependency mappings:**
+
+For dependencies that require special `find_dependency()` syntax (e.g., Qt with COMPONENTS), use `cpp_library_map_dependency()` to specify the exact call:
+
+```cmake
+# Map Qt components to use COMPONENTS syntax
+cpp_library_map_dependency("Qt5::Core" "Qt5 COMPONENTS Core")
+cpp_library_map_dependency("Qt5::Widgets" "Qt5 COMPONENTS Widgets")
+
+# Then link as usual
+target_link_libraries(my-lib INTERFACE
+    Qt5::Core
+    Qt5::Widgets
+    Threads::Threads  # Works automatically, no mapping needed
+)
+```
+
+The generated config file will use your custom mappings where specified:
+
+```cmake
+find_dependency(Qt5 COMPONENTS Core)
+find_dependency(Qt5 COMPONENTS Widgets)
+find_dependency(Threads)  # Automatic from Threads::Threads
+```
 
 ### Updating cpp-library
 
@@ -259,6 +282,44 @@ cpp_library_setup(
 
 Results in `namespace-library` and `namespace::library` targets.
 
+### `cpp_library_map_dependency`
+
+```cmake
+cpp_library_map_dependency(target find_dependency_call)
+```
+
+Registers a custom dependency mapping for `find_dependency()` generation in installed CMake package config files.
+
+**Parameters:**
+
+- `target`: The namespaced target (e.g., `"Qt5::Core"`, `"Threads::Threads"`)
+- `find_dependency_call`: The exact arguments to pass to `find_dependency()` (e.g., `"Qt5 COMPONENTS Core"`, `"Threads"`)
+
+**When to use:**
+
+- Dependencies requiring `COMPONENTS` syntax (e.g., Qt)
+- Dependencies requiring `OPTIONAL_COMPONENTS` or other special arguments
+- Dependencies where the target name pattern doesn't match the desired `find_dependency()` call
+
+**Note:** Most common dependencies like `Threads::Threads`, `Boost::filesystem`, etc. work automatically with the default behavior and don't need mapping.
+
+**Example:**
+
+```cmake
+# Register mappings for dependencies needing special syntax
+cpp_library_map_dependency("Qt5::Core" "Qt5 COMPONENTS Core")
+cpp_library_map_dependency("Qt5::Widgets" "Qt5 COMPONENTS Widgets")
+
+# Then link normally
+target_link_libraries(my-target INTERFACE
+    Qt5::Core
+    Qt5::Widgets
+    Threads::Threads  # No mapping needed
+)
+```
+
+See [Dependency Handling in Installed Packages](#dependency-handling-in-installed-packages) for more details.
+
 ### Path Conventions
 
 The template uses consistent path conventions for all file specifications:

cmake/cpp-library-install.cmake

@@ -12,10 +12,19 @@
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)
 
+# Registers a custom dependency mapping for find_dependency() generation
+# - 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")
+function(cpp_library_map_dependency TARGET FIND_DEPENDENCY_CALL)
+    set_property(GLOBAL PROPERTY _CPP_LIBRARY_DEPENDENCY_MAP_${TARGET} "${FIND_DEPENDENCY_CALL}")
+endfunction()
+
 # Generates find_dependency() calls for target's INTERFACE link libraries
 # - Precondition: TARGET_NAME specifies existing target with INTERFACE_LINK_LIBRARIES
 # - Postcondition: OUTPUT_VAR contains newline-separated find_dependency() calls for public dependencies
-# - Handles common patterns: namespace::target from CPM, Qt5/Qt6::Component, Threads::Threads, etc.
+# - Uses cpp_library_map_dependency() mappings if registered, otherwise uses defaults
+# - Automatically handles cpp-library dependencies (matching NAMESPACE)
 function(_cpp_library_generate_dependencies OUTPUT_VAR TARGET_NAME NAMESPACE)
     get_target_property(LINK_LIBS ${TARGET_NAME} INTERFACE_LINK_LIBRARIES)
 
@@ -37,17 +46,18 @@ function(_cpp_library_generate_dependencies OUTPUT_VAR TARGET_NAME NAMESPACE)
             set(PKG_NAME "${CMAKE_MATCH_1}")
             set(COMPONENT "${CMAKE_MATCH_2}")
 
-            # Determine find_dependency() call based on package pattern
-            if(PKG_NAME STREQUAL NAMESPACE)
-                # Internal dependency: use component as package name (e.g., stlab::copy-on-write → copy-on-write)
+            # Check for custom mapping first
+            get_property(CUSTOM_MAPPING GLOBAL PROPERTY _CPP_LIBRARY_DEPENDENCY_MAP_${LIB})
+            
+            if(CUSTOM_MAPPING)
+                # 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})")
-            elseif(PKG_NAME STREQUAL "Threads")
-                list(APPEND DEPENDENCY_LIST "find_dependency(Threads)")
-            elseif(PKG_NAME MATCHES "^Qt[56]$")
-                # Qt with component (e.g., Qt5::Core → find_dependency(Qt5 COMPONENTS Core))
-                list(APPEND DEPENDENCY_LIST "find_dependency(${PKG_NAME} COMPONENTS ${COMPONENT})")
             else()
-                # Generic package (e.g., libdispatch::libdispatch → libdispatch)
+                # Default: use package name only (e.g., libdispatch::libdispatch → find_dependency(libdispatch))
                 list(APPEND DEPENDENCY_LIST "find_dependency(${PKG_NAME})")
             endif()
         endif()