15 files changed, 184 insertions, 28 deletions
diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst
index 0ccebc679b..869d0c2ced 100644
--- a/Help/command/add_compile_options.rst
+++ b/Help/command/add_compile_options.rst
@@ -11,6 +11,11 @@ Adds options to the :prop_dir:`COMPILE_OPTIONS` directory property.
 These options are used when compiling targets from the current
 directory and below.
 
+.. note::
+
+  These options are not used when linking.
+  See the :command:`add_link_options` command for that.
+
 Arguments
 ^^^^^^^^^
 
@@ -48,5 +53,15 @@ See Also
 
 * The command :command:`target_compile_options` adds target-specific options.
 
+* This command adds compile options for all languages.
+  Use the :genex:`COMPILE_LANGUAGE` generator expression to specify
+  per-language compile options.
+
 * The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one
   source file.
+
+* :command:`add_link_options` adds options for linking.
+
+* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
+  add language-wide flags passed to all invocations of the compiler.
+  This includes invocations that drive compiling and those that drive linking.
diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst
index c09e106908..df72715431 100644
--- a/Help/command/add_link_options.rst
+++ b/Help/command/add_link_options.rst
@@ -38,3 +38,7 @@ See Also
 * :command:`link_libraries`
 * :command:`target_link_libraries`
 * :command:`target_link_options`
+
+* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
+  add language-wide flags passed to all invocations of the compiler.
+  This includes invocations that drive compiling and those that drive linking.
diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst
index f3ac97bd09..7cfb24b18f 100644
--- a/Help/command/target_compile_options.rst
+++ b/Help/command/target_compile_options.rst
@@ -15,6 +15,11 @@ are used when compiling the given ``<target>``, which must have been
 created by a command such as :command:`add_executable` or
 :command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`.
 
+.. note::
+
+  These options are not used when linking the target.
+  See the :command:`target_link_options` command for that.
+
 Arguments
 ^^^^^^^^^
 
@@ -60,3 +65,7 @@ See Also
 * :command:`target_link_options`
 * :command:`target_precompile_headers`
 * :command:`target_sources`
+
+* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
+  add language-wide flags passed to all invocations of the compiler.
+  This includes invocations that drive compiling and those that drive linking.
diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst
index 0d026f2456..dca9598611 100644
--- a/Help/command/target_link_options.rst
+++ b/Help/command/target_link_options.rst
@@ -62,3 +62,7 @@ See Also
 * :command:`target_link_directories`
 * :command:`target_precompile_headers`
 * :command:`target_sources`
+
+* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
+  add language-wide flags passed to all invocations of the compiler.
+  This includes invocations that drive compiling and those that drive linking.
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. </policy/CMP0149>
    CMP0148: The FindPythonInterp and FindPythonLibs modules are removed. </policy/CMP0148>
    CMP0147: Visual Studio generators build custom commands in parallel. </policy/CMP0147>
    CMP0146: The FindCUDA module is removed. </policy/CMP0146>
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/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/prop_tgt/COMPILE_OPTIONS.rst b/Help/prop_tgt/COMPILE_OPTIONS.rst
index 0dec25015d..8b032adeee 100644
--- a/Help/prop_tgt/COMPILE_OPTIONS.rst
+++ b/Help/prop_tgt/COMPILE_OPTIONS.rst
@@ -6,7 +6,7 @@ List of options to pass to the compiler.
 This property holds a :ref:`semicolon-separated list <CMake Language Lists>`
 of options specified so far for its target.  Use the
 :command:`target_compile_options` command to append more options.
-The options will be added after after flags in the
+The options will be added after flags in the
 :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
 variables, but before those propagated from dependencies by the
 :prop_tgt:`INTERFACE_COMPILE_OPTIONS` property.
diff --git a/Help/release/3.26.rst b/Help/release/3.26.rst
index 67ace4a459..9e9327ea57 100644
--- a/Help/release/3.26.rst
+++ b/Help/release/3.26.rst
@@ -175,8 +175,8 @@ Updates
 
 Changes made since CMake 3.26.0 include the following.
 
-3.26.1, 3.26.2
---------------
+3.26.1, 3.26.2, 3.26.3
+----------------------
 
 * These versions made no changes to documented features or interfaces.
   Some implementation updates were made to support ecosystem changes
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 acb7b2e1a2..416ff60f34 100644
--- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
+++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
@@ -26,8 +26,46 @@ 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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-On :ref:`Visual Studio Generators` the selected platform name
-is provided in the :variable:`CMAKE_VS_PLATFORM_NAME` variable.
+The :ref:`Visual Studio Generators` support platform specification
+using one of these forms:
+
+* ``platform``
+* ``platform[,key=value]*``
+* ``key=value[,key=value]*``
+
+The ``platform`` specifies the target platform (VS target architecture),
+such as ``x64``, ``ARM64``, or ``Win32``.  The selected platform
+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.
+Supported pairs are:
+
+``version=<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 ``<version>`` may be one of:
+
+  ``10.0``
+    Specify that any 10.0 SDK version may be used, and let Visual Studio
+    pick one.  This is supported by VS 2019 and above.
+
+  ``10.0.<build>.<increment>``
+    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_LANG_FLAGS.rst b/Help/variable/CMAKE_LANG_FLAGS.rst
index 4b39b1deff..909a001a9c 100644
--- a/Help/variable/CMAKE_LANG_FLAGS.rst
+++ b/Help/variable/CMAKE_LANG_FLAGS.rst
@@ -1,9 +1,10 @@
 CMAKE_<LANG>_FLAGS
 ------------------
 
-Flags for all build types.
-
-``<LANG>`` flags used regardless of the value of :variable:`CMAKE_BUILD_TYPE`.
+Language-wide flags for language ``<LANG>`` used when building for
+all configurations.  These flags will be passed to all invocations
+of the compiler.  This includes invocations that drive compiling
+and those that drive linking.
 
 For each language, if this variable is not defined, it is initialized
 and stored in the cache using values from environment variables in
@@ -27,7 +28,10 @@ combination with CMake's builtin defaults for the toolchain:
 This value is a command-line string fragment. Therefore, multiple options
 should be separated by spaces, and options with spaces should be quoted.
 
-The flags in this variable will be passed to the compiler before those
-in the per-configuration :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variant,
-and before flags added by the :command:`add_compile_options` or
-:command:`target_compile_options` commands.
+The flags in this variable will be passed before those in the
+per-configuration :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable.
+On invocations driving compiling, flags from both variables will be passed
+before flags added by commands such as :command:`add_compile_options` and
+:command:`target_compile_options`. On invocations driving linking,
+they will be passed before flags added by commands such as
+:command:`add_link_options` and :command:`target_link_options`.
diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst
index f0900fdc8d..5daa4c06a1 100644
--- a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst
+++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst
@@ -1,9 +1,16 @@
 CMAKE_<LANG>_FLAGS_<CONFIG>
 ---------------------------
 
-Flags for language ``<LANG>`` when building for the ``<CONFIG>`` configuration.
+Language-wide flags for language ``<LANG>`` used when building for
+the ``<CONFIG>`` configuration.  These flags will be passed to all
+invocations of the compiler in the corresponding configuration.
+This includes invocations that drive compiling and those that drive
+linking.
 
-The flags in this variable will be passed to the compiler after those
-in the :variable:`CMAKE_<LANG>_FLAGS` variable, but before flags added
-by the :command:`add_compile_options` or :command:`target_compile_options`
-commands.
+The flags in this variable will be passed after those in the
+:variable:`CMAKE_<LANG>_FLAGS` variable.  On invocations driving compiling,
+flags from both variables will be passed before flags added by commands
+such as :command:`add_compile_options` and :command:`target_compile_options`.
+On invocations driving linking, they will be passed before flags added by
+commands such as :command:`add_link_options` and
+:command:`target_link_options`.
diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst
index eb7104998a..2c14d3900d 100644
--- a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst
+++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst
@@ -5,11 +5,30 @@ 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 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.
+
+  .. 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
 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`.