stlab · sean-parent · Dec 22, 2025 · Dec 23, 2025 · May 20, 2026 · cursor
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -14,6 +14,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      # [DEPENDENCY] https://github.com/actions/checkout/releases
       - uses: actions/checkout@v6
 
       - name: Run dependency mapping tests
@@ -27,6 +28,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      # [DEPENDENCY] https://github.com/actions/checkout/releases
       - uses: actions/checkout@v6
 
       - name: Download CPM.cmake
@@ -136,6 +138,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
+      # [DEPENDENCY] https://github.com/actions/checkout/releases
       - uses: actions/checkout@v6
 
       - name: Check README examples

diff --git a/README.md b/README.md
@@ -92,10 +92,17 @@ cmake --build --preset=init
 
 ## Manual Setup
 
-If you prefer to set up your project manually, or need to integrate cpp-library into an existing project, follow these steps.
+If you prefer to set up your project manually or need to integrate the cpp-library into an existing project, follow these steps.
 
 ### Usage
 
+Install [CPM.cmake](https://github.com/cpm-cmake/CPM.cmake):
+
+```bash
+mkdir -p cmake
+curl -L -o cmake/CPM.cmake "https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake"
+```
+
 Use `CPMAddPackage` to fetch cpp-library directly in your `CMakeLists.txt`:
 
 ```cmake
@@ -130,8 +137,6 @@ cpp_library_setup(
 )
 ```
 
-**Requirements:** CMake 3.24+, C++17+ compiler (GCC 7+, Clang 5+, MSVC 2017+, or Apple Clang 9+)
-
 ### Consuming Libraries Built with cpp-library
 
 #### Using CPMAddPackage (recommended)
@@ -171,6 +176,13 @@ cmake --install build/install --prefix /opt/mylib
 ```
 The `install` preset enables `CPM_USE_LOCAL_PACKAGES`, which verifies your generated Config.cmake works correctly. See the [CPM.cmake documentation](https://github.com/cpm-cmake/CPM.cmake#cpm_use_local_packages) for more about using installed packages.
 
+**Controlling installation**: The `${NAMESPACE}_INSTALL` option controls whether installation is enabled (defaults to `PROJECT_IS_TOP_LEVEL`). Use `-D${NAMESPACE}_INSTALL=ON/OFF` to override:
+
+```bash
+cmake -DSTLAB_INSTALL=OFF -B build  # Disable install for top-level project
+cmake -DSTLAB_INSTALL=ON -B build   # Enable install for non-top-level (e.g., via CPM)
+```
+
 **Re-exporting CPM dependencies:** When re-exporting dependencies from `CPMAddPackage`, wrap them in `BUILD_INTERFACE` to avoid export errors (CPM creates non-IMPORTED targets that can't be exported):
 
 ```cmake
@@ -333,6 +345,7 @@ cpp_library_setup(
 - The project name is automatically taken from `PROJECT_NAME` (set by the `project()` command). You must call `project(your-library)` before `cpp_library_setup()`.
 - **If you specify `TESTS` or `EXAMPLES`**, call `include(CTest)` after `project()` and before `cpp_library_setup()`.
 - Version is automatically detected from git tags (see [Version Management](#version-management) for overrides).
+- Installation is controlled by the `${NAMESPACE}_INSTALL` option, which defaults to `PROJECT_IS_TOP_LEVEL`.
 
 ### Target Naming
 
@@ -517,6 +530,20 @@ The dependency provider (CMake 3.24+) tracks `find_package()` and `CPMAddPackage
 
 ## Development
 
+To use a local copy of cpp-library:
+
+```
+CPMAddPackage(
+    NAME cpp-library
+     SOURCE_DIR "${CMAKE_SOURCE_DIR}/../cpp-library"
+)
+```
+
+To use cpp-library from a specific commit:
+```
+CPMAddPackage("gh:stlab/cpp-library#65dbed9fff9a0331355bd51dc1e8156262390154")
+```
+
 To run cpp-library's unit tests for dependency mapping and installation:
 
 ```bash

diff --git a/cmake/cpp-library-ci.cmake b/cmake/cpp-library-ci.cmake
@@ -9,6 +9,22 @@
 # - Postcondition: .github/workflows/ci.yml created from template if not present
 # - With force_init: overwrites existing workflow file
 function(_cpp_library_setup_ci PACKAGE_NAME force_init)
+    # GitHub Actions refs (versions and source links) - update here to bump CI deps
+    # [DEPENDENCY] https://github.com/actions/checkout/releases
+    set(CI_ACTION_CHECKOUT "actions/checkout@v6")
+    # [DEPENDENCY] https://github.com/ilammy/msvc-dev-cmd/releases
+    # @1.13.0
+    set(CI_ACTION_MSVC_DEV_CMD "ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756")
+    # [DEPENDENCY] https://github.com/ssciwr/doxygen-install/releases
+    # @2.0.1
+    set(CI_ACTION_DOXYGEN_INSTALL "ssciwr/doxygen-install@329d88f5a303066a5bd006db7516b1925b86350e")
+    # [DEPENDENCY] https://github.com/actions/configure-pages/releases
+    set(CI_ACTION_CONFIGURE_PAGES "actions/configure-pages@v6")
+    # [DEPENDENCY] https://github.com/actions/upload-pages-artifact/releases
+    set(CI_ACTION_UPLOAD_PAGES_ARTIFACT "actions/upload-pages-artifact@v5")
+    # [DEPENDENCY] https://github.com/actions/deploy-pages/releases
+    set(CI_ACTION_DEPLOY_PAGES "actions/deploy-pages@v5")
+
     set(ci_template "${CPP_LIBRARY_ROOT}/templates/.github/workflows/ci.yml.in")
     set(ci_dest "${CMAKE_CURRENT_SOURCE_DIR}/.github/workflows/ci.yml")
 

diff --git a/cmake/cpp-library-docs.cmake b/cmake/cpp-library-docs.cmake
@@ -26,7 +26,8 @@ function(_cpp_library_setup_docs)
     # Download doxygen-awesome-css theme via CPM
     # https://github.com/jothepro/doxygen-awesome-css
     CPMAddPackage(
-        URI gh:jothepro/doxygen-awesome-css@2.4.1
+        # [DEPENDENCY] https://github.com/jothepro/doxygen-awesome-css/releases
+        URI gh:jothepro/doxygen-awesome-css@2.4.2
         DOWNLOAD_ONLY YES
     )
 

diff --git a/cmake/cpp-library-install.cmake b/cmake/cpp-library-install.cmake
@@ -409,6 +409,7 @@ endfunction()
 # - Precondition: NAME, PACKAGE_NAME, VERSION, and NAMESPACE specified; target NAME exists
 # - Postcondition: install rules created for target, config files, and export with NAMESPACE:: prefix
 # - Supports header-only (INTERFACE) and compiled libraries, uses SameMajorVersion compatibility
+# - Installation can be controlled via ${NAMESPACE}_INSTALL option (defaults to PROJECT_IS_TOP_LEVEL)
 function(_cpp_library_setup_install)
     set(oneValueArgs
         NAME            # Target name (e.g., "stlab-enum-ops")
@@ -422,10 +423,6 @@ function(_cpp_library_setup_install)
 
     cmake_parse_arguments(ARG "" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
 
-    # Include required CMake modules (deferred from top-level to avoid requiring project() before include)
-    include(GNUInstallDirs)
-    include(CMakePackageConfigHelpers)
-
     # Validate required arguments
     if(NOT ARG_NAME)
         message(FATAL_ERROR "_cpp_library_setup_install: NAME is required")
@@ -440,6 +437,22 @@ function(_cpp_library_setup_install)
         message(FATAL_ERROR "_cpp_library_setup_install: NAMESPACE is required")
     endif()
 
+    # Define installation option with PROJECT_IS_TOP_LEVEL as default
+    # This allows explicit control: -D${NAMESPACE}_INSTALL=ON/OFF
+    # Upper-case the namespace for the option name
+    string(TOUPPER "${ARG_NAMESPACE}" NAMESPACE_UPPER)
+    option(${NAMESPACE_UPPER}_INSTALL "Enable installation of ${ARG_PACKAGE_NAME}" ${PROJECT_IS_TOP_LEVEL})
+
+    # Check if installation is enabled
+    if(NOT ${NAMESPACE_UPPER}_INSTALL)
+        message(STATUS "cpp-library: Installation disabled for ${ARG_PACKAGE_NAME} (${NAMESPACE_UPPER}_INSTALL=OFF)")
+        return()
+    endif()
+
+    # Include required CMake modules (deferred from top-level to avoid requiring project() before include)
+    include(GNUInstallDirs)
+    include(CMakePackageConfigHelpers)
+
     # Install the library target
     # For header-only libraries (INTERFACE), this installs the target metadata
     # For compiled libraries, this installs the library files and headers

diff --git a/cmake/cpp-library-setup.cmake b/cmake/cpp-library-setup.cmake
@@ -119,16 +119,15 @@ function(_cpp_library_setup_core)
         endif()
     endif()
 
-    # Setup installation when building as top-level project
-    if(ARG_TOP_LEVEL)
-        _cpp_library_setup_install(
-            NAME "${ARG_NAME}"
-            PACKAGE_NAME "${ARG_PACKAGE_NAME}"
-            VERSION "${ARG_VERSION}"
-            NAMESPACE "${ARG_NAMESPACE}"
-            HEADERS "${ARG_HEADERS}"
-        )
-    endif()
+    # Setup installation (controlled by ${NAMESPACE}_INSTALL option, defaults to PROJECT_IS_TOP_LEVEL)
+    # The option is defined and checked inside _cpp_library_setup_install()
+    _cpp_library_setup_install(
+        NAME "${ARG_NAME}"
+        PACKAGE_NAME "${ARG_PACKAGE_NAME}"
+        VERSION "${ARG_VERSION}"
+        NAMESPACE "${ARG_NAMESPACE}"
+        HEADERS "${ARG_HEADERS}"
+    )
 
 endfunction()
 

diff --git a/cpp-library.cmake b/cpp-library.cmake
@@ -289,7 +289,8 @@ function(cpp_library_setup)
     # This must happen during normal configuration (not deferred) because CPMAddPackage uses add_subdirectory
     if(BUILD_TESTING AND (ARG_TESTS OR ARG_EXAMPLES))
         if(NOT TARGET doctest::doctest)
-            CPMAddPackage("gh:doctest/doctest@2.4.12")
+            # [DEPENDENCY] https://github.com/doctest/doctest/releases
+            CPMAddPackage("gh:doctest/doctest@2.5.2")
         endif()
     endif()
 

diff --git a/templates/.github/workflows/ci.yml.in b/templates/.github/workflows/ci.yml.in
@@ -1,5 +1,6 @@
 # Auto-generated from cpp-library (https://github.com/stlab/cpp-library)
 # Do not edit this file directly - it will be overwritten when templates are regenerated
+# Dependency versions are defined in cmake/cpp-library-ci.cmake (with source links)
 
 name: CI
 
@@ -34,7 +35,9 @@ jobs:
     runs-on: ${{ matrix.os }}
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: @CI_ACTION_CHECKOUT@
+      - if: ${{ startsWith(matrix.config.os, 'windows') }}
+        uses: @CI_ACTION_MSVC_DEV_CMD@
 
       - name: Configure CMake
         run: cmake --preset=test
@@ -97,7 +100,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: @CI_ACTION_CHECKOUT@
 
       - name: Configure CMake with clang-tidy
         run: cmake --preset=clang-tidy
@@ -117,11 +120,10 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: @CI_ACTION_CHECKOUT@
 
-      # ssciwr/doxygen-install@1.6.4
       - name: Install Doxygen
-        uses: ssciwr/doxygen-install@501e53b879da7648ab392ee226f5b90e42148449
+        uses: @CI_ACTION_DOXYGEN_INSTALL@
 
       - name: Configure CMake
         run: cmake --preset=docs
@@ -130,13 +132,13 @@ jobs:
         run: cmake --build --preset=docs
 
       - name: Setup Pages
-        uses: actions/configure-pages@v5
+        uses: @CI_ACTION_CONFIGURE_PAGES@
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: @CI_ACTION_UPLOAD_PAGES_ARTIFACT@
         with:
           path: build/docs/html
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: @CI_ACTION_DEPLOY_PAGES@
diff --git a/templates/Doxyfile.in b/templates/Doxyfile.in
@@ -25,3 +25,10 @@ DISTRIBUTE_GROUP_DOC    = YES
 MAX_INITIALIZER_LINES   = 0
 MULTILINE_CPP_IS_BRIEF  = YES
 WARN_AS_ERROR           = YES
+INCLUDE_GRAPH           = NO
+INCLUDED_BY_GRAPH       = NO
+DIRECTORY_GRAPH         = NO
+CLASS_GRAPH             = NO
+COLLABORATION_GRAPH     = NO
+GRAPHICAL_HIERARCHY     = NO
+GROUP_GRAPHS            = NO