VS: Select latest available Windows SDK version by default

Add policy `CMP0149` to stop preferring SDKs exactly matching
`CMAKE_SYSTEM_VERSION` over the latest SDK.

Fixes: #16202

7 files changed, 75 insertions, 4 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 158bf62..8c7189a 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.27
 .. toctree::
    :maxdepth: 1
 
+   CMP0149: Visual Studio generators select latest Windows SDK by default. </policy/CMP0149>
    CMP0148: The FindPythonInterp and FindPythonLibs modules are removed. </policy/CMP0148>
    CMP0147: Visual Studio generators build custom commands in parallel. </policy/CMP0147>
    CMP0146: The FindCUDA module is removed. </policy/CMP0146>
diff --git a/Help/policy/CMP0149.rst b/Help/policy/CMP0149.rst
new file mode 100644
index 0000000..714eeaf
--- /dev/null
+++ b/Help/policy/CMP0149.rst
@@ -0,0 +1,47 @@
+CMP0149
+-------
+
+.. versionadded:: 3.27
+
+:ref:`Visual Studio Generators` select latest Windows SDK by default.
+
+Visual Studio Generators select a Windows SDK version to put in the
+``WindowsTargetPlatformVersion`` setting in ``.vcxproj`` files.
+CMake sets the :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION`
+variable to the selected SDK version.
+
+Prior to CMake 3.27, the SDK version was always selected by the value of
+the :variable:`CMAKE_SYSTEM_VERSION` variable.  Users or toolchain files
+could set that variable to one of the exact Windows SDK versions available
+on the host system.  Since :variable:`CMAKE_SYSTEM_VERSION` defaults to
+:variable:`CMAKE_HOST_SYSTEM_VERSION`, and it is not guaranteed that a
+matching Windows SDK version is available, CMake had to fall back to
+using the latest Windows SDK version if no exact match was available.
+This approach was problematic:
+
+* The latest Windows SDK might or might not be selected based on whether
+  the host version of Windows happens to match an available SDK version.
+
+* An old Windows SDK version might be selected that has not been updated
+  for newer language standards such as C11.
+
+CMake 3.27 and higher prefer to ignore the exact value of
+:variable:`CMAKE_SYSTEM_VERSION` and by default select the latest SDK
+version available.  An exact SDK version may be specified explicitly
+using a ``version=`` field in the :variable:`CMAKE_GENERATOR_PLATFORM`
+variable.  See :ref:`Visual Studio Platform Selection`.
+
+This policy provides compatibility for projects, toolchain files, and
+build scripts that have not been ported away from using
+:variable:`CMAKE_SYSTEM_VERSION` to specify an exact SDK version.
+
+The ``OLD`` behavior for this policy is to use the exact value of
+:variable:`CMAKE_SYSTEM_VERSION` if possible.  The ``NEW`` behavior
+for this policy is to ignore it.
+
+This policy was introduced in CMake version 3.27.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst
index 4a3ef47..d69bb7b 100644
--- a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst
+++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst
@@ -15,6 +15,9 @@ VS 2015 and above support specification of a Windows SDK version:
 * Otherwise, if :variable:`CMAKE_SYSTEM_VERSION` is set to an available
   SDK version, that version is selected.
 
+  .. versionchanged:: 3.27
+    This is disabled by policy :policy:`CMP0149`.
+
 * Otherwise, CMake uses the latest Windows SDK version available.
 
 The chosen Windows target version number is provided
diff --git a/Source/cmGlobalVisualStudio14Generator.cxx b/Source/cmGlobalVisualStudio14Generator.cxx
index 57082f4..0f9a334 100644
--- a/Source/cmGlobalVisualStudio14Generator.cxx
+++ b/Source/cmGlobalVisualStudio14Generator.cxx
@@ -12,6 +12,7 @@
 #include "cmGlobalVisualStudioGenerator.h"
 #include "cmMakefile.h"
 #include "cmMessageType.h"
+#include "cmPolicies.h"
 #include "cmStringAlgorithms.h"
 #include "cmSystemTools.h"
 #include "cmValue.h"
@@ -436,10 +437,12 @@ std::string cmGlobalVisualStudio14Generator::GetWindows10SDKVersion(
     return std::string();
   }
 
-  // Look for a SDK exactly matching the target Windows version.
-  for (std::string const& i : sdks) {
-    if (cmSystemTools::VersionCompareEqual(i, this->SystemVersion)) {
-      return i;
+  if (mf->GetPolicyStatus(cmPolicies::CMP0149) != cmPolicies::NEW) {
+    // Look for a SDK exactly matching the target Windows version.
+    for (std::string const& i : sdks) {
+      if (cmSystemTools::VersionCompareEqual(i, this->SystemVersion)) {
+        return i;
+      }
     }
   }
 
diff --git a/Source/cmPolicies.h b/Source/cmPolicies.h
index 37d697f..fe88382 100644
--- a/Source/cmPolicies.h
+++ b/Source/cmPolicies.h
@@ -447,6 +447,9 @@ class cmMakefile;
          27, 0, cmPolicies::WARN)                                             \
   SELECT(POLICY, CMP0148,                                                     \
          "The FindPythonInterp and FindPythonLibs modules are removed.", 3,   \
+         27, 0, cmPolicies::WARN)                                             \
+  SELECT(POLICY, CMP0149,                                                     \
+         "Visual Studio generators select latest Windows SDK by default.", 3, \
          27, 0, cmPolicies::WARN)
 
 #define CM_SELECT_ID(F, A1, A2, A3, A4, A5, A6) F(A1)
diff --git a/Tests/RunCMake/GeneratorPlatform/RunCMakeTest.cmake b/Tests/RunCMake/GeneratorPlatform/RunCMakeTest.cmake
index 96c2b6b..ffd105c 100644
--- a/Tests/RunCMake/GeneratorPlatform/RunCMakeTest.cmake
+++ b/Tests/RunCMake/GeneratorPlatform/RunCMakeTest.cmake
@@ -88,5 +88,16 @@ if("${RunCMake_GENERATOR}" MATCHES "^Visual Studio (1[4567])( 20[0-9][0-9])?$")
       run_cmake_with_options(VersionExists -DCMAKE_SYSTEM_VERSION=10.0)
       unset(RunCMake_GENERATOR_PLATFORM)
     endforeach()
+    foreach(expect_version IN LISTS kits)
+      set(RunCMake_TEST_VARIANT_DESCRIPTION "-CMP0149-OLD-${expect_version}")
+      run_cmake_with_options(VersionExists -DCMAKE_SYSTEM_VERSION=${expect_version} -DCMAKE_POLICY_DEFAULT_CMP0149=OLD)
+    endforeach()
+    if(kits MATCHES "(^|;)([0-9.]+)$")
+      set(expect_version "${CMAKE_MATCH_2}")
+      foreach(test_version IN LISTS kits)
+        set(RunCMake_TEST_VARIANT_DESCRIPTION "-CMP0149-NEW-${test_version}")
+        run_cmake_with_options(VersionExists -DCMAKE_SYSTEM_VERSION=${test_version} -DCMAKE_POLICY_DEFAULT_CMP0149=NEW)
+      endforeach()
+    endif()
   endif()
 endif()
diff --git a/Tests/RunCMake/GeneratorPlatform/VersionExists.cmake b/Tests/RunCMake/GeneratorPlatform/VersionExists.cmake
index 0d7a9ba..5369ca0 100644
--- a/Tests/RunCMake/GeneratorPlatform/VersionExists.cmake
+++ b/Tests/RunCMake/GeneratorPlatform/VersionExists.cmake
@@ -1 +1,4 @@
+cmake_policy(GET CMP0149 cmp0149)
+message(STATUS "CMP0149='${cmp0149}'")
+message(STATUS "CMAKE_SYSTEM_VERSION='${CMAKE_SYSTEM_VERSION}'")
 message(STATUS "CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION='${CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION}'")