VS: Teach CMAKE_GENERATOR_PLATFORM to support Windows 8.1 SDK selection

Honor an explicit `version=8.1` field value regardless of the Windows
target version.

Issue: #25170

4 files changed, 40 insertions, 0 deletions

diff --git a/Help/release/3.27.rst b/Help/release/3.27.rst
index a8218ba..9b9db83 100644
--- a/Help/release/3.27.rst
+++ b/Help/release/3.27.rst
@@ -271,3 +271,11 @@ Changes made since CMake 3.27.0 include the following.
 * This version made no changes to documented features or interfaces.
   Some implementation updates were made to support ecosystem changes
   and/or fix regressions.
+
+3.27.2
+------
+
+* :ref:`Visual Studio Generators` for VS 14 (2015) and above now support
+  using ``version=8.1`` in the :variable:`CMAKE_GENERATOR_PLATFORM` variable
+  to select the Windows 8.1 SDK.  In CMake 3.27.[0-1] the ``version=`` field
+  was limited to selecting Windows 10 SDKs.
diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
index 7fbf6ba..22bf655 100644
--- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
+++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
@@ -66,6 +66,10 @@ Supported pairs are:
     the value of :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM`,
     if that variable is set.
 
+  ``8.1``
+    Specify the 8.1 SDK version.  This is always supported by VS 2015.
+    On VS 2017 and above the 8.1 SDK must be installed.
+
   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/Source/cmGlobalVisualStudio14Generator.cxx b/Source/cmGlobalVisualStudio14Generator.cxx
index 8e8062c..506a12a 100644
--- a/Source/cmGlobalVisualStudio14Generator.cxx
+++ b/Source/cmGlobalVisualStudio14Generator.cxx
@@ -167,6 +167,23 @@ bool cmGlobalVisualStudio14Generator::InitializePlatformWindows(cmMakefile* mf)
       return this->SelectWindows10SDK(mf);
     }
 
+    if (version == "8.1"_s) {
+      if (this->IsWin81SDKInstalled()) {
+        this->SetWindowsTargetPlatformVersion("8.1", mf);
+        return true;
+      }
+      /* clang-format off */
+      mf->IssueMessage(MessageType::FATAL_ERROR, cmStrCat(
+          "Generator\n"
+          "  ", this->GetName(), "\n"
+          "given platform specification containing a\n"
+          "  version=8.1\n"
+          "field, but the Windows 8.1 SDK is not installed.\n"
+          ));
+      /* clang-format on */
+      return false;
+    }
+
     if (version.empty()) {
       /* clang-format off */
       mf->IssueMessage(MessageType::FATAL_ERROR, cmStrCat(
diff --git a/Tests/RunCMake/GeneratorPlatform/RunCMakeTest.cmake b/Tests/RunCMake/GeneratorPlatform/RunCMakeTest.cmake
index 5c1689a..7620b13 100644
--- a/Tests/RunCMake/GeneratorPlatform/RunCMakeTest.cmake
+++ b/Tests/RunCMake/GeneratorPlatform/RunCMakeTest.cmake
@@ -65,6 +65,16 @@ if("${RunCMake_GENERATOR}" MATCHES "^Visual Studio (1[4567])( 20[0-9][0-9])?$")
     file(GLOB kits RELATIVE "${kitsInclude}" "${kitsInclude}/*/um/windows.h")
     list(TRANSFORM kits REPLACE "/.*" "")
   endif()
+  cmake_host_system_information(RESULT kitsRoot81
+    QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Microsoft/Windows Kits/Installed Roots"
+    VALUE "KitsRoot81"
+    VIEW 64_32
+    ERROR_VARIABLE kitsRoot81Error
+    )
+  if(NOT kitsRoot81Error AND EXISTS "${kitsRoot81}/include/um/windows.h")
+    list(PREPEND kits "8.1")
+  endif()
+
   if(kits)
     message(STATUS "Available Kits: ${kits}")
     if(RunCMake_GENERATOR MATCHES "^Visual Studio 14 ")
@@ -93,6 +103,7 @@ 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()
+  list(REMOVE_ITEM kits 8.1)
   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)