Update docs and install logic; add troubleshooting

Expanded the README with a troubleshooting section and clarified documentation deployment instructions. Updated comments and logic in cpp-library-install.cmake to centralize system package handling for dependency mapping. Generalized cpp-library.cmake to support both header-only and compiled C++ libraries.

Author: sean-parent

README.md

@@ -111,8 +111,8 @@ if(PROJECT_IS_TOP_LEVEL AND NOT CPM_SOURCE_CACHE AND NOT DEFINED ENV{CPM_SOURCE_
 endif()
 include(cmake/CPM.cmake)
 
-# Fetch cpp-library via CPM
-CPMAddPackage("gh:stlab/cpp-library@4.0.3")
+# Fetch cpp-library via CPM (update to latest version)
+CPMAddPackage("gh:stlab/cpp-library@4.0.3")  # Check for latest version
 include(${cpp-library_SOURCE_DIR}/cpp-library.cmake)
 
 cpp_library_setup(
@@ -358,9 +358,9 @@ To enable automatic documentation deployment to GitHub Pages:
 
 1. Go to your repository **Settings** → **Pages**
 2. Under **Source**, select **GitHub Actions**
-3. Push a commit to trigger the CI workflow
+3. Publish a release to trigger documentation build
 
-Your documentation will be automatically built and deployed to `https://your-org.github.io/your-library/` on every push to the main branch.
+Your documentation will be automatically built and deployed to `https://your-org.github.io/your-library/` when you publish a GitHub release.
 
 ## API Reference
 
@@ -410,21 +410,6 @@ This produces:
 - **Target alias**: `stlab::enum-ops` (used in `target_link_libraries()`)
 - **Repository name**: `stlab/stlab-enum-ops` (must match package name)
 
-**Alternative Patterns:**
-
-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 stlab
-    # ...
-)
-```
-
-Produces the same result as above.
-
 **Special case** — single-component namespace (e.g., `project(stlab)` with `NAMESPACE stlab`):
 
 - Target name: `stlab`
@@ -617,6 +602,49 @@ See these projects using cpp-library:
 
 Note: Repository names include the namespace prefix for CPM compatibility and collision prevention.
 
+## Troubleshooting
+
+### Version Detection Fails
+
+**Problem**: Error message: "Cannot determine version for dependency..."
+
+**Solution**: Add explicit version mapping before `cpp_library_setup()`:
+```cmake
+cpp_library_map_dependency("stlab::enum-ops" "stlab-enum-ops 1.0.0")
+```
+
+The error message shows the exact line to add.
+
+### Non-Namespaced Target Error
+
+**Problem**: "Cannot automatically handle non-namespaced dependency: opencv_core"
+
+**Solution**: Non-namespaced targets must be explicitly mapped:
+```cmake
+cpp_library_map_dependency("opencv_core" "OpenCV 4.5.0")
+```
+
+### Component Merging Not Working
+
+**Problem**: Multiple Qt/Boost components generate separate `find_dependency()` calls
+
+**Solution**: Ensure all components have **identical** package name, version, and additional arguments:
+```cmake
+# ✓ Correct - will merge
+cpp_library_map_dependency("Qt6::Core" "Qt6 6.5.0 COMPONENTS Core")
+cpp_library_map_dependency("Qt6::Widgets" "Qt6 6.5.0 COMPONENTS Widgets")
+
+# ✗ Wrong - won't merge (different versions)
+cpp_library_map_dependency("Qt6::Core" "Qt6 6.5.0 COMPONENTS Core")
+cpp_library_map_dependency("Qt6::Widgets" "Qt6 6.4.0 COMPONENTS Widgets")
+```
+
+### CPM Cannot Find Package
+
+**Problem**: `CPMAddPackage("gh:stlab/enum-ops@1.0.0")` fails with `CPM_USE_LOCAL_PACKAGES`
+
+**Solution**: Repository name must match package name. If package name is `stlab-enum-ops`, repository must be `stlab/stlab-enum-ops`, not `stlab/enum-ops`.
+
 ## Development
 
 ### Running Tests

cmake/cpp-library-install.cmake

@@ -12,6 +12,11 @@
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)
 
+# System packages that don't require version constraints in find_dependency()
+# These are commonly available system libraries where version requirements are typically not specified.
+# To extend this list in your project, use cpp_library_map_dependency() to explicitly map additional packages.
+set(_CPP_LIBRARY_SYSTEM_PACKAGES "Threads" "OpenMP" "ZLIB" "CURL" "OpenSSL")
+
 # Registers a custom dependency mapping for find_dependency() generation
 # - Precondition: TARGET is a namespaced target (e.g., "Qt6::Core", "stlab::enum-ops") or non-namespaced (e.g., "opencv_core")
 # - Postcondition: FIND_DEPENDENCY_CALL stored for TARGET, used in package config generation
@@ -86,10 +91,7 @@ function(_cpp_library_generate_dependencies OUTPUT_VAR TARGET_NAME NAMESPACE)
                 endif()
                 
                 # Check if this is a system package that doesn't require versions
-                # These packages are commonly available and don't need version constraints
-                set(SYSTEM_PACKAGES "Threads" "OpenMP" "ZLIB" "CURL" "OpenSSL")
-                
-                if(FIND_PACKAGE_NAME IN_LIST SYSTEM_PACKAGES)
+                if(FIND_PACKAGE_NAME IN_LIST _CPP_LIBRARY_SYSTEM_PACKAGES)
                     # System package - no version required
                     set(FIND_DEP_CALL "${FIND_PACKAGE_NAME}")
                 else()

cpp-library.cmake

@@ -1,8 +1,8 @@
 # SPDX-License-Identifier: BSL-1.0
 #
-# cpp-library.cmake - Modern C++ Header-Only Library Template
+# cpp-library.cmake - Modern C++ Library Template
 # 
-# This file provides common CMake infrastructure for stlab header-only libraries.
+# This file provides common CMake infrastructure for C++ libraries (header-only and compiled).
 # Usage: include(cmake/cpp-library.cmake) then call cpp_library_setup(...)
 
 # Determine the directory where this file is located