Defer install module inclusion until after project() in CMake

Moved inclusion of cpp-library-install.cmake and related modules to after project() is called to avoid requiring language/architecture information too early. Updated documentation and comments to clarify this behavior. Improved CPM cache setup logic in README and setup.cmake. Removed the 'install' preset from CMakePresets.json.

Author: sean-parent

.vscode/settings.json

@@ -5,5 +5,6 @@
         "doctest",
         "MSVC",
         "mylib"
-    ]
+    ],
+    "cmake.ignoreCMakeListsMissing": true
 }

README.md

@@ -102,8 +102,9 @@ Use `CPMAddPackage` to fetch cpp-library directly in your `CMakeLists.txt`:
 cmake_minimum_required(VERSION 3.24)
 
 # Setup CPM cache before project()
-if(NOT CPM_SOURCE_CACHE AND NOT DEFINED ENV{CPM_SOURCE_CACHE})
+if(PROJECT_IS_TOP_LEVEL AND NOT CPM_SOURCE_CACHE AND NOT DEFINED ENV{CPM_SOURCE_CACHE})
     set(CPM_SOURCE_CACHE "${CMAKE_SOURCE_DIR}/.cache/cpm" CACHE PATH "CPM source cache")
+    message(STATUS "Setting cpm cache dir to: ${CPM_SOURCE_CACHE}")
 endif()
 include(cmake/CPM.cmake)
 

cmake/cpp-library-install.cmake

@@ -8,9 +8,10 @@
 # - Static libraries
 # - Shared libraries (when BUILD_SHARED_LIBS is ON)
 # - CMake package config generation for find_package() support
-
-include(GNUInstallDirs)
-include(CMakePackageConfigHelpers)
+#
+# Note: GNUInstallDirs and CMakePackageConfigHelpers are included inside
+# _cpp_library_setup_install() to avoid requiring project() to be called
+# when this module is loaded.
 
 # System packages that don't require version constraints in find_dependency()
 # These are commonly available system libraries where version requirements are typically not specified.
@@ -337,6 +338,10 @@ 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")

cpp-library.cmake

@@ -35,12 +35,12 @@ function(cpp_library_enable_dependency_tracking)
 endfunction()
 
 # Include all the component modules
-# Note: CTest is NOT included here because it requires project() to be called first.
-# It will be included in cpp_library_setup() which is called after project().
+# Note: Some modules (CTest, cpp-library-install) require project() to be called first
+# because they need language/architecture information. These are included in
+# cpp_library_setup() which is called after project().
 include("${CPP_LIBRARY_ROOT}/cmake/cpp-library-setup.cmake")
 include("${CPP_LIBRARY_ROOT}/cmake/cpp-library-testing.cmake")  
 include("${CPP_LIBRARY_ROOT}/cmake/cpp-library-docs.cmake")
-include("${CPP_LIBRARY_ROOT}/cmake/cpp-library-install.cmake")
 include("${CPP_LIBRARY_ROOT}/cmake/cpp-library-ci.cmake")
 
 # Creates test or example executables and registers them with CTest.
@@ -165,8 +165,10 @@ function(cpp_library_setup)
     endif()
     set(ARG_NAME "${PROJECT_NAME}")
 
-    # Include CTest for testing support (must be after project())
+    # Include modules that require project() to be called first
+    # (CTest and GNUInstallDirs need language/architecture information)
     include(CTest)
+    include("${CPP_LIBRARY_ROOT}/cmake/cpp-library-install.cmake")
 
     # Calculate clean name (without namespace prefix) for target alias
     # If PROJECT_NAME starts with NAMESPACE-, strip it; otherwise use PROJECT_NAME as-is

setup.cmake

@@ -315,8 +315,9 @@ file(WRITE "${PROJECT_DIR}/CMakeLists.txt"
 "cmake_minimum_required(VERSION 3.24)
 
 # Setup CPM cache before project()
-if(NOT CPM_SOURCE_CACHE AND NOT DEFINED ENV{CPM_SOURCE_CACHE})
-    set(CPM_SOURCE_CACHE \"\${CMAKE_SOURCE_DIR}/.cache/cpm\" CACHE PATH \"CPM source cache\")
+if(PROJECT_IS_TOP_LEVEL AND NOT CPM_SOURCE_CACHE AND NOT DEFINED ENV{CPM_SOURCE_CACHE})
+    set(CPM_SOURCE_CACHE "${CMAKE_SOURCE_DIR}/.cache/cpm" CACHE PATH "CPM source cache")
+    message(STATUS "Setting cpm cache dir to: ${CPM_SOURCE_CACHE}")
 endif()
 include(cmake/CPM.cmake)
 

templates/CMakePresets.json

@@ -68,29 +68,14 @@
         "CMAKE_CXX_EXTENSIONS": "OFF",
         "CPP_LIBRARY_FORCE_INIT": "ON"
       }
-    },
-    {
-      "name": "install",
-      "displayName": "Local Install Test",
-      "description": "Configuration for testing installation locally (installs to build/install/prefix)",
-      "binaryDir": "${sourceDir}/build/install",
-      "generator": "Ninja",
-      "cacheVariables": {
-        "CMAKE_BUILD_TYPE": "Release",
-        "BUILD_TESTING": "OFF",
-        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
-        "CMAKE_CXX_EXTENSIONS": "OFF",
-        "CMAKE_INSTALL_PREFIX": "${sourceDir}/build/install/prefix"
-      }
     }
   ],
   "buildPresets": [
     { "name": "default", "displayName": "Default Build", "configurePreset": "default" },
     { "name": "test", "displayName": "Build Tests", "configurePreset": "test" },
     { "name": "docs", "displayName": "Build Docs", "configurePreset": "docs", "targets": "docs" },
     { "name": "clang-tidy", "displayName": "Build with Clang-Tidy", "configurePreset": "clang-tidy" },
-    { "name": "init", "displayName": "Initialize Templates", "configurePreset": "init" },
-    { "name": "install", "displayName": "Build for Local Install", "configurePreset": "install" }
+    { "name": "init", "displayName": "Initialize Templates", "configurePreset": "init" }
   ],
   "testPresets": [
     { "name": "test", "displayName": "Run All Tests", "configurePreset": "test", "output": { "outputOnFailure": true } },