New upstream version 3.28.0

.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-*,\

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
 

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";

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")

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!")

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

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.
 

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

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.

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
 

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.
 

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
 

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.

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).

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>)
 

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:
+.. |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`

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:
+.. |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

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

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:
+.. |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`

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|

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.
 

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
 ^^^^^^^^
 

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

Help/command/install.rst

@@ -1,6 +1,10 @@
 install
 -------
 
+.. only:: html
+
+   .. contents::
+
 Specify rules to run at install time.
 
 Synopsis
@@ -34,12 +38,14 @@ are executed in order during installation.
   The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the
   default copying behavior of ``install()``.
 
+.. _`common options`:
+
 There are multiple signatures for this command.  Some of them define
 installation options for files and targets.  Options common to
 multiple signatures are covered here but they are valid only for
 signatures that specify them.  The common options are:
 
-``DESTINATION``
+``DESTINATION <dir>``
   Specify the directory on disk to which a file will be installed.
   Arguments can be relative or absolute paths.
 
@@ -58,32 +64,28 @@ signatures that specify them.  The common options are:
   :variable:`CMAKE_INSTALL_PREFIX`; this prefix is used by default if
   the DESTINATION is a relative path.
 
-``PERMISSIONS``
+``PERMISSIONS <permission>...``
   Specify permissions for installed files.  Valid permissions are
   ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``,
   ``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``, ``WORLD_WRITE``,
   ``WORLD_EXECUTE``, ``SETUID``, and ``SETGID``.  Permissions that do
   not make sense on certain platforms are ignored on those platforms.
 
-``CONFIGURATIONS``
-  Specify a list of build configurations for which the install rule
-  applies (Debug, Release, etc.). Note that the values specified for
-  this option only apply to options listed AFTER the ``CONFIGURATIONS``
-  option. For example, to set separate install paths for the Debug and
-  Release configurations, do the following:
-
-  .. code-block:: cmake
+  If this option is used multiple times in a single call, its list
+  of permissions accumulates.  If an :command:`install(TARGETS)` call
+  uses `\<artifact-kind\>`_ arguments, a separate list of permissions
+  is accumulated for each kind of artifact.
 
-    install(TARGETS target
-            CONFIGURATIONS Debug
-            RUNTIME DESTINATION Debug/bin)
-    install(TARGETS target
-            CONFIGURATIONS Release
-            RUNTIME DESTINATION Release/bin)
+``CONFIGURATIONS <config>...``
+  Specify a list of build configurations for which the install rule
+  applies (Debug, Release, etc.).
 
-  Note that ``CONFIGURATIONS`` appears BEFORE ``RUNTIME DESTINATION``.
+  If this option is used multiple times in a single call, its list
+  of configurations accumulates.  If an :command:`install(TARGETS)`
+  call uses `\<artifact-kind\>`_ arguments, a separate list of
+  configurations is accumulated for each kind of artifact.
 
-``COMPONENT``
+``COMPONENT <component>``
   Specify an installation component name with which the install rule
   is associated, such as ``Runtime`` or ``Development``.  During
   component-specific installation only install rules associated with
@@ -99,7 +101,7 @@ signatures that specify them.  The common options are:
   Specify that the file is excluded from a full installation and only
   installed as part of a component-specific installation
 
-``RENAME``
+``RENAME <name>``
   Specify a name for an installed file that may be different from the
   original file.  Renaming is allowed only when a single file is
   installed by the command.
@@ -121,32 +123,43 @@ signatures that specify them.  The common options are:
   they will be created according to the uname rules on Unix-like platforms.
   Windows platforms are unaffected.
 
-Installing Targets
-^^^^^^^^^^^^^^^^^^
+Signatures
+^^^^^^^^^^
+
+.. signature::
+  install(TARGETS <target>... [...])
 
-.. _`install(TARGETS)`:
-.. _TARGETS:
+  Install target :ref:`Output Artifacts` and associated files:
+
+  .. code-block:: cmake
+
+    install(TARGETS <target>... [EXPORT <export-name>]
+            [RUNTIME_DEPENDENCIES <arg>...|RUNTIME_DEPENDENCY_SET <set-name>]
+            [<artifact-option>...]
+            [<artifact-kind> <artifact-option>...]...
+            [INCLUDES DESTINATION [<dir> ...]]
+            )
+
+  where ``<artifact-option>...`` group may contain:
 
   .. code-block:: cmake
 
-  install(TARGETS targets... [EXPORT <export-name>]
-          [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>]
-          [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
-            PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>|CXX_MODULES_BMI]
     [DESTINATION <dir>]
-           [PERMISSIONS permissions...]
-           [CONFIGURATIONS [Debug|Release|...]]
+    [PERMISSIONS <permission>...]
+    [CONFIGURATIONS <config>...]
     [COMPONENT <component>]
     [NAMELINK_COMPONENT <component>]
     [OPTIONAL] [EXCLUDE_FROM_ALL]
     [NAMELINK_ONLY|NAMELINK_SKIP]
-          ] [...]
-          [INCLUDES DESTINATION [<dir> ...]]
-          )
 
-The ``TARGETS`` form specifies rules for installing targets from a
-project.  There are several kinds of target :ref:`Output Artifacts`
-that may be installed:
+  The first ``<artifact-option>...`` group applies to target
+  :ref:`Output Artifacts` that do not have a dedicated group specified
+  later in the same call.
+
+  .. _`<artifact-kind>`:
+
+  Each ``<artifact-kind> <artifact-option>...`` group applies to
+  :ref:`Output Artifacts` of the specified artifact kind:
 
   ``ARCHIVE``
     Target artifacts of this kind include:
@@ -207,22 +220,19 @@ that may be installed:
     Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for
     ``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details.
 
-``FILE_SET <set>``
+  ``FILE_SET <set-name>``
     .. versionadded:: 3.23
 
     File sets are defined by the :command:`target_sources(FILE_SET)` command.
-  If the file set ``<set>`` exists and is ``PUBLIC`` or ``INTERFACE``, any
-  files in the set are installed under the destination (see below).
+    If the file set ``<set-name>`` exists and is ``PUBLIC`` or ``INTERFACE``,
+    any files in the set are installed under the destination (see below).
     The directory structure relative to the file set's base directories is
     preserved. For example, a file added to the file set as
     ``/blah/include/myproj/here.h`` with a base directory ``/blah/include``
     would be installed to ``myproj/here.h`` below the destination.
 
   ``CXX_MODULES_BMI``
-
-  .. note ::
-
-    Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+    .. versionadded:: 3.28
 
     Any module files from C++ modules from ``PUBLIC`` sources in a file set of
     type ``CXX_MODULES`` will be installed to the given ``DESTINATION``. All
@@ -230,10 +240,6 @@ that may be installed:
     derived from the names of the modules. An empty ``DESTINATION`` may be used
     to suppress installing these files (for use in generic code).
 
-For each of these arguments given, the arguments following them only apply
-to the target or file type specified in the argument. If none is given, the
-installation properties apply to all target types.
-
   For regular executables, static libraries and shared libraries, the
   ``DESTINATION`` argument is not required.  For these target types, when
   ``DESTINATION`` is omitted, a default destination will be taken from the
@@ -292,7 +298,7 @@ subdirectory without using file sets:
               DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
     )
 
-In addition to the common options listed above, each target can accept
+  In addition to the `common options`_ listed above, each target can accept
   the following additional arguments:
 
   ``NAMELINK_COMPONENT``
@@ -316,24 +322,8 @@ the following additional arguments:
       the linker import file created, on macOS, for shared libraries with
       :prop_tgt:`ENABLE_EXPORTS` enabled.
 
-  Consider the following example:
-
-  .. code-block:: cmake
-
-    install(TARGETS mylib
-            LIBRARY
-              COMPONENT Libraries
-              NAMELINK_COMPONENT Development
-            PUBLIC_HEADER
-              COMPONENT Development
-           )
-
-  In this scenario, if you choose to install only the ``Development``
-  component, both the headers and namelink will be installed without the
-  library. (If you don't also install the ``Libraries`` component, the
-  namelink will be a dangling symlink, and projects that link to the library
-  will have build errors.) If you install only the ``Libraries`` component,
-  only the library will be installed, without the headers and namelink.
+    See the `Example: Install Targets with Per-Artifact Components`_
+    for an example using ``NAMELINK_COMPONENT``.
 
     This option is typically used for package managers that have separate
     runtime and development packages. For example, on Debian systems, the
@@ -377,13 +367,14 @@ the following additional arguments:
     is not recommended to use ``NAMELINK_SKIP`` in conjunction with
     ``NAMELINK_COMPONENT``.
 
-The `install(TARGETS)`_ command can also accept the following options at the
-top level:
+  The :command:`install(TARGETS)` command can also accept the following
+  options at the top level:
 
   ``EXPORT``
     This option associates the installed target files with an export called
-  ``<export-name>``.  It must appear before any target options.  To actually
-  install the export file itself, call `install(EXPORT)`_, documented below.
+    ``<export-name>``.  It must appear before any target options.
+    To actually install the export file itself, call
+    :command:`install(EXPORT)`, documented below.
     See documentation of the :prop_tgt:`EXPORT_NAME` target property to change
     the name of the exported target.
 
@@ -395,22 +386,22 @@ top level:
   ``INCLUDES DESTINATION``
     This option specifies a list of directories which will be added to the
     :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the
-  ``<targets>`` when exported by the `install(EXPORT)`_ command. If a
-  relative path is specified, it is treated as relative to the
+    ``<targets>`` when exported by the :command:`install(EXPORT)` command.
+    If a relative path is specified, it is treated as relative to the
     :genex:`$<INSTALL_PREFIX>`.
 
-``RUNTIME_DEPENDENCY_SET``
+  ``RUNTIME_DEPENDENCY_SET <set-name>``
     .. versionadded:: 3.21
 
     This option causes all runtime dependencies of installed executable, shared
     library, and module targets to be added to the specified runtime dependency
     set. This set can then be installed with an
-  `install(RUNTIME_DEPENDENCY_SET)`_ command.
+    :command:`install(RUNTIME_DEPENDENCY_SET)` command.
 
     This keyword and the ``RUNTIME_DEPENDENCIES`` keyword are mutually
     exclusive.
 
-``RUNTIME_DEPENDENCIES``
+  ``RUNTIME_DEPENDENCIES <arg>...``
     .. versionadded:: 3.21
 
     This option causes all runtime dependencies of installed executable, shared
@@ -425,11 +416,11 @@ top level:
     .. code-block:: cmake
 
       install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>)
-    install(RUNTIME_DEPENDENCY_SET <set-name> args...)
+      install(RUNTIME_DEPENDENCY_SET <set-name> <arg>...)
 
     where ``<set-name>`` will be a randomly generated set name.
-  The ``args...`` may include any of the following keywords supported by
-  the `install(RUNTIME_DEPENDENCY_SET)`_ command:
+    ``<arg>...`` may include any of the following keywords supported by
+    the :command:`install(RUNTIME_DEPENDENCY_SET)` command:
 
     * ``DIRECTORIES``
     * ``PRE_INCLUDE_REGEXES``
@@ -442,26 +433,6 @@ top level:
     The ``RUNTIME_DEPENDENCIES`` and ``RUNTIME_DEPENDENCY_SET`` keywords are
     mutually exclusive.
 
-One or more groups of properties may be specified in a single call to
-the ``TARGETS`` form of this command.  A target may be installed more than
-once to different locations.  Consider hypothetical targets ``myExe``,
-``mySharedLib``, and ``myStaticLib``.  The code:
-
-.. code-block:: cmake
-
-  install(TARGETS myExe mySharedLib myStaticLib
-          RUNTIME DESTINATION bin
-          LIBRARY DESTINATION lib
-          ARCHIVE DESTINATION lib/static)
-  install(TARGETS mySharedLib DESTINATION /some/full/path)
-
-will install ``myExe`` to ``<prefix>/bin`` and ``myStaticLib`` to
-``<prefix>/lib/static``.  On non-DLL platforms ``mySharedLib`` will be
-installed to ``<prefix>/lib`` and ``/some/full/path``.  On DLL platforms
-the ``mySharedLib`` DLL will be installed to ``<prefix>/bin`` and
-``/some/full/path`` and its import library will be installed to
-``<prefix>/lib/static`` and ``/some/full/path``.
-
   :ref:`Interface Libraries` may be listed among the targets to install.
   They install no artifacts but will be included in an associated ``EXPORT``.
   If :ref:`Object Libraries` are listed but given no destination for their
@@ -478,7 +449,7 @@ set to ``TRUE`` has undefined behavior.
     :manual:`cmake-generator-expressions(7)` manual for available expressions.
 
   .. versionadded:: 3.13
-  `install(TARGETS)`_ can install targets that were created in
+    :command:`install(TARGETS)` can install targets that were created in
     other directories.  When using such cross-directory install rules, running
     ``make install`` (or similar) from a subdirectory will not guarantee that
     targets from other directories are up-to-date.  You can use
@@ -486,22 +457,21 @@ set to ``TRUE`` has undefined behavior.
     to ensure that such out-of-directory targets are built before the
     subdirectory-specific install rules are run.
 
-Installing Imported Runtime Artifacts
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. _`install(IMPORTED_RUNTIME_ARTIFACTS)`:
-.. _IMPORTED_RUNTIME_ARTIFACTS:
+.. signature::
+  install(IMPORTED_RUNTIME_ARTIFACTS <target>... [...])
 
   .. versionadded:: 3.21
 
+  Install runtime artifacts of imported targets:
+
   .. code-block:: cmake
 
-  install(IMPORTED_RUNTIME_ARTIFACTS targets...
+    install(IMPORTED_RUNTIME_ARTIFACTS <target>...
             [RUNTIME_DEPENDENCY_SET <set-name>]
             [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
              [DESTINATION <dir>]
-           [PERMISSIONS permissions...]
-           [CONFIGURATIONS [Debug|Release|...]]
+             [PERMISSIONS <permission>...]
+             [CONFIGURATIONS <config>...]
              [COMPONENT <component>]
              [OPTIONAL] [EXCLUDE_FROM_ALL]
             ] [...]
@@ -522,15 +492,11 @@ entire directory is installed.
   The ``RUNTIME_DEPENDENCY_SET`` option causes the runtime artifacts of the
   imported executable, shared library, and module library ``targets`` to be
   added to the ``<set-name>`` runtime dependency set. This set can then be
-installed with an `install(RUNTIME_DEPENDENCY_SET)`_ command.
-
-Installing Files
-^^^^^^^^^^^^^^^^
+  installed with an :command:`install(RUNTIME_DEPENDENCY_SET)` command.
 
-.. _`install(FILES)`:
-.. _`install(PROGRAMS)`:
-.. _FILES:
-.. _PROGRAMS:
+.. signature::
+  install(FILES <file>... [...])
+  install(PROGRAMS <program>... [...])
 
   .. note::
 
@@ -538,12 +504,14 @@ Installing Files
     :command:`target_sources(FILE_SET)` instead. File sets associate
     headers with a target and they install as part of the target.
 
+  Install files or programs:
+
   .. code-block:: cmake
 
-  install(<FILES|PROGRAMS> files...
+    install(<FILES|PROGRAMS> <file>...
             TYPE <type> | DESTINATION <dir>
-          [PERMISSIONS permissions...]
-          [CONFIGURATIONS [Debug|Release|...]]
+            [PERMISSIONS <permission>...]
+            [CONFIGURATIONS <config>...]
             [COMPONENT <component>]
             [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
 
@@ -628,11 +596,8 @@ subdirectory:
     use "generator expressions" with the syntax ``$<...>``.  See the
     :manual:`cmake-generator-expressions(7)` manual for available expressions.
 
-Installing Directories
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. _`install(DIRECTORY)`:
-.. _DIRECTORY:
+.. signature::
+  install(DIRECTORY <dir>... [...])
 
   .. note::
 
@@ -641,18 +606,20 @@ Installing Directories
     preserve directory structure, they also associate headers with a target
     and install as part of the target.
 
+  Install the contents of one or more directories:
+
   .. code-block:: cmake
 
     install(DIRECTORY dirs...
             TYPE <type> | DESTINATION <dir>
-          [FILE_PERMISSIONS permissions...]
-          [DIRECTORY_PERMISSIONS permissions...]
+            [FILE_PERMISSIONS <permission>...]
+            [DIRECTORY_PERMISSIONS <permission>...]
             [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
-          [CONFIGURATIONS [Debug|Release|...]]
+            [CONFIGURATIONS <config>...]
             [COMPONENT <component>] [EXCLUDE_FROM_ALL]
             [FILES_MATCHING]
             [[PATTERN <pattern> | REGEX <regex>]
-           [EXCLUDE] [PERMISSIONS permissions...]] [...])
+             [EXCLUDE] [PERMISSIONS <permission>...]] [...])
 
   The ``DIRECTORY`` form installs contents of one or more directories to a
   given destination.  The directory structure is copied verbatim to the
@@ -766,13 +733,11 @@ the appropriate cache variables.
     The list of ``dirs...`` given to ``DIRECTORY`` may use
     "generator expressions" too.
 
-Custom Installation Logic
-^^^^^^^^^^^^^^^^^^^^^^^^^
+.. signature::
+  install(SCRIPT <file> [...])
+  install(CODE <code> [...])
 
-.. _`install(CODE)`:
-.. _`install(SCRIPT)`:
-.. _CODE:
-.. _SCRIPT:
+  Invoke CMake scripts or code during installation:
 
   .. code-block:: cmake
 
@@ -805,18 +770,17 @@ will print a message during installation.
     name, not the file's contents).  See the
     :manual:`cmake-generator-expressions(7)` manual for available expressions.
 
-Installing Exports
-^^^^^^^^^^^^^^^^^^
+.. signature::
+  install(EXPORT <export-name> [...])
 
-.. _`install(EXPORT)`:
-.. _EXPORT:
+  Install a CMake file exporting targets for dependent projects:
 
   .. code-block:: cmake
 
     install(EXPORT <export-name> DESTINATION <dir>
             [NAMESPACE <namespace>] [FILE <name>.cmake]
-          [PERMISSIONS permissions...]
-          [CONFIGURATIONS [Debug|Release|...]
+            [PERMISSIONS <permission>...]
+            [CONFIGURATIONS <config>...]
             [CXX_MODULES_DIRECTORY <directory>]
             [EXPORT_LINK_INTERFACE_LIBRARIES]
             [COMPONENT <component>]
@@ -826,7 +790,7 @@ Installing Exports
   The ``EXPORT`` form generates and installs a CMake file containing code to
   import targets from the installation tree into another project.
   Target installations are associated with the export ``<export-name>``
-using the ``EXPORT`` option of the `install(TARGETS)`_ signature
+  using the ``EXPORT`` option of the :command:`install(TARGETS)` signature
   documented above.  The ``NAMESPACE`` option will prepend ``<namespace>`` to
   the target names as they are written to the import file.  By default
   the generated file will be called ``<export-name>.cmake`` but the ``FILE``
@@ -876,10 +840,7 @@ library is always installed if the headers and CMake export file are present.
     and defines required to use the libraries.
 
   ``CXX_MODULES_DIRECTORY``
-
-  .. note ::
-
-    Experimental. Gated by ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API``
+    .. versionadded:: 3.28
 
     Specify a subdirectory to store C++ module information for targets in the
     export set. This directory will be populated with files which add the
@@ -913,43 +874,42 @@ executable from the installation tree using the imported target name
     :command:`install_files`, and :command:`install_programs` commands
     is not defined.
 
-Installing Runtime Dependencies
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. _`install(RUNTIME_DEPENDENCY_SET)`:
-.. _RUNTIME_DEPENDENCY_SET:
+.. signature::
+  install(RUNTIME_DEPENDENCY_SET <set-name> [...])
 
   .. versionadded:: 3.21
 
+  Installs a runtime dependency set:
+
   .. code-block:: cmake
 
     install(RUNTIME_DEPENDENCY_SET <set-name>
             [[LIBRARY|RUNTIME|FRAMEWORK]
              [DESTINATION <dir>]
-           [PERMISSIONS permissions...]
-           [CONFIGURATIONS [Debug|Release|...]]
+             [PERMISSIONS <permission>...]
+             [CONFIGURATIONS <config>...]
              [COMPONENT <component>]
              [NAMELINK_COMPONENT <component>]
              [OPTIONAL] [EXCLUDE_FROM_ALL]
             ] [...]
-          [PRE_INCLUDE_REGEXES regexes...]
-          [PRE_EXCLUDE_REGEXES regexes...]
-          [POST_INCLUDE_REGEXES regexes...]
-          [POST_EXCLUDE_REGEXES regexes...]
-          [POST_INCLUDE_FILES files...]
-          [POST_EXCLUDE_FILES files...]
-          [DIRECTORIES directories...]
+            [PRE_INCLUDE_REGEXES <regex>...]
+            [PRE_EXCLUDE_REGEXES <regex>...]
+            [POST_INCLUDE_REGEXES <regex>...]
+            [POST_EXCLUDE_REGEXES <regex>...]
+            [POST_INCLUDE_FILES <file>...]
+            [POST_EXCLUDE_FILES <file>...]
+            [DIRECTORIES <dir>...]
             )
 
   Installs a runtime dependency set previously created by one or more
-`install(TARGETS)`_ or `install(IMPORTED_RUNTIME_ARTIFACTS)`_ commands. The
-dependencies of targets belonging to a runtime dependency set are installed in
-the ``RUNTIME`` destination and component on DLL platforms, and in the
-``LIBRARY`` destination and component on non-DLL platforms. macOS frameworks
-are installed in the ``FRAMEWORK`` destination and component.
+  :command:`install(TARGETS)` or :command:`install(IMPORTED_RUNTIME_ARTIFACTS)`
+  commands.  The dependencies of targets belonging to a runtime dependency set
+  are installed in the ``RUNTIME`` destination and component on DLL platforms,
+  and in the ``LIBRARY`` destination and component on non-DLL platforms.
+  macOS frameworks are installed in the ``FRAMEWORK`` destination and component.
   Targets built within the build tree will never be installed as runtime
   dependencies, nor will their own dependencies, unless the targets themselves
-are installed with `install(TARGETS)`_.
+  are installed with :command:`install(TARGETS)`.
 
   The generated install script calls :command:`file(GET_RUNTIME_DEPENDENCIES)`
   on the build-tree files to calculate the runtime dependencies. The build-tree
@@ -969,13 +929,105 @@ arguments to :command:`file(GET_RUNTIME_DEPENDENCIES)` (for those that provide
   a non-empty list of directories, regular expressions or files).  They all
   support :manual:`generator expressions <cmake-generator-expressions(7)>`.
 
-* ``DIRECTORIES <directories>``
-* ``PRE_INCLUDE_REGEXES <regexes>``
-* ``PRE_EXCLUDE_REGEXES <regexes>``
-* ``POST_INCLUDE_REGEXES <regexes>``
-* ``POST_EXCLUDE_REGEXES <regexes>``
-* ``POST_INCLUDE_FILES <files>``
-* ``POST_EXCLUDE_FILES <files>``
+  * ``DIRECTORIES <dir>...``
+  * ``PRE_INCLUDE_REGEXES <regex>...``
+  * ``PRE_EXCLUDE_REGEXES <regex>...``
+  * ``POST_INCLUDE_REGEXES <regex>...``
+  * ``POST_EXCLUDE_REGEXES <regex>...``
+  * ``POST_INCLUDE_FILES <file>...``
+  * ``POST_EXCLUDE_FILES <file>...``
+
+Examples
+^^^^^^^^
+
+Example: Install Targets with Per-Artifact Components
+"""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Consider a project that defines targets with different artifact kinds:
+
+.. code-block:: cmake
+
+  add_executable(myExe myExe.c)
+  add_library(myStaticLib STATIC myStaticLib.c)
+  target_sources(myStaticLib PUBLIC FILE_SET HEADERS FILES myStaticLib.h)
+  add_library(mySharedLib SHARED mySharedLib.c)
+  target_sources(mySharedLib PUBLIC FILE_SET HEADERS FILES mySharedLib.h)
+  set_property(TARGET mySharedLib PROPERTY SOVERSION 1)
+
+We may call :command:`install(TARGETS)` with `\<artifact-kind\>`_ arguments
+to specify different options for each kind of artifact:
+
+.. code-block:: cmake
+
+  install(TARGETS
+            myExe
+            mySharedLib
+            myStaticLib
+          RUNTIME           # Following options apply to runtime artifacts.
+            COMPONENT Runtime
+          LIBRARY           # Following options apply to library artifacts.
+            COMPONENT Runtime
+            NAMELINK_COMPONENT Development
+          ARCHIVE           # Following options apply to archive artifacts.
+            COMPONENT Development
+            DESTINATION lib/static
+          FILE_SET HEADERS  # Following options apply to file set HEADERS.
+            COMPONENT Development
+          )
+
+This will:
+
+* Install ``myExe`` to ``<prefix>/bin``, the default RUNTIME artifact
+  destination, as part of the ``Runtime`` component.
+
+* On non-DLL platforms:
+
+  * Install ``libmySharedLib.so.1`` to ``<prefix>/lib``, the default
+    LIBRARY artifact destination, as part of the ``Runtime`` component.
+
+  * Install the ``libmySharedLib.so`` "namelink" (symbolic link) to
+    ``<prefix>/lib``, the default LIBRARY artifact destination, as part
+    of the ``Development`` component.
+
+* On DLL platforms:
+
+  * Install ``mySharedLib.dll`` to ``<prefix>/bin``, the default RUNTIME
+    artifact destination, as part of the ``Runtime`` component.
+
+  * Install ``mySharedLib.lib`` to ``<prefix>/lib/static``, the specified
+    ARCHIVE artifact destination, as part of the ``Development`` component.
+
+* Install ``myStaticLib`` to ``<prefix>/lib/static``, the specified
+  ARCHIVE artifact destination, as part of the ``Development`` component.
+
+* Install ``mySharedLib.h`` and ``myStaticLib.h`` to ``<prefix>/include``,
+  the default destination for a file set of type HEADERS, as part of the
+  ``Development`` component.
+
+Example: Install Targets to Per-Config Destinations
+"""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Each :command:`install(TARGETS)` call installs a given target
+:ref:`output artifact <Output Artifacts>` to at most one ``DESTINATION``,
+but the install rule itself may be filtered by the ``CONFIGURATIONS`` option.
+In order to install to a different destination for each configuration, one
+call per configuration is needed.  For example, the code:
+
+.. code-block:: cmake
+
+  install(TARGETS myExe
+          CONFIGURATIONS Debug
+          RUNTIME
+            DESTINATION Debug/bin
+          )
+  install(TARGETS myExe
+          CONFIGURATIONS Release
+          RUNTIME
+            DESTINATION Release/bin
+          )
+
+will install ``myExe`` to ``<prefix>/Debug/bin`` in the Debug configuration,
+and to ``<prefix>/Release/bin`` in the Release configuration.
 
 Generated Installation Script
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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)`

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.
 

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

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

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

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

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
 

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>``

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

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
 ^^^^^^^^^^^^^^^^^

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

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.
 

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`.

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.

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`.

Help/generator/Visual Studio 10 2010.rst

@@ -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.

Help/generator/Visual Studio 11 2012.rst

@@ -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.

Help/generator/Visual Studio 12 2013.rst

@@ -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.

Help/generator/Visual Studio 9 2008.rst

@@ -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.

Help/guide/tutorial/A Basic Starting Point.rst

@@ -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
 --------
 

Help/guide/tutorial/Adding Generator Expressions.rst

@@ -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
 

Help/guide/tutorial/Adding Usage Requirements for a Library.rst

@@ -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
 

Help/guide/tutorial/Adding a Library.rst

@@ -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
 

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

Help/guide/tutorial/Selecting Static or Shared Libraries.rst

@@ -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?

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

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

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

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

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)

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

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

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

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

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

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

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.
 

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.

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.

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

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

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

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
 =================================
 

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:

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

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

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
+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``

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

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

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
 ========
 

Help/manual/presets/schema.json

@@ -106,12 +106,35 @@
         "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
     }
   ],
   "required": [
     "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.",

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

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

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

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

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::
 

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.

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.

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

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

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

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

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

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

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.

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.
 

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

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.

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.

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

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.

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.

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

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,

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