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

3 files changed, 51 insertions, 0 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 158bf62155..8c7189a72b 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 0000000000..714eeaff2b
--- /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 4a3ef4714d..d69bb7b274 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