From 2f3d945f8382fef4139c7d0c3879f6ff2f3756a0 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 3 Apr 2023 10:11:49 -0400 Subject: VS: Add CMAKE_GENERATOR_PLATFORM field to control Windows SDK selection Add a `version=` field to explicitly control the SDK version selection without relying on `CMAKE_SYSTEM_VERSION`. Fixes: #16713 --- Help/manual/cmake-toolchains.7.rst | 9 ++++---- Help/release/dev/vs-sdk-selection.rst | 7 +++++++ Help/variable/CMAKE_GENERATOR_PLATFORM.rst | 24 +++++++++++++++++++++- .../CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst | 18 +++++++++++----- ..._VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst | 4 ++-- 5 files changed, 50 insertions(+), 12 deletions(-) create mode 100644 Help/release/dev/vs-sdk-selection.rst (limited to 'Help') diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 9feb4d203a..a831fa6ef1 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/release/dev/vs-sdk-selection.rst b/Help/release/dev/vs-sdk-selection.rst new file mode 100644 index 0000000000..856a2033c5 --- /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 0238183d0d..3b6932a559 100644 --- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst +++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst @@ -26,6 +26,8 @@ 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -42,4 +44,24 @@ 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. -There are no supported pairs: this syntax is reserved for future use. +Supported pairs are: + +``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 ```` may be one of: + + ``10.0..`` + 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 eb7104998a..4a3ef4714d 100644 --- a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst +++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst @@ -5,11 +5,19 @@ 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 :variable:`CMAKE_SYSTEM_VERSION` is set to an available + SDK version, that version is selected. + +* 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 f1a1977448..727ccc95be 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`. -- cgit v1.2.1