Update upstream source from tag 'upstream/3.28.0'

Update to upstream version '3.28.0' with Debian dir cb0702ba1e90278c648b80b54b19cb775fcc7733
2023-12-07 09:13:18 +01:00 · 2023-12-07 09:13:18 +01:00 · 1d6b45be38
commit 1d6b45be38
parent 65096aee45 cf677c087a
1685 changed files with 32832 additions and 21371 deletions
--- a/.clang-tidy
+++ b/.clang-tidy
@ -3,15 +3,18 @@ Checks: "-*,\
 bugprone-*,\
 -bugprone-assignment-in-if-condition,\
 -bugprone-easily-swappable-parameters,\
+-bugprone-empty-catch,\
 -bugprone-implicit-widening-of-multiplication-result,\
 -bugprone-macro-parentheses,\
 -bugprone-misplaced-widening-cast,\
 -bugprone-narrowing-conversions,\
+-bugprone-switch-missing-default-case,\
 -bugprone-too-small-loop-variable,\
 -bugprone-unchecked-optional-access,\
 misc-*,\
 -misc-confusable-identifiers,\
 -misc-const-correctness,\
+-misc-include-cleaner,\
 -misc-no-recursion,\
 -misc-non-private-member-variables-in-classes,\
 -misc-static-assert,\
@ -20,14 +23,18 @@ modernize-*,\
 -modernize-avoid-c-arrays,\
 -modernize-macro-to-enum,\
 -modernize-return-braced-init-list,\
+-modernize-type-traits,\
 -modernize-use-emplace,\
 -modernize-use-nodiscard,\
 -modernize-use-noexcept,\
 -modernize-use-trailing-return-type,\
 -modernize-use-transparent-functors,\
 performance-*,\
+-performance-avoid-endl,\
 -performance-inefficient-vector-operation,\
+-performance-noexcept-swap,\
 readability-*,\
+-readability-avoid-unconditional-preprocessor-if,\
 -readability-convert-member-functions-to-static,\
 -readability-function-cognitive-complexity,\
 -readability-function-size,\
@ -41,6 +48,7 @@ readability-*,\
 -readability-redundant-declaration,\
 -readability-redundant-member-init,\
 -readability-simplify-boolean-expr,\
+-readability-static-accessed-through-instance,\
 -readability-suspicious-call-argument,\
 -readability-uppercase-literal-suffix,\
 cmake-*,\
--- a/Auxiliary/vim/cmake.vim.in
+++ b/Auxiliary/vim/cmake.vim.in
@ -22,20 +22,20 @@ set cpo&vim
 syn region cmakeBracketArgument start="\[\z(=\?\|=[0-9]*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell

 syn region cmakeComment start="#" end="$" contains=cmakeTodo,@Spell
-syn region cmakeBracketComment start="#\[\z(=\?\|=[0-9]*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell
+syn region cmakeBracketComment start="\[\z(=*\)\[" end="\]\z1\]" contains=cmakeTodo,@Spell

 syn match cmakeEscaped /\(\\\\\|\\"\|\\n\|\\t\)/ contained
 syn region cmakeRegistry start="\[" end="]" contained oneline contains=cmakeTodo,cmakeEscaped

 syn region cmakeGeneratorExpression start="$<" end=">" contained oneline contains=cmakeVariableValue,cmakeProperty,cmakeGeneratorExpressions,cmakeTodo

-syn region cmakeString start='"' end='"' contained contains=cmakeTodo,cmakeVariableValue,cmakeEscaped
+syn region cmakeString start='"' end='"' contained contains=cmakeTodo,cmakeVariableValue,cmakeEscaped,@Spell

 syn region cmakeVariableValue start="${" end="}" contained oneline contains=cmakeVariable,cmakeTodo,cmakeVariableValue

 syn region cmakeEnvironment start="$ENV{" end="}" contained oneline contains=cmakeTodo

-syn region cmakeArguments start="(" end=")" contains=ALLBUT,cmakeGeneratorExpressions,cmakeCommand,cmakeCommandConditional,cmakeCommandRepeat,cmakeCommandDeprecated,cmakeCommandManuallyAdded,cmakeArguments,cmakeTodo
+syn region cmakeArguments start="(" end=")" contains=ALLBUT,cmakeGeneratorExpressions,cmakeCommand,cmakeCommandConditional,cmakeCommandRepeat,cmakeCommandDeprecated,cmakeCommandManuallyAdded,cmakeArguments,cmakeTodo,@Spell

 syn case match

--- a/Auxiliary/vim/extract-upper-case.pl
+++ b/Auxiliary/vim/extract-upper-case.pl
@ -16,10 +16,10 @@ my @modules;
 my %keywords; # command => keyword-list

 # find cmake/Modules/ | sed -rn 's/.*CMakeDetermine(.+)Compiler.cmake/\1/p' | sort
-my @languages = qw(ASM ASM_MASM ASM_NASM C CSharp CUDA CXX Fortran Java RC Swift);
+my @languages = qw(ASM ASM_MASM ASM_NASM C CSharp CUDA CXX Fortran Java RC Swift HIP);

 # unwanted upper-cases
-my %unwanted = map { $_ => 1 } qw(VS CXX IDE NOTFOUND NO_ DFOO DBAR NEW);
+my %unwanted = map { $_ => 1 } qw(VS CXX IDE NOTFOUND NO_ DFOO DBAR NEW GNU);
 	# cannot remove ALL - exists for add_custom_command

 # control-statements
@ -30,7 +30,7 @@ my %loop = map { $_ => 1 } qw(foreach while endforeach endwhile);
 my %deprecated = map { $_ => 1 } qw(build_name exec_program export_library_dependencies install_files install_programs install_targets link_libraries make_directory output_required_files remove subdir_depends subdirs use_mangled_mesa utility_source variable_requires write_file);

 # add some (popular) modules
-push @modules, "ExternalProject";
+push @modules, "ExternalProject", "FetchContent";

 # variables
 open(CMAKE, "$cmake --help-variable-list|") or die "could not run cmake";
--- a/Auxiliary/vim/syntax/cmake.vim
+++ b/Auxiliary/vim/syntax/cmake.vim
--- a/CMakeCPackOptions.cmake.in
+++ b/CMakeCPackOptions.cmake.in
@ -5,7 +5,7 @@
 if(CPACK_GENERATOR MATCHES "NSIS")
  set(CPACK_NSIS_INSTALL_ROOT "@CPACK_NSIS_INSTALL_ROOT@")

-  # set the install/unistall icon used for the installer itself
+  # set the install/uninstall icon used for the installer itself
  # There is a bug in NSI that does not handle full unix paths properly.
  set(CPACK_NSIS_MUI_ICON "@CMake_SOURCE_DIR@/Utilities/Release\\CMakeLogo.ico")
  set(CPACK_NSIS_MUI_UNIICON "@CMake_SOURCE_DIR@/Utilities/Release\\CMakeLogo.ico")
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@ -1,7 +1,7 @@
 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
 # file Copyright.txt or https://cmake.org/licensing for details.

-cmake_minimum_required(VERSION 3.13...3.25 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.13...3.26 FATAL_ERROR)
 set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake)
 set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake)

@ -131,6 +131,8 @@ if(CMake_BUILD_LTO)
  endif()
 endif()

+option(CMake_BUILD_PCH "Compile CMake with precompiled headers" OFF)
+
 # Check whether to build support for the debugger mode.
 if(NOT CMake_TEST_EXTERNAL_CMAKE)
  if(NOT DEFINED CMake_ENABLE_DEBUGGER)
@ -153,7 +155,6 @@ endif()
 # simply to improve readability of the main script
 #-----------------------------------------------------------------------
 macro(CMAKE_HANDLE_SYSTEM_LIBRARIES)
-  # Options have dependencies.
  include(CMakeDependentOption)

  # Allow the user to enable/disable all system utility library options by
@ -324,6 +325,9 @@ configure_file(.clang-tidy .clang-tidy COPYONLY)

 option(CMake_RUN_IWYU "Run include-what-you-use with the compiler." OFF)
 if(CMake_RUN_IWYU)
+  if(CMake_BUILD_PCH)
+    message(FATAL_ERROR "CMake_RUN_IWYU and CMake_BUILD_PCH are ON, but they are incompatible!")
+  endif()
  find_program(IWYU_COMMAND NAMES include-what-you-use iwyu)
  if(NOT IWYU_COMMAND)
    message(FATAL_ERROR "CMake_RUN_IWYU is ON but include-what-you-use is not found!")
--- a/Help/command/FIND_XXX.txt
+++ b/Help/command/FIND_XXX.txt
@ -211,7 +211,8 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
   setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``.

   * |SYSTEM_ENVIRONMENT_PATH_XXX|
-   * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX|
+
+   |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX|

 6. Search cmake variables defined in the Platform files
   for the current system.  The searching of ``CMAKE_INSTALL_PREFIX`` and
--- a/Help/command/add_custom_command.rst
+++ b/Help/command/add_custom_command.rst
@ -24,6 +24,7 @@ The first signature is for adding a custom command to produce an output:
                     [COMMENT comment]
                     [DEPFILE depfile]
                     [JOB_POOL job_pool]
+                     [JOB_SERVER_AWARE <bool>]
                     [VERBATIM] [APPEND] [USES_TERMINAL]
                     [COMMAND_EXPAND_LISTS]
                     [DEPENDS_EXPLICIT_ONLY])
@ -86,6 +87,11 @@ The options are:
    :ref:`Target-dependent expressions <Target-Dependent Queries>` are not
    permitted.

+  .. versionchanged:: 3.28
+    In targets using :ref:`file sets`, custom command byproducts are now
+    considered private unless they are listed in a non-private file set.
+    See policy :policy:`CMP0154`.
+
 ``COMMAND``
  Specify the command-line(s) to execute at build time.
  If more than one ``COMMAND`` is specified they will be executed in order,
@ -221,6 +227,19 @@ The options are:
  Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
  an error by ninja at build time.

+``JOB_SERVER_AWARE``
+  .. versionadded:: 3.28
+
+  Specify that the command is GNU Make job server aware.
+
+  For the :generator:`Unix Makefiles`, :generator:`MSYS Makefiles`, and
+  :generator:`MinGW Makefiles` generators this will add the ``+`` prefix to the
+  recipe line. See the `GNU Make Documentation`_ for more information.
+
+  This option is silently ignored by other generators.
+
+.. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html
+
 ``MAIN_DEPENDENCY``
  Specify the primary input source file to the command.  This is
  treated just like any value given to the ``DEPENDS`` option
@ -256,6 +275,11 @@ The options are:
    :ref:`Target-dependent expressions <Target-Dependent Queries>` are not
    permitted.

+  .. versionchanged:: 3.28
+    In targets using :ref:`file sets`, custom command outputs are now
+    considered private unless they are listed in a non-private file set.
+    See policy :policy:`CMP0154`.
+
 ``USES_TERMINAL``
  .. versionadded:: 3.2

@ -516,7 +540,7 @@ one of the keywords to make clear the behavior they expect.
  Because generator expressions can be used in custom commands,
  it is possible to define ``COMMAND`` lines or whole custom commands
  which evaluate to empty strings for certain configurations.
-  For **Visual Studio 11 2012 (and newer)** generators these command
+  For **Visual Studio 12 2013 (and newer)** generators these command
  lines or custom commands will be omitted for the specific
  configuration and no "empty-string-command" will be added.

--- a/Help/command/add_custom_target.rst
+++ b/Help/command/add_custom_target.rst
@ -12,6 +12,7 @@ Add a target with no output so it will always be built.
                    [WORKING_DIRECTORY dir]
                    [COMMENT comment]
                    [JOB_POOL job_pool]
+                    [JOB_SERVER_AWARE <bool>]
                    [VERBATIM] [USES_TERMINAL]
                    [COMMAND_EXPAND_LISTS]
                    [SOURCES src1 [src2...]])
@ -62,6 +63,11 @@ The options are:
    :ref:`Target-dependent expressions <Target-Dependent Queries>` are not
    permitted.

+  .. versionchanged:: 3.28
+    In custom targets using :ref:`file sets`, byproducts are now
+    considered private unless they are listed in a non-private file set.
+    See policy :policy:`CMP0154`.
+
 ``COMMAND``
  Specify the command-line(s) to execute at build time.
  If more than one ``COMMAND`` is specified they will be executed in order,
@ -146,6 +152,19 @@ The options are:
  Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
  an error by ninja at build time.

+``JOB_SERVER_AWARE``
+  .. versionadded:: 3.28
+
+  Specify that the command is GNU Make job server aware.
+
+  For the :generator:`Unix Makefiles`, :generator:`MSYS Makefiles`, and
+  :generator:`MinGW Makefiles` generators this will add the ``+`` prefix to the
+  recipe line. See the `GNU Make Documentation`_ for more information.
+
+  This option is silently ignored by other generators.
+
+.. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html
+
 ``SOURCES``
  Specify additional source files to be included in the custom target.
  Specified source files will be added to IDE project files for
--- a/Help/command/block.rst
+++ b/Help/command/block.rst
@ -21,7 +21,8 @@ scopes created by the ``block()`` command are removed.

  ``POLICIES``
    Create a new policy scope. This is equivalent to
-    :command:`cmake_policy(PUSH)`.
+    :command:`cmake_policy(PUSH)` with an automatic
+    :command:`cmake_policy(POP)` when leaving the block scope.

  ``VARIABLES``
    Create a new variable scope.
--- a/Help/command/cmake_host_system_information.rst
+++ b/Help/command/cmake_host_system_information.rst
@ -146,6 +146,13 @@ queried.  The list of queried values is stored in ``<variable>``.

  See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR`

+``MSYSTEM_PREFIX``
+  .. versionadded:: 3.28
+
+  Available only on Windows hosts.  In a MSYS or MinGW development
+  environment that sets the ``MSYSTEM`` environment variable, this
+  is its installation prefix.  Otherwise, this is the empty string.
+
 ``DISTRIB_INFO``
  .. versionadded:: 3.22

--- a/Help/command/cmake_language.rst
+++ b/Help/command/cmake_language.rst
@ -195,7 +195,7 @@ prints::
  Immediate Message
  Deferred Message

-The ``Cancelled Message`` is never printed because its command is
+The ``Canceled Message`` is never printed because its command is
 canceled.  The ``deferred_message`` variable reference is not evaluated
 until the call site, so it can be set after the deferred call is scheduled.

--- a/Help/command/cmake_policy.rst
+++ b/Help/command/cmake_policy.rst
@ -24,9 +24,8 @@ The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
 behavior.  While setting policies individually is supported, we
 encourage projects to set policies based on CMake versions:

-.. code-block:: cmake
-
-  cmake_policy(VERSION <min>[...<max>])
+.. signature:: cmake_policy(VERSION <min>[...<max>])
+  :target: VERSION

 .. versionadded:: 3.12
  The optional ``<max>`` version.
@ -57,10 +56,8 @@ command implicitly calls ``cmake_policy(VERSION)`` too.
 Setting Policies Explicitly
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

-.. code-block:: cmake
-
-  cmake_policy(SET CMP<NNNN> NEW)
-  cmake_policy(SET CMP<NNNN> OLD)
+.. signature:: cmake_policy(SET CMP<NNNN> NEW|OLD)
+  :target: SET

 Tell CMake to use the ``OLD`` or ``NEW`` behavior for a given policy.
 Projects depending on the old behavior of a given policy may silence a
@ -73,9 +70,8 @@ policy state to ``NEW``.
 Checking Policy Settings
 ^^^^^^^^^^^^^^^^^^^^^^^^

-.. code-block:: cmake
-
-  cmake_policy(GET CMP<NNNN> <variable>)
+.. signature:: cmake_policy(GET CMP<NNNN> <variable>)
+  :target: GET

 Check whether a given policy is set to ``OLD`` or ``NEW`` behavior.
 The output ``<variable>`` value will be ``OLD`` or ``NEW`` if the
@ -94,23 +90,27 @@ except when invoked with the ``NO_POLICY_SCOPE`` option
 The ``cmake_policy`` command provides an interface to manage custom
 entries on the policy stack:

-.. code-block:: cmake
+.. signature:: cmake_policy(PUSH)
+  :target: PUSH

-  cmake_policy(PUSH)
-  cmake_policy(POP)
+  Create a new entry on the policy stack.
+
+.. signature:: cmake_policy(POP)
+  :target: POP
+
+  Remove the last policy stack entry created with ``cmake_policy(PUSH)``.

 Each ``PUSH`` must have a matching ``POP`` to erase any changes.
 This is useful to make temporary changes to policy settings.
 Calls to the :command:`cmake_minimum_required(VERSION)`,
-``cmake_policy(VERSION)``, or ``cmake_policy(SET)`` commands
+:command:`cmake_policy(VERSION)`, or :command:`cmake_policy(SET)` commands
 influence only the current top of the policy stack.

 .. versionadded:: 3.25
-  The :command:`block` and :command:`endblock` commands offer a more flexible
+  The :command:`block(SCOPE_FOR POLICIES)` command offers a more flexible
  and more secure way to manage the policy stack. The pop action is done
-  automatically when the :command:`endblock` command is executed, so it avoid
-  to call the :command:`cmake_policy(POP)` command before each
-  :command:`return` command.
+  automatically when leaving the block scope, so there is no need to
+  precede each :command:`return` with a call to :command:`cmake_policy(POP)`.

  .. code-block:: cmake

--- a/Help/command/exec_program.rst
+++ b/Help/command/exec_program.rst
@ -1,6 +1,10 @@
 exec_program
 ------------

+.. versionchanged:: 3.28
+  This command is available only if policy :policy:`CMP0153` is not set to ``NEW``.
+  Port projects to the :command:`execute_process` command.
+
 .. deprecated:: 3.0

  Use the :command:`execute_process` command instead.
--- a/Help/command/export.rst
+++ b/Help/command/export.rst
@ -54,10 +54,7 @@ The options are:
  to support consumers using CMake versions older than 2.8.12.

 ``CXX_MODULES_DIRECTORY <directory>``
-
-  .. note ::
-
-    Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+  .. versionadded:: 3.28

  Export C++ module properties to files under the given directory. Each file
  will be named according to the target's export name (without any namespace).
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@ -981,6 +981,11 @@ Path Conversion
      if ``USERPROFILE`` is not defined.  On all other platforms, only ``HOME``
      is used.

+  .. versionchanged:: 3.28
+
+    All symlinks are resolved before collapsing ``../`` components.
+    See policy :policy:`CMP0152`.
+
 .. signature::
  file(RELATIVE_PATH <variable> <directory> <file>)

--- a/Help/command/find_file.rst
+++ b/Help/command/find_file.rst
@ -28,9 +28,11 @@ find_file

 .. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE``
   and ``PATH``.
-.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
-      ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
-      is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
+.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace::
+   On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
+   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
+   This behavior was removed by CMake 3.28.

 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
--- a/Help/command/find_library.rst
+++ b/Help/command/find_library.rst
@ -27,9 +27,11 @@ find_library

 .. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``LIB``
   and ``PATH``.
-.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
-      ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
-      is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
+.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace::
+   On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
+   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
+   This behavior was removed by CMake 3.28.

 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
@ -60,6 +62,10 @@ path to the framework ``<fullPath>/A.framework``.  When a full path to a
 framework is used as a library, CMake will use a ``-framework A``, and a
 ``-F<fullPath>`` to link the framework to the target.

+.. versionadded:: 3.28
+
+  The library found can now be a ``.xcframework`` folder.
+
 If the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable is set all
 search paths will be tested as normal, with the suffix appended, and with
 all matches of ``lib/`` replaced with
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@ -323,18 +323,27 @@ containing a configuration file:
 In all cases the ``<name>`` is treated as case-insensitive and corresponds
 to any of the names specified (``<PackageName>`` or names given by ``NAMES``).

-Paths with ``lib/<arch>`` are enabled if the
-:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. ``lib*`` includes one
-or more of the values ``lib64``, ``lib32``, ``libx32`` or ``lib`` (searched in
-that order).
+If at least one compiled language has been enabled, the architecture-specific
+``lib/<arch>`` and ``lib*`` directories may be searched based on the compiler's
+target architecture, in the following order:

-* Paths with ``lib64`` are searched on 64 bit platforms if the
+``lib/<arch>``
+  Searched if the :variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set.
+
+``lib64``
+  Searched on 64 bit platforms (:variable:`CMAKE_SIZEOF_VOID_P` is 8) and the
  :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` property is set to ``TRUE``.
-* Paths with ``lib32`` are searched on 32 bit platforms if the
+
+``lib32``
+  Searched on 32 bit platforms (:variable:`CMAKE_SIZEOF_VOID_P` is 4) and the
  :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` property is set to ``TRUE``.
-* Paths with ``libx32`` are searched on platforms using the x32 ABI
+
+``libx32``
+  Searched on platforms using the x32 ABI
  if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``.
-* The ``lib`` path is always searched.
+
+``lib``
+  Always searched.

 .. versionchanged:: 3.24
  On ``Windows`` platform, it is possible to include registry queries as part
@ -346,7 +355,7 @@ that order).
  ``REGISTRY_VIEW`` can be specified to manage ``Windows`` registry queries
  specified as part of ``PATHS`` and ``HINTS``.

-.. include:: FIND_XXX_REGISTRY_VIEW.txt
+  .. include:: FIND_XXX_REGISTRY_VIEW.txt

 If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each
 (``W``) or (``U``) directory entry one-by-one.
--- a/Help/command/find_path.rst
+++ b/Help/command/find_path.rst
@ -27,9 +27,11 @@ find_path

 .. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE``
   and ``PATH``.
-.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts:
-      ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
-      is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
+.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace::
+   On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
+   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
+   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
+   This behavior was removed by CMake 3.28.

 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
--- a/Help/command/find_program.rst
+++ b/Help/command/find_program.rst
@ -23,7 +23,7 @@ find_program
 .. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_APPBUNDLE_PATH`

 .. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` itself.
-.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: On Windows hosts no extra search paths are included
+.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: \

 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
   |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
--- a/Help/command/get_property.rst
+++ b/Help/command/get_property.rst
@ -12,7 +12,8 @@ Get a property.
                SOURCE    <source>
                          [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
                INSTALL   <file>   |
-                TEST      <test>   |
+                TEST      <test>
+                          [DIRECTORY <dir>] |
                CACHE     <entry>  |
                VARIABLE           >
               PROPERTY <name>
@ -73,6 +74,16 @@ It must be one of the following:
  Scope must name one existing test.
  See also the :command:`get_test_property` command.

+  .. versionadded:: 3.28
+    Directory scope can be overridden with the following sub-option:
+
+    ``DIRECTORY <dir>``
+      The test property will be read from the ``<dir>`` directory's
+      scope.  CMake must already know about the directory, either by having added
+      it through a call to :command:`add_subdirectory` or ``<dir>`` being the top
+      level directory. Relative paths are treated as relative to the current
+      source directory. ``<dir>`` may reference a binary directory.
+
 ``CACHE``
  Scope must name one cache entry.

--- a/Help/command/get_test_property.rst
+++ b/Help/command/get_test_property.rst
@ -5,7 +5,7 @@ Get a property of the test.

 .. code-block:: cmake

-  get_test_property(test property VAR)
+  get_test_property(test property [DIRECTORY <dir>] VAR)

 Get a property from the test.  The value of the property is stored in
 the variable ``VAR``.  If the test property is not found, the behavior
@ -19,6 +19,17 @@ an empty string.
 For a list of standard properties you can type
 :option:`cmake --help-property-list`.

+.. versionadded:: 3.28
+  Directory scope can be overridden with the following sub-option:
+
+  ``DIRECTORY <dir>``
+    The test property will be read from the ``<dir>`` directory's
+    scope.  CMake must already know about that source directory, either by
+    having added it through a call to :command:`add_subdirectory` or ``<dir>``
+    being the top level source directory.  Relative paths are treated as
+    relative to the current source directory. ``<dir>`` may reference a binary
+    directory.
+
 See Also
 ^^^^^^^^

--- a/Help/command/if.rst
+++ b/Help/command/if.rst
@ -228,36 +228,36 @@ Comparisons
 .. signature:: if(<variable|string> LESS <variable|string>)
  :target: LESS

-  True if the given string or variable's value is a valid number and less
-  than that on the right.
+  True if the given string or variable's value parses as a real number
+  (like a C ``double``) and less than that on the right.

 .. signature:: if(<variable|string> GREATER <variable|string>)
  :target: GREATER

-  True if the given string or variable's value is a valid number and greater
-  than that on the right.
+  True if the given string or variable's value parses as a real number
+  (like a C ``double``) and greater than that on the right.

 .. signature:: if(<variable|string> EQUAL <variable|string>)
  :target: EQUAL

-  True if the given string or variable's value is a valid number and equal
-  to that on the right.
+  True if the given string or variable's value parses as a real number
+  (like a C ``double``) and equal to that on the right.

 .. signature:: if(<variable|string> LESS_EQUAL <variable|string>)
  :target: LESS_EQUAL

  .. versionadded:: 3.7

-  True if the given string or variable's value is a valid number and less
-  than or equal to that on the right.
+  True if the given string or variable's value parses as a real number
+  (like a C ``double``) and less than or equal to that on the right.

 .. signature:: if(<variable|string> GREATER_EQUAL <variable|string>)
  :target: GREATER_EQUAL

  .. versionadded:: 3.7

-  True if the given string or variable's value is a valid number and greater
-  than or equal to that on the right.
+  True if the given string or variable's value parses as a real number
+  (like a C ``double``) and greater than or equal to that on the right.

 .. signature:: if(<variable|string> STRLESS <variable|string>)
  :target: STRLESS
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
--- a/Help/command/set.rst
+++ b/Help/command/set.rst
@ -27,11 +27,12 @@ Set Normal Variable
  If the ``PARENT_SCOPE`` option is given the variable will be set in
  the scope above the current scope.  Each new directory or :command:`function`
  command creates a new scope.  A scope can also be created with the
-  :command:`block` command. This command will set the value of a variable into
-  the parent directory, calling function or encompassing scope (whichever is
-  applicable to the case at hand). The previous state of the variable's value
-  stays the same in the current scope (e.g., if it was undefined before, it is
-  still undefined and if it had a value, it is still that value).
+  :command:`block` command. ``set(PARENT_SCOPE)`` will set the value
+  of a variable into the parent directory, calling function, or
+  encompassing scope (whichever is applicable to the case at hand).
+  The previous state of the variable's value stays the same in the
+  current scope (e.g., if it was undefined before, it is still undefined
+  and if it had a value, it is still that value).

  The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands
  can be used as an alternate method to the :command:`set(PARENT_SCOPE)`
--- a/Help/command/set_property.rst
+++ b/Help/command/set_property.rst
@ -12,7 +12,8 @@ Set a named property in a given scope.
                          [DIRECTORY <dirs> ...]
                          [TARGET_DIRECTORY <targets> ...] |
                INSTALL   [<file1> ...]     |
-                TEST      [<test1> ...]     |
+                TEST      [<test1> ...]
+                          [DIRECTORY <dir>] |
                CACHE     [<entry1> ...]    >
               [APPEND] [APPEND_STRING]
               PROPERTY <name> [<value1> ...])
@ -91,6 +92,17 @@ It must be one of the following:
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  for tests created by the :command:`add_test(NAME)` signature.

+  .. versionadded:: 3.28
+
+    Visibility can be set in other directory scopes using the following sub-option:
+
+    ``DIRECTORY <dir>``
+      The test property will be set in the ``<dir>`` directory's scope. CMake must
+      already know about this directory, either by having added it through a call
+      to :command:`add_subdirectory` or it being the top level source directory.
+      Relative paths are treated as relative to the current source directory.
+      ``<dir>`` may reference a binary directory.
+
 ``CACHE``
  Scope must name zero or more existing cache entries.

--- a/Help/command/set_tests_properties.rst
+++ b/Help/command/set_tests_properties.rst
@ -14,10 +14,20 @@ Test property values may be specified using
 :manual:`generator expressions <cmake-generator-expressions(7)>`
 for tests created by the :command:`add_test(NAME)` signature.

+.. versionadded:: 3.28
+  Visibility can be set in other directory scopes using the following option:
+
+  ``DIRECTORY <dir>``
+    The test properties will be set in the ``<dir>`` directory's scope.
+    CMake must already know about this directory, either by having added it
+    through a call to :command:`add_subdirectory` or it being the top level
+    source directory. Relative paths are treated as relative to the current
+    source directory. ``<dir>`` may reference a binary directory.
+
 See Also
 ^^^^^^^^

 * :command:`add_test`
 * :command:`define_property`
 * the more general :command:`set_property` command
-* :ref:`Target Properties` for the list of properties known to CMake
+* :ref:`Test Properties` for the list of properties known to CMake
--- a/Help/command/target_link_libraries.rst
+++ b/Help/command/target_link_libraries.rst
@ -66,6 +66,12 @@ Each ``<item>`` may be:
  :ref:`usage requirement <Target Usage Requirements>`.  This has the same
  effect as passing the framework directory as an include directory.

+  .. versionadded:: 3.28
+
+    The library file may point to a ``.xcframework`` folder on macOS. If it
+    does, the target will get the selected library's ``Headers`` directory as
+    a usage requirement.
+
  .. versionadded:: 3.8
    On :ref:`Visual Studio Generators` for VS 2010 and above, library files
    ending in ``.targets`` will be treated as MSBuild targets files and
--- a/Help/command/target_precompile_headers.rst
+++ b/Help/command/target_precompile_headers.rst
@ -33,7 +33,7 @@ property of ``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
 Repeated calls for the same ``<target>`` will append items in the order called.

 Projects should generally avoid using ``PUBLIC`` or ``INTERFACE`` for targets
-that will be :ref:`exported <install(EXPORT)>`, or they should at least use
+that will be :command:`exported <install(EXPORT)>`, or they should at least use
 the :genex:`$<BUILD_INTERFACE:...>` generator expression to prevent precompile
 headers from appearing in an installed exported target.  Consumers of a target
 should typically be in control of what precompile headers they use, not have
@ -94,7 +94,7 @@ Reusing Precompile Headers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^

 The command also supports a second signature which can be used to specify that
-one target re-uses a precompiled header file artifact from another target
+one target reuses a precompiled header file artifact from another target
 instead of generating its own:

 .. code-block:: cmake
--- a/Help/command/target_sources.rst
+++ b/Help/command/target_sources.rst
@ -60,6 +60,8 @@ expressions to ensure the sources are correctly assigned to the target.
 See the :manual:`cmake-buildsystem(7)` manual for more on defining
 buildsystem properties.

+.. _`File Sets`:
+
 File Sets
 ^^^^^^^^^

@ -82,10 +84,7 @@ files within those directories. The acceptable types include:
  Sources intended to be used via a language's ``#include`` mechanism.

 ``CXX_MODULES``
-
-  .. note ::
-
-    Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+  .. versionadded:: 3.28

  Sources which contain C++ interface module or partition units (i.e., those
  using the ``export`` keyword). This file set type may not have an
--- a/Help/command/try_compile.rst
+++ b/Help/command/try_compile.rst
@ -65,6 +65,7 @@ Try Compiling Source Files
 .. code-block:: cmake

  try_compile(<compileResultVar>
+              [SOURCES_TYPE <type>]
              <SOURCES <srcfile...>                 |
               SOURCE_FROM_CONTENT <name> <content> |
               SOURCE_FROM_VAR <name> <var>         |
@ -143,7 +144,12 @@ single output directory, such that you can only debug one such ``try_compile``
 call at a time.  Use of the newer signature is recommended to simplify
 debugging of multiple ``try_compile`` operations.

-The options are:
+.. _`try_compile Options`:
+
+Options
+^^^^^^^
+
+The options for the above signatures are:

 ``CMAKE_FLAGS <flags>...``
  Specify flags of the form :option:`-DVAR:TYPE=VALUE <cmake -D>` to be passed
@ -244,6 +250,24 @@ The options are:

  ``SOURCE_FROM_VAR`` may be specified multiple times.

+``SOURCES_TYPE <type>``
+  .. versionadded:: 3.28
+
+  Sources may be classified using the ``SOURCES_TYPE`` argument. Once
+  specified, all subsequent sources specified will be treated as that type
+  until another ``SOURCES_TYPE`` is given. Available types are:
+
+  ``NORMAL``
+    Sources are not added to any ``FILE_SET`` in the generated project.
+
+  ``CXX_MODULE``
+    .. versionadded:: 3.28
+
+    Sources are added to a ``FILE_SET`` of type ``CXX_MODULES`` in the
+    generated project.
+
+  The default type of sources is ``NORMAL``.
+
 ``<LANG>_STANDARD <std>``
  .. versionadded:: 3.8

--- a/Help/command/try_run.rst
+++ b/Help/command/try_run.rst
@ -13,6 +13,7 @@ Try Compiling and Running Source Files
 .. code-block:: cmake

  try_run(<runResultVar> <compileResultVar>
+          [SOURCES_TYPE <type>]
          <SOURCES <srcfile...>                 |
           SOURCE_FROM_CONTENT <name> <content> |
           SOURCE_FROM_VAR <name> <var>         |
@ -77,6 +78,11 @@ The signature above is recommended for clarity.
          [ARGS <args>...]
          )

+.. _`try_run Options`:
+
+Options
+^^^^^^^
+
 The options specific to ``try_run`` are:

 ``COMPILE_OUTPUT_VARIABLE <var>``
--- a/Help/cpack_gen/freebsd.rst
+++ b/Help/cpack_gen/freebsd.rst
@ -19,9 +19,9 @@ be used on FreeBSD, DragonflyBSD, NetBSD, OpenBSD, but also on Linux or OSX,
 depending on the installed package-management tools -- using :module:`CPack`.

 The CPack FreeBSD generator is a :module:`CPack` generator and uses the
-:variable:`!CPACK_XXX` variables used by :module:`CPack`. It tries to re-use packaging
+:variable:`!CPACK_XXX` variables used by :module:`CPack`. It tries to reuse packaging
 information that may already be specified for Debian packages for the
-:cpack_gen:`CPack DEB Generator`. It also tries to re-use RPM packaging
+:cpack_gen:`CPack DEB Generator`. It also tries to reuse RPM packaging
 information when Debian does not specify.

 The CPack FreeBSD generator should work on any host with libpkg installed. The
--- a/Help/dev/documentation.rst
+++ b/Help/dev/documentation.rst
@ -431,6 +431,7 @@ The section header underline character hierarchy is
 * ``-``: Subsection or `CMake Domain`_ object document title
 * ``^``: Subsubsection or `CMake Domain`_ object document section
 * ``"``: Paragraph or `CMake Domain`_ object document subsection
+* ``~``: `CMake Domain`_ object document subsubsection

 Style: Whitespace
 ^^^^^^^^^^^^^^^^^
--- a/Help/dev/experimental.rst
+++ b/Help/dev/experimental.rst
@ -13,127 +13,3 @@ specific values will change over time to reinforce their experimental nature.
 When used, a warning will be generated to indicate that an experimental
 feature is in use and that the affected behavior in the project is not part of
 CMake's stability guarantees.
-
-C++20 Module APIs
-=================
-
-Variable: ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
-Value: ``aa1f7df0-828a-4fcd-9afc-2dc80491aca7``
-
-In order to support C++20 modules, there are a number of behaviors that have
-CMake APIs to provide the required features to build and export them from a
-project.
-
-Limitations
-----------
-
-There are a number of known limitations of the current C++20 module support in
-CMake.  This does not document known limitations or bugs in compilers as these
-can change over time.
-
-For all generators:
-
- Only in-project modules may be used.  While there is some support for
-  exporting module information, there is no mechanism for using it at the
-  moment.
-
-For the Ninja Generators:
-
- ``ninja`` 1.10 or newer is required.
-
-For the Visual Studio Generators:
-
- Only Visual Studio 2022 and toolchains newer than 19.34 (Visual Studio
-  17.4).
- No support for exporting or installing BMI or module information.
- No diagnosis of using modules provided by ``PRIVATE`` sources from
-  ``PUBLIC`` module sources.
-
-C++20 Module Dependencies
-=========================
-
-The Ninja generator has experimental infrastructure supporting C++20 module
-dependency scanning.  This is similar to the Fortran modules support, but
-relies on external tools to scan C++20 translation units for module
-dependencies.  The approach is described by Kitware's `D1483r1`_ paper.
-
-In order to activate CMake's experimental support for C++20 module
-dependencies, set the following variables:
-
-``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
-  Set this to the UUID documented above.
-
-Some compilers already have support for module dependency scanning:
-
-* MSVC 19.34 and newer (provided with Visual Studio 17.4 and newer)
-* LLVM/Clang 16.0 and newer
-
-For those, only the above variables need to be set by project code.
-For compilers with in-development support, additional variables must
-be set as follows.
-
-``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE``
-  Set this to tell CMake how to invoke the C++20 module dependency
-  scanning tool.
-
-``CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FORMAT``
-  Set this for compilers that generate module maps.  See below.
-
-``CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FLAG``
-  Set this for compilers that generate module maps.  See below.
-
-For example, add code like the following to a test project:
-
-.. code-block:: cmake
-
-  string(CONCAT CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE
-    "<CMAKE_CXX_COMPILER> <DEFINES> <INCLUDES> <FLAGS> <SOURCE>"
-    " -MT <DYNDEP_FILE> -MD -MF <DEP_FILE>"
-    " ${flags_to_scan_deps} -fdep-file=<DYNDEP_FILE> -fdep-output=<OBJECT>"
-    )
-
-The tool specified by ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` is
-expected to process the translation unit, write preprocessor dependencies
-to the file specified by the ``<DEP_FILE>`` placeholder, and write module
-dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. The
-``CMAKE_EXPERIMENTAL_CXX_SCANDEP_DEPFILE_FORMAT`` file may be set to ``msvc``
-for scandep rules which use ``msvc``-style dependency reporting.
-
-The module dependencies should be written in the format described
-by the `P1689r5`_ paper.
-
-Compiler writers may try out their scanning functionality using
-the `cxx-modules-sandbox`_ test project, modified to set variables
-as above for their compiler.
-
-For compilers that generate module maps, tell CMake as follows:
-
-.. code-block:: cmake
-
-  set(CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FORMAT "gcc")
-  set(CMAKE_EXPERIMENTAL_CXX_MODULE_MAP_FLAG
-    "${compiler_flags_for_module_map} -fmodule-mapper=<MODULE_MAP_FILE>")
-
-Currently, the only supported formats are, ``clang``, ``gcc``, and ``msvc``.
-The ``gcc`` format is described in the GCC documentation, but the relevant
-section for the purposes of CMake is:
-
-    A mapping file consisting of space-separated module-name, filename
-    pairs, one per line.  Only the mappings for the direct imports and any
-    module export name need be provided.  If other mappings are provided,
-    they override those stored in any imported CMI files.  A repository
-    root may be specified in the mapping file by using ``$root`` as the
-    module name in the first active line.
-
-    -- GCC module mapper documentation
-
-The ``msvc`` format is a response file containing flags required to compile
-any module interfaces properly as well as find any required files to satisfy
-``import`` statements as required for Microsoft's Visual Studio toolchains.
-
-Similarly, the ``clang`` format is a response file containing flags using
-Clang's module flags.
-
-.. _`D1483r1`: https://mathstuf.fedorapeople.org/fortran-modules/fortran-modules.html
-.. _`P1689r5`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html
-.. _`cxx-modules-sandbox`: https://github.com/mathstuf/cxx-modules-sandbox
--- a/Help/dev/maint.rst
+++ b/Help/dev/maint.rst
@ -338,7 +338,7 @@ policies added for that version.  Commit with a message such as::

  export: Increase maximum policy version in exported files to $prev

-  The files generatd by `install(EXPORT)` and `export()` commands
+  The files generated by `install(EXPORT)` and `export()` commands
  are known to work with policies as of CMake $prev, so enable them
  in sufficiently new CMake versions.

--- a/Help/envvar/CMAKE_CROSSCOMPILING_EMULATOR.rst
+++ b/Help/envvar/CMAKE_CROSSCOMPILING_EMULATOR.rst
@ -0,0 +1,11 @@
+CMAKE_CROSSCOMPILING_EMULATOR
+-----------------------------
+
+.. versionadded:: 3.28
+
+.. include:: ENV_VAR.txt
+
+The default value for :variable:`CMAKE_CROSSCOMPILING_EMULATOR` when there
+is no explicit configuration given on the first run while creating a new
+build tree.  On later runs in an existing build tree the value persists in
+the cache as :variable:`CMAKE_CROSSCOMPILING_EMULATOR`.
--- a/Help/envvar/CUDAHOSTCXX.rst
+++ b/Help/envvar/CUDAHOSTCXX.rst
@ -8,8 +8,10 @@ CUDAHOSTCXX
 Preferred executable for compiling host code when compiling ``CUDA``
 language files. Will only be used by CMake on the first configuration to
 determine ``CUDA`` host compiler, after which the value for ``CUDAHOSTCXX`` is
-stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. This environment
-variable is preferred over :variable:`CMAKE_CUDA_HOST_COMPILER`.
+stored in the cache as
+:variable:`CMAKE_CUDA_HOST_COMPILER <CMAKE_<LANG>_HOST_COMPILER>`.
+This environment variable is preferred over
+:variable:`CMAKE_CUDA_HOST_COMPILER <CMAKE_<LANG>_HOST_COMPILER>`.

 This environment variable is primarily meant for use with projects that
 enable ``CUDA`` as a first-class language.
--- a/Help/envvar/HIPHOSTCXX.rst
+++ b/Help/envvar/HIPHOSTCXX.rst
@ -0,0 +1,19 @@
+HIPHOSTCXX
+-----------
+
+.. versionadded:: 3.28
+
+.. include:: ENV_VAR.txt
+
+Preferred executable for compiling host code when compiling ``HIP``
+language files with the NVIDIA CUDA Compiler. Will only be used by CMake
+on the first configuration to determine ``HIP`` host compiler, after which
+the value for ``HIPHOSTCXX`` is stored in the cache as
+:variable:`CMAKE_HIP_HOST_COMPILER <CMAKE_<LANG>_HOST_COMPILER>`.
+
+This environment variable is primarily meant for use with projects that
+enable ``HIP`` as a first-class language.
+
+.. note::
+
+  Ignored when using :ref:`Visual Studio Generators`.
--- a/Help/generator/Visual
+++ b/Help/generator/Visual
@ -3,6 +3,6 @@ Visual Studio 10 2010

 Removed.  This once generated Visual Studio 10 2010 project files, but
 the generator has been removed since CMake 3.25.  It is still possible
-to build with VS 10 2010 tools using the :generator:`Visual Studio 12 2013`
+to build with VS 10 2010 tools using the :generator:`Visual Studio 14 2015`
 (or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to
 ``v100``, or by using the :generator:`NMake Makefiles` generator.
--- a/Help/generator/Visual
+++ b/Help/generator/Visual
@ -1,57 +1,8 @@
 Visual Studio 11 2012
 ---------------------

-Deprecated.  Generates Visual Studio 11 (VS 2012) project files.
-
-.. note::
-  This generator is deprecated and will be removed in a future version
-  of CMake.  It will still be possible to build with VS 11 2012 tools
-  using the :generator:`Visual Studio 12 2013` (or above) generator
-  with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v110``, or by
-  using the :generator:`NMake Makefiles` generator.
-
-For compatibility with CMake versions prior to 3.0, one may specify this
-generator using the name "Visual Studio 11" without the year component.
-
-Project Types
-^^^^^^^^^^^^^
-
-Only Visual C++ and C# projects may be generated (and Fortran with
-Intel compiler integration).  Other types of projects (JavaScript,
-Database, Website, etc.) are not supported.
-
-Platform Selection
-^^^^^^^^^^^^^^^^^^
-
-The default target platform name (architecture) is ``Win32``.
-
-.. versionadded:: 3.1
-  The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
-  via the :option:`cmake -A` option, to specify a target platform
-  name (architecture).  For example:
-
-  * ``cmake -G "Visual Studio 11 2012" -A Win32``
-  * ``cmake -G "Visual Studio 11 2012" -A x64``
-  * ``cmake -G "Visual Studio 11 2012" -A ARM``
-  * ``cmake -G "Visual Studio 11 2012" -A <WinCE-SDK>``
-    (Specify a target platform matching a Windows CE SDK name.)
-
-For compatibility with CMake versions prior to 3.1, one may specify
-a target platform name optionally at the end of the generator name.
-This is supported only for:
-
-``Visual Studio 11 2012 Win64``
-  Specify target platform ``x64``.
-
-``Visual Studio 11 2012 ARM``
-  Specify target platform ``ARM``.
-
-``Visual Studio 11 2012 <WinCE-SDK>``
-  Specify target platform matching a Windows CE SDK name.
-
-Toolset Selection
-^^^^^^^^^^^^^^^^^
-
-The ``v110`` toolset that comes with Visual Studio 11 2012 is selected by
-default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
-via the :option:`cmake -T` option, to specify another toolset.
+Removed.  This once generated Visual Studio 11 2012 project files, but
+the generator has been removed since CMake 3.28.  It is still possible
+to build with VS 11 2012 tools using the :generator:`Visual Studio 14 2015`
+(or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v110``,
+or by using the :generator:`NMake Makefiles` generator.
--- a/Help/generator/Visual
+++ b/Help/generator/Visual
@ -1,7 +1,14 @@
 Visual Studio 12 2013
 ---------------------

-Generates Visual Studio 12 (VS 2013) project files.
+Deprecated.  Generates Visual Studio 12 (VS 2013) project files.
+
+.. note::
+  This generator is deprecated and will be removed in a future version
+  of CMake.  It will still be possible to build with VS 12 2013 tools
+  using the :generator:`Visual Studio 14 2015` (or above) generator
+  with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v120``, or by
+  using the :generator:`NMake Makefiles` generator.

 For compatibility with CMake versions prior to 3.0, one may specify this
 generator using the name "Visual Studio 12" without the year component.
--- a/Help/generator/Visual
+++ b/Help/generator/Visual
@ -6,7 +6,7 @@ Deprecated.  Generates Visual Studio 9 2008 project files.
 .. note::
  This generator is deprecated and will be removed in a future version
  of CMake.  It will still be possible to build with VS 9 2008 tools
-  using the :generator:`Visual Studio 12 2013` generator (or above,
+  using the :generator:`Visual Studio 14 2015` generator (or above,
  and with VS 10 2010 also installed) with
  :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v90``,
  or by using the :generator:`NMake Makefiles` generator.
--- a/Help/guide/tutorial/A
+++ b/Help/guide/tutorial/A
@ -102,7 +102,14 @@ Then call that build system to actually compile/link the project:

  cmake --build .

-Finally, try to use the newly built ``Tutorial`` with these commands:
+For multi-config generators (e.g. Visual Studio), first navigate to the
+appropriate subdirectory, for example:
+
+.. code-block:: console
+
+  cd Debug
+
+Finally, try to use the newly built ``Tutorial``:

 .. code-block:: console

@ -110,6 +117,11 @@ Finally, try to use the newly built ``Tutorial`` with these commands:
  Tutorial 10
  Tutorial

+
+**Note:** Depending on the shell, the correct syntax may be ``Tutorial``,
+``./Tutorial`` or ``.\Tutorial``. For simplicity, the exercises will use
+``Tutorial`` throughout.
+
 Solution
 --------

--- a/Help/guide/tutorial/Adding
+++ b/Help/guide/tutorial/Adding
@ -149,8 +149,8 @@ interface library.

 Lastly, we only want these warning flags to be used during builds. Consumers
 of our installed project should not inherit our warning flags. To specify
-this, we wrap our flags in a generator expression using the ``BUILD_INTERFACE``
-condition. The resulting full code looks like the following:
+this, we wrap our flags from TODO 3 in a generator expression using the
+``BUILD_INTERFACE`` condition. The resulting full code looks like the following:

 .. raw:: html

--- a/Help/guide/tutorial/Adding
+++ b/Help/guide/tutorial/Adding
@ -127,7 +127,7 @@ Remove this line:

  </details>

-And the lines:
+And remove ``EXTRA_INCLUDES`` from ``target_include_directories``:

 .. raw:: html

@ -143,23 +143,6 @@ And the lines:

  </details>

-The remaining code looks like:
-
-.. raw:: html
-
-  <details><summary>Click to show/hide the resulting code</summary>
-
-.. literalinclude:: Step4/CMakeLists.txt
-  :caption: Remaining code after removing EXTRA_INCLUDES
-  :name: CMakeLists.txt-after-removing-EXTRA_INCLUDES
-  :language: cmake
-  :start-after: add_subdirectory(MathFunctions)
-
-.. raw:: html
-
-  </details>
-
-
 Notice that with this technique, the only thing our executable target does to
 use our library is call :command:`target_link_libraries` with the name
 of the library target. In larger projects, the classic method of specifying
@ -262,10 +245,9 @@ then use :command:`target_compile_features` to add the compiler feature
  </details>

 Finally, with our interface library set up, we need to link our
-executable ``Target``, our ``MathFunctions`` library, and our ``SqrtLibrary``
-library to our new
-``tutorial_compiler_flags`` library. Respectively, the code will look like
-this:
+executable ``Tutorial``, our ``SqrtLibrary`` library and our ``MathFunctions``
+library to our new ``tutorial_compiler_flags`` library. Respectively, the code
+will look like this:

 .. raw:: html

@ -292,7 +274,7 @@ this:
  :caption: TODO 6: MathFunctions/CMakeLists.txt
  :name: MathFunctions-CMakeLists.txt-target_link_libraries-step4
  :language: cmake
-  :start-after: # link our compiler flags interface library
+  :start-after: # link SqrtLibrary to tutorial_compiler_flags
  :end-before: target_link_libraries(MathFunctions

 .. raw:: html
@ -309,8 +291,7 @@ and this:
  :caption: TODO 7: MathFunctions/CMakeLists.txt
  :name: MathFunctions-SqrtLibrary-target_link_libraries-step4
  :language: cmake
-  :start-after: target_link_libraries(SqrtLibrary
-  :end-before: endif()
+  :start-after: # link MathFunctions to tutorial_compiler_flags

 .. raw:: html

--- a/Help/guide/tutorial/Adding
+++ b/Help/guide/tutorial/Adding
@ -96,7 +96,7 @@ a library target called ``MathFunctions`` with :command:`add_library`. The
 source files for the library are passed as an argument to
 :command:`add_library`. This looks like the following line:

-.. raw:: html/
+.. raw:: html

  <details><summary>TODO 1: Click to show/hide answer</summary>

@ -184,7 +184,7 @@ Now let's use our library. In ``tutorial.cxx``, include ``MathFunctions.h``:

  </details>

-Lastly, replace ``sqrt`` with our library function ``mathfunctions::mysqrt``.
+Lastly, replace ``sqrt`` with the wrapper function ``mathfunctions::sqrt``.

 .. raw:: html

--- a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt
@ -33,10 +33,13 @@ if(USE_MYMATH)
                        POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
                        )

+  # link SqrtLibrary to tutorial_compiler_flags
  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
+
  target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()

+# link MathFunctions to tutorial_compiler_flags
 target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)

 # define the symbol stating we are using the declspec(dllexport) when
--- a/Help/guide/tutorial/Selecting
+++ b/Help/guide/tutorial/Selecting
@ -44,7 +44,18 @@ SqrtLibrary to be ``True`` when building shared libraries.
  :caption: MathFunctions/CMakeLists.txt
  :name: MathFunctions/CMakeLists.txt-POSITION_INDEPENDENT_CODE
  :language: cmake
-  :lines: 37-42
+  :start-at: # state that SqrtLibrary need PIC when the default is shared libraries
+  :end-at:  )
+
+Define ``EXPORTING_MYMATH`` stating we are using ``declspec(dllexport)`` when
+building on Windows.
+
+.. literalinclude:: Step11/MathFunctions/CMakeLists.txt
+  :caption: MathFunctions/CMakeLists.txt
+  :name: MathFunctions/CMakeLists.txt-dll-export
+  :language: cmake
+  :start-at: # define the symbol stating we are using the declspec(dllexport) when
+  :end-at: target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")

 **Exercise**: We modified ``MathFunctions.h`` to use dll export defines.
 Using CMake documentation can you find a helper module to simplify this?
--- a/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt
@ -26,10 +26,13 @@ if(USE_MYMATH)
                             ${CMAKE_CURRENT_BINARY_DIR}
                             )

+  # link SqrtLibrary to tutorial_compiler_flags
  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
+
  target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()

+# link MathFunctions to tutorial_compiler_flags
 target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)

 # install libs
--- a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt
@ -31,10 +31,13 @@ if(USE_MYMATH)
                        POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
                        )

+  # link SqrtLibrary to tutorial_compiler_flags
  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
+
  target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()

+# link MathFunctions to tutorial_compiler_flags
 target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)

 # define the symbol stating we are using the declspec(dllexport) when
--- a/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt
@ -33,10 +33,13 @@ if(USE_MYMATH)
                        POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
                        )

+  # link SqrtLibrary to tutorial_compiler_flags
  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
+
  target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()

+# link MathFunctions to tutorial_compiler_flags
 target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)

 # define the symbol stating we are using the declspec(dllexport) when
--- a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt
@ -16,7 +16,7 @@ if (USE_MYMATH)

  # TODO 7: Link SqrtLibrary to tutorial_compiler_flags

-  target_link_libraries(MathFunctions PUBLIC SqrtLibrary)
+  target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()

 # TODO 6: Link MathFunctions to tutorial_compiler_flags
--- a/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt
@ -17,10 +17,11 @@ if (USE_MYMATH)
              mysqrt.cxx
              )

-  # link our compiler flags interface library
+  # link SqrtLibrary to tutorial_compiler_flags
  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
-  target_link_libraries(MathFunctions PUBLIC SqrtLibrary)
+
+  target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()

-# link our compiler flags interface library
+# link MathFunctions to tutorial_compiler_flags
 target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
--- a/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt
@ -16,12 +16,13 @@ if (USE_MYMATH)
              mysqrt.cxx
              )

-  # link our compiler flags interface library
+  # link SqrtLibrary to tutorial_compiler_flags
  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
+
  target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()

-# link our compiler flags interface library
+# link MathFunctions to tutorial_compiler_flags
 target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)

 # TODO 1: Create a variable called installable_libs that is a list of all
--- a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt
@ -16,11 +16,13 @@ if (USE_MYMATH)
              mysqrt.cxx
              )

+  # link SqrtLibrary to tutorial_compiler_flags
  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
+
  target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()

-# link our compiler flags interface library
+# link MathFunctions to tutorial_compiler_flags
 target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)

 # install libs
--- a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt
@ -16,6 +16,7 @@ if (USE_MYMATH)
              mysqrt.cxx
              )

+  # link SqrtLibrary to tutorial_compiler_flags
  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)

  # TODO 1: Include CheckCXXSourceCompiles
@ -41,7 +42,7 @@ if (USE_MYMATH)
  target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()

-# link our compiler flags interface library
+# link MathFunctions to tutorial_compiler_flags
 target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)

 # install libs
--- a/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt
@ -10,6 +10,7 @@ if (USE_MYMATH)
              mysqrt.cxx
              )

+  # link SqrtLibrary to tutorial_compiler_flags
  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)

  # does this system provide the log and exp functions?
@ -45,7 +46,7 @@ target_include_directories(MathFunctions
                           INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
                           )

-# link our compiler flags interface library
+# link MathFunctions to tutorial_compiler_flags
 target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)

 # install libs
--- a/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt
@ -25,10 +25,13 @@ if (USE_MYMATH)
                             ${CMAKE_CURRENT_BINARY_DIR}
                             )

+  # link SqrtLibrary to tutorial_compiler_flags
  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
+
  target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()

+# link MathFunctions to tutorial_compiler_flags
 target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)

 # install libs
--- a/Help/index.rst
+++ b/Help/index.rst
@ -58,6 +58,7 @@ Reference Manuals
   /manual/cmake-commands.7
   /manual/cmake-compile-features.7
   /manual/cmake-configure-log.7
+   /manual/cmake-cxxmodules.7
   /manual/cmake-developer.7
   /manual/cmake-env-variables.7
   /manual/cmake-file-api.7
--- a/Help/manual/OPTIONS_BUILD.txt
+++ b/Help/manual/OPTIONS_BUILD.txt
@ -105,11 +105,15 @@

 .. option:: --toolchain <path-to-file>

+ .. versionadded:: 3.21
+
 Specify the cross compiling toolchain file, equivalent to setting
 :variable:`CMAKE_TOOLCHAIN_FILE` variable.

 .. option:: --install-prefix <directory>

+ .. versionadded:: 3.21
+
 Specify the installation directory, used by the
 :variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path.

--- a/Help/manual/OPTIONS_HELP.txt
+++ b/Help/manual/OPTIONS_HELP.txt
@ -11,6 +11,21 @@

 Usage describes the basic command line interface and its options.

+.. option:: --help <keyword> [<file>]
+
+ Print help for one CMake keyword.
+
+ ``<keyword>`` can be a property, variable, command, policy, generator
+ or module.
+
+ The relevant manual entry for ``<keyword>`` is
+ printed in a human-readable text format.
+ |file|
+
+ .. versionchanged:: 3.28
+
+   Prior to CMake 3.28, this option supported command names only.
+
 .. option:: --help-full [<file>]

 Print all help manuals and exit.
--- a/Help/manual/cmake-cxxmodules.7.rst
+++ b/Help/manual/cmake-cxxmodules.7.rst
@ -0,0 +1,74 @@
+.. cmake-manual-description: CMake C++ Modules Support Reference
+
+cmake-cxxmodules(7)
+*******************
+
+.. versionadded:: 3.28
+
+C++ 20 introduced the concept of "modules" to the language.  The design
+requires build systems to order compilations among each other to satisfy
+``import`` statements reliably.  CMake's implementation asks the compiler
+to scan source files for module dependencies during the build, collates
+scanning results to infer ordering constraints, and tells the build tool
+how to dynamically update the build graph.
+
+Scanning Control
+================
+
+Whether or not sources get scanned for C++ module usage is dependent on the
+following queries. The first query that provides a yes/no answer is used.
+
+- If the source file belongs to a file set of type ``CXX_MODULES``, it will
+  be scanned.
+- If the target does not use at least C++ 20, it will not be scanned.
+- If the source file is not the language ``CXX``, it will not be scanned.
+- If the :prop_sf:`CXX_SCAN_FOR_MODULES` source file property is set, its
+  value will be used.
+- If the :prop_tgt:`CXX_SCAN_FOR_MODULES` target property is set, its value
+  will be used.  Set the :variable:`CMAKE_CXX_SCAN_FOR_MODULES` variable
+  to initialize this property on all targets as they are created.
+- Otherwise, the source file will be scanned if the compiler and generator
+  support scanning.  See policy :policy:`CMP0155`.
+
+Compiler Support
+================
+
+Compilers which CMake natively supports module dependency scanning include:
+
+* MSVC toolset 14.34 and newer (provided with Visual Studio 17.4 and newer)
+* LLVM/Clang 16.0 and newer
+* GCC 14 (for the in-development branch, after 2023-09-20) and newer
+
+Generator Support
+=================
+
+The list of generators which support scanning sources for C++ modules include:
+
+- :generator:`Ninja`
+- :generator:`Ninja Multi-Config`
+- :generator:`Visual Studio 17 2022`
+
+Limitations
+-----------
+
+There are a number of known limitations of the current C++ module support in
+CMake.  This does not document known limitations or bugs in compilers as these
+can change over time.
+
+For all generators:
+
+- Header units are not supported.
+- No builtin support for ``import std;`` or other compiler-provided modules.
+
+For the Ninja Generators:
+
+- ``ninja`` 1.11 or newer is required.
+
+For the :ref:`Visual Studio Generators`:
+
+- Only Visual Studio 2022 and MSVC toolsets 14.34 (Visual Studio
+  17.4) and newer.
+- No support for exporting or installing BMI or module information.
+- No support for compiling BMIs from ``IMPORTED`` targets with C++ modules.
+- No diagnosis of using modules provided by ``PRIVATE`` sources from
+  ``PUBLIC`` module sources.
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/Help/manual/cmake-env-variables.7.rst
@ -43,6 +43,7 @@ Environment Variables that Control the Build
   /envvar/CMAKE_COLOR_DIAGNOSTICS
   /envvar/CMAKE_CONFIGURATION_TYPES
   /envvar/CMAKE_CONFIG_TYPE
+   /envvar/CMAKE_CROSSCOMPILING_EMULATOR
   /envvar/CMAKE_EXPORT_COMPILE_COMMANDS
   /envvar/CMAKE_GENERATOR
   /envvar/CMAKE_GENERATOR_INSTANCE
@ -83,6 +84,7 @@ Environment Variables for Languages
   /envvar/FFLAGS
   /envvar/HIPCXX
   /envvar/HIPFLAGS
+   /envvar/HIPHOSTCXX
   /envvar/ISPC
   /envvar/ISPCFLAGS
   /envvar/OBJC
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@ -195,6 +195,12 @@ Two forms of conditional generator expressions are supported:
  if ``condition`` is ``0``.  Any other value for ``condition`` results in an
  error.

+  .. versionadded:: 3.28
+
+    This generator expression short-circuits such that generator expressions in
+    ``false_string`` will not evaluate when ``condition`` is ``1``, and generator
+    expressions in ``true_string`` will not evaluate when condition is ``0``.
+
 Typically, the ``condition`` is itself a generator expression.  For instance,
 the following expression expands to ``DEBUG_MODE`` when the ``Debug``
 configuration is used, and the empty string for all other configurations:
@ -252,6 +258,11 @@ The common boolean logic operators are supported:
  ``condition`` must be ``0`` or ``1``.  The result of the expression is
  ``0`` if ``condition`` is ``1``, else ``1``.

+.. versionadded:: 3.28
+
+  Logical operators short-circuit such that generator expressions in the
+  arguments list will not be evaluated once a return value can be determined.
+
 .. _`Comparison Expressions`:

 Primary Comparison Expressions
--- a/Help/manual/cmake-modules.7.rst
+++ b/Help/manual/cmake-modules.7.rst
@ -72,7 +72,6 @@ These modules are loaded using the :command:`include` command.
   /module/CTestCoverageCollectGCOV
   /module/CTestScriptMode
   /module/CTestUseLaunchers
-   /module/Dart
   /module/DeployQt4
   /module/ExternalData
   /module/ExternalProject
@ -82,14 +81,12 @@ These modules are loaded using the :command:`include` command.
   /module/FindPackageMessage
   /module/FortranCInterface
   /module/GenerateExportHeader
-   /module/GetPrerequisites
   /module/GNUInstallDirs
   /module/GoogleTest
   /module/InstallRequiredSystemLibraries
   /module/ProcessorCount
   /module/SelectLibraryConfigurations
   /module/SquishTestScript
-   /module/TestBigEndian
   /module/TestForANSIForScope
   /module/TestForANSIStreamHeaders
   /module/TestForSSTREAM
@ -127,7 +124,6 @@ They are normally called through the :command:`find_package` command.
   /module/FindCVS
   /module/FindCxxTest
   /module/FindCygwin
-   /module/FindDart
   /module/FindDCMTK
   /module/FindDevIL
   /module/FindDoxygen
@ -276,8 +272,11 @@ Deprecated Utility Modules
   /module/CMakeExpandImportedTargets
   /module/CMakeForceCompiler
   /module/CMakeParseArguments
+   /module/Dart
   /module/Documentation
+   /module/GetPrerequisites
   /module/MacroAddFileDependencies
+   /module/TestBigEndian
   /module/TestCXXAcceptsFlag
   /module/UseJavaClassFilelist
   /module/UseJavaSymlinks
@ -293,6 +292,7 @@ Deprecated Find Modules
   :maxdepth: 1

   /module/FindCUDA
+   /module/FindDart
   /module/FindITK
   /module/FindPythonInterp
   /module/FindPythonLibs
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@ -51,6 +51,17 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
 to determine whether to report an error on use of deprecated macros or
 functions.

+Policies Introduced by CMake 3.28
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0155: C++ sources in targets with at least C++20 are scanned for imports when supported. </policy/CMP0155>
+   CMP0154: Generated files are private by default in targets using file sets. </policy/CMP0154>
+   CMP0153: The exec_program command should not be called. </policy/CMP0153>
+   CMP0152: file(REAL_PATH) resolves symlinks before collapsing ../ components.  </policy/CMP0152>
+
 Policies Introduced by CMake 3.27
 =================================

--- a/Help/manual/cmake-presets.7.rst
+++ b/Help/manual/cmake-presets.7.rst
@ -41,6 +41,15 @@ The files are a JSON document with an object as the root:

 The root object recognizes the following fields:

+``$schema``
+  An optional string that provides a URI to the JSON schema that describes the
+  structure of this JSON document. This field is used for validation and
+  autocompletion in editors that support JSON schema. It doesn't affect the
+  behavior of the document itself. If this field is not specified, the JSON
+  document will still be valid, but tools that use JSON schema for validation
+  and autocompletion may not function correctly.
+  This is allowed in preset files specifying version ``8`` or above.
+
 ``version``
  A required integer representing the version of the JSON schema.
  The supported versions are:
@ -66,6 +75,9 @@ The root object recognizes the following fields:
  ``7``
    .. versionadded:: 3.27

+  ``8``
+    .. versionadded:: 3.28
+
 ``cmakeMinimumRequired``
  An optional object representing the minimum version of CMake needed to
  build this project. This object consists of the following fields:
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@ -240,6 +240,11 @@ Properties on Targets
   /prop_tgt/IMPORTED
   /prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME
   /prop_tgt/IMPORTED_CONFIGURATIONS
+   /prop_tgt/IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS
+   /prop_tgt/IMPORTED_CXX_MODULES_COMPILE_FEATURES
+   /prop_tgt/IMPORTED_CXX_MODULES_COMPILE_OPTIONS
+   /prop_tgt/IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES
+   /prop_tgt/IMPORTED_CXX_MODULES_LINK_LIBRARIES
   /prop_tgt/IMPORTED_GLOBAL
   /prop_tgt/IMPORTED_IMPLIB
   /prop_tgt/IMPORTED_IMPLIB_CONFIG
@ -257,7 +262,6 @@ Properties on Targets
   /prop_tgt/IMPORTED_LOCATION_CONFIG
   /prop_tgt/IMPORTED_NO_SONAME
   /prop_tgt/IMPORTED_NO_SONAME_CONFIG
-   /prop_tgt/IMPORTED_NO_SYSTEM
   /prop_tgt/IMPORTED_OBJECTS
   /prop_tgt/IMPORTED_OBJECTS_CONFIG
   /prop_tgt/IMPORTED_SONAME
@ -290,7 +294,6 @@ Properties on Targets
   /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES
   /prop_tgt/INTERPROCEDURAL_OPTIMIZATION
   /prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG
-   /prop_tgt/IOS_INSTALL_COMBINED
   /prop_tgt/ISPC_HEADER_DIRECTORY
   /prop_tgt/ISPC_HEADER_SUFFIX
   /prop_tgt/ISPC_INSTRUCTION_SETS
@ -439,7 +442,6 @@ Properties on Targets
   /prop_tgt/VS_USER_PROPS
   /prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
   /prop_tgt/VS_WINRT_COMPONENT
-   /prop_tgt/VS_WINRT_EXTENSIONS
   /prop_tgt/VS_WINRT_REFERENCES
   /prop_tgt/WATCOM_RUNTIME_LIBRARY
   /prop_tgt/WIN32_EXECUTABLE
@ -503,6 +505,7 @@ Properties on Tests
   /prop_test/FIXTURES_CLEANUP
   /prop_test/FIXTURES_REQUIRED
   /prop_test/FIXTURES_SETUP
+   /prop_test/GENERATED_RESOURCE_SPEC_FILE
   /prop_test/LABELS
   /prop_test/MEASUREMENT
   /prop_test/PASS_REGULAR_EXPRESSION
@ -634,8 +637,11 @@ Deprecated Properties on Targets
   :maxdepth: 1

   /prop_tgt/COMPILE_DEFINITIONS_CONFIG
+   /prop_tgt/IMPORTED_NO_SYSTEM
+   /prop_tgt/IOS_INSTALL_COMBINED
   /prop_tgt/POST_INSTALL_SCRIPT
   /prop_tgt/PRE_INSTALL_SCRIPT
+   /prop_tgt/VS_WINRT_EXTENSIONS


 Deprecated Properties on Source Files
--- a/Help/manual/cmake-qt.7.rst
+++ b/Help/manual/cmake-qt.7.rst
@ -14,7 +14,7 @@ CMake can find and use Qt 4 and Qt 5 libraries.  The Qt 4 libraries are found
 by the :module:`FindQt4` find-module shipped with CMake, whereas the
 Qt 5 libraries are found using "Config-file Packages" shipped with Qt 5. See
 :manual:`cmake-packages(7)` for more information about CMake packages, and
-see `the Qt cmake manual <https://contribute.qt-project.org/doc/qt-5/cmake-manual.html>`_
+see `the Qt cmake manual <https://doc.qt.io/qt-5/cmake-manual.html>`_
 for your Qt version.

 Qt 4 and Qt 5 may be used together in the same
--- a/Help/manual/cmake-toolchains.7.rst
+++ b/Help/manual/cmake-toolchains.7.rst
@ -573,12 +573,12 @@ See also target properties:
 * :prop_tgt:`ANDROID_SKIP_ANT_STEP`
 * :prop_tgt:`ANDROID_STL_TYPE`

-.. _`Cross Compiling for iOS, tvOS, or watchOS`:
+.. _`Cross Compiling for iOS, tvOS, visionOS, or watchOS`:

-Cross Compiling for iOS, tvOS, or watchOS
-----------------------------------------
+Cross Compiling for iOS, tvOS, visionOS, or watchOS
+---------------------------------------------------

-For cross-compiling to iOS, tvOS, or watchOS, the :generator:`Xcode`
+For cross-compiling to iOS, tvOS, visionOS, or watchOS, the :generator:`Xcode`
 generator is recommended.  The :generator:`Unix Makefiles` or
 :generator:`Ninja` generators can also be used, but they require the
 project to handle more areas like target CPU selection and code signing.
@ -591,13 +591,14 @@ a different SDK (e.g. a simulator) can be selected by setting the
 necessary (see :ref:`Switching Between Device and Simulator` below).
 A list of available SDKs can be obtained by running ``xcodebuild -showsdks``.

-=======  ================= ==================== ================
-OS       CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK
-=======  ================= ==================== ================
-iOS      iOS               iphoneos             iphonesimulator
-tvOS     tvOS              appletvos            appletvsimulator
-watchOS  watchOS           watchos              watchsimulator
-=======  ================= ==================== ================
+========  ================= ==================== ================
+OS        CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK
+========  ================= ==================== ================
+iOS       iOS               iphoneos             iphonesimulator
+tvOS      tvOS              appletvos            appletvsimulator
+visionOS  visionOS          xros                 xrsimulator
+watchOS   watchOS           watchos              watchsimulator
+========  ================= ==================== ================

 For example, to create a CMake configuration for iOS, the following
 command is sufficient:
@ -608,7 +609,7 @@ command is sufficient:

 Variable :variable:`CMAKE_OSX_ARCHITECTURES` can be used to set architectures
 for both device and simulator. Variable :variable:`CMAKE_OSX_DEPLOYMENT_TARGET`
-can be used to set an iOS/tvOS/watchOS deployment target.
+can be used to set an iOS/tvOS/visionOS/watchOS deployment target.

 Next configuration will install fat 5 architectures iOS library
 and add the ``-miphoneos-version-min=9.3``/``-mios-simulator-version-min=9.3``
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@ -590,6 +590,7 @@ Variables for Languages
   /variable/CMAKE_Fortran_MODOUT_FLAG
   /variable/CMAKE_HIP_ARCHITECTURES
   /variable/CMAKE_HIP_EXTENSIONS
+   /variable/CMAKE_HIP_PLATFORM
   /variable/CMAKE_HIP_STANDARD
   /variable/CMAKE_HIP_STANDARD_REQUIRED
   /variable/CMAKE_ISPC_HEADER_DIRECTORY
@ -627,6 +628,7 @@ Variables for Languages
   /variable/CMAKE_LANG_FLAGS_RELEASE_INIT
   /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO
   /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT
+   /variable/CMAKE_LANG_HOST_COMPILER
   /variable/CMAKE_LANG_IGNORE_EXTENSIONS
   /variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES
   /variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@ -309,6 +309,8 @@ Options

 .. option:: --debug-find

+ .. versionadded:: 3.17
+
 Put cmake find commands in a debug mode.

 Print extra find call information during the cmake run to standard
@ -318,6 +320,8 @@ Options

 .. option:: --debug-find-pkg=<pkg>[,...]

+ .. versionadded:: 3.23
+
 Put cmake find commands in a debug mode when running under calls
 to :command:`find_package(\<pkg\>) <find_package>`, where ``<pkg>``
 is an entry in the given comma-separated list of case-sensitive package
@ -328,6 +332,8 @@ Options

 .. option:: --debug-find-var=<var>[,...]

+ .. versionadded:: 3.23
+
 Put cmake find commands in a debug mode when called with ``<var>``
 as the result variable, where ``<var>`` is an entry in the given
 comma-separated list.
@ -349,6 +355,8 @@ Options

 .. option:: --trace-format=<format>

+ .. versionadded:: 3.17
+
 Put cmake in trace mode and sets the trace output format.

 ``<format>`` can be one of the following values.
@ -471,12 +479,16 @@ Options

 .. option:: --compile-no-warning-as-error

+ .. versionadded:: 3.24
+
 Ignore target property :prop_tgt:`COMPILE_WARNING_AS_ERROR` and variable
 :variable:`CMAKE_COMPILE_WARNING_AS_ERROR`, preventing warnings from being
 treated as errors on compile.

 .. option:: --profiling-output=<path>

+ .. versionadded:: 3.18
+
 Used in conjunction with
 :option:`--profiling-format <cmake --profiling-format>` to output to a
 given path.
@ -1325,6 +1337,8 @@ autoconf-based projects (via ``share/aclocal/cmake.m4``).
 Run a Workflow Preset
 =====================

+.. versionadded:: 3.25
+
 .. program:: cmake

 :manual:`CMake Presets <cmake-presets(7)>` provides a way to execute multiple
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@ -1820,6 +1820,25 @@ The following variables are passed to the test process:
  uppercase in the ``CTEST_RESOURCE_GROUP_<num>_<resource-type>`` environment
  variable.

+.. _`ctest-resource-dynamically-generated-spec-file`:
+
+Dynamically-Generated Resource Specification File
+-------------------------------------------------
+
+.. versionadded:: 3.28
+
+A project may optionally specify a single test which will be used to
+dynamically generate the resource specification file that CTest will use for
+scheduling tests that use resources. The test that generates the file must
+have the :prop_test:`GENERATED_RESOURCE_SPEC_FILE` property set, and must have
+exactly one fixture in its :prop_test:`FIXTURES_SETUP` property. This fixture
+is considered by CTest to have special meaning: it's the fixture that generates
+the resource spec file. The fixture may have any name. If such a fixture
+exists, all tests that have :prop_test:`RESOURCE_GROUPS` set must have the
+fixture in their :prop_test:`FIXTURES_REQUIRED`, and a resource spec file may
+not be specified with the ``--resource-spec-file`` argument or the
+:variable:`CTEST_RESOURCE_SPEC_FILE` variable.
+
 See Also
 ========

--- a/Help/manual/presets/schema.json
+++ b/Help/manual/presets/schema.json
@ -9,9 +9,9 @@
          "const": 1,
          "description": "A required integer representing the version of the JSON schema."
        },
-        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
+        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
        "vendor": { "$ref": "#/definitions/vendor" },
-        "configurePresets": { "$ref": "#/definitions/configurePresetsV1"}
+        "configurePresets": { "$ref": "#/definitions/configurePresetsV1" }
      },
      "additionalProperties": false
    },
@ -21,11 +21,11 @@
          "const": 2,
          "description": "A required integer representing the version of the JSON schema."
        },
-        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
+        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
        "vendor": { "$ref": "#/definitions/vendor" },
-        "configurePresets": { "$ref": "#/definitions/configurePresetsV1"},
-        "buildPresets": { "$ref": "#/definitions/buildPresetsV2"},
-        "testPresets": { "$ref": "#/definitions/testPresetsV2"}
+        "configurePresets": { "$ref": "#/definitions/configurePresetsV1" },
+        "buildPresets": { "$ref": "#/definitions/buildPresetsV2" },
+        "testPresets": { "$ref": "#/definitions/testPresetsV2" }
      },
      "additionalProperties": false
    },
@ -35,11 +35,11 @@
          "const": 3,
          "description": "A required integer representing the version of the JSON schema."
        },
-        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
+        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
        "vendor": { "$ref": "#/definitions/vendor" },
-        "configurePresets": { "$ref": "#/definitions/configurePresetsV3"},
-        "buildPresets": { "$ref": "#/definitions/buildPresetsV3"},
-        "testPresets": { "$ref": "#/definitions/testPresetsV3"}
+        "configurePresets": { "$ref": "#/definitions/configurePresetsV3" },
+        "buildPresets": { "$ref": "#/definitions/buildPresetsV3" },
+        "testPresets": { "$ref": "#/definitions/testPresetsV3" }
      },
      "additionalProperties": false
    },
@ -49,12 +49,12 @@
          "const": 4,
          "description": "A required integer representing the version of the JSON schema."
        },
-        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
+        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
        "vendor": { "$ref": "#/definitions/vendor" },
-        "configurePresets": { "$ref": "#/definitions/configurePresetsV3"},
-        "buildPresets": { "$ref": "#/definitions/buildPresetsV4"},
-        "testPresets": { "$ref": "#/definitions/testPresetsV3"},
-        "include": { "$ref": "#/definitions/include"}
+        "configurePresets": { "$ref": "#/definitions/configurePresetsV3" },
+        "buildPresets": { "$ref": "#/definitions/buildPresetsV4" },
+        "testPresets": { "$ref": "#/definitions/testPresetsV3" },
+        "include": { "$ref": "#/definitions/include" }
      },
      "additionalProperties": false
    },
@ -64,12 +64,12 @@
          "const": 5,
          "description": "A required integer representing the version of the JSON schema."
        },
-        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
+        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
        "vendor": { "$ref": "#/definitions/vendor" },
-        "configurePresets": { "$ref": "#/definitions/configurePresetsV3"},
-        "buildPresets": { "$ref": "#/definitions/buildPresetsV4"},
-        "testPresets": { "$ref": "#/definitions/testPresetsV5"},
-        "include": { "$ref": "#/definitions/include"}
+        "configurePresets": { "$ref": "#/definitions/configurePresetsV3" },
+        "buildPresets": { "$ref": "#/definitions/buildPresetsV4" },
+        "testPresets": { "$ref": "#/definitions/testPresetsV5" },
+        "include": { "$ref": "#/definitions/include" }
      },
      "additionalProperties": false
    },
@ -79,14 +79,14 @@
          "const": 6,
          "description": "A required integer representing the version of the JSON schema."
        },
-        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
+        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
        "vendor": { "$ref": "#/definitions/vendor" },
-        "configurePresets": { "$ref": "#/definitions/configurePresetsV3"},
-        "buildPresets": { "$ref": "#/definitions/buildPresetsV4"},
-        "testPresets": { "$ref": "#/definitions/testPresetsV6"},
-        "packagePresets": { "$ref": "#/definitions/packagePresetsV6"},
+        "configurePresets": { "$ref": "#/definitions/configurePresetsV3" },
+        "buildPresets": { "$ref": "#/definitions/buildPresetsV4" },
+        "testPresets": { "$ref": "#/definitions/testPresetsV6" },
+        "packagePresets": { "$ref": "#/definitions/packagePresetsV6" },
        "workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" },
-        "include": { "$ref": "#/definitions/include"}
+        "include": { "$ref": "#/definitions/include" }
      },
      "additionalProperties": false
    },
@ -96,14 +96,32 @@
          "const": 7,
          "description": "A required integer representing the version of the JSON schema."
        },
-        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
+        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
        "vendor": { "$ref": "#/definitions/vendor" },
-        "configurePresets": { "$ref": "#/definitions/configurePresetsV7"},
-        "buildPresets": { "$ref": "#/definitions/buildPresetsV4"},
-        "testPresets": { "$ref": "#/definitions/testPresetsV6"},
-        "packagePresets": { "$ref": "#/definitions/packagePresetsV6"},
+        "configurePresets": { "$ref": "#/definitions/configurePresetsV7" },
+        "buildPresets": { "$ref": "#/definitions/buildPresetsV4" },
+        "testPresets": { "$ref": "#/definitions/testPresetsV6" },
+        "packagePresets": { "$ref": "#/definitions/packagePresetsV6" },
        "workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" },
-        "include": { "$ref": "#/definitions/include"}
+        "include": { "$ref": "#/definitions/include" }
+      },
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "$schema": { "$ref": "#/definitions/$schema" },
+        "version": {
+          "const": 8,
+          "description": "A required integer representing the version of the JSON schema."
+        },
+        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired" },
+        "vendor": { "$ref": "#/definitions/vendor" },
+        "configurePresets": { "$ref": "#/definitions/configurePresetsV7" },
+        "buildPresets": { "$ref": "#/definitions/buildPresetsV4" },
+        "testPresets": { "$ref": "#/definitions/testPresetsV6" },
+        "packagePresets": { "$ref": "#/definitions/packagePresetsV6" },
+        "workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" },
+        "include": { "$ref": "#/definitions/include" }
      },
      "additionalProperties": false
    }
@ -112,6 +130,11 @@
    "version"
  ],
  "definitions": {
+    "$schema": {
+      "type": "string",
+      "description": "The schema against which to verify this document.",
+      "format": "uri-reference"
+    },
    "cmakeMinimumRequired": {
      "type": "object",
      "description": "An optional object representing the minimum version of CMake needed to build this project.",
--- a/Help/policy/CMP0152.rst
+++ b/Help/policy/CMP0152.rst
@ -0,0 +1,20 @@
+CMP0152
+-------
+
+.. versionadded:: 3.28
+
+:command:`file(REAL_PATH)` resolves symlinks before collapsing ../ components.
+
+In CMake 3.27 and below, :command:`file(REAL_PATH)` collapsed any ``../``
+components in a path before resolving symlinks.  This produced incorrect
+results when the ``../`` collapsed away a symlink.
+
+The ``OLD`` behavior for this policy is to collapse ``../`` components before
+resolving symlinks.
+The ``NEW`` behavior for this policy is to resolve all symlinks before
+collapsing ``../`` components.
+
+This policy was introduced in CMake version 3.28.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt
--- a/Help/policy/CMP0153.rst
+++ b/Help/policy/CMP0153.rst
@ -0,0 +1,14 @@
+CMP0153
+-------
+
+.. versionadded:: 3.28
+
+The :command:`exec_program` command should not be called.
+
+This command has long been superseded by the :command:`execute_process`
+command and has been deprecated since CMake 3.0.
+
+.. |disallowed_version| replace:: 3.28
+.. include:: DISALLOWED_COMMAND.txt
+
+.. include:: DEPRECATED.txt
--- a/Help/policy/CMP0154.rst
+++ b/Help/policy/CMP0154.rst
@ -0,0 +1,59 @@
+CMP0154
+-------
+
+.. versionadded:: 3.28
+
+Generated files are private by default in targets using :ref:`file sets`.
+
+CMake 3.27 and below assume that any file generated as an output or byproduct
+of :command:`add_custom_command` or :command:`add_custom_target` may be a
+public header file meant for inclusion by dependents' source files.  This
+requires :ref:`Ninja Generators` to add conservative order-only dependencies
+that prevent a target's source files from compiling before custom commands
+from the target's dependencies are finished, even if those custom commands
+only produce sources private to their own target.
+
+:ref:`File Sets`, introduced by CMake 3.23, provide a way to express the
+visibility of generated header files.  CMake 3.28 and above prefer to
+assume that, in targets using file sets, generated files are private to
+their own target by default.  Generated public headers must be specified
+as members of a ``PUBLIC`` (or ``INTERFACE``) ``FILE_SET``, typically of
+type ``HEADERS``.  With this information, :ref:`Ninja Generators` may omit
+the above-mentioned conservative dependencies and produce more efficient
+build graphs.
+
+Additionally, if the custom command's output is a member of a file set of type
+``CXX_MODULES``, it will additionally not be required to exist before
+compiling other sources in the same target.  Since these files should not be
+included at compile time directly, they may not be implicitly required to
+exist for other compilation rules.
+
+This policy provides compatibility for projects using file sets in targets
+with generated header files that have not been updated.  Such projects
+should be updated to express generated public headers in a file set.
+For example:
+
+.. code-block:: cmake
+
+  add_custom_command(
+    OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/foo.h
+    ...
+  )
+  target_sources(foo
+    PUBLIC FILE_SET HEADERS
+      BASE_DIRS ${CMAKE_CURRENT_BINARY_DIR}
+      FILES     ${CMAKE_CURRENT_BINARY_DIR}/foo.h
+  )
+
+The ``OLD`` behavior for this policy is to assume generated files are
+public, even in targets using file sets, and for :ref:`Ninja Generators`
+to produce conservative build graphs.  The ``NEW`` behavior for this
+policy is to assume generated files are private in targets using file sets,
+and for :ref:`Ninja Generators` to produce more efficient build graphs.
+
+This policy was introduced in CMake version 3.28.  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
--- a/Help/policy/CMP0155.rst
+++ b/Help/policy/CMP0155.rst
@ -0,0 +1,28 @@
+CMP0155
+-------
+
+.. versionadded:: 3.28
+
+C++ sources in targets with at least C++20 are scanned for imports
+when supported.
+
+CMake 3.27 and below assume that C++ sources do not ``import`` modules.
+CMake 3.28 and above prefer to assume that C++ sources in targets using C++20
+or higher might ``import`` modules, and must be scanned before compiling,
+unless explicitly disabled.  This policy provides compatibility for projects
+that use C++20 or higher, without modules, that have not been updated to turn
+off scanning, e.g., via the :variable:`CMAKE_CXX_SCAN_FOR_MODULES` variable.
+See the :manual:`cmake-cxxmodules(7)` manual for more details on C++ module
+support.
+
+The ``OLD`` behavior for this policy is to assume that C++ 20 and newer
+sources do not import modules.  The ``NEW`` behavior for this policy is to
+assume that C++ 20 and newer files may import modules if the compiler
+understands how to scan for their dependencies, and need to be scanned.
+
+This policy was introduced in CMake version 3.28.  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
--- a/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst
+++ b/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst
@ -16,8 +16,8 @@ generator emits the ``EFFECTIVE_PLATFORM_NAME`` variable:
 - If set to ``ON`` it will always be emitted
 - If set to ``OFF`` it will never be emitted
 - If unset (the default) it will only be emitted when the project was
-  configured for an embedded Xcode SDK like iOS, tvOS, watchOS or any
-  of the simulators.
+  configured for an embedded Xcode SDK like iOS, tvOS, visionOS, watchOS
+  or any of the simulators.

 .. note::

--- a/Help/prop_sf/CXX_SCAN_FOR_MODULES.rst
+++ b/Help/prop_sf/CXX_SCAN_FOR_MODULES.rst
@ -1,7 +1,7 @@
 CXX_SCAN_FOR_MODULES
 --------------------

-.. versionadded:: 3.26
+.. versionadded:: 3.28

 ``CXX_SCAN_FOR_MODULES`` is a boolean specifying whether CMake will scan the
 source for C++ module dependencies.  See also the
@ -16,8 +16,3 @@ consulted.
 Note that scanning is only performed if C++20 or higher is enabled for the
 target and the source uses the ``CXX`` language.  Scanning for modules in
 sources belonging to file sets of type ``CXX_MODULES`` is always performed.
-
-.. note ::
-
-  This setting is meaningful only when experimental support for C++ modules
-  has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` gate.
--- a/Help/prop_test/GENERATED_RESOURCE_SPEC_FILE.rst
+++ b/Help/prop_test/GENERATED_RESOURCE_SPEC_FILE.rst
@ -0,0 +1,7 @@
+GENERATED_RESOURCE_SPEC_FILE
+----------------------------
+
+.. versionadded:: 3.28
+
+Path to the :ref:`dynamically-generated resource spec file
+<ctest-resource-dynamically-generated-spec-file>` generated by this test.
--- a/Help/prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MIN.rst
+++ b/Help/prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MIN.rst
@ -1,7 +1,7 @@
 COMPATIBLE_INTERFACE_NUMBER_MIN
 -------------------------------

-Properties whose maximum value from the link interface will be used.
+Properties whose minimum value from the link interface will be used.

 The ``COMPATIBLE_INTERFACE_NUMBER_MIN`` property may contain a list of
 properties for this target whose minimum value may be read at generate
--- a/Help/prop_tgt/CXX_MODULE_DIRS.rst
+++ b/Help/prop_tgt/CXX_MODULE_DIRS.rst
@ -1,11 +1,7 @@
 CXX_MODULE_DIRS
 ---------------

-.. versionadded:: 3.25
-
-.. note ::
-
-  Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+.. versionadded:: 3.28

 Semicolon-separated list of base directories of the target's default
 C++ module set (i.e. the file set with name and type ``CXX_MODULES``). The
--- a/Help/prop_tgt/CXX_MODULE_DIRS_NAME.rst
+++ b/Help/prop_tgt/CXX_MODULE_DIRS_NAME.rst
@ -1,11 +1,7 @@
 CXX_MODULE_DIRS_<NAME>
 ----------------------

-.. versionadded:: 3.25
-
-.. note ::
-
-  Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+.. versionadded:: 3.28

 Semicolon-separated list of base directories of the target's ``<NAME>`` C++
 module set, which has the set type ``CXX_MODULES``. The property supports
--- a/Help/prop_tgt/CXX_MODULE_SET.rst
+++ b/Help/prop_tgt/CXX_MODULE_SET.rst
@ -1,11 +1,7 @@
 CXX_MODULE_SET
 --------------

-.. versionadded:: 3.25
-
-.. note ::
-
-  Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+.. versionadded:: 3.28

 Semicolon-separated list of files in the target's default C++ module set,
 (i.e. the file set with name and type ``CXX_MODULES``). If any of the paths
--- a/Help/prop_tgt/CXX_MODULE_SETS.rst
+++ b/Help/prop_tgt/CXX_MODULE_SETS.rst
@ -1,11 +1,7 @@
 CXX_MODULE_SETS
 ---------------

-.. versionadded:: 3.25
-
-.. note ::
-
-  Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+.. versionadded:: 3.28

 Read-only list of the target's ``PRIVATE`` and ``PUBLIC`` C++ module sets (i.e.
 all file sets with the type ``CXX_MODULES``). Files listed in these file sets
--- a/Help/prop_tgt/CXX_MODULE_SET_NAME.rst
+++ b/Help/prop_tgt/CXX_MODULE_SET_NAME.rst
@ -1,11 +1,7 @@
 CXX_MODULE_SET_<NAME>
 ---------------------

-.. versionadded:: 3.25
-
-.. note ::
-
-  Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+.. versionadded:: 3.28

 Semicolon-separated list of files in the target's ``<NAME>`` C++ module set,
 which has the set type ``CXX_MODULES``. If any of the paths are relative, they
--- a/Help/prop_tgt/CXX_SCAN_FOR_MODULES.rst
+++ b/Help/prop_tgt/CXX_SCAN_FOR_MODULES.rst
@ -1,7 +1,7 @@
 CXX_SCAN_FOR_MODULES
 --------------------

-.. versionadded:: 3.26
+.. versionadded:: 3.28

 ``CXX_SCAN_FOR_MODULES`` is a boolean specifying whether CMake will scan C++
 sources in the target for module dependencies.  See also the
@ -20,8 +20,3 @@ scan the target's ``CXX`` sources at build time.
 Note that scanning is only performed if C++20 or higher is enabled for the
 target.  Scanning for modules in the target's sources belonging to file sets
 of type ``CXX_MODULES`` is always performed.
-
-.. note ::
-
-  This setting is meaningful only when experimental support for C++ modules
-  has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` gate.
--- a/Help/prop_tgt/DLL_NAME_WITH_SOVERSION.rst
+++ b/Help/prop_tgt/DLL_NAME_WITH_SOVERSION.rst
@ -3,8 +3,8 @@ DLL_NAME_WITH_SOVERSION

 .. versionadded:: 3.27

-This property control whether the :prop_tgt:`SOVERSION` target
-property are added to the filename of generated DLL filenames
+This property controls whether the :prop_tgt:`SOVERSION` target
+property is added to the filename of generated DLL filenames
 for the Windows platform, which is selected when the
 :variable:`WIN32` variable is set.

--- a/Help/prop_tgt/HIP_ARCHITECTURES.rst
+++ b/Help/prop_tgt/HIP_ARCHITECTURES.rst
@ -3,7 +3,8 @@ HIP_ARCHITECTURES

 .. versionadded:: 3.21

-List of AMD GPU architectures to generate device code for.
+List of GPU architectures to for which to generate device code.
+Architecture names are interpreted based on :variable:`CMAKE_HIP_PLATFORM`.

 A non-empty false value (e.g. ``OFF``) disables adding architectures.
 This is intended to support packagers and rare cases where full control
--- a/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS.rst
+++ b/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS.rst
@ -0,0 +1,10 @@
+IMPORTED_CXX_MODULES_COMPILE_DEFINITIONS
+----------------------------------------
+
+.. versionadded:: 3.28
+
+Preprocessor definitions for compiling an ``IMPORTED`` target's C++ module
+sources.
+
+CMake will automatically drop some definitions that are not supported
+by the native build tool.
--- a/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_FEATURES.rst
+++ b/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_FEATURES.rst
@ -0,0 +1,9 @@
+IMPORTED_CXX_MODULES_COMPILE_FEATURES
+-------------------------------------
+
+.. versionadded:: 3.28
+
+Compiler features enabled for this ``IMPORTED`` target's C++ modules.
+
+The value of this property is used by the generators to set the include
+paths for the compiler.
--- a/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_OPTIONS.rst
+++ b/Help/prop_tgt/IMPORTED_CXX_MODULES_COMPILE_OPTIONS.rst
@ -0,0 +1,9 @@
+IMPORTED_CXX_MODULES_COMPILE_OPTIONS
+------------------------------------
+
+.. versionadded:: 3.28
+
+List of options to pass to the compiler for this ``IMPORTED`` target's C++
+modules.
+
+.. include:: ../command/OPTIONS_SHELL.txt
--- a/Help/prop_tgt/IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES.rst
+++ b/Help/prop_tgt/IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES.rst
@ -0,0 +1,10 @@
+IMPORTED_CXX_MODULES_INCLUDE_DIRECTORIES
+----------------------------------------
+
+.. versionadded:: 3.28
+
+List of preprocessor include file search directories when compiling C++
+modules for ``IMPORTED`` targets.
+
+The value of this property is used by the generators to set the include
+paths for the compiler.
--- a/Help/prop_tgt/IMPORTED_CXX_MODULES_LINK_LIBRARIES.rst
+++ b/Help/prop_tgt/IMPORTED_CXX_MODULES_LINK_LIBRARIES.rst
@ -0,0 +1,7 @@
+IMPORTED_CXX_MODULES_LINK_LIBRARIES
+-----------------------------------
+
+.. versionadded:: 3.28
+
+List of direct dependencies to use for usage requirements for C++ modules in
+the target's C++ modules.
--- a/Help/prop_tgt/IMPORTED_IMPLIB.rst
+++ b/Help/prop_tgt/IMPORTED_IMPLIB.rst
@ -11,6 +11,12 @@ This property may be set:
 * On macOS, to an import file (e.g. ``.tbd``) created for shared libraries (see
  the :prop_tgt:`ENABLE_EXPORTS` target property). For frameworks this is the
  location of the ``.tbd`` file symlink just inside the framework folder.
+* .. versionadded:: 3.28
+    On non-DLL platforms, to the location of a shared library.
+    When set without also specifying an :prop_tgt:`IMPORTED_LOCATION`,
+    the library is considered to be a stub, and its location will not
+    be added as a runtime search path to dependents that link it.
+

 The ``IMPORTED_IMPLIB`` target property may be overridden for a
 given configuration ``<CONFIG>`` by the configuration-specific
--- a/Help/prop_tgt/IMPORTED_LOCATION.rst
+++ b/Help/prop_tgt/IMPORTED_LOCATION.rst
@ -15,6 +15,17 @@ is the location of the ``.dll`` part of the library.  For ``UNKNOWN``
 libraries this is the location of the file to be linked.  Ignored for
 non-imported targets.

+.. versionadded:: 3.28
+
+  For frameworks on macOS, this may be the location of the framework folder
+  itself.
+
+.. versionadded:: 3.28
+
+  This may be the location of a ``.xcframework`` folder on macOS. If it is,
+  any target that links against it will get the selected library's ``Headers``
+  directory as a usage requirement.
+
 The ``IMPORTED_LOCATION`` target property may be overridden for a
 given configuration ``<CONFIG>`` by the configuration-specific
 :prop_tgt:`IMPORTED_LOCATION_<CONFIG>` target property.  Furthermore,
--- a/Help/prop_tgt/IMPORTED_OBJECTS.rst
+++ b/Help/prop_tgt/IMPORTED_OBJECTS.rst
@ -31,7 +31,7 @@ once per architecture for each source file.  Unlike the other generators,
 it does not generate universal object file binaries.

 A further complication with the :generator:`Xcode` generator is that when
-targeting device platforms (iOS, tvOS or watchOS), the :generator:`Xcode`
+targeting device platforms (iOS, tvOS, visionOS or watchOS), the :generator:`Xcode`
 generator has the ability to use either the device or simulator SDK without
 needing CMake to be re-run.  The SDK can be selected at build time.
 But since some architectures can be supported by both the device and the
--- a/Show More
+++ b/Show More