From f90c8ab54ebd751600f525a3e548841e6aa16049 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 3 Apr 2023 11:12:18 -0400 Subject: 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 --- Help/manual/cmake-policies.7.rst | 1 + Help/policy/CMP0149.rst | 47 ++++++++++++++++++++++ .../CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst | 3 ++ 3 files changed, 51 insertions(+) create mode 100644 Help/policy/CMP0149.rst (limited to 'Help') 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. CMP0148: The FindPythonInterp and FindPythonLibs modules are removed. CMP0147: Visual Studio generators build custom commands in parallel. CMP0146: The FindCUDA module is removed. 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 -- cgit v1.2.1