Standardize version usage and improve setup automation

Replaced hardcoded version numbers with a placeholder (X.Y.Z) in documentation, templates, and CMake scripts to encourage users to check for the latest release. Added logic in setup.cmake to auto-detect the current version from git tags, falling back to a placeholder if unavailable. Centralized example usage generation for consistent error messages and updated CI workflows to use actions/checkout@v6.

Author: sean-parent

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Run dependency mapping tests
         run: cmake -P tests/install/CMakeLists.txt
@@ -27,7 +27,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Download CPM.cmake
         run: |
@@ -135,7 +135,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Check README examples
         run: |

README.md

@@ -28,7 +28,7 @@ The easiest way to create a new library project using cpp-library is with the `s
 
 **Interactive mode:**
 
-```bash
+```bash 
 cmake -P <(curl -sSL https://raw.githubusercontent.com/stlab/cpp-library/main/setup.cmake)
 ```
 
@@ -210,7 +210,7 @@ cmake_minimum_required(VERSION 3.24)
 include(cmake/CPM.cmake)
 
 # Check https://github.com/stlab/cpp-library/releases for the latest version
-CPMAddPackage("gh:stlab/cpp-library@5.0.0")
+CPMAddPackage("gh:stlab/cpp-library@X.Y.Z")
 include(${cpp-library_SOURCE_DIR}/cpp-library.cmake)
 
 cpp_library_enable_dependency_tracking()  # Before project()
@@ -247,7 +247,7 @@ To update to the latest version of cpp-library in your project:
 Change the version tag in your `CPMAddPackage` call:
 
 ```cmake
-CPMAddPackage("gh:stlab/cpp-library@4.1.0")  # Update version here
+CPMAddPackage("gh:stlab/cpp-library@X.Y.Z")  # Update version here
 ```
 
 #### Step 2: Regenerate template files

cmake/cpp-library-dependency-provider.cmake

@@ -10,7 +10,7 @@
 # Usage:
 #   cmake_minimum_required(VERSION 3.24)
 #   include(cmake/CPM.cmake)
-#   CPMAddPackage("gh:stlab/cpp-library@5.0.0")
+#   CPMAddPackage("gh:stlab/cpp-library@X.Y.Z")
 #   
 #   # Enable dependency tracking
 #   list(APPEND CMAKE_PROJECT_TOP_LEVEL_INCLUDES 

cmake/cpp-library-install.cmake

@@ -125,17 +125,13 @@ function(_cpp_library_resolve_dependency LIB NAMESPACE OUTPUT_VAR)
                 # Not tracked and not a system package - check if provider is installed
                 get_property(PROVIDER_INSTALLED GLOBAL PROPERTY _CPP_LIBRARY_PROVIDER_INSTALLED)
                 if(NOT PROVIDER_INSTALLED)
+                    _cpp_library_example_usage(EXAMPLE)
                     message(FATAL_ERROR 
                         "cpp-library: Dependency provider not installed.\n"
                         "You must call cpp_library_enable_dependency_tracking() before project().\n"
                         "\n"
                         "Example:\n"
-                        "    cmake_minimum_required(VERSION 3.24)\n"
-                        "    include(cmake/CPM.cmake)\n"
-                        "    CPMAddPackage(\"gh:stlab/cpp-library@5.0.0\")\n"
-                        "    include(\${cpp-library_SOURCE_DIR}/cpp-library.cmake)\n"
-                        "    cpp_library_enable_dependency_tracking()\n"
-                        "    project(my-library)\n"
+                        "${EXAMPLE}\n"
                     )
                 else()
                     # Provider is installed but dependency wasn't tracked

cmake/cpp-library-setup.cmake

@@ -32,6 +32,27 @@ function(_cpp_library_get_git_version OUTPUT_VAR)
     endif()
 endfunction()
 
+# Returns standardized example usage string with current cpp-library version
+# This ensures consistent error messages across the library
+function(_cpp_library_example_usage OUTPUT_VAR)
+    # Get the current cpp-library version
+    _cpp_library_get_git_version(LIB_VERSION)
+    
+    # If version detection failed, use X.Y.Z placeholder
+    if(LIB_VERSION STREQUAL "0.0.0")
+        set(LIB_VERSION "X.Y.Z")
+    endif()
+    
+    set(${OUTPUT_VAR} 
+"cmake_minimum_required(VERSION 3.24)
+include(cmake/CPM.cmake)
+CPMAddPackage(\"gh:stlab/cpp-library@${LIB_VERSION}\")
+include(\${cpp-library_SOURCE_DIR}/cpp-library.cmake)
+cpp_library_enable_dependency_tracking()
+project(my-library)" 
+        PARENT_SCOPE)
+endfunction()
+
 # Creates library target (INTERFACE or compiled) with headers and proper configuration.
 # - 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

cpp-library.cmake

@@ -15,7 +15,7 @@ get_filename_component(CPP_LIBRARY_ROOT "${CMAKE_CURRENT_LIST_FILE}" DIRECTORY)
 # Usage:
 #   cmake_minimum_required(VERSION 3.24)
 #   include(cmake/CPM.cmake)
-#   CPMAddPackage("gh:stlab/cpp-library@5.0.0")
+#   CPMAddPackage("gh:stlab/cpp-library@X.Y.Z")
 #   include(${cpp-library_SOURCE_DIR}/cpp-library.cmake)
 #   
 #   cpp_library_enable_dependency_tracking()  # Must be before project()

setup.cmake

@@ -9,6 +9,26 @@
 
 cmake_minimum_required(VERSION 3.20)
 
+# Detect cpp-library version from git tags
+execute_process(
+    COMMAND git describe --tags --abbrev=0
+    WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
+    OUTPUT_VARIABLE CPP_LIBRARY_GIT_VERSION
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    ERROR_QUIET
+)
+
+# Clean version (remove 'v' prefix if present)
+if(CPP_LIBRARY_GIT_VERSION)
+    string(REGEX REPLACE "^v" "" CPP_LIBRARY_VERSION "${CPP_LIBRARY_GIT_VERSION}")
+else()
+    # Fallback to X.Y.Z placeholder if no git tag found
+    set(CPP_LIBRARY_VERSION "X.Y.Z")
+    message(WARNING "No git tag found for cpp-library version. Using placeholder 'X.Y.Z'. Check https://github.com/stlab/cpp-library/releases for the latest version.")
+endif()
+
+message(STATUS "cpp-library version: ${CPP_LIBRARY_VERSION}")
+
 # Parse command line arguments
 set(CMD_LINE_ARGS "")
 if(CMAKE_ARGV3)
@@ -317,7 +337,8 @@ file(WRITE "${PROJECT_DIR}/CMakeLists.txt"
 include(cmake/CPM.cmake)
 
 # Fetch cpp-library before project()
-CPMAddPackage(\"gh:stlab/cpp-library@5.0.0\")
+# Check https://github.com/stlab/cpp-library/releases for the latest version
+CPMAddPackage(\"gh:stlab/cpp-library@${CPP_LIBRARY_VERSION}\")
 include(\${cpp-library_SOURCE_DIR}/cpp-library.cmake)
 
 # Enable dependency tracking before project()

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

@@ -97,7 +97,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Configure CMake with clang-tidy
         run: cmake --preset=clang-tidy
@@ -117,7 +117,7 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       # ssciwr/doxygen-install@1.6.4
       - name: Install Doxygen

tests/install/test_integration_example.txt

@@ -10,7 +10,7 @@ cmake_minimum_required(VERSION 3.24)
 include(cmake/CPM.cmake)
 
 # Step 2: Fetch cpp-library before project()
-CPMAddPackage("gh:stlab/cpp-library@5.0.0")
+CPMAddPackage("gh:stlab/cpp-library@X.Y.Z")
 include(${cpp-library_SOURCE_DIR}/cpp-library.cmake)
 
 # Step 3: Enable dependency tracking BEFORE project()