Add CMAKE_POLICY_VERSION_MINIMUM environment variable

Extend commit 1a35351125 (Add CMAKE_POLICY_VERSION_MINIMUM to help
configure outdated projects, 2025-02-13, v4.0.0-rc1~12^2) with an
environment variable to initialize the cache entry.  That will make it
easier to use when `cmake` is invoked under layers of scripting.

Closes: #26715

Help/envvar/CMAKE_POLICY_VERSION_MINIMUM.rst

@@ -0,0 +1,11 @@
+CMAKE_POLICY_VERSION_MINIMUM
+----------------------------
+
+.. versionadded:: 4.0
+
+.. include:: ENV_VAR.txt
+
+The default value for :variable:`CMAKE_POLICY_VERSION_MINIMUM` when there
+is no explicit configuration given on the first run while creating a new
+build tree.  On later runs in an existing build tree the value persists in
+the cache as :variable:`CMAKE_POLICY_VERSION_MINIMUM`.

Help/manual/cmake-env-variables.7.rst

@@ -27,6 +27,7 @@ Environment Variables that Change Behavior
    /envvar/CMAKE_INCLUDE_PATH
    /envvar/CMAKE_LIBRARY_PATH
    /envvar/CMAKE_MAXIMUM_RECURSION_DEPTH
+   /envvar/CMAKE_POLICY_VERSION_MINIMUM
    /envvar/CMAKE_PREFIX_PATH
    /envvar/CMAKE_PROGRAM_PATH
    /envvar/CMAKE_TLS_VERIFY

Help/release/4.0.rst

@@ -75,6 +75,8 @@ Variables
 * The :variable:`CMAKE_POLICY_VERSION_MINIMUM` variable was added to
   help packagers and end users try to configure existing projects that
   have not been updated to work with supported CMake versions.
+  The :envvar:`CMAKE_POLICY_VERSION_MINIMUM` environment variable was
+  added to initialize it.
 
 * The :variable:`CMAKE_XCODE_SCHEME_LLDB_INIT_FILE` variable and corresponding
   :prop_tgt:`XCODE_SCHEME_LLDB_INIT_FILE` target property were added to tell

Help/variable/CMAKE_POLICY_VERSION_MINIMUM.rst

@@ -16,6 +16,10 @@ to externally set policies for which a project has not itself been updated:
   ``-DCMAKE_POLICY_VERSION_MINIMUM=3.5``, to try configuring a project
   that has not been updated to set at least that policy version itself.
 
+  Alternatively, users may set the :envvar:`CMAKE_POLICY_VERSION_MINIMUM`
+  environment variable to initialize the cache entry in new build trees
+  automatically.
+
 * Projects may set this variable before a call to :command:`add_subdirectory`
   that adds a third-party project in order to set its policy version without
   modifying third-party code.

Source/cmake.cxx

@@ -547,6 +547,21 @@ void cmake::PrintPresetEnvironment()
 // Parse the args
 bool cmake::SetCacheArgs(std::vector<std::string> const& args)
 {
+  static std::string const kCMAKE_POLICY_VERSION_MINIMUM =
+    "CMAKE_POLICY_VERSION_MINIMUM";
+  if (!this->State->GetInitializedCacheValue(kCMAKE_POLICY_VERSION_MINIMUM)) {
+    cm::optional<std::string> policyVersion =
+      cmSystemTools::GetEnvVar(kCMAKE_POLICY_VERSION_MINIMUM);
+    if (policyVersion && !policyVersion->empty()) {
+      this->AddCacheEntry(
+        kCMAKE_POLICY_VERSION_MINIMUM, *policyVersion,
+        "Override policy version for cmake_minimum_required calls.",
+        cmStateEnums::STRING);
+      this->State->SetCacheEntryProperty(kCMAKE_POLICY_VERSION_MINIMUM,
+                                         "ADVANCED", "1");
+    }
+  }
+
   auto DefineLambda = [](std::string const& entry, cmake* state) -> bool {
     std::string var;
     std::string value;

Tests/EnforceConfig.cmake.in

@@ -36,6 +36,7 @@ unset(ENV{CMAKE_GENERATOR_INSTANCE})
 unset(ENV{CMAKE_GENERATOR_PLATFORM})
 unset(ENV{CMAKE_GENERATOR_TOOLSET})
 unset(ENV{CMAKE_EXPORT_COMPILE_COMMANDS})
+unset(ENV{CMAKE_POLICY_VERSION_MINIMUM})
 
 # Verify that our module implementations do not recurse too much.
 set(ENV{CMAKE_MAXIMUM_RECURSION_DEPTH} 100)

Tests/RunCMake/cmake_minimum_required/PolicyVersionEnvVar-stderr.txt

@@ -0,0 +1,4 @@
+^CMAKE_POLICY_VERSION_MINIMUM='3\.10'
+CMAKE_MINIMUM_REQUIRED_VERSION='3\.1'
+CMP0071='NEW'
+CMP0072=''$

Tests/RunCMake/cmake_minimum_required/PolicyVersionEnvVar.cmake

@@ -0,0 +1 @@
+include(${CMAKE_CURRENT_LIST_DIR}/PolicyVersionVar.cmake)

Tests/RunCMake/cmake_minimum_required/PolicyVersionEnvVarBad-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_minimum_required/PolicyVersionEnvVarBad-stderr.txt

@@ -0,0 +1,10 @@
+^CMake Error at CMakeLists\.txt:1 \(cmake_minimum_required\):
+  Invalid CMAKE_POLICY_VERSION_MINIMUM value "\.\.\.3\.10"\.  A numeric
+  major\.minor\[\.patch\[\.tweak\]\] must be given\.
++
+CMake Error at PolicyVersionVarBad\.cmake:1 \(cmake_minimum_required\):
+  Invalid CMAKE_POLICY_VERSION_MINIMUM value "\.\.\.3\.10"\.  A numeric
+  major\.minor\[\.patch\[\.tweak\]\] must be given\.
+Call Stack \(most recent call first\):
+  PolicyVersionEnvVarBad\.cmake:[0-9]+ \(include\)
+  CMakeLists\.txt:[0-9]+ \(include\)$

Tests/RunCMake/cmake_minimum_required/PolicyVersionEnvVarBad.cmake

@@ -0,0 +1 @@
+include(${CMAKE_CURRENT_LIST_DIR}/PolicyVersionVarBad.cmake)

Tests/RunCMake/cmake_minimum_required/PolicyVersionEnvVarBadCache-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_minimum_required/PolicyVersionEnvVarBadCache-stderr.txt

@@ -0,0 +1,9 @@
+^CMake Error at PolicyVersionVarBad\.cmake:1 \(cmake_minimum_required\):
+  Invalid CMAKE_POLICY_VERSION_MINIMUM value "\.\.\.3\.10"\.  A numeric
+  major\.minor\[\.patch\[\.tweak\]\] must be given\.
+Call Stack \(most recent call first\):
+  PolicyVersionEnvVarBad\.cmake:[0-9]+ \(include\)
++
+CMake Error at CMakeLists\.txt:1 \(cmake_minimum_required\):
+  Invalid CMAKE_POLICY_VERSION_MINIMUM value "\.\.\.3\.10"\.  A numeric
+  major\.minor\[\.patch\[\.tweak\]\] must be given\.$

Tests/RunCMake/cmake_minimum_required/PolicyVersionEnvVarBadScript-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/cmake_minimum_required/PolicyVersionEnvVarBadScript-stderr.txt

@@ -0,0 +1,7 @@
+^CMake Error at [^
+]*/PolicyVersionVarBad\.cmake:1 \(cmake_minimum_required\):
+  Invalid CMAKE_POLICY_VERSION_MINIMUM value "\.\.\.3\.10"\.  A numeric
+  major\.minor\[\.patch\[\.tweak\]\] must be given\.
+Call Stack \(most recent call first\):
+  [^
+]*/PolicyVersionEnvVarBadScript\.cmake:[0-9]+ \(include\)$

Tests/RunCMake/cmake_minimum_required/PolicyVersionEnvVarBadScript.cmake

@@ -0,0 +1 @@
+include(${CMAKE_CURRENT_LIST_DIR}/PolicyVersionVarBad.cmake)

Tests/RunCMake/cmake_minimum_required/PolicyVersionEnvVarCache-stderr.txt

@@ -0,0 +1,4 @@
+^CMAKE_POLICY_VERSION_MINIMUM='3\.10'
+CMAKE_MINIMUM_REQUIRED_VERSION='3\.1'
+CMP0071='NEW'
+CMP0072=''$

Tests/RunCMake/cmake_minimum_required/PolicyVersionEnvVarScript-stderr.txt

@@ -0,0 +1,4 @@
+^CMAKE_POLICY_VERSION_MINIMUM='3\.10'
+CMAKE_MINIMUM_REQUIRED_VERSION='3\.1'
+CMP0071='NEW'
+CMP0072=''$

Tests/RunCMake/cmake_minimum_required/PolicyVersionEnvVarScript.cmake

@@ -0,0 +1 @@
+include(${CMAKE_CURRENT_LIST_DIR}/PolicyVersionVar.cmake)

Tests/RunCMake/cmake_minimum_required/RunCMakeTest.cmake

@@ -14,3 +14,13 @@ run_cmake_script(PolicyVersionVarScript -DCMAKE_POLICY_VERSION_MINIMUM=3.10)
 run_cmake_with_options(PolicyVersionVarBad -DCMAKE_POLICY_VERSION_MINIMUM=...3.10)
 run_cmake_with_options(PolicyVersionVarBadCache -DCMAKE_POLICY_VERSION_MINIMUM=...3.10 -C ${CMAKE_CURRENT_LIST_DIR}/PolicyVersionVarBad.cmake)
 run_cmake_script(PolicyVersionVarBadScript -DCMAKE_POLICY_VERSION_MINIMUM=...3.10)
+
+set(ENV{CMAKE_POLICY_VERSION_MINIMUM} 3.10)
+run_cmake(PolicyVersionEnvVar)
+run_cmake_with_options(PolicyVersionEnvVarCache -C ${CMAKE_CURRENT_LIST_DIR}/PolicyVersionEnvVar.cmake)
+run_cmake_script(PolicyVersionEnvVarScript)
+set(ENV{CMAKE_POLICY_VERSION_MINIMUM} ...3.10)
+run_cmake(PolicyVersionEnvVarBad)
+run_cmake_with_options(PolicyVersionEnvVarBadCache -C ${CMAKE_CURRENT_LIST_DIR}/PolicyVersionEnvVarBad.cmake)
+run_cmake_script(PolicyVersionEnvVarBadScript)
+unset(ENV{CMAKE_POLICY_VERSION_MINIMUM})