Merge topic 'vs-sdk-selection'

8ecb645934 VS: Select Windows SDK matching WindowsSDKVersion env var
f90c8ab54e VS: Select latest available Windows SDK version by default
b512c53d43 VS: Add support for setting WindowsTargetPlatformVersion to 10.0
2f3d945f83 VS: Add CMAKE_GENERATOR_PLATFORM field to control Windows SDK selection
f0a67b6291 VS: Parse comma-separated fields from CMAKE_GENERATOR_PLATFORM
e259063b0a VS: Defer Windows SDK selection until CMAKE_GENERATOR_PLATFORM is known
8499374c6a VS: Simplify logic to require SDK for Windows Store
1c8d4b4bf1 Tests: Teach RunCMake_TEST_FILTER to account for test variant description

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !8389

7 files changed, 126 insertions, 13 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/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst
index 9feb4d2..a831fa6 100644
--- a/Help/manual/cmake-toolchains.7.rst
+++ b/Help/manual/cmake-toolchains.7.rst
@@ -273,7 +273,7 @@ supported out of the box.  Other versions may require one to set
 Cross Compiling for Windows 10 Universal Applications
 -----------------------------------------------------
 
-A toolchain file to configure a Visual Studio generator for a
+A toolchain file to configure :ref:`Visual Studio Generators` for a
 Windows 10 Universal Application may look like this:
 
 .. code-block:: cmake
@@ -283,9 +283,10 @@ Windows 10 Universal Application may look like this:
 
 A Windows 10 Universal Application targets both Windows Store and
 Windows Phone.  Specify the :variable:`CMAKE_SYSTEM_VERSION` variable
-to be ``10.0`` to build with the latest available Windows 10 SDK.
-Specify a more specific version (e.g. ``10.0.10240.0`` for RTM)
-to build with the corresponding SDK.
+to be ``10.0`` or higher.
+
+CMake selects a Windows SDK as described by documentation of the
+:variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION` variable.
 
 Cross Compiling for Windows Phone
 ---------------------------------
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/release/dev/vs-sdk-selection.rst b/Help/release/dev/vs-sdk-selection.rst
new file mode 100644
index 0000000..856a203
--- /dev/null
+++ b/Help/release/dev/vs-sdk-selection.rst
@@ -0,0 +1,7 @@
+vs-sdk-selection
+----------------
+
+* The :ref:`Visual Studio Generators` for VS 2015 and above learned to
+  select the Windows SDK version explicitly using a ``version=`` field
+  in the :variable:`CMAKE_GENERATOR_PLATFORM` variable.
+  See :ref:`Visual Studio Platform Selection`.
diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
index acb7b2e..416ff60 100644
--- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
+++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
@@ -26,8 +26,46 @@ Platform specification is supported only on specific generators:
 
 See native build system documentation for allowed platform names.
 
+.. _`Visual Studio Platform Selection`:
+
 Visual Studio Platform Selection
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-On :ref:`Visual Studio Generators` the selected platform name
-is provided in the :variable:`CMAKE_VS_PLATFORM_NAME` variable.
+The :ref:`Visual Studio Generators` support platform specification
+using one of these forms:
+
+* ``platform``
+* ``platform[,key=value]*``
+* ``key=value[,key=value]*``
+
+The ``platform`` specifies the target platform (VS target architecture),
+such as ``x64``, ``ARM64``, or ``Win32``.  The selected platform
+name is provided in the :variable:`CMAKE_VS_PLATFORM_NAME` variable.
+
+The ``key=value`` pairs form a comma-separated list of options to
+specify generator-specific details of the platform selection.
+Supported pairs are:
+
+``version=<version>``
+  .. versionadded:: 3.27
+
+  Specify the Windows SDK version to use.  This is supported by VS 2015 and
+  above when targeting Windows 10.0+ or Windows Store.  CMake will set the
+  :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION` variable to the
+  selected SDK version.
+
+  The ``<version>`` may be one of:
+
+  ``10.0``
+    Specify that any 10.0 SDK version may be used, and let Visual Studio
+    pick one.  This is supported by VS 2019 and above.
+
+  ``10.0.<build>.<increment>``
+    Specify the exact 4-component SDK version, e.g., ``10.0.19041.0``.
+    The specified version of the SDK must be installed.  It may not exceed
+    the value of :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM`,
+    if that variable is set.
+
+  If the ``version`` field is not specified, CMake selects a version as
+  described in the :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION`
+  variable documentation.
diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst
index eb71049..2c14d39 100644
--- a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst
+++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst
@@ -5,11 +5,30 @@ CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
 
 Visual Studio Windows Target Platform Version.
 
-When targeting Windows 10 and above Visual Studio 2015 and above support
-specification of a target Windows version to select a corresponding SDK.
-The :variable:`CMAKE_SYSTEM_VERSION` variable may be set to specify a
-version.  Otherwise CMake computes a default version based on the Windows
-SDK versions available.  The chosen Windows target version number is provided
+When targeting Windows 10 and above, :ref:`Visual Studio Generators` for
+VS 2015 and above support specification of a Windows SDK version:
+
+* If :variable:`CMAKE_GENERATOR_PLATFORM` specifies a ``version=`` field,
+  as documented by :ref:`Visual Studio Platform Selection`, that SDK
+  version is selected.
+
+* Otherwise, if the ``WindowsSDKVersion`` environment variable
+  is set to an available SDK version, that version is selected.
+  This is intended for use in environments established by ``vcvarsall.bat``
+  or similar scripts.
+
+  .. versionadded:: 3.27
+    This is enabled by policy :policy:`CMP0149`.
+
+* 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
 in ``CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION``.  If no Windows 10 SDK
 is available this value will be empty.
 
diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst
index f1a1977..727ccc9 100644
--- a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst
+++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst
@@ -10,5 +10,5 @@ be set to a false value (e.g. ``OFF``, ``FALSE``, or ``0``) or the SDK version
 to use as the maximum (e.g. ``10.0.14393.0``).  If unset, the default depends
 on which version of Visual Studio is targeted by the current generator.
 
-This can be used in conjunction with :variable:`CMAKE_SYSTEM_VERSION`, which
-CMake uses to select :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION`.
+This can be used to exclude Windows SDK versions from consideration for
+:variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION`.