VS: Select Windows SDK matching WindowsSDKVersion env var

In an environment established by `vcvarsall.bat` or similar, this
environment variable may be set to select a Windows SDK version.
If the VS generator is used in such an environment, use that SDK.
This is similar to how `CMAKE_GENERATOR_INSTANCE` defaults using
a `VS##0COMNTOOLS` environment variable.

Fixes: #17992

Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst

@@ -12,6 +12,14 @@ VS 2015 and above support specification of a Windows SDK version:
   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.
 

Source/cmGlobalVisualStudio14Generator.cxx

@@ -437,7 +437,17 @@ std::string cmGlobalVisualStudio14Generator::GetWindows10SDKVersion(
     return std::string();
   }
 
-  if (mf->GetPolicyStatus(cmPolicies::CMP0149) != cmPolicies::NEW) {
+  if (mf->GetPolicyStatus(cmPolicies::CMP0149) == cmPolicies::NEW) {
+    if (cm::optional<std::string> const envVer =
+          cmSystemTools::GetEnvVar("WindowsSDKVersion")) {
+      // Look for a SDK exactly matching the environment variable.
+      for (std::string const& i : sdks) {
+        if (cmSystemTools::VersionCompareEqual(i, *envVer)) {
+          return i;
+        }
+      }
+    }
+  } else {
     // Look for a SDK exactly matching the target Windows version.
     for (std::string const& i : sdks) {
       if (cmSystemTools::VersionCompareEqual(i, this->SystemVersion)) {

Tests/RunCMake/GeneratorPlatform/RunCMakeTest.cmake

@@ -28,6 +28,8 @@ else()
 endif()
 
 if("${RunCMake_GENERATOR}" MATCHES "^Visual Studio (1[4567])( 20[0-9][0-9])?$")
+  unset(ENV{WindowsSDKVersion})
+
   set(RunCMake_GENERATOR_PLATFORM "Test Platform,nocomma")
   run_cmake(BadFieldNoComma)
   set(RunCMake_GENERATOR_PLATFORM "Test Platform,unknown=")
@@ -99,5 +101,11 @@ if("${RunCMake_GENERATOR}" MATCHES "^Visual Studio (1[4567])( 20[0-9][0-9])?$")
         run_cmake_with_options(VersionExists -DCMAKE_SYSTEM_VERSION=${test_version} -DCMAKE_POLICY_DEFAULT_CMP0149=NEW)
       endforeach()
     endif()
+    foreach(expect_version IN LISTS kits)
+      set(RunCMake_TEST_VARIANT_DESCRIPTION "-WindowsSDKVersion-${expect_version}")
+      set(ENV{WindowsSDKVersion} "${expect_version}\\")
+      run_cmake_with_options(VersionExists -DCMAKE_SYSTEM_VERSION=10.0 -DCMAKE_POLICY_DEFAULT_CMP0149=NEW)
+      unset(ENV{WindowsSDKVersion})
+    endforeach()
   endif()
 endif()

Tests/RunCMake/GeneratorPlatform/VersionExists.cmake

@@ -1,4 +1,5 @@
 cmake_policy(GET CMP0149 cmp0149)
 message(STATUS "CMP0149='${cmp0149}'")
 message(STATUS "CMAKE_SYSTEM_VERSION='${CMAKE_SYSTEM_VERSION}'")
+message(STATUS "ENV{WindowsSDKVersion}='$ENV{WindowsSDKVersion}'")
 message(STATUS "CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION='${CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION}'")