Implement #406: CPM_<dependency>_SOURCE explicit->env fallback (#696)

* Reimplement #406 with cascading env overrides

* style: format package override env unit test

* style: align env override test with cmake-format layout

* style: apply cmake-format to env override unit test

* feat: warn when CPM_<name>_SOURCE override activates

Reviewer request: add a warning for any overridden dependencies to
minimise the risk of having unexpected dependency versions injected.

Both override paths now emit message(WARNING):
- ENV variable path: fires inside the ENV-fallback block when an
  environment variable activates the override
- CMake variable path: fires only when no ENV variable is active,
  avoiding a double-warn when ENV sets the CMake variable

Warning format matches CPM_INDENT prefix convention:
  "CPM: '<name>' version overridden by environment variable
   CPM_<name>_SOURCE='<path>'"

Unit tests updated to capture stderr and assert the expected warning
text is present for both override paths.

* style: apply cmake-format to warning messages

* style: apply cmake-format to package-override-env test

* style: apply cmake-format to package-override test

Author: CraigHutchinson

README.md

@@ -260,6 +260,16 @@ For example, to use the local version of the dependency `Dep` at the path `/path
 cmake -Bbuild -DCPM_Dep_SOURCE=/path/to/dep
 ```
 
+Environment-based local package overrides are also available via `CPM_<dependency name>_SOURCE`.
+For example:
+
+```bash
+export CPM_Dep_SOURCE=/path/to/dep
+cmake -Bbuild
+```
+
+If both the CMake option and environment variable are set, the explicit CMake option takes precedence.
+
 ## Package lock
 
 In large projects with many transitive dependencies, it can be useful to introduce a package lock file.

cmake/CPM.cmake

@@ -768,10 +768,23 @@ function(CPMAddPackage)
     return()
   endif()
 
+  if(NOT DEFINED CPM_${CPM_ARGS_NAME}_SOURCE AND DEFINED ENV{CPM_${CPM_ARGS_NAME}_SOURCE})
+    # Normalize separators to support Windows paths when reading from environment variables.
+    file(TO_CMAKE_PATH "$ENV{CPM_${CPM_ARGS_NAME}_SOURCE}" CPM_${CPM_ARGS_NAME}_SOURCE)
+    message(WARNING "${CPM_INDENT} '${CPM_ARGS_NAME}' version overridden by environment variable "
+                    "CPM_${CPM_ARGS_NAME}_SOURCE='${CPM_${CPM_ARGS_NAME}_SOURCE}'"
+    )
+  endif()
+
   # Check for manual overrides
   if(NOT CPM_ARGS_FORCE AND NOT "${CPM_${CPM_ARGS_NAME}_SOURCE}" STREQUAL "")
     set(PACKAGE_SOURCE ${CPM_${CPM_ARGS_NAME}_SOURCE})
     set(CPM_${CPM_ARGS_NAME}_SOURCE "")
+    if(NOT DEFINED ENV{CPM_${CPM_ARGS_NAME}_SOURCE})
+      message(WARNING "${CPM_INDENT} '${CPM_ARGS_NAME}' version overridden by CMake variable "
+                      "CPM_${CPM_ARGS_NAME}_SOURCE='${PACKAGE_SOURCE}'"
+      )
+    endif()
     CPMAddPackage(
       NAME "${CPM_ARGS_NAME}"
       SOURCE_DIR "${PACKAGE_SOURCE}"

cmake/get_cpm.cmake

@@ -5,7 +5,11 @@
 set(CPM_DOWNLOAD_VERSION 1.0.0-development-version)
 set(CPM_HASH_SUM "CPM_HASH_SUM_PLACEHOLDER")
 
-if(CPM_SOURCE_CACHE)
+if(CPM_PATH)
+  set(CPM_DOWNLOAD_LOCATION "${CPM_PATH}/CPM.cmake")
+elseif(DEFINED ENV{CPM_PATH})
+  file(TO_CMAKE_PATH "$ENV{CPM_PATH}/CPM.cmake" CPM_DOWNLOAD_LOCATION)
+elseif(CPM_SOURCE_CACHE)
   set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
 elseif(DEFINED ENV{CPM_SOURCE_CACHE})
   set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")

test/unit/package-override-env.cmake

@@ -0,0 +1,29 @@
+include(CMakePackageConfigHelpers)
+include(${CPM_PATH}/testing.cmake)
+
+set(TEST_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/project-override-env)
+
+execute_process(COMMAND ${CMAKE_COMMAND} -E rm -rf ${TEST_BUILD_DIR})
+
+configure_package_config_file(
+  "${CMAKE_CURRENT_LIST_DIR}/local_dependency/OverrideCMakeLists.txt.in"
+  "${CMAKE_CURRENT_LIST_DIR}/local_dependency/CMakeLists.txt"
+  INSTALL_DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/junk
+)
+
+execute_process(
+  COMMAND
+    ${CMAKE_COMMAND} -E env
+    "CPM_Dependency_SOURCE=${CMAKE_CURRENT_LIST_DIR}/local_dependency/dependency" ${CMAKE_COMMAND}
+    "-S${CMAKE_CURRENT_LIST_DIR}/local_dependency" "-B${TEST_BUILD_DIR}"
+  RESULT_VARIABLE ret
+  ERROR_VARIABLE cmake_stderr
+)
+
+assert_equal(${ret} "0")
+
+if(NOT "${cmake_stderr}" MATCHES "CPM:.*Dependency.*overridden by environment variable")
+  message(FATAL_ERROR "Expected CPM ENV override warning not found in output:\n${cmake_stderr}")
+else()
+  message(STATUS "test passed: CPM ENV override warning was emitted")
+endif()

test/unit/package-override.cmake

@@ -12,9 +12,18 @@ configure_package_config_file(
 )
 
 execute_process(
-  COMMAND ${CMAKE_COMMAND} -S${CMAKE_CURRENT_LIST_DIR}/local_dependency -B${TEST_BUILD_DIR}
-          -DCPM_Dependency_SOURCE=${CMAKE_CURRENT_LIST_DIR}/local_dependency/dependency
+  COMMAND ${CMAKE_COMMAND} "-S${CMAKE_CURRENT_LIST_DIR}/local_dependency" "-B${TEST_BUILD_DIR}"
+          "-DCPM_Dependency_SOURCE=${CMAKE_CURRENT_LIST_DIR}/local_dependency/dependency"
   RESULT_VARIABLE ret
+  ERROR_VARIABLE cmake_stderr
 )
 
 assert_equal(${ret} "0")
+
+if(NOT "${cmake_stderr}" MATCHES "CPM:.*Dependency.*overridden by CMake variable")
+  message(
+    FATAL_ERROR "Expected CPM CMake variable override warning not found in output:\n${cmake_stderr}"
+  )
+else()
+  message(STATUS "test passed: CPM CMake variable override warning was emitted")
+endif()