VS: Add option for custom Win10 SDK version maximum

Since commit 83ddc4d289 (VS: Do not select a Windows SDK too high for
current VS version, 2017-08-07, v3.13.0-rc1~72^2~2) we enforce a maximum
SDK version for the VS 2015 generator.  The blog post linked in the
original commit is no longer available, but it can be seen here:

* https://web.archive.org/web/20190108032520/https://blogs.msdn.microsoft.com/chuckw/2018/10/02/windows-10-october-2018-update/

In particular, it states:

> VS 2015 Users: The Windows 10 SDK (15063, 16299, 17134, 17763)
> is officially only supported for VS 2017.

However, in some circumstances a higher version can be used.

Add a `CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` to override the
generator's default maximum SDK version.

Fixes: #20633

5 files changed, 39 insertions, 0 deletions

diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst
index 401845d..5b319bb 100644
--- a/Help/generator/Visual Studio 14 2015.rst
+++ b/Help/generator/Visual Studio 14 2015.rst
@@ -45,3 +45,19 @@ via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
    By default this generator uses the 32-bit variant even on a 64-bit host.
 
 .. include:: VS_TOOLSET_HOST_ARCH.txt
+
+.. _`Windows 10 SDK Maximum Version for VS 2015`:
+
+Windows 10 SDK Maximum Version for VS 2015
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Microsoft stated in a "Windows 10 October 2018 Update" blog post that Windows
+10 SDK versions (15063, 16299, 17134, 17763) are not supported by VS 2015 and
+are only supported by VS 2017 and later.  Therefore by default CMake
+automatically ignores Windows 10 SDKs beyond ``10.0.14393.0``.
+
+However, there are other recommendations for certain driver/Win32 builds that
+indicate otherwise.  A user can override this behavior by either setting the
+:variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` to a false value
+or setting the :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` to
+the string value of the required maximum (e.g. ``10.0.15063.0``).
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 4b40917..53cdd0b 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -124,6 +124,7 @@ Variables that Provide Information
    /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE
    /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION
    /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
+   /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM
    /variable/CMAKE_XCODE_GENERATE_SCHEME
    /variable/CMAKE_XCODE_PLATFORM_TOOLSET
    /variable/PROJECT-NAME_BINARY_DIR
diff --git a/Help/release/dev/vs-win-sdk-custom-max.rst b/Help/release/dev/vs-win-sdk-custom-max.rst
new file mode 100644
index 0000000..bd19fc8
--- /dev/null
+++ b/Help/release/dev/vs-win-sdk-custom-max.rst
@@ -0,0 +1,6 @@
+vs-win-sdk-custom-max
+---------------------
+
+* A :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable
+  was added to tell the :ref:`Visual Studio Generators` what maximumm
+  version of the Windows SDK to choose.
diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst
index cb55bc2..eb71049 100644
--- a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst
+++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst
@@ -17,3 +17,5 @@ One may set a ``CMAKE_WINDOWS_KITS_10_DIR`` *environment variable*
 to an absolute path to tell CMake to look for Windows 10 SDKs in
 a custom location.  The specified directory is expected to contain
 ``Include/10.0.*`` directories.
+
+See also :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM`.
diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst
new file mode 100644
index 0000000..591ea91
--- /dev/null
+++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst
@@ -0,0 +1,14 @@
+CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM
+------------------------------------------------
+
+.. versionadded:: 3.19
+
+Override the :ref:`Windows 10 SDK Maximum Version for VS 2015`.
+
+The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable may
+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`.