New upstream version 3.23.0

.clang-tidy

@@ -1,6 +1,8 @@
 ---
 Checks: "-*,\
 bugprone-*,\
+-bugprone-easily-swappable-parameters,\
+-bugprone-implicit-widening-of-multiplication-result,\
 -bugprone-macro-parentheses,\
 -bugprone-misplaced-widening-cast,\
 -bugprone-narrowing-conversions,\
@@ -12,6 +14,7 @@ misc-*,\
 -misc-static-assert,\
 modernize-*,\
 -modernize-avoid-c-arrays,\
+-modernize-return-braced-init-list,\
 -modernize-use-nodiscard,\
 -modernize-use-noexcept,\
 -modernize-use-trailing-return-type,\
@@ -27,6 +30,8 @@ readability-*,\
 -readability-magic-numbers,\
 -readability-named-parameter,\
 -readability-redundant-declaration,\
+-readability-redundant-member-init,\
+-readability-suspicious-call-argument,\
 -readability-uppercase-literal-suffix,\
 "
 HeaderFilterRegex: 'Source/cm[^/]*\.(h|hxx|cxx)$'

Auxiliary/cmake.m4

@@ -13,7 +13,7 @@ fi
 # $2: language (e.g. C/CXX/Fortran)
 # $3: The compiler ID, defaults to GNU.
 #     Possible values are: GNU, Intel, Clang, SunPro, HP, XL, VisualAge, PGI,
-#     PathScale, Cray, SCO, MSVC
+#     PathScale, Cray, SCO, MSVC, LCC
 # $4: optional extra arguments to cmake, e.g. "-DCMAKE_SIZEOF_VOID_P=8"
 # $5: optional path to cmake binary
 AC_DEFUN([CMAKE_FIND_PACKAGE], [

Auxiliary/vim/syntax/cmake.vim

@@ -152,6 +152,7 @@ syn keyword cmakeProperty contained
             \ DISABLED
             \ DISABLED_FEATURES
             \ DISABLE_PRECOMPILE_HEADERS
+            \ DOTNET_SDK
             \ DOTNET_TARGET_FRAMEWORK
             \ DOTNET_TARGET_FRAMEWORK_VERSION
             \ ECLIPSE_EXTRA_CPROJECT_CONTENTS
@@ -426,6 +427,7 @@ syn keyword cmakeProperty contained
             \ XCODE_SCHEME_ARGUMENTS
             \ XCODE_SCHEME_DEBUG_AS_ROOT
             \ XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
+            \ XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
             \ XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
             \ XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
             \ XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
@@ -1000,6 +1002,7 @@ syn keyword cmakeVariable contained
             \ CMAKE_DIRECTORY_LABELS
             \ CMAKE_DISABLE_PRECOMPILE_HEADERS
             \ CMAKE_DL_LIBS
+            \ CMAKE_DOTNET_SDK
             \ CMAKE_DOTNET_TARGET_FRAMEWORK
             \ CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION
             \ CMAKE_ECLIPSE_GENERATE_LINKED_RESOURCES
@@ -1524,6 +1527,7 @@ syn keyword cmakeVariable contained
             \ CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER
             \ CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
             \ CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
+            \ CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
             \ CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
             \ CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
             \ CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
@@ -1608,6 +1612,7 @@ syn keyword cmakeVariable contained
             \ CTEST_SCP_COMMAND
             \ CTEST_SITE
             \ CTEST_SOURCE_DIRECTORY
+            \ CTEST_SUBMIT_INACTIVITY_TIMEOUT
             \ CTEST_SUBMIT_URL
             \ CTEST_SVN_COMMAND
             \ CTEST_SVN_OPTIONS
@@ -1900,7 +1905,7 @@ syn keyword cmakeVariable contained
             \ DOXYGEN_XML_PROGRAMLISTING
             \ ENV
             \ EXECUTABLE_OUTPUT_PATH
-            \ GHS-MULTI
+            \ GHSMULTI
             \ IOS
             \ LIBRARY_OUTPUT_PATH
             \ MINGW
@@ -2051,6 +2056,7 @@ syn keyword cmakeKWExternalProject contained
             \ USES_TERMINAL_CONFIGURE
             \ USES_TERMINAL_DOWNLOAD
             \ USES_TERMINAL_INSTALL
+            \ USES_TERMINAL_PATCH
             \ USES_TERMINAL_TEST
             \ USES_TERMINAL_UPDATE
             \ WORKING_DIRECTORY

CMakeLists.txt

@@ -1,9 +1,14 @@
 # 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.1...3.20 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.1...3.21 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)
+
+if(POLICY CMP0129)
+  cmake_policy(SET CMP0129 NEW) # CMake 3.23
+endif()
+
 project(CMake)
 unset(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX)
 unset(CMAKE_USER_MAKE_RULES_OVERRIDE_C)
@@ -633,7 +638,7 @@ macro (CMAKE_BUILD_UTILITIES)
       message(FATAL_ERROR
         "CMAKE_USE_SYSTEM_JSONCPP is ON but a JsonCpp is not found!")
     endif()
-    if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+    if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|LCC|Clang")
       set_property(TARGET JsonCpp::JsonCpp APPEND PROPERTY
         INTERFACE_COMPILE_OPTIONS -Wno-deprecated-declarations)
     endif()
@@ -650,7 +655,7 @@ macro (CMAKE_BUILD_UTILITIES)
     if(WIN32)
       find_package(LibUV 1.38.0)
     else()
-      find_package(LibUV 1.10.0)
+      find_package(LibUV 1.28.0)
     endif()
     if(NOT LIBUV_FOUND)
       message(FATAL_ERROR
@@ -665,23 +670,33 @@ macro (CMAKE_BUILD_UTILITIES)
 
   #---------------------------------------------------------------------
   # Use curses?
-  if (UNIX)
+  if(NOT DEFINED BUILD_CursesDialog)
-    if(NOT DEFINED BUILD_CursesDialog)
+    if (UNIX)
       include(${CMake_SOURCE_DIR}/Source/Checks/Curses.cmake)
-      option(BUILD_CursesDialog "Build the CMake Curses Dialog ccmake" "${CMakeCheckCurses_COMPILED}")
+      set(BUILD_CursesDialog_DEFAULT "${CMakeCheckCurses_COMPILED}")
+    elseif(WIN32)
+      set(BUILD_CursesDialog_DEFAULT "OFF")
     endif()
-  else ()
+    option(BUILD_CursesDialog "Build the CMake Curses Dialog ccmake" "${BUILD_CursesDialog_DEFAULT}")
-    set(BUILD_CursesDialog 0)
   endif ()
   if(BUILD_CursesDialog)
-    set(CURSES_NEED_NCURSES TRUE)
+    if(UNIX)
-    find_package(Curses)
+      set(CURSES_NEED_NCURSES TRUE)
-    if(NOT CURSES_FOUND)
+      find_package(Curses)
-      message(WARNING
+      if(NOT CURSES_FOUND)
-        "'ccmake' will not be built because Curses was not found.\n"
+        message(WARNING
-        "Turn off BUILD_CursesDialog to suppress this message."
+          "'ccmake' will not be built because Curses was not found.\n"
-        )
+          "Turn off BUILD_CursesDialog to suppress this message."
-      set(BUILD_CursesDialog 0)
+          )
+        set(BUILD_CursesDialog 0)
+      endif()
+    elseif(WIN32)
+      # FIXME: Add support for system-provided pdcurses.
+      add_subdirectory(Utilities/cmpdcurses)
+      set(CURSES_LIBRARY cmpdcurses)
+      set(CURSES_INCLUDE_PATH "") # cmpdcurses has usage requirements
+      set(CMAKE_USE_SYSTEM_FORM 0)
+      set(HAVE_CURSES_USE_DEFAULT_COLORS 1)
     endif()
   endif()
   if(BUILD_CursesDialog)
@@ -820,7 +835,8 @@ if(NOT CMake_TEST_EXTERNAL_CMAKE)
        (CMAKE_C_COMPILER_ID STREQUAL "Clang" AND
         NOT "${CMAKE_C_COMPILER_VERSION}" VERSION_LESS 3.0 AND
         NOT "x${CMAKE_C_SIMULATE_ID}" STREQUAL "xMSVC") OR
-       CMAKE_C_COMPILER_ID STREQUAL "AppleClang")
+       CMAKE_C_COMPILER_ID STREQUAL "AppleClang" OR
+       CMAKE_C_COMPILER_ID STREQUAL "LCC")
       set(C_FLAGS_LIST -Wcast-align -Werror-implicit-function-declaration -Wchar-subscripts
                        -Wall -W -Wpointer-arith -Wwrite-strings -Wformat-security
                        -Wmissing-format-attribute -fno-common -Wundef

Copyright.txt

@@ -1,5 +1,5 @@
 CMake - Cross Platform Makefile Generator
-Copyright 2000-2021 Kitware, Inc. and Contributors
+Copyright 2000-2022 Kitware, Inc. and Contributors
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -62,7 +62,9 @@ The following individuals and institutions are among the Contributors:
 * Helio Chissini de Castro <helio@kde.org>
 * Ilya Lavrenov <ilya.lavrenov@itseez.com>
 * Insight Software Consortium <insightsoftwareconsortium.org>
+* Intel Corporation <www.intel.com>
 * Jan Woetzel
+* Jordan Williams <jordan@jwillikers.com>
 * Julien Schueller
 * Kelly Thompson <kgt@lanl.gov>
 * Konstantin Podsvirov <konstantin@podsvirov.pro>

Help/command/FIND_XXX.txt

@@ -170,6 +170,11 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    or in the short-hand version of the command.
    These are typically hard-coded guesses.
 
+The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`,
+:variable:`CMAKE_SYSTEM_IGNORE_PATH` and
+:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some
+of the above locations to be ignored.
+
 .. versionadded:: 3.16
   Added ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable
   various search locations.

Help/command/add_custom_command.rst

@@ -271,9 +271,47 @@ The options are:
 ``DEPFILE``
   .. versionadded:: 3.7
 
-  Specify a ``.d`` depfile which holds dependencies for the custom command.
+  Specify a depfile which holds dependencies for the custom command. It is
-  It is usually emitted by the custom command itself.  This keyword may only
+  usually emitted by the custom command itself.  This keyword may only be used
-  be used if the generator supports it, as detailed below.
+  if the generator supports it, as detailed below.
+
+  The expected format, compatible with what is generated by ``gcc`` with the
+  option ``-M``, is independent of the generator or platform.
+
+  The formal syntax, as specified using
+  `BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with
+  the regular extensions, is the following:
+
+  .. raw:: latex
+
+    \begin{small}
+
+  .. productionlist:: depfile
+    depfile: `rule`*
+    rule: `targets` (`:` (`separator` `dependencies`?)?)? `eol`
+    targets: `target` (`separator` `target`)* `separator`*
+    target: `pathname`
+    dependencies: `dependency` (`separator` `dependency`)* `separator`*
+    dependency: `pathname`
+    separator: (space | line_continue)+
+    line_continue: '\' `eol`
+    space: ' ' | '\t'
+    pathname: `character`+
+    character: `std_character` | `dollar` | `hash` | `whitespace`
+    std_character: <any character except '$', '#' or ' '>
+    dollar: '$$'
+    hash: '\#'
+    whitespace: '\ '
+    eol: '\r'? '\n'
+
+  .. raw:: latex
+
+    \end{small}
+
+  .. note::
+
+    As part of ``pathname``, any slash and backslash is interpreted as
+    a directory separator.
 
   .. versionadded:: 3.7
     The :generator:`Ninja` generator supports ``DEPFILE`` since the keyword

Help/command/add_test.rst

@@ -20,6 +20,9 @@ if necessary.  See policy :policy:`CMP0110`.  The options are:
   automatically be replaced by the location of the executable created
   at build time.
 
+  The command may be specified using
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
 ``CONFIGURATIONS``
   Restrict execution of the test only to the named configurations.
 
@@ -30,6 +33,9 @@ if necessary.  See policy :policy:`CMP0110`.  The options are:
   directory set to the build directory corresponding to the
   current source directory.
 
+  The working directory may be specified using
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
 ``COMMAND_EXPAND_LISTS``
   .. versionadded:: 3.16
 
@@ -48,9 +54,10 @@ unless the :prop_test:`PASS_REGULAR_EXPRESSION`,
 .. versionadded:: 3.16
   Added :prop_test:`SKIP_REGULAR_EXPRESSION` property.
 
-The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator
+Tests added with the ``add_test(NAME)`` signature support using
-expressions" with the syntax ``$<...>``.  See the
+:manual:`generator expressions <cmake-generator-expressions(7)>`
-:manual:`cmake-generator-expressions(7)` manual for available expressions.
+in test properties set by :command:`set_property(TEST)` or
+:command:`set_tests_properties`.
 
 Example usage:
 
@@ -73,10 +80,15 @@ file produced by target ``myexe``.
 
 ---------------------------------------------------------------------
 
+This command also supports a simpler, but less flexible, signature:
+
 .. code-block:: cmake
 
   add_test(<name> <command> [<arg>...])
 
-Add a test called ``<name>`` with the given command-line.  Unlike
+Add a test called ``<name>`` with the given command-line.
-the above ``NAME`` signature no transformation is performed on the
+
-command-line to support target names or generator expressions.
+Unlike the above ``NAME`` signature, target names are not supported
+in the command-line.  Furthermore, tests added with this signature do not
+support :manual:`generator expressions <cmake-generator-expressions(7)>`
+in the command-line or test properties.

Help/command/define_property.rst

@@ -8,15 +8,18 @@ Define and document custom properties.
   define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
                    TEST | VARIABLE | CACHED_VARIABLE>
                    PROPERTY <name> [INHERITED]
-                   BRIEF_DOCS <brief-doc> [docs...]
+                   [BRIEF_DOCS <brief-doc> [docs...]]
-                   FULL_DOCS <full-doc> [docs...])
+                   [FULL_DOCS <full-doc> [docs...]]
+                   [INITIALIZE_FROM_VARIABLE <variable>])
 
 Defines one property in a scope for use with the :command:`set_property` and
-:command:`get_property` commands.  This is primarily useful to associate
+:command:`get_property` commands. It is mainly useful for defining the way
-documentation with property names that may be retrieved with the
+a property is initialized or inherited. Historically, the command also
-:command:`get_property` command. The first argument determines the kind of
+associated documentation with a property, but that is no longer considered a
-scope in which the property should be used.  It must be one of the
+primary use case.
-following:
+
+The first argument determines the kind of scope in which the property should
+be used.  It must be one of the following:
 
 ::
 
@@ -55,5 +58,18 @@ out the contents to append to.
 
 The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be
 associated with the property as its brief and full documentation.
-Corresponding options to the :command:`get_property` command will retrieve
+CMake does not use this documentation other than making it available to the
-the documentation.
+project via corresponding options to the :command:`get_property` command.
+
+.. versionchanged:: 3.23
+
+  The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are optional.
+
+.. versionadded:: 3.23
+
+  The ``INITIALIZE_FROM_VARIABLE`` option specifies a variable from which the
+  property should be initialized. It can only be used with target properties.
+  The ``<variable>`` name must end with the property name and must not begin
+  with ``CMAKE_`` or ``_CMAKE_``. The property name must contain at least one
+  underscore. It is recommended that the property name have a prefix specific
+  to the project.

Help/command/export.rst

@@ -1,44 +1,62 @@
 export
 ------
 
-Export targets from the build tree for use by outside projects.
+Export targets or packages for outside projects to use them directly
+from the current project's build tree, without installation.
+
+See the :command:`install(EXPORT)` command to export targets from an
+install tree.
+
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+  export(`TARGETS`_ <target>... [...])
+  export(`EXPORT`_ <export-name> [...])
+  export(`PACKAGE`_ <PackageName>)
+
+Exporting Targets
+^^^^^^^^^^^^^^^^^
+
+.. _`export(TARGETS)`:
+.. _TARGETS:
 
 .. code-block:: cmake
 
-  export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
+  export(TARGETS <target>... [NAMESPACE <namespace>]
+         [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
 
 Creates a file ``<filename>`` that may be included by outside projects to
-import targets from the current project's build tree.  This is useful
+import targets named by ``<target>...`` from the current project's build tree.
-during cross-compiling to build utility executables that can run on
+This is useful during cross-compiling to build utility executables that can
-the host platform in one project and then import them into another
+run on the host platform in one project and then import them into another
-project being compiled for the target platform.  If the ``NAMESPACE``
+project being compiled for the target platform.
-option is given the ``<namespace>`` string will be prepended to all target
-names written to the file.
-
-Target installations are associated with the export ``<export-name>``
-using the ``EXPORT`` option of the :command:`install(TARGETS)` command.
 
 The file created by this command is specific to the build tree and
 should never be installed.  See the :command:`install(EXPORT)` command to
-export targets from an installation tree.
+export targets from an install tree.
 
-The properties set on the generated IMPORTED targets will have the
+The options are:
-same values as the final values of the input TARGETS.
 
-.. code-block:: cmake
+``NAMESPACE <namespace>``
+  Prepend the ``<namespace>`` string to all target names written to the file.
 
-  export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
+``APPEND``
-         [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
+  Append to the file instead of overwriting it.  This can be used to
+  incrementally export multiple targets to the same file.
+
+``EXPORT_LINK_INTERFACE_LIBRARIES``
+  Include the contents of the properties named with the pattern
+  ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``
+  in the export, even when policy :policy:`CMP0022` is NEW.  This is useful
+  to support consumers using CMake versions older than 2.8.12.
 
-This signature is similar to the ``EXPORT`` signature, but targets are listed
+This signature requires all targets to be listed explicitly.  If a library
-explicitly rather than specified as an export-name.  If the APPEND option is
+target is included in the export, but a target to which it links is not
-given the generated code will be appended to the file instead of overwriting it.
+included, the behavior is unspecified.  See the `export(EXPORT)`_ signature
-The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the
+to automatically export the same targets from the build tree as
-contents of the properties matching
+:command:`install(EXPORT)` would from an install tree.
-``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when
-policy CMP0022 is NEW.  If a library target is included in the export
-but a target to which it links is not included the behavior is
-unspecified.
 
 .. note::
 
@@ -49,6 +67,50 @@ unspecified.
   transitive usage requirements of other targets that link to the
   object libraries in their implementation.
 
+Exporting Targets to Android.mk
+"""""""""""""""""""""""""""""""
+
+.. code-block:: cmake
+
+  export(TARGETS <target>... ANDROID_MK <filename>)
+
+.. versionadded:: 3.7
+
+This signature exports cmake built targets to the android ndk build system
+by creating an ``Android.mk`` file that references the prebuilt targets. The
+Android NDK supports the use of prebuilt libraries, both static and shared.
+This allows cmake to build the libraries of a project and make them available
+to an ndk build system complete with transitive dependencies, include flags
+and defines required to use the libraries. The signature takes a list of
+targets and puts them in the ``Android.mk`` file specified by the
+``<filename>`` given. This signature can only be used if policy
+:policy:`CMP0022` is NEW for all targets given. A error will be issued if
+that policy is set to OLD for one of the targets.
+
+Exporting Targets matching install(EXPORT)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _`export(EXPORT)`:
+.. _EXPORT:
+
+.. code-block:: cmake
+
+  export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
+
+Creates a file ``<filename>`` that may be included by outside projects to
+import targets from the current project's build tree.  This is the same
+as the `export(TARGETS)`_ signature, except that the targets are not
+explicitly listed.  Instead, it exports the targets associated with
+the installation export ``<export-name>``.  Target installations may be
+associated with the export ``<export-name>`` using the ``EXPORT`` option
+of the :command:`install(TARGETS)` command.
+
+Exporting Packages
+^^^^^^^^^^^^^^^^^^
+
+.. _`export(PACKAGE)`:
+.. _PACKAGE:
+
 .. code-block:: cmake
 
   export(PACKAGE <PackageName>)
@@ -74,20 +136,3 @@ registry.
   outside the source and build trees.  Set the
   :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories
   to the CMake user package registry.
-
-.. code-block:: cmake
-
-  export(TARGETS [target1 [target2 [...]]]  [ANDROID_MK <filename>])
-
-.. versionadded:: 3.7
-
-This signature exports cmake built targets to the android ndk build system
-by creating an Android.mk file that references the prebuilt targets. The
-Android NDK supports the use of prebuilt libraries, both static and shared.
-This allows cmake to build the libraries of a project and make them available
-to an ndk build system complete with transitive dependencies, include flags
-and defines required to use the libraries. The signature takes a list of
-targets and puts them in the Android.mk file specified by the ``<filename>``
-given. This signature can only be used if policy CMP0022 is NEW for all
-targets given. A error will be issued if that policy is set to OLD for one
-of the targets.

Help/command/find_package.rst

@@ -363,6 +363,11 @@ enabled.
 9. Search paths specified by the ``PATHS`` option.  These are typically
    hard-coded guesses.
 
+The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`,
+:variable:`CMAKE_SYSTEM_IGNORE_PATH` and
+:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some
+of the above locations to be ignored.
+
 .. versionadded:: 3.16
    Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable
    various search locations.

Help/command/if.rst

@@ -38,21 +38,29 @@ The following syntax applies to the ``condition`` argument of
 the ``if``, ``elseif`` and :command:`while` clauses.
 
 Compound conditions are evaluated in the following order of precedence:
-Innermost parentheses are evaluated first. Next come unary tests such
+
-as `EXISTS`_, `COMMAND`_, and `DEFINED`_.  Then binary tests such as
+1. Parentheses.
-`EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_, `GREATER_EQUAL`_,
+
-`STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_, `STRGREATER`_,
+2. Unary tests such as `EXISTS`_, `COMMAND`_, and `DEFINED`_.
-`STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_,
+
-`VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_,
+3. Binary tests such as `EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_,
-and `MATCHES`_.  Then the boolean operators in the order `NOT`_,  `AND`_,
+   `GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_,
-and finally `OR`_.
+   `STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_,
+   `VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_,
+   and `MATCHES`_.
+
+4. Unary logical operator `NOT`_.
+
+5. Binary logical operators `AND`_ and `OR`_, from left to right,
+   without any short-circuit.
 
 Basic Expressions
 """""""""""""""""
 
 ``if(<constant>)``
  True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``,
- or a non-zero number.  False if the constant is ``0``, ``OFF``,
+ or a non-zero number (including floating point numbers).
+ False if the constant is ``0``, ``OFF``,
  ``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string,
  or ends in the suffix ``-NOTFOUND``.  Named boolean constants are
  case-insensitive.  If the argument is not one of these specific
@@ -126,7 +134,16 @@ Existence Checks
 ``if(DEFINED <name>|CACHE{<name>}|ENV{<name>})``
  True if a variable, cache variable or environment variable
  with given ``<name>`` is defined. The value of the variable
- does not matter. Note that macro arguments are not variables.
+ does not matter. Note the following caveats:
+
+ * Macro arguments are not variables.
+ * It is not possible to test directly whether a `<name>` is a non-cache
+   variable.  The expression ``if(DEFINED someName)`` will evaluate to true
+   if either a cache or non-cache variable ``someName`` exists.  In
+   comparison, the expression ``if(DEFINED CACHE{someName})`` will only
+   evaluate to true if a cache variable ``someName`` exists.  Both expressions
+   need to be tested if you need to know whether a non-cache variable exists:
+   ``if(DEFINED someName AND NOT DEFINED CACHE{someName})``.
 
  .. versionadded:: 3.14
   Added support for ``CACHE{<name>}`` variables.

Help/command/install.rst

@@ -132,7 +132,7 @@ Installing Targets
   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]
+            PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>]
            [DESTINATION <dir>]
            [PERMISSIONS permissions...]
            [CONFIGURATIONS [Debug|Release|...]]
@@ -204,6 +204,17 @@ that may be installed:
   Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for
   ``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details.
 
+``FILE_SET <set>``
+  .. 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).
+  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.
+
 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. If only one is given then
@@ -214,30 +225,32 @@ 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
 appropriate variable from :module:`GNUInstallDirs`, or set to a built-in
-default value if that variable is not defined.  The same is true for the
+default value if that variable is not defined.  The same is true for file
-public and private headers associated with the installed targets through the
+sets, and the public and private headers associated with the installed
-:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties.
+targets through the :prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER`
-A destination must always be provided for module libraries, Apple bundles and
+target properties. A destination must always be provided for module libraries,
-frameworks.  A destination can be omitted for interface and object libraries,
+Apple bundles and frameworks.  A destination can be omitted for interface and
-but they are handled differently (see the discussion of this topic toward the
+object libraries, but they are handled differently (see the discussion of this
-end of this section).
+topic toward the end of this section).
 
 The following table shows the target types with their associated variables and
 built-in defaults that apply when no destination is given:
 
-================== =============================== ======================
+=============================== =============================== ======================
-   Target Type         GNUInstallDirs Variable        Built-In Default
+   Target Type                      GNUInstallDirs Variable        Built-In Default
-================== =============================== ======================
+=============================== =============================== ======================
-``RUNTIME``        ``${CMAKE_INSTALL_BINDIR}``     ``bin``
+``RUNTIME``                     ``${CMAKE_INSTALL_BINDIR}``     ``bin``
-``LIBRARY``        ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
+``LIBRARY``                     ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
-``ARCHIVE``        ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
+``ARCHIVE``                     ``${CMAKE_INSTALL_LIBDIR}``     ``lib``
-``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
+``PRIVATE_HEADER``              ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
-``PUBLIC_HEADER``  ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
+``PUBLIC_HEADER``               ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
-================== =============================== ======================
+``FILE_SET`` (type ``HEADERS``) ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
+=============================== =============================== ======================
 
 Projects wishing to follow the common practice of installing headers into a
-project-specific subdirectory will need to provide a destination rather than
+project-specific subdirectory may prefer using file sets with appropriate
-rely on the above.
+paths and base directories. Otherwise, they must provide a ``DESTINATION``
+instead of being able to rely on the above (see next example below).
 
 To make packages compliant with distribution filesystem layout policies, if
 projects must specify a ``DESTINATION``, it is recommended that they use a
@@ -246,7 +259,7 @@ This allows package maintainers to control the install destination by setting
 the appropriate cache variables.  The following example shows a static library
 being installed to the default destination provided by
 :module:`GNUInstallDirs`, but with its headers installed to a project-specific
-subdirectory that follows the above recommendation:
+subdirectory without using file sets:
 
 .. code-block:: cmake
 
@@ -338,6 +351,11 @@ top level:
   See documentation of the :prop_tgt:`EXPORT_NAME` target property to change
   the name of the exported target.
 
+  If ``EXPORT`` is used and the targets include ``PUBLIC`` or ``INTERFACE``
+  file sets, all of them must be specified with ``FILE_SET`` arguments. All
+  ``PUBLIC`` or ``INTERFACE`` file sets associated with a target are included
+  in the export.
+
 ``INCLUDES DESTINATION``
   This option specifies a list of directories which will be added to the
   :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the
@@ -478,6 +496,12 @@ Installing Files
 .. _FILES:
 .. _PROGRAMS:
 
+.. note::
+
+  If installing header files, consider using file sets defined by
+  :command:`target_sources(FILE_SET)` instead. File sets associate
+  headers with a target and they install as part of the target.
+
 .. code-block:: cmake
 
   install(<FILES|PROGRAMS> files...
@@ -534,7 +558,8 @@ file type if they wish to explicitly define the install destination.
 
 Projects wishing to follow the common practice of installing headers into a
 project-specific subdirectory will need to provide a destination rather than
-rely on the above.
+rely on the above. Using file sets for headers instead of ``install(FILES)``
+would be even better (see :command:`target_sources(FILE_SET)`).
 
 Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
 a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
@@ -547,13 +572,14 @@ projects must specify a ``DESTINATION``, it is recommended that they use a
 path that begins with the appropriate :module:`GNUInstallDirs` variable.
 This allows package maintainers to control the install destination by setting
 the appropriate cache variables.  The following example shows how to follow
-this advice while installing headers to a project-specific subdirectory:
+this advice while installing an image to a project-specific documentation
+subdirectory:
 
 .. code-block:: cmake
 
   include(GNUInstallDirs)
-  install(FILES mylib.h
+  install(FILES logo.png
-          DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
+          DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj
   )
 
 .. versionadded:: 3.4
@@ -572,6 +598,13 @@ Installing Directories
 .. _`install(DIRECTORY)`:
 .. _DIRECTORY:
 
+.. note::
+
+  To install a directory sub-tree of headers, consider using file sets
+  defined by :command:`target_sources(FILE_SET)` instead. File sets not only
+  preserve directory structure, they also associate headers with a target
+  and install as part of the target.
+
 .. code-block:: cmake
 
   install(DIRECTORY dirs...
@@ -623,10 +656,10 @@ any expression.  For example, the code
 
 .. code-block:: cmake
 
-  install(DIRECTORY src/ DESTINATION include/myproj
+  install(DIRECTORY src/ DESTINATION doc/myproj
-          FILES_MATCHING PATTERN "*.h")
+          FILES_MATCHING PATTERN "*.png")
 
-will extract and install header files from a source tree.
+will extract and install images from a source tree.
 
 Some options may follow a ``PATTERN`` or ``REGEX`` expression as described
 under :ref:`string(REGEX) <Regex Specification>` and are applied

Help/command/list.rst

@@ -128,7 +128,9 @@ Modification
 
   list(APPEND <list> [<element> ...])
 
-Appends elements to the list.
+Appends elements to the list. If no variable named ``<list>`` exists in the
+current scope its value is treated as empty and the elements are appended to
+that empty list.
 
 .. _FILTER:
 
@@ -150,7 +152,12 @@ For more information on regular expressions look under
 
   list(INSERT <list> <element_index> <element> [<element> ...])
 
-Inserts elements to the list to the specified location.
+Inserts elements to the list to the specified index. It is an
+error to specify an out-of-range index. Valid indexes are 0 to `N`
+where `N` is the length of the list, inclusive. An empty list
+has length 0. If no variable named ``<list>`` exists in the
+current scope its value is treated as empty and the elements are
+inserted in that empty list.
 
 .. _POP_BACK:
 
@@ -186,7 +193,9 @@ to the given variables and then remove the first `N` values from
 
 .. versionadded:: 3.15
 
-Insert elements to the 0th position in the list.
+Insert elements to the 0th position in the list. If no variable named
+``<list>`` exists in the current scope its value is treated as empty and
+the elements are prepended to that empty list.
 
 .. _REMOVE_ITEM:
 

Help/command/set_property.rst

@@ -85,6 +85,10 @@ It must be one of the following:
   Scope may name zero or more existing tests.
   See also the :command:`set_tests_properties` command.
 
+  Test property values may be specified using
+  :manual:`generator expressions <cmake-generator-expressions(7)>`
+  for tests created by the :command:`add_test(NAME)` signature.
+
 ``CACHE``
   Scope must name zero or more cache existing entries.
 

Help/command/set_tests_properties.rst

@@ -9,8 +9,10 @@ Set a property of the tests.
 
 Sets a property for the tests.  If the test is not found, CMake
 will report an error.
-:manual:`Generator expressions <cmake-generator-expressions(7)>` will be
+
-expanded the same as supported by the test's :command:`add_test` call.
+Test property values may be specified using
+:manual:`generator expressions <cmake-generator-expressions(7)>`
+for tests created by the :command:`add_test(NAME)` signature.
 
 See also the :command:`set_property(TEST)` command.
 

Help/command/string.rst

@@ -490,6 +490,9 @@ specifiers:
 ``%S``
   The second of the current minute.  60 represents a leap second. (00-60)
 
+``%f``
+  The microsecond of the current second (000000-999999).
+
 ``%U``
   The week number of the current year (00-53).
 

Help/command/target_include_directories.rst

@@ -27,14 +27,16 @@ The following arguments specify include directories.
 .. versionadded:: 3.11
   Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
 
-Specified include directories may be absolute paths or relative paths.
+Repeated calls for the same ``<target>`` append items in the order called.
-Repeated calls for the same <target> append items in the order called.  If
+
-``SYSTEM`` is specified, the compiler will be told the
+If ``SYSTEM`` is specified, the compiler will be told the directories
-directories are meant as system include directories on some platforms
+are meant as system include directories on some platforms.  This may
-(signalling this setting might achieve effects such as the compiler
+have effects such as suppressing warnings or skipping the contained
-skipping warnings, or these fixed-install system files not being
+headers in dependency calculations (see compiler documentation).
-considered in dependency calculations - see compiler docs).  If ``SYSTEM``
+Additionally, system include directories are searched after normal
-is used together with ``PUBLIC`` or ``INTERFACE``, the
+include directories regardless of the order specified.
+
+If ``SYSTEM`` is used together with ``PUBLIC`` or ``INTERFACE``, the
 :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be
 populated with the specified directories.
 
@@ -43,12 +45,22 @@ with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
 
+Specified include directories may be absolute paths or relative paths.
+A relative path will be interpreted as relative to the current source
+directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and converted to an
+absolute path before storing it in the associated target property.
+If the path starts with a generator expression, it will always be assumed
+to be an absolute path (with one exception noted below) and will be used
+unmodified.
+
 Include directories usage requirements commonly differ between the build-tree
-and the install-tree.  The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE``
+and the install-tree.  The :genex:`BUILD_INTERFACE` and
-generator expressions can be used to describe separate usage requirements
+:genex:`INSTALL_INTERFACE` generator expressions can be used to describe
-based on the usage location.  Relative paths are allowed within the
+separate usage requirements based on the usage location.  Relative paths
-``INSTALL_INTERFACE`` expression and are interpreted relative to the
+are allowed within the :genex:`INSTALL_INTERFACE` expression and are
-installation prefix.  For example:
+interpreted as relative to the installation prefix.  Relative paths should not
+be used in :genex:`BUILD_INTERFACE` expressions because they will not be
+converted to absolute.  For example:
 
 .. code-block:: cmake
 

Help/command/target_sources.rst

@@ -15,34 +15,143 @@ Specifies sources to use when building a target and/or its dependents.
 The named ``<target>`` must have been created by a command such as
 :command:`add_executable` or :command:`add_library` or
 :command:`add_custom_target` and must not be an
-:ref:`ALIAS target <Alias Targets>`.
+:ref:`ALIAS target <Alias Targets>`.  The ``<items>`` may use
-
+:manual:`generator expressions <cmake-generator-expressions(7)>`.
-.. versionchanged:: 3.13
-  Relative source file paths are interpreted as being relative to the current
-  source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`).
-  See policy :policy:`CMP0076`.
 
 .. versionadded:: 3.20
   ``<target>`` can be a custom target.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the scope of the items following them.  ``PRIVATE`` and ``PUBLIC``
+specify the scope of the source file paths (``<items>``) that follow
-items will populate the :prop_tgt:`SOURCES` property of
+them.  ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`SOURCES`
-``<target>``, which are used when building the target itself.
+property of ``<target>``, which are used when building the target itself.
 ``PUBLIC`` and ``INTERFACE`` items will populate the
 :prop_tgt:`INTERFACE_SOURCES` property of ``<target>``, which are used
-when building dependents.
+when building dependents.  A target created by :command:`add_custom_target`
-The following arguments specify sources.  Repeated calls for the same
+can only have ``PRIVATE`` scope.
-``<target>`` append items in the order called. The targets created by
+
-:command:`add_custom_target` can only have ``PRIVATE`` scope.
+Repeated calls for the same ``<target>`` append items in the order called.
 
 .. versionadded:: 3.3
   Allow exporting targets with :prop_tgt:`INTERFACE_SOURCES`.
 
 .. versionadded:: 3.11
-  Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
+  Allow setting ``INTERFACE`` items on
+  :ref:`IMPORTED targets <Imported Targets>`.
+
+.. versionchanged:: 3.13
+  Relative source file paths are interpreted as being relative to the current
+  source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`).
+  See policy :policy:`CMP0076`.
+
+A path that begins with a generator expression is left unmodified.
+When a target's :prop_tgt:`SOURCE_DIR` property differs from
+:variable:`CMAKE_CURRENT_SOURCE_DIR`, use absolute paths in generator
+expressions to ensure the sources are correctly assigned to the target.
+
+.. code-block:: cmake
+
+  # WRONG: starts with generator expression, but relative path used
+  target_sources(MyTarget "$<$<CONFIG:Debug>:dbgsrc.cpp>")
+
+  # CORRECT: absolute path used inside the generator expression
+  target_sources(MyTarget "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>")
+
+See the :manual:`cmake-buildsystem(7)` manual for more on defining
+buildsystem properties.
+
+File Sets
+^^^^^^^^^
+
+.. versionadded:: 3.23
+
+.. code-block:: cmake
+
+  target_sources(<target>
+    [<INTERFACE|PUBLIC|PRIVATE>
+     [FILE_SET <set> [TYPE <type>] [BASE_DIRS <dirs>...] [FILES <files>...]]...
+    ]...)
+
+Adds a file set to a target, or adds files to an existing file set. Targets
+have zero or more named file sets. Each file set has a name, a type, a scope of
+``INTERFACE``, ``PUBLIC``, or ``PRIVATE``, one or more base directories, and
+files within those directories. The only acceptable type is ``HEADERS``. The
+optional default file sets are named after their type. The target may not be a
+custom target.
+
+Files in a ``PRIVATE`` or ``PUBLIC`` file set are marked as source files for
+the purposes of IDE integration. Additionally, files in ``HEADERS`` file sets
+have their :prop_sf:`HEADER_FILE_ONLY` property set to ``TRUE``. Files in an
+``INTERFACE`` or ``PUBLIC`` file set can be installed with the
+:command:`install(TARGETS)` command, and exported with the
+:command:`install(EXPORT)` and :command:`export` commands.
+
+Each ``target_sources(FILE_SET)`` entry starts with ``INTERFACE``, ``PUBLIC``, or
+``PRIVATE`` and accepts the following arguments:
+
+``FILE_SET <set>``
+
+  The name of the file set to create or add to. It must contain only letters,
+  numbers and underscores. Names starting with a capital letter are reserved
+  for built-in file sets predefined by CMake. The only predefined set name is
+  ``HEADERS``. All other set names must not start with a capital letter or
+  underscore.
+
+``TYPE <type>``
+
+  Every file set is associated with a particular type of file. ``HEADERS``
+  is currently the only defined type and it is an error to specify anything
+  else. As a special case, if the name of the file set is ``HEADERS``, the
+  type does not need to be specified and the ``TYPE <type>`` arguments can be
+  omitted. For all other file set names, ``TYPE`` is required.
+
+``BASE_DIRS <dirs>...``
+
+  An optional list of base directories of the file set. Any relative path
+  is treated as relative to the current source directory
+  (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). If no ``BASE_DIRS`` are
+  specified when the file set is first created, the value of
+  :variable:`CMAKE_CURRENT_SOURCE_DIR` is added. This argument supports
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+  No two base directories for a file set may be sub-directories of each other.
+  This requirement must be met across all base directories added to a file set,
+  not just those within a single call to ``target_sources()``.
+
+``FILES <files>...``
+
+  An optional list of files to add to the file set. Each file must be in
+  one of the base directories, or a subdirectory of one of the base
+  directories. This argument supports
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+  If relative paths are specified, they are considered relative to
+  :variable:`CMAKE_CURRENT_SOURCE_DIR` at the time ``target_sources()`` is
+  called. An exception to this is a path starting with ``$<``. Such paths
+  are treated as relative to the target's source directory after evaluation
+  of generator expressions.
+
+The following target properties are set by ``target_sources(FILE_SET)``,
+but they should not generally be manipulated directly:
+
+* :prop_tgt:`HEADER_SETS`
+* :prop_tgt:`INTERFACE_HEADER_SETS`
+* :prop_tgt:`HEADER_SET`
+* :prop_tgt:`HEADER_SET_<NAME>`
+* :prop_tgt:`HEADER_DIRS`
+* :prop_tgt:`HEADER_DIRS_<NAME>`
+
+Target properties related to include directories are also modified by
+``target_sources(FILE_SET)`` as follows:
+
+:prop_tgt:`INCLUDE_DIRECTORIES`
+
+  If the ``TYPE`` is ``HEADERS``, and the scope of the file set is ``PRIVATE``
+  or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are wrapped in
+  :genex:`$<BUILD_INTERFACE>` and appended to this property.
+
+:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
 
-Arguments to ``target_sources`` may use "generator expressions"
+  If the ``TYPE`` is ``HEADERS``, and the scope of the file set is
-with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
+  ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of the file set are
-manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
+  wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this property.
-manual for more on defining buildsystem properties.

Help/command/try_compile.rst

@@ -19,10 +19,6 @@ Try Compiling Whole Projects
 Try building a project.  The success or failure of the ``try_compile``,
 i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``.
 
-.. versionadded:: 3.14
-  The name of the ``<resultVar>`` is defined by the user.  Previously, it had
-  a fixed name ``RESULT_VAR``.
-
 In this form, ``<srcdir>`` should contain a complete CMake project with a
 ``CMakeLists.txt`` file and all sources.  The ``<bindir>`` and ``<srcdir>``
 will not be deleted after this command is run.  Specify ``<targetName>`` to
@@ -51,10 +47,6 @@ Try building an executable or static library from one or more source files
 variable).  The success or failure of the ``try_compile``, i.e. ``TRUE`` or
 ``FALSE`` respectively, is returned in ``<resultVar>``.
 
-.. versionadded:: 3.14
-  The name of the ``<resultVar>`` is defined by the user.  Previously, it had
-  a fixed name ``RESULT_VAR``.
-
 In this form, one or more source files must be provided.  If
 :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to ``EXECUTABLE``,
 the sources must include a definition for ``main`` and CMake will create a

Help/command/try_run.rst

@@ -30,11 +30,6 @@ executable was built, but failed to run, then ``<runResultVar>`` will be
 set to ``FAILED_TO_RUN``.  See the :command:`try_compile` command for
 information on how the test project is constructed to build the source file.
 
-.. versionadded:: 3.14
-  The names of the result variables ``<runResultVar>`` and
-  ``<compileResultVar>`` are defined by the user.  Previously, they had
-  fixed names ``RUN_RESULT_VAR`` and ``COMPILE_RESULT_VAR``.
-
 The options are:
 
 ``CMAKE_FLAGS <flags>...``

Help/cpack_gen/dmg.rst

@@ -54,6 +54,27 @@ on macOS:
  Default behavior is to include a symlink to ``/Applications`` in the DMG.
  Set this option to ``ON`` to avoid adding the symlink.
 
+.. variable:: CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE
+
+ .. versionadded:: 3.23
+
+ Control whether :variable:`CPACK_RESOURCE_FILE_LICENSE`, if set to a
+ non-default value, is used as the license agreement provided when
+ mounting the DMG.  If ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`` is
+ not set, :manual:`cpack(1)` defaults to off.
+
+ In a CMake project that uses the :module:`CPack` module to generate
+ ``CPackConfig.cmake``, ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE``
+ is automatically enabled by default if it is not set and
+ :variable:`CPACK_RESOURCE_FILE_LICENSE` is set to a non-default value.
+
+ .. note::
+
+  This option was added in response to macOS 12.0's deprecation of
+  the ``hdiutil udifrez`` command to make its use optional.
+  CPack 3.22 and below always use :variable:`CPACK_RESOURCE_FILE_LICENSE`,
+  if set to a non-default value, as the DMG license.
+
 .. variable:: CPACK_DMG_SLA_DIR
 
   .. versionadded:: 3.5

Help/cpack_gen/ifw.rst

@@ -24,12 +24,12 @@ Microsoft Windows, and macOS.
 To make use of this generator, QtIFW needs to be installed.
 The :module:`CPackIFW` module looks for the location of the
 QtIFW command-line utilities, and defines several commands to
-control the behavior of this generator.
+control the behavior of this generator. See `Hints for Finding QtIFW`_.
 
 Variables
 ^^^^^^^^^
 
-You can use the following variables to change behavior of CPack ``IFW``
+You can use the following variables to change the behavior of the CPack ``IFW``
 generator.
 
 Debug
@@ -48,12 +48,12 @@ Package
 .. variable:: CPACK_IFW_PACKAGE_TITLE
 
  Name of the installer as displayed on the title bar.
- By default used :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`.
+ If not specified, it defaults to :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`.
 
 .. variable:: CPACK_IFW_PACKAGE_PUBLISHER
 
  Publisher of the software (as shown in the Windows Control Panel).
- By default used :variable:`CPACK_PACKAGE_VENDOR`.
+ If not specified, it defaults to :variable:`CPACK_PACKAGE_VENDOR`.
 
 .. variable:: CPACK_IFW_PRODUCT_URL
 
@@ -61,83 +61,93 @@ Package
 
 .. variable:: CPACK_IFW_PACKAGE_ICON
 
- Filename for a custom installer icon. The actual file is '.icns' (macOS),
+ Filename for a custom installer icon. It must be an absolute path.
- '.ico' (Windows). No functionality on Unix.
+ This should be a ``.icns`` file on macOS and a ``.ico`` file on Windows.
+ It is ignored on other platforms.
 
 .. variable:: CPACK_IFW_PACKAGE_WINDOW_ICON
 
  Filename for a custom window icon in PNG format for the Installer
- application.
+ application. It must be an absolute path.
 
 .. variable:: CPACK_IFW_PACKAGE_LOGO
 
- Filename for a logo is used as QWizard::LogoPixmap.
+ Filename for a logo image in PNG format, used as ``QWizard::LogoPixmap``.
+ It must be an absolute path.
 
 .. variable:: CPACK_IFW_PACKAGE_WATERMARK
 
  .. versionadded:: 3.8
 
- Filename for a watermark is used as QWizard::WatermarkPixmap.
+ Filename for a watermark image in PNG format, used as
+ ``QWizard::WatermarkPixmap``. It must be an absolute path.
 
 .. variable:: CPACK_IFW_PACKAGE_BANNER
 
  .. versionadded:: 3.8
 
- Filename for a banner is used as QWizard::BannerPixmap.
+ Filename for a banner image in PNG format, used as ``QWizard::BannerPixmap``.
+ It must be an absolute path.
 
 .. variable:: CPACK_IFW_PACKAGE_BACKGROUND
 
  .. versionadded:: 3.8
 
- Filename for an image used as QWizard::BackgroundPixmap (only used by MacStyle).
+ Filename for a background image in PNG format, used as
+ ``QWizard::BackgroundPixmap`` (only used by ``MacStyle``). It must be an
+ absolute path.
 
 .. variable:: CPACK_IFW_PACKAGE_WIZARD_STYLE
 
  .. versionadded:: 3.8
 
- Wizard style to be used ("Modern", "Mac", "Aero" or "Classic").
+ Wizard style to be used (``Modern``, ``Mac``, ``Aero`` or ``Classic``).
 
 .. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH
 
  .. versionadded:: 3.8
 
- Default width of the wizard in pixels. Setting a banner image will override this.
+ Default width of the wizard in pixels. Setting a banner image will override
+ this.
 
 .. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT
 
  .. versionadded:: 3.8
 
- Default height of the wizard in pixels. Setting a watermark image will override this.
+ Default height of the wizard in pixels. Setting a watermark image will
+ override this.
 
 .. variable:: CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST
 
  .. versionadded:: 3.20
 
- Set to ``OFF`` if the widget listing installer pages on the left side of the wizard should not be shown.
+ Set to ``OFF`` if the widget listing installer pages on the left side of the
+ wizard should not be shown.
 
- It is ``ON`` by default, but will only have an effect if using QtIFW 4.0 or later.
+ It is ``ON`` by default, but will only have an effect if using QtIFW 4.0 or
+ later.
 
 .. variable:: CPACK_IFW_PACKAGE_TITLE_COLOR
 
  .. versionadded:: 3.8
 
- Color of the titles and subtitles (takes an HTML color code, such as "#88FF33").
+ Color of the titles and subtitles (takes an HTML color code, such as
+ ``#88FF33``).
 
 .. variable:: CPACK_IFW_PACKAGE_STYLE_SHEET
 
  .. versionadded:: 3.15
 
- Filename for a stylesheet.
+ Filename for a stylesheet. It must be an absolute path.
 
 .. variable:: CPACK_IFW_TARGET_DIRECTORY
 
  Default target directory for installation.
- By default used
+ If :variable:`CPACK_PACKAGE_INSTALL_DIRECTORY` is set, this defaults to
- "@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`"
+ ``@ApplicationsDir@/${CPACK_PACKAGE_INSTALL_DIRECTORY}``. If that variable
- (variables embedded in '@' are expanded by the
+ isn't set either, the default used is ``@RootDir@/usr/local``.
- `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_).
+ Predefined variables of the form ``@...@`` are expanded by the
-
+ `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_.
- You can use predefined variables.
 
 .. variable:: CPACK_IFW_ADMIN_TARGET_DIRECTORY
 
@@ -155,29 +165,28 @@ Package
 
 .. variable:: CPACK_IFW_PACKAGE_GROUP
 
- The group, which will be used to configure the root package
+ The group, which will be used to configure the root package.
 
 .. variable:: CPACK_IFW_PACKAGE_NAME
 
- The root package name, which will be used if configuration group is not
+ The root package name, which will be used if the configuration group is not
- specified
+ specified.
 
 .. variable:: CPACK_IFW_PACKAGE_START_MENU_DIRECTORY
 
  .. versionadded:: 3.3
 
  Name of the default program group for the product in the Windows Start menu.
-
+ If not specified, it defaults to :variable:`CPACK_IFW_PACKAGE_NAME`.
- By default used :variable:`CPACK_IFW_PACKAGE_NAME`.
 
 .. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME
 
  .. versionadded:: 3.3
 
  Filename of the generated maintenance tool.
- The platform-specific executable file extension is appended.
+ The platform-specific executable file extension will be appended.
 
- By default used QtIFW defaults (``maintenancetool``).
+ If not specified, QtIFW provides a default name (``maintenancetool``).
 
 .. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE
 
@@ -185,15 +194,15 @@ Package
 
  Filename for the configuration of the generated maintenance tool.
 
- By default used QtIFW defaults (``maintenancetool.ini``).
+ If not specified, QtIFW uses a default file name (``maintenancetool.ini``).
 
 .. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS
 
  .. versionadded:: 3.3
 
  Set to ``ON`` if the installation path can contain non-ASCII characters.
-
+ Only supported for QtIFW 2.0 and later. Older QtIFW versions will always
- Is ``ON`` for QtIFW less 2.0 tools.
+ allow non-ASCII characters.
 
 .. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH
 
@@ -203,6 +212,14 @@ Package
 
  Is ``ON`` for QtIFW less 2.0 tools.
 
+.. variable:: CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE
+
+ .. versionadded:: 3.23
+
+ Set to ``ON`` if command line interface features should be disabled.
+ It is ``OFF`` by default and will only have an effect if using QtIFW 4.0 or
+ later.
+
 .. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT
 
  .. versionadded:: 3.3
@@ -213,10 +230,11 @@ Package
 
  .. versionadded:: 3.7
 
- List of additional resources ('.qrc' files) to include in the installer
+ List of additional resources (``.qrc`` files) to include in the installer
- binary.
+ binary. They should be specified as absolute paths and no two resource files
+ can have the same file name.
 
- You can use :command:`cpack_ifw_add_package_resources` command to resolve
+ You can use the :command:`cpack_ifw_add_package_resources` command to resolve
  relative paths.
 
 .. variable:: CPACK_IFW_PACKAGE_FILE_EXTENSION
@@ -226,27 +244,117 @@ Package
  The target binary extension.
 
  On Linux, the name of the target binary is automatically extended with
- '.run', if you do not specify the extension.
+ ``.run``, if you do not specify the extension.
 
  On Windows, the target is created as an application with the extension
- '.exe', which is automatically added, if not supplied.
+ ``.exe``, which is automatically added, if not supplied.
 
  On Mac, the target is created as an DMG disk image with the extension
- '.dmg', which is automatically added, if not supplied.
+ ``.dmg``, which is automatically added, if not supplied.
 
 .. variable:: CPACK_IFW_REPOSITORIES_ALL
 
  The list of remote repositories.
 
  The default value of this variable is computed by CPack and contains
- all repositories added with command :command:`cpack_ifw_add_repository`
+ all repositories added with :command:`cpack_ifw_add_repository`
- or updated with command :command:`cpack_ifw_update_repository`.
+ or updated with :command:`cpack_ifw_update_repository`.
 
 .. variable:: CPACK_IFW_DOWNLOAD_ALL
 
- If this is ``ON`` all components will be downloaded.
+ If this is ``ON``, all components will be downloaded. If not set, the
- By default is ``OFF`` or used value
+ behavior is determined by whether :command:`cpack_configure_downloads` has
- from ``CPACK_DOWNLOAD_ALL`` if set
+ been called with the ``ALL`` option or not.
+
+.. variable:: CPACK_IFW_PACKAGE_PRODUCT_IMAGES
+
+ .. versionadded:: 3.23
+
+ A list of images to be shown on the ``PerformInstallationPage``. These
+ must be absolute paths and the images must be in PNG format.
+
+ This feature is available for QtIFW 4.0.0 and later.
+
+.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM
+
+ .. versionadded:: 3.23
+
+ Command executed after the installer is finished, if the user accepts the
+ action. Provide the full path to the application, as found when installed.
+ This typically means the path should begin with the QtIFW predefined variable
+ ``@TargetDir@``.
+
+ This feature is available for QtIFW 4.0.0 and later.
+
+.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_ARGUMENTS
+
+ .. versionadded:: 3.23
+
+ List of arguments passed to the program specified in
+ :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM`.
+
+ This feature is available for QtIFW 4.0.0 and later.
+
+.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_DESCRIPTION
+
+ .. versionadded:: 3.23
+
+ Text shown next to the check box for running the program after the
+ installation. If :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM` is set but no
+ description is provided, QtIFW will use a default message like
+ ``Run <Name> now``.
+
+ This feature is available for QtIFW 4.0.0 and later.
+
+.. variable:: CPACK_IFW_PACKAGE_SIGNING_IDENTITY
+
+ .. versionadded:: 3.23
+
+ Allows specifying a code signing identity to be used for signing the generated
+ app bundle. Only available on macOS, ignored on other platforms.
+
+.. variable:: CPACK_IFW_ARCHIVE_FORMAT
+
+ .. versionadded:: 3.23
+
+ Set the format used when packaging new component data archives. If you omit
+ this option, the ``7z`` format will be used as a default. Supported formats:
+
+ * 7z
+ * zip
+ * tar.gz
+ * tar.bz2
+ * tar.xz
+
+ .. note::
+
+  If the Qt Installer Framework tools were built without libarchive support,
+  only ``7z`` format is supported.
+
+ This feature is available for QtIFW 4.2.0 and later.
+
+.. variable:: CPACK_IFW_ARCHIVE_COMPRESSION
+
+ .. versionadded:: 3.23
+
+ Archive compression level. The allowable values are:
+
+  * 0 (*No compression*)
+  * 1 (*Fastest compression*)
+  * 3 (*Fast compression*)
+  * 5 (*Normal compression*)
+  * 7 (*Maximum compression*)
+  * 9 (*Ultra compression*)
+
+ If this variable is not set, QtIFW will use a default compression level,
+ which will typically be 5 (*Normal compression*).
+
+ .. note::
+
+  Some formats do not support all the possible values. For example ``zip``
+  compression only supports values from 1 to 7.
+
+ This feature is available for QtIFW 4.2.0 and later.
 
 Components
 """"""""""
@@ -257,16 +365,17 @@ Components
 
 .. variable:: CPACK_IFW_PACKAGES_DIRECTORIES
 
- Additional prepared packages dirs that will be used to resolve
+ Additional prepared packages directories that will be used to resolve
  dependent components.
 
 .. variable:: CPACK_IFW_REPOSITORIES_DIRECTORIES
 
  .. versionadded:: 3.10
 
- Additional prepared repository dirs that will be used to resolve and
+ Additional prepared repository directories that will be used to resolve and
- repack dependent components. This feature available only
+ repack dependent components.
- since QtIFW 3.1.
+
+ This feature is available for QtIFW 3.1 and later.
 
 QtIFW Tools
 """""""""""
@@ -275,10 +384,11 @@ QtIFW Tools
 
  .. versionadded:: 3.3
 
- The version of used QtIFW tools.
+ The version of the QtIFW tools that will be used. This variable is set
+ by the :module:`CPackIFW` module.
 
 The following variables provide the locations of the QtIFW
-command-line tools as discovered by the module :module:`CPackIFW`.
+command-line tools as discovered by the :module:`CPackIFW` module.
 These variables are cached, and may be configured if needed.
 
 .. variable:: CPACK_IFW_ARCHIVEGEN_EXECUTABLE
@@ -306,30 +416,33 @@ These variables are cached, and may be configured if needed.
 Hints for Finding QtIFW
 """""""""""""""""""""""
 
-Generally, the CPack ``IFW`` generator automatically finds QtIFW tools,
+Generally, the CPack ``IFW`` generator automatically finds QtIFW tools.
-but if you don't use a default path for installation of the QtIFW tools,
+The following (in order of precedence) can also be set to augment the
-the path may be specified in either a CMake or an environment variable:
+locations normally searched by :command:`find_program`:
 
 .. variable:: CPACK_IFW_ROOT
 
- .. versionadded:: 3.9
+  .. versionadded:: 3.9
+
+  CMake variable
+
+.. envvar:: CPACK_IFW_ROOT
 
- An CMake variable which specifies the location of the QtIFW tool suite.
+  .. versionadded:: 3.9
 
- The variable will be cached in the ``CPackConfig.cmake`` file and used at
+  Environment variable
- CPack runtime.
 
 .. variable:: QTIFWDIR
 
- An environment variable which specifies the location of the QtIFW tool
+  CMake variable
- suite.
 
-.. note::
+.. envvar:: QTIFWDIR
-  The specified path should not contain "bin" at the end
+
-  (for example: "D:\\DevTools\\QtIFW2.0.5").
+  Environment variable
 
-The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides
+.. note::
-the value of the :variable:`QTIFWDIR` variable.
+  The specified path should not contain ``bin`` at the end
+  (for example: ``D:\\DevTools\\QtIFW2.0.5``).
 
 Other Settings
 ^^^^^^^^^^^^^^
@@ -337,7 +450,7 @@ Other Settings
 Online installer
 """"""""""""""""
 
-By default, this generator generates an *offline installer*. This means that
+By default, this generator generates an *offline installer*. This means
 that all packaged files are fully contained in the installer executable.
 
 In contrast, an *online installer* will download some or all components from
@@ -367,14 +480,13 @@ CMake script. This is an optional feature.
 
 Installers created by QtIFW tools have built-in support for
 internationalization and many phrases are localized to many languages,
-but this does not apply to the description of the your components and groups
+but this does not apply to the description of your components and groups.
-that will be distributed.
 
 Localization of the description of your components and groups is useful for
 users of your installers.
 
-A localized variable or argument can contain a single default value, and a
+A localized variable or argument can contain a single default value, and
-set of pairs the name of the locale and the localized value.
+after that a set of pairs with the name of the locale and the localized value.
 
 For example:
 
@@ -392,16 +504,16 @@ See Also
 Qt Installer Framework Manual:
 
 * Index page:
-  http://doc.qt.io/qtinstallerframework/index.html
+  https://doc.qt.io/qtinstallerframework/index.html
 
 * Component Scripting:
-  http://doc.qt.io/qtinstallerframework/scripting.html
+  https://doc.qt.io/qtinstallerframework/scripting.html
 
 * Predefined Variables:
-  http://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables
+  https://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables
 
 * Promoting Updates:
-  http://doc.qt.io/qtinstallerframework/ifw-updates.html
+  https://doc.qt.io/qtinstallerframework/ifw-updates.html
 
 Download Qt Installer Framework for your platform from Qt site:
- http://download.qt.io/official_releases/qt-installer-framework
+ https://download.qt.io/official_releases/qt-installer-framework

Help/cpack_gen/productbuild.rst

@@ -18,6 +18,14 @@ macOS using ProductBuild:
  the automatically detected command (or specify its location if the
  auto-detection fails to find it).
 
+.. variable:: CPACK_PRODUCTBUILD_IDENTIFIER
+
+ .. versionadded:: 3.23
+
+ Set the unique (non-localized) product identifier to be associated with the
+ product (i.e., ``com.kitware.cmake``). Any component product names will be
+ appended to this value.
+
 .. variable:: CPACK_PRODUCTBUILD_IDENTITY_NAME
 
  .. versionadded:: 3.8
@@ -78,6 +86,65 @@ macOS using ProductBuild:
  :variable:`CPACK_RESOURCE_FILE_README`, and
  :variable:`CPACK_RESOURCE_FILE_LICENSE` files are copied.
 
+.. variable:: CPACK_PRODUCTBUILD_DOMAINS
+
+ .. versionadded:: 3.23
+
+ This option enables more granular control over where the product may be
+ installed. When it is set to true, a ``domains`` element of the following
+ form will be added to the productbuild Distribution XML:
+
+ .. code-block:: xml
+
+    <domains enable_anywhere="true" enable_currentUserHome="false" enable_localSystem="true"/>
+
+ The default values are as shown above, but can be overridden with
+ :variable:`CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE`,
+ :variable:`CPACK_PRODUCTBUILD_DOMAINS_USER`, and
+ :variable:`CPACK_PRODUCTBUILD_DOMAINS_ROOT`.
+
+.. variable:: CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE
+
+ .. versionadded:: 3.23
+
+ May be used to override the ``enable_anywhere`` attribute in the ``domains``
+ element of the Distribution XML. When set to true, the product can be
+ installed at the root of any volume, including non-system volumes.
+
+ :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable
+ to have any effect.
+
+.. variable:: CPACK_PRODUCTBUILD_DOMAINS_USER
+
+ .. versionadded:: 3.23
+
+ May be used to override the ``enable_currentUserHome`` attribute in the
+ ``domains`` element of the Distribution XML. When set to true, the product
+ can be installed into the current user's home directory. Note that when
+ installing into the user's home directory, the following additional
+ requirements will apply:
+
+ * The installer may not write outside the user's home directory.
+ * The install will be performed as the current user rather than as ``root``.
+   This may have ramifications for :variable:`CPACK_PREFLIGHT_<COMP>_SCRIPT`
+   and :variable:`CPACK_POSTFLIGHT_<COMP>_SCRIPT`.
+ * Administrative privileges will not be needed to perform the install.
+
+ :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable
+ to have any effect.
+
+.. variable:: CPACK_PRODUCTBUILD_DOMAINS_ROOT
+
+ .. versionadded:: 3.23
+
+ May be used to override the ``enable_localSystem`` attribute in the
+ ``domains`` element of the Distribution XML. When set to true, the product
+ can be installed in the root directory. This should normally be set to true
+ unless the product should only be installed to the user's home directory.
+
+ :variable:`CPACK_PRODUCTBUILD_DOMAINS` must be set to true for this variable
+ to have any effect.
+
 Background Image
 """"""""""""""""
 

Help/cpack_gen/wix.rst

@@ -320,3 +320,11 @@ Windows using WiX.
  name is the plain namespace without the usual xmlns: prefix and url is an unquoted
  namespace url. A list of commonly known WiX schemata can be found here:
  https://wixtoolset.org/documentation/manual/v3/xsd/
+
+.. variable:: CPACK_WIX_SKIP_WIX_UI_EXTENSION
+
+ .. versionadded:: 3.23
+
+ If this variable is set then the inclusion of WixUIExtensions is skipped,
+ i.e. the ``-ext "WixUIExtension"`` command line is not included during
+ the execution of the WiX light tool.

Help/dev/documentation.rst

@@ -513,7 +513,7 @@ bracket is excluded if and only if the line starts in ``#``.
 Additional such ``.rst:`` comments may appear anywhere in the module file.
 All such comments must start with ``#`` in the first column.
 
-For example, a ``Findxxx.cmake`` module may contain:
+For example, a ``FindXxx.cmake`` module may contain:
 
 ::
 
@@ -540,13 +540,13 @@ For example, a ``Findxxx.cmake`` module may contain:
   <code>
 
   #[=======================================================================[.rst:
-  .. command:: xxx_do_something
+  .. command:: Xxx_do_something
 
    This command does something for Xxx::
 
-    xxx_do_something(some arguments)
+    Xxx_do_something(some arguments)
   #]=======================================================================]
-  macro(xxx_do_something)
+  macro(Xxx_do_something)
     <code>
   endmacro()
 
@@ -559,3 +559,56 @@ documentation, simply leave out the ``Help/module/<module-name>.rst``
 file and the ``Help/manual/cmake-modules.7.rst`` toctree entry.
 
 .. _`Bracket Comment`: https://cmake.org/cmake/help/latest/manual/cmake-language.7.html#bracket-comment
+
+Module Functions and Macros
+---------------------------
+
+Modules may provide CMake functions and macros defined by the `function()`_
+and `macro()`_ commands.  To avoid conflicts across modules, name the
+functions and macros using the prefix ``<ModuleName>_`` followed by the
+rest of the name, where ``<ModuleName>`` is the exact-case spelling of
+the module name.  We have no convention for the portion of names after
+the ``<ModuleName>_`` prefix.
+
+For historical reasons, some modules that come with CMake do not follow
+this prefix convention.  When adding new functions to these modules,
+discussion during review can decide whether to follow their existing
+convention or to use the module name prefix.
+
+Documentation of public functions and macros should be provided in
+the module, typically in the main `module documentation`_ at the top.
+For example, a ``MyModule`` module may document a function like this::
+
+  #[=======================================================================[.rst:
+  MyModule
+  --------
+
+  This is my module.  It provides some functions.
+
+  .. command:: MyModule_Some_Function
+
+    This is some function:
+
+    .. code-block:: cmake
+
+      MyModule_Some_Function(...)
+  #]=======================================================================]
+
+Documentation may alternatively be placed just before each definition.
+For example, a ``MyModule`` module may document another function like this::
+
+  #[=======================================================================[.rst:
+  .. command:: MyModule_Other_Function
+
+    This is another function:
+
+    .. code-block:: cmake
+
+      MyModule_Other_Function(...)
+  #]=======================================================================]
+  function(MyModule_Other_Function ...)
+    # ...
+  endfunction()
+
+.. _`function()`: https://cmake.org/cmake/help/latest/command/function.html
+.. _`macro()`: https://cmake.org/cmake/help/latest/command/macro.html

Help/dev/maint.rst

@@ -270,8 +270,8 @@ Update ``Source/CMakeVersion.cmake`` to set the version to
   set(CMake_VERSION_PATCH 0)
   set(CMake_VERSION_RC 0)
 
-Update uses of ``DEVEL_CMAKE_VERSION`` in the source tree to mention the
+Replace uses of ``DEVEL_CMAKE_VERSION`` in the source tree with
-actual version number:
+the literal release version number string ``"$major.$minor.0"``:
 
 .. code-block:: shell
 

Help/envvar/CUDAARCHS.rst

@@ -6,8 +6,7 @@ CUDAARCHS
 .. include:: ENV_VAR.txt
 
 Value used to initialize :variable:`CMAKE_CUDA_ARCHITECTURES` on the first
-configuration if it's not already defined. Subsequent runs will use the value
+configuration. Subsequent runs will use the value stored in the cache.
-stored in the cache.
 
 This is a semicolon-separated list of architectures as described in
 :prop_tgt:`CUDA_ARCHITECTURES`.

Help/envvar/CUDAHOSTCXX.rst

@@ -8,9 +8,8 @@ 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`. For any
+stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. This environment
-configuration run (including the first), the environment variable will be
+variable is preferred over :variable:`CMAKE_CUDA_HOST_COMPILER`.
-ignored if the :variable:`CMAKE_CUDA_HOST_COMPILER` variable is defined.
 
 This environment variable is primarily meant for use with projects that
 enable ``CUDA`` as a first-class language.

Help/envvar/DESTDIR.rst

@@ -5,17 +5,26 @@ DESTDIR
 
 On UNIX one can use the ``DESTDIR`` mechanism in order to relocate the
 whole installation.  ``DESTDIR`` means DESTination DIRectory.  It is
-commonly used by makefile users in order to install software at
+commonly used by packagers to install software in a staging directory.
-non-default location.  It is usually invoked like this:
 
-::
+For example, running
 
- make DESTDIR=/home/john install
+.. code-block:: shell
 
-which will install the concerned software using the installation
+  make DESTDIR=/package/stage install
-prefix, e.g.  ``/usr/local`` prepended with the ``DESTDIR`` value which
-finally gives ``/home/john/usr/local``.
 
-WARNING: ``DESTDIR`` may not be used on Windows because installation
+will install the software using the installation prefix, e.g. ``/usr/local``,
-prefix usually contains a drive letter like in ``C:/Program Files``
+prepended with the ``DESTDIR`` value which gives ``/package/stage/usr/local``.
-which cannot be prepended with some other prefix.
+The packaging tool may then construct the package from the content of the
+``/package/stage`` directory.
+
+See the :variable:`CMAKE_INSTALL_PREFIX` variable to control the
+installation prefix when configuring a build tree.  Or, when using
+the :manual:`cmake(1)` command-line tool's ``--install`` mode,
+one may specify a different prefix using the ``--prefix`` option.
+
+.. note::
+
+  ``DESTDIR`` may not be used on Windows because installation
+  prefix usually contains a drive letter like in ``C:/Program Files``
+  which cannot be prepended with some other prefix.

Help/generator/Green Hills MULTI.rst

@@ -8,70 +8,125 @@ Green Hills MULTI
 
 Generates Green Hills MULTI project files (experimental, work-in-progress).
 
-Customizations are available through the following cache variables:
-
-* ``GHS_CUSTOMIZATION``
-* ``GHS_GPJ_MACROS``
-
-.. versionadded:: 3.14
   The buildsystem has predetermined build-configuration settings that can be controlled
   via the :variable:`CMAKE_BUILD_TYPE` variable.
 
-Toolset and Platform Selection
+Platform Selection
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^
 
 .. versionadded:: 3.13
 
-Customizations that are used to pick toolset and target system:
+The variable ``GHS_PRIMARY_TARGET`` can be used to select the target platform.
+
+  | Sets ``primaryTarget`` entry in project file.
+
+For example:
 
-* The ``-A <arch>`` can be supplied for setting the target architecture.
+* ``cmake -G "Green Hills MULTI" -D GHS_PRIMARY_TARGET=ppc_integrity.tgt``
-  ``<arch>`` usually is one of ``arm``, ``ppc``, ``86``, etcetera.
-  If the target architecture is not specified then
-  the default architecture of ``arm`` will be used.
 
-* The ``-T <toolset>`` option can be used to set the directory location of the toolset.
+Otherwise the ``primaryTarget`` will be composed from the values of :variable:`CMAKE_GENERATOR_PLATFORM`
-  Both absolute and relative paths are valid. Relative paths use ``GHS_TOOLSET_ROOT``
+and ``GHS_TARGET_PLATFORM``. Defaulting to the value of ``arm_integrity.tgt``
-  as the root. If the toolset is not specified then the latest toolset found in
-  ``GHS_TOOLSET_ROOT`` will be used.
 
-Cache variables that are used for toolset and target system customization:
+* The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
+  via the :manual:`cmake(1)` ``-A`` option.
 
-* ``GHS_TARGET_PLATFORM``
+  | Typical values of ``arm``, ``ppc``, ``86``, etcetera, are used.
+
+* The variable ``GHS_TARGET_PLATFORM`` may be set, perhaps via the :manual:`cmake(1)`
+  ``-D`` option.
 
   | Defaults to ``integrity``.
   | Usual values are ``integrity``, ``threadx``, ``uvelosity``, ``velosity``,
     ``vxworks``, ``standalone``.
 
-* ``GHS_PRIMARY_TARGET``
+For example:
 
-  | Sets ``primaryTarget`` entry in project file.
+* ``cmake -G "Green Hills MULTI"`` for ``arm_integrity.tgt``.
-  | Defaults to ``<arch>_<GHS_TARGET_PLATFORM>.tgt``.
+* ``cmake -G "Green Hills MULTI" -A 86`` for ``86_integrity.tgt``.
+* ``cmake -G "Green Hills MULTI" -D GHS_TARGET_PLATFORM=standalone`` for ``arm_standalone.tgt``.
+* ``cmake -G "Green Hills MULTI" -A ppc -D GHS_TARGET_PLATFORM=standalone`` for ``ppc_standalone.tgt``.
 
-* ``GHS_TOOLSET_ROOT``
+Toolset Selection
+^^^^^^^^^^^^^^^^^
 
-  | Root path for ``toolset`` searches.
+.. versionadded:: 3.13
-  | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux.
 
-* ``GHS_OS_ROOT``
+The generator searches for the latest compiler or can be given a location to use.
+``GHS_TOOLSET_ROOT`` is the directory that is checked for the latest compiler.
 
-  | Root path for RTOS searches.
+* The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
+  via the :manual:`cmake(1)` ``-T`` option, to specify the location of the toolset.
+  Both absolute and relative paths are valid. Paths are relative to ``GHS_TOOLSET_ROOT``.
+
+* The variable ``GHS_TOOLSET_ROOT`` may be set, perhaps via the :manual:`cmake(1)`
+  ``-D`` option.
+
+  | Root path for toolset searches and relative paths.
   | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux.
 
+For example, setting a specific compiler:
+
+* ``cmake -G "Green Hills MULTI" -T comp_201754`` for ``/usr/ghs/comp_201754``.
+* ``cmake -G "Green Hills MULTI" -T comp_201754 -D GHS_TOOLSET_ROOT=/opt/ghs`` for ``/opt/ghs/comp_201754``.
+* ``cmake -G "Green Hills MULTI" -T /usr/ghs/comp_201554``
+* ``cmake -G "Green Hills MULTI" -T C:/ghs/comp_201754``
+
+For example, searching for latest compiler:
+
+* ``cmake -G "Green Hills MULTI"`` for searching ``/usr/ghs``.
+* ``cmake -G "Green Hills MULTI -D GHS_TOOLSET_ROOT=/opt/ghs"`` for searching ``/opt/ghs``.
+
+.. note::
+  The :variable:`CMAKE_GENERATOR_TOOLSET` should use CMake style paths.
+
+OS and BSP Selection
+^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.3
+
+Certain target platforms, like Integrity, require an OS.  The RTOS directory path
+can be explicitly set using ``GHS_OS_DIR``.  Otherwise ``GHS_OS_ROOT`` will be
+searched for the latest Integrity RTOS.
+
+If the target platform, like Integrity, requires a BSP name then it can be set via
+the ``GHS_BSP_NAME`` variable.
+
 * ``GHS_OS_DIR`` and ``GHS_OS_DIR_OPTION``
 
   | Sets ``-os_dir`` entry in project file.
-  | Defaults to latest platform OS installation at ``GHS_OS_ROOT``.  Set this value if
+
-    a specific RTOS is to be used.
   | ``GHS_OS_DIR_OPTION`` default value is ``-os_dir``.
 
   .. versionadded:: 3.15
     The ``GHS_OS_DIR_OPTION`` variable.
 
+  For example:
+
+  * ``cmake -G "Green Hills MULTI" -D GHS_OS_DIR=/usr/ghs/int1144``
+
+* ``GHS_OS_ROOT``
+
+  | Root path for RTOS searches.
+  | Defaults to ``C:/ghs`` in Windows or ``/usr/ghs`` in Linux.
+
+  For example:
+
+  * ``cmake -G "Green Hills MULTI" -D GHS_OS_ROOT=/opt/ghs``
+
 * ``GHS_BSP_NAME``
 
   | Sets ``-bsp`` entry in project file.
   | Defaults to ``sim<arch>`` for ``integrity`` platforms.
 
+  For example:
+
+  * ``cmake -G "Green Hills MULTI"`` for ``simarm`` on ``arm_integrity.tgt``.
+  * ``cmake -G "Green Hills MULTI" -A 86`` for ``sim86`` on ``86_integrity.tgt``.
+  * ``cmake -G "Green Hills MULTI" -A ppc -D GHS_BSP_NAME=sim800`` for ``sim800``
+    on ``ppc_integrity.tgt``.
+  * ``cmake -G "Green Hills MULTI" -D GHS_PRIMARY_TARGET=ppc_integrity.tgt -D GHS_BSP_NAME=fsl-t1040``
+    for ``fsl-t1040`` on ``ppc_integrity.tgt``.
+
 Target Properties
 ^^^^^^^^^^^^^^^^^
 
@@ -82,6 +137,17 @@ The following properties are available:
 * :prop_tgt:`GHS_INTEGRITY_APP`
 * :prop_tgt:`GHS_NO_SOURCE_GROUP_FILE`
 
+MULTI Project Variables
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.3
+
+Adding a Customization file and macros are available through the use of the following
+variables:
+
+* ``GHS_CUSTOMIZATION`` - CMake path name to Customization File.
+* ``GHS_GPJ_MACROS`` - CMake list of Macros.
+
 .. note::
   This generator is deemed experimental as of CMake |release|
   and is still a work in progress.  Future versions of CMake

Help/generator/Visual Studio 15 2017.rst

@@ -17,18 +17,8 @@ Instance Selection
 
 .. versionadded:: 3.11
 
-VS 2017 supports multiple installations on the same machine.
+VS 2017 supports multiple installations on the same machine.  The
-The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a
+:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one.
-cache entry containing the absolute path to a Visual Studio instance.
-If the value is not specified explicitly by the user or a toolchain file,
-CMake queries the Visual Studio Installer to locate VS instances, chooses
-one, and sets the variable as a cache entry to hold the value persistently.
-
-When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment
-variable is set and points to the ``Common7/Tools`` directory within
-one of the instances, that instance will be used.  Otherwise, if more
-than one instance is installed we do not define which one is chosen
-by default.
 
 Platform Selection
 ^^^^^^^^^^^^^^^^^^

Help/generator/Visual Studio 16 2019.rst

@@ -15,18 +15,8 @@ Powershell, Python, etc.) are not supported.
 Instance Selection
 ^^^^^^^^^^^^^^^^^^
 
-VS 2019 supports multiple installations on the same machine.
+VS 2019 supports multiple installations on the same machine.  The
-The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a
+:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one.
-cache entry containing the absolute path to a Visual Studio instance.
-If the value is not specified explicitly by the user or a toolchain file,
-CMake queries the Visual Studio Installer to locate VS instances, chooses
-one, and sets the variable as a cache entry to hold the value persistently.
-
-When CMake first chooses an instance, if the ``VS160COMNTOOLS`` environment
-variable is set and points to the ``Common7/Tools`` directory within
-one of the instances, that instance will be used.  Otherwise, if more
-than one instance is installed we do not define which one is chosen
-by default.
 
 Platform Selection
 ^^^^^^^^^^^^^^^^^^

Help/generator/Visual Studio 17 2022.rst

@@ -15,18 +15,8 @@ Powershell, Python, etc.) are not supported.
 Instance Selection
 ^^^^^^^^^^^^^^^^^^
 
-VS 2022 supports multiple installations on the same machine.
+VS 2022 supports multiple installations on the same machine.  The
-The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a
+:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one.
-cache entry containing the absolute path to a Visual Studio instance.
-If the value is not specified explicitly by the user or a toolchain file,
-CMake queries the Visual Studio Installer to locate VS instances, chooses
-one, and sets the variable as a cache entry to hold the value persistently.
-
-When CMake first chooses an instance, if the ``VS170COMNTOOLS`` environment
-variable is set and points to the ``Common7/Tools`` directory within
-one of the instances, that instance will be used.  Otherwise, if more
-than one instance is installed we do not define which one is chosen
-by default.
 
 Platform Selection
 ^^^^^^^^^^^^^^^^^^

Help/guide/ide-integration/index.rst

@@ -65,6 +65,12 @@ run:
 
   cmake -S /path/to/source -B /path/to/source/build -G Ninja
 
+In cases where a preset contains lots of cache variables, and passing all of
+them as ``-D`` flags would cause the command line length limit of the platform
+to be exceeded, the IDE should instead construct a temporary cache script and
+pass it with the ``-C`` flag. See :ref:`CMake Options` for details on how the
+``-C`` flag is used.
+
 While reading, parsing, and evaluating the contents of ``CMakePresets.json`` is
 straightforward, it is not trivial. In addition to the documentation, IDE
 vendors may also wish to refer to the CMake source code and test cases for a
@@ -124,3 +130,31 @@ obtain this information and use it to present the user with a list of tests.
 
 IDEs should not invoke the ``test`` target of the generated buildsystem.
 Instead, they should invoke :manual:`ctest(1)` directly.
+
+IDEs with CMake integration
+===========================
+
+The following IDEs support CMake natively:
+
+* `CLion`_
+* `KDevelop`_
+* `QtCreator`_
+* `Vim`_ (via a plugin)
+* `Visual Studio`_
+* `VSCode`_ (via a plugin)
+
+.. _CLion: https://www.jetbrains.com/clion/
+.. _KDevelop: https://www.kdevelop.org/
+.. _QtCreator: https://www.qt.io/product/development-tools
+.. _Vim: https://www.vim.org/
+.. _Visual Studio: https://visualstudio.microsoft.com/
+.. _VSCode: https://code.visualstudio.com/
+
+Additionally, CMake has builtin support for some IDEs:
+
+* :ref:`IDE Build Tool Generators`:
+  Generate IDE native build systems such as Visual Studio or Xcode.
+* :ref:`Extra Generators`:
+  Extend :ref:`Command-Line Build Tool Generators` to generate IDE
+  project files that hook into the command-line build system.
+  Superseded by the :manual:`File API <cmake-file-api(7)>`.

Help/guide/importing-exporting/MathFunctionsComponents/Config.cmake.in

@@ -1,9 +1,9 @@
 @PACKAGE_INIT@
 
-set(_supported_components Addition SquareRoot)
+set(_MathFunctions_supported_components Addition SquareRoot)
 
 foreach(_comp ${MathFunctions_FIND_COMPONENTS})
-  if (NOT _comp IN_LIST _supported_components)
+  if (NOT _comp IN_LIST _MathFunctions_supported_components)
     set(MathFunctions_FOUND False)
     set(MathFunctions_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")
   endif()

Help/guide/tutorial/Complete/CMakeLists.txt

@@ -10,7 +10,7 @@ target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
 
 # add compiler warning flags just when building this project via
 # the BUILD_INTERFACE genex
-set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>")
+set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>")
 set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
 target_compile_options(tutorial_compiler_flags INTERFACE
   "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"
@@ -88,6 +88,7 @@ include(InstallRequiredSystemLibraries)
 set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
 set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
 set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
+set(CPACK_SOURCE_GENERATOR "TGZ")
 include(CPack)
 
 # install the configuration targets

Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt

@@ -62,6 +62,6 @@ if(TARGET SqrtLibrary)
   list(APPEND installable_libs SqrtLibrary)
 endif()
 install(TARGETS ${installable_libs}
-        DESTINATION lib
+        EXPORT MathFunctionsTargets
-        EXPORT MathFunctionsTargets)
+        DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Packaging an Installer.rst

@@ -22,8 +22,9 @@ That is all there is to it. We start by including
 libraries that are needed by the project for the current platform. Next we set
 some CPack variables to where we have stored the license and version
 information for this project. The version information was set earlier in this
-tutorial and the ``license.txt`` has been included in the top-level source
+tutorial and the ``License.txt`` has been included in the top-level source
-directory for this step.
+directory for this step.  The :variable:`CPACK_SOURCE_GENERATOR` variable
+selects a file format for the source package.
 
 Finally we include the :module:`CPack module <CPack>` which will use these
 variables and some other properties of the current system to setup an
@@ -44,7 +45,11 @@ To specify the generator, use the ``-G`` option. For multi-config builds, use
 
   cpack -G ZIP -C Debug
 
-To create a source distribution you would type:
+For a list of available generators, see :manual:`cpack-generators(7)` or call
+``cpack --help``. An :cpack_gen:`archive generator <CPack Archive Generator>`
+like ZIP creates a compressed archive of all *installed* files.
+
+To create an archive of the *full* source tree you would type:
 
 .. code-block:: console
 

Help/guide/tutorial/Step10/CMakeLists.txt

@@ -70,4 +70,5 @@ include(InstallRequiredSystemLibraries)
 set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
 set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
 set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
+set(CPACK_SOURCE_GENERATOR "TGZ")
 include(CPack)

Help/guide/tutorial/Step11/CMakeLists.txt

@@ -8,7 +8,7 @@ target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
 
 # add compiler warning flags just when building this project via
 # the BUILD_INTERFACE genex
-set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>")
+set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>")
 set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
 target_compile_options(tutorial_compiler_flags INTERFACE
   "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"
@@ -78,4 +78,5 @@ include(InstallRequiredSystemLibraries)
 set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
 set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
 set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
+set(CPACK_SOURCE_GENERATOR "TGZ")
 include(CPack)

Help/guide/tutorial/Step12/CMakeLists.txt

@@ -8,7 +8,7 @@ target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
 
 # add compiler warning flags just when building this project via
 # the BUILD_INTERFACE genex
-set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>")
+set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC>")
 set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
 target_compile_options(tutorial_compiler_flags INTERFACE
   "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"

Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt

@@ -58,6 +58,6 @@ if(TARGET SqrtLibrary)
   list(APPEND installable_libs SqrtLibrary)
 endif()
 install(TARGETS ${installable_libs}
-        DESTINATION lib
+        EXPORT MathFunctionsTargets
-        EXPORT MathFunctionsTargets)
+        DESTINATION lib)
 install(FILES MathFunctions.h DESTINATION include)

Help/guide/tutorial/Step8/CMakeLists.txt

@@ -70,4 +70,5 @@ include(InstallRequiredSystemLibraries)
 set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
 set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
 set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
+set(CPACK_SOURCE_GENERATOR "TGZ")
 include(CPack)

Help/guide/tutorial/Step9/CMakeLists.txt

@@ -69,4 +69,5 @@ include(InstallRequiredSystemLibraries)
 set(CPACK_RESOURCE_FILE_LICENSE "${CMAKE_CURRENT_SOURCE_DIR}/License.txt")
 set(CPACK_PACKAGE_VERSION_MAJOR "${Tutorial_VERSION_MAJOR}")
 set(CPACK_PACKAGE_VERSION_MINOR "${Tutorial_VERSION_MINOR}")
+set(CPACK_SOURCE_GENERATOR "TGZ")
 include(CPack)

Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt

@@ -1,11 +1,11 @@
 
-Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the
+Note that it is not advisable to populate the :genex:`INSTALL_INTERFACE` of
-|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
+the |INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
 directories of dependencies.  That would hard-code into installed packages
 the include directory paths for dependencies
 **as found on the machine the package was made on**.
 
-The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only
+The :genex:`INSTALL_INTERFACE` of the |INTERFACE_PROPERTY_LINK| is only
 suitable for specifying the required include directories for headers
 provided with the target itself, not those provided by the transitive
 dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target

Help/manual/cmake-buildsystem.7.rst

@@ -675,7 +675,9 @@ listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` of the
 dependency. This can result in omission of compiler warnings for headers
 found in those directories.  This behavior for :ref:`imported targets` may
 be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target
-property on the *consumers* of imported targets.
+property on the *consumers* of imported targets, or by setting the
+:prop_tgt:`IMPORTED_NO_SYSTEM` target property on the imported targets
+themselves.
 
 If a binary target is linked transitively to a macOS :prop_tgt:`FRAMEWORK`, the
 ``Headers`` directory of the framework is also treated as a usage requirement.

Help/manual/cmake-compile-features.7.rst

@@ -115,6 +115,8 @@ of at-least C++ 11 (or C++ 14, C++ 17, ...), adding flags such as
 ``-std=gnu++11`` if necessary.  This applies to sources within ``mylib``
 as well as any dependents (that may include headers from ``mylib``).
 
+.. include:: ../prop_gbl/CMAKE_LANG_STD_FLAGS.txt
+
 Availability of Compiler Extensions
 -----------------------------------
 

Help/manual/cmake-file-api.7.rst

@@ -425,7 +425,7 @@ Version 1 does not exist to avoid confusion with that from
 
   {
     "kind": "codemodel",
-    "version": { "major": 2, "minor": 2 },
+    "version": { "major": 2, "minor": 4 },
     "paths": {
       "source": "/path/to/top-level-source-dir",
       "build": "/path/to/top-level-build-dir"
@@ -758,6 +758,15 @@ with members:
       ``destination`` member is populated. This type has additional members
       ``runtimeDependencySetName`` and ``runtimeDependencySetType``.
 
+    ``fileSet``
+      An :command:`install(TARGETS)` call with ``FILE_SET``.
+      The ``destination`` and ``paths`` members are populated.
+      The ``isOptional`` member may exist.
+      This type has additional members ``fileSetName``, ``fileSetType``,
+      ``fileSetDirectories``, and ``fileSetTarget``.
+
+      This type was added in codemodel version 2.4.
+
   ``isExcludeFromAll``
     Optional member that is present with boolean value ``true`` when
     :command:`install` is called with the ``EXCLUDE_FROM_ALL`` option.
@@ -835,6 +844,41 @@ with members:
       Indicates that this installer installs dependencies that are macOS
       frameworks.
 
+  ``fileSetName``
+    Optional member that is present when ``type`` is ``fileSet``. The value is
+    a string with the name of the file set.
+
+    This field was added in codemodel version 2.4.
+
+  ``fileSetType``
+    Optional member that is present when ``type`` is ``fileSet``. The value is
+    a string with the type of the file set.
+
+    This field was added in codemodel version 2.4.
+
+  ``fileSetDirectories``
+    Optional member that is present when ``type`` is ``fileSet``. The value
+    is a list of strings with the file set's base directories (determined by
+    genex-evaluation of :prop_tgt:`HEADER_DIRS` or
+    :prop_tgt:`HEADER_DIRS_<NAME>`).
+
+    This field was added in codemodel version 2.4.
+
+  ``fileSetTarget``
+    Optional member that is present when ``type`` is ``fileSet``. The value
+    is a JSON object with members:
+
+    ``id``
+      A string uniquely identifying the target.  This matches
+      the ``id`` member of the target in the main "codemodel"
+      object's ``targets`` array.
+
+    ``index``
+      An unsigned integer 0-based index into the main "codemodel"
+      object's ``targets`` array for the target.
+
+    This field was added in codemodel version 2.4.
+
   ``scriptFile``
     Optional member that is present when ``type`` is ``script``.
     The value is a string specifying the path to the script file on disk,

Help/manual/cmake-generators.7.rst

@@ -102,6 +102,8 @@ Other Generators
    /generator/Green Hills MULTI
    /generator/Xcode
 
+.. _`Extra Generators`:
+
 Extra Generators
 ================
 

Help/manual/cmake-language.7.rst

@@ -627,3 +627,45 @@ in list elements, thus flattening nested lists:
 .. code-block:: cmake
 
  set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c"
+
+In general, lists do not support elements containing ``;`` characters.
+To avoid problems, consider the following advice:
+
+* The interfaces of many CMake commands, variables, and properties accept
+  semicolon-separated lists.  Avoid passing lists with elements containing
+  semicolons to these interfaces unless they document either direct support
+  or some way to escape or encode semicolons.
+
+* When constructing a list, substitute an otherwise-unused placeholder
+  for ``;`` in elements when.  Then substitute ``;`` for the placeholder
+  when processing list elements.
+  For example, the following code uses ``|`` in place of ``;`` characters:
+
+  .. code-block:: cmake
+
+    set(mylist a "b|c")
+    foreach(entry IN LISTS mylist)
+      string(REPLACE "|" ";" entry "${entry}")
+      # use "${entry}" normally
+    endforeach()
+
+  The :module:`ExternalProject` module's ``LIST_SEPARATOR`` option is an
+  example of an interface built using this approach.
+
+* In lists of :manual:`generator expressions <cmake-generator-expressions(7)>`,
+  use the :genex:`$<SEMICOLON>` generator expression.
+
+* In command calls, use `Quoted Argument`_ syntax whenever possible.
+  The called command will receive the content of the argument with
+  semicolons preserved.  An `Unquoted Argument`_ will be split on
+  semicolons.
+
+* In :command:`function` implementations, avoid ``ARGV`` and ``ARGN``,
+  which do not distinguish semicolons in values from those separating values.
+  Instead, prefer using named positional arguments and the ``ARGC`` and
+  ``ARGV#`` variables.
+  When using :command:`cmake_parse_arguments` to parse arguments, prefer
+  its ``PARSE_ARGV`` signature, which uses the ``ARGV#`` variables.
+
+  Note that this approach does not apply to :command:`macro` implementations
+  because they reference arguments using placeholders, not real variables.

Help/manual/cmake-packages.7.rst

@@ -446,10 +446,10 @@ be true. This can be tested with logic in the package configuration file:
   include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
   include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")
 
-  set(_supported_components Plot Table)
+  set(_ClimbingStats_supported_components Plot Table)
 
   foreach(_comp ${ClimbingStats_FIND_COMPONENTS})
-    if (NOT ";${_supported_components};" MATCHES ";${_comp};")
+    if (NOT ";${_ClimbingStats_supported_components};" MATCHES ";${_comp};")
       set(ClimbingStats_FOUND False)
       set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")
     endif()

Help/manual/cmake-policies.7.rst

@@ -51,6 +51,15 @@ 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.23
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0129: Compiler id for MCST LCC compilers is now LCC, not GNU. </policy/CMP0129>
+
 Policies Introduced by CMake 3.22
 =================================
 

Help/manual/cmake-presets.7.rst

@@ -12,18 +12,21 @@ Introduction
 
 One problem that CMake users often face is sharing settings with other people
 for common ways to configure a project. This may be done to support CI builds,
-or for users who frequently use the same build. CMake supports two files,
+or for users who frequently use the same build. CMake supports two main files,
 ``CMakePresets.json`` and ``CMakeUserPresets.json``, that allow users to
-specify common configure options and share them with others.
+specify common configure options and share them with others. CMake also
+supports files included with the ``include`` field.
 
 ``CMakePresets.json`` and ``CMakeUserPresets.json`` live in the project's root
 directory. They both have exactly the same format, and both are optional
-(though at least one must be present if ``--preset`` is specified.)
+(though at least one must be present if ``--preset`` is specified).
-``CMakePresets.json`` is meant to save project-wide builds, while
+``CMakePresets.json`` is meant to specify project-wide build details, while
-``CMakeUserPresets.json`` is meant for developers to save their own local
+``CMakeUserPresets.json`` is meant for developers to specify their own local
-builds. ``CMakePresets.json`` may be checked into a version control system, and
+build details.
-``CMakeUserPresets.json`` should NOT be checked in. For example, if a project
+
-is using Git, ``CMakePresets.json`` may be tracked, and
+``CMakePresets.json`` may be checked into a version control system, and
+``CMakeUserPresets.json`` should NOT be checked in. For example, if a
+project is using Git, ``CMakePresets.json`` may be tracked, and
 ``CMakeUserPresets.json`` should be added to the ``.gitignore``.
 
 Format
@@ -39,7 +42,7 @@ The root object recognizes the following fields:
 ``version``
 
   A required integer representing the version of the JSON schema.
-  The supported versions are ``1``, ``2``, and ``3``.
+  The supported versions are ``1``, ``2``, ``3``, and ``4``.
 
 ``cmakeMinimumRequired``
 
@@ -58,6 +61,13 @@ The root object recognizes the following fields:
 
     An optional integer representing the patch version.
 
+``include``
+
+  An optional array of strings representing files to include. If the filenames
+  are not absolute, they are considered relative to the current file.
+  This is allowed in preset files specifying version ``4`` or above.
+  See `Includes`_ for discussion of the constraints on included files.
+
 ``vendor``
 
   An optional map containing vendor-specific information. CMake does not
@@ -82,6 +92,26 @@ The root object recognizes the following fields:
   An optional array of `Test Preset`_ objects.
   This is allowed in preset files specifying version ``2`` or above.
 
+Includes
+^^^^^^^^
+
+``CMakePresets.json`` and ``CMakeUserPresets.json`` can include other files
+with the ``include`` field in file version ``4`` and later. Files included
+by these files can also include other files. If ``CMakePresets.json`` and
+``CMakeUserPresets.json`` are both present, ``CMakeUserPresets.json``
+implicitly includes ``CMakePresets.json``, even with no ``include`` field,
+in all versions of the format.
+
+If a preset file contains presets that inherit from presets in another file,
+the file must include the other file either directly or indirectly.
+Include cycles are not allowed among files. If ``a.json`` includes
+``b.json``, ``b.json`` cannot include ``a.json``. However, a file may be
+included multiple times from the same file or from different files.
+
+Files directly or indirectly included from ``CMakePresets.json`` should be
+guaranteed to be provided by the project. ``CMakeUserPresets.json`` may
+include files from anywhere.
+
 Configure Preset
 ^^^^^^^^^^^^^^^^
 
@@ -108,16 +138,20 @@ that may contain the following fields:
 ``inherits``
 
   An optional array of strings representing the names of presets to inherit
-  from. The preset will inherit all of the fields from the ``inherits``
+  from. This field can also be a string, which is equivalent to an array
+  containing one string.
+
+  The preset will inherit all of the fields from the ``inherits``
   presets by default (except ``name``, ``hidden``, ``inherits``,
   ``description``, and ``displayName``), but can override them as
   desired. If multiple ``inherits`` presets provide conflicting values for
   the same field, the earlier preset in the ``inherits`` list will be
-  preferred. Presets in ``CMakePresets.json`` may not inherit from presets
+  preferred.
-  in ``CMakeUserPresets.json``.
 
-  This field can also be a string, which is equivalent to an array
+  A preset can only inherit from another preset that is defined in the
-  containing one string.
+  same file or in one of the files it includes (directly or indirectly).
+  Presets in ``CMakePresets.json`` may not inherit from presets in
+  ``CMakeUserPresets.json``.
 
 ``condition``
 
@@ -350,17 +384,21 @@ that may contain the following fields:
 
 ``inherits``
 
-  An optional array of strings representing the names of presets to
+  An optional array of strings representing the names of presets to inherit
-  inherit from. The preset will inherit all of the fields from the
+  from. This field can also be a string, which is equivalent to an array
+  containing one string.
+
+  The preset will inherit all of the fields from the
   ``inherits`` presets by default (except ``name``, ``hidden``,
   ``inherits``, ``description``, and ``displayName``), but can override
   them as desired. If multiple ``inherits`` presets provide conflicting
   values for the same field, the earlier preset in the ``inherits`` list
-  will be preferred. Presets in ``CMakePresets.json`` may not inherit from
+  will be preferred.
-  presets in ``CMakeUserPresets.json``.
 
-  This field can also be a string, which is equivalent to an array
+  A preset can only inherit from another preset that is defined in the
-  containing one string.
+  same file or in one of the files it includes (directly or indirectly).
+  Presets in ``CMakePresets.json`` may not inherit from presets in
+  ``CMakeUserPresets.json``.
 
 ``condition``
 
@@ -453,6 +491,42 @@ that may contain the following fields:
   An optional bool. If true, equivalent to passing ``--clean-first`` on
   the command line.
 
+``resolvePackageReferences``
+
+  An optional string that specifies the package resolve mode. This is
+  allowed in preset files specifying version ``4`` or above.
+
+  Package references are used to define dependencies to packages from
+  external package managers. Currently only NuGet in combination with the
+  Visual Studio generator is supported. If there are no targets that define
+  package references, this option does nothing. Valid values are:
+
+  ``on``
+
+    Causes package references to be resolved before attempting a build.
+
+  ``off``
+
+    Package references will not be resolved. Note that this may cause
+    errors in some build environments, such as .NET SDK style projects.
+
+  ``only``
+
+    Only resolve package references, but do not perform a build.
+
+  .. note::
+
+    The command line parameter ``--resolve-package-references`` will take
+    priority over this setting. If the command line parameter is not provided
+    and this setting is not specified, an environment-specific cache variable
+    will be evaluated to decide, if package restoration should be performed.
+
+    When using the Visual Studio generator, package references are defined
+    using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references
+    are restored using NuGet. It can be disabled by setting the
+    ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``. This can also be
+    done from within a configure preset.
+
 ``verbose``
 
   An optional bool. If true, equivalent to passing ``--verbose`` on the
@@ -487,17 +561,21 @@ that may contain the following fields:
 
 ``inherits``
 
-  An optional array of strings representing the names of presets to
+  An optional array of strings representing the names of presets to inherit
-  inherit from. The preset will inherit all of the fields from the
+  from. This field can also be a string, which is equivalent to an array
+  containing one string.
+
+  The preset will inherit all of the fields from the
   ``inherits`` presets by default (except ``name``, ``hidden``,
   ``inherits``, ``description``, and ``displayName``), but can override
   them as desired. If multiple ``inherits`` presets provide conflicting
   values for the same field, the earlier preset in the ``inherits`` list
-  will be preferred. Presets in ``CMakePresets.json`` may not inherit from
+  will be preferred.
-  presets in ``CMakeUserPresets.json``.
 
-  This field can also be a string, which is equivalent to an array
+  A preset can only inherit from another preset that is defined in the
-  containing one string.
+  same file or in one of the files it includes (directly or indirectly).
+  Presets in ``CMakePresets.json`` may not inherit from presets in
+  ``CMakeUserPresets.json``.
 
 ``condition``
 
@@ -947,7 +1025,8 @@ Recognized macros include:
 
 ``${sourceDir}``
 
-  Path to the project source directory.
+  Path to the project source directory (i.e. the same as
+  :variable:`CMAKE_SOURCE_DIR`).
 
 ``${sourceParentDir}``
 
@@ -974,6 +1053,11 @@ Recognized macros include:
   :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files
   specifying version ``3`` or above.
 
+``${fileDir}``
+
+  Path to the directory containing the preset file which contains the macro.
+  This is allowed in preset files specifying version ``4`` or above.
+
 ``${dollar}``
 
   A literal dollar sign (``$``).

Help/manual/cmake-properties.7.rst

@@ -191,6 +191,7 @@ Properties on Targets
    /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY
    /prop_tgt/DEPRECATION
    /prop_tgt/DISABLE_PRECOMPILE_HEADERS
+   /prop_tgt/DOTNET_SDK
    /prop_tgt/DOTNET_TARGET_FRAMEWORK
    /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION
    /prop_tgt/EchoString
@@ -214,6 +215,11 @@ Properties on Targets
    /prop_tgt/GHS_NO_SOURCE_GROUP_FILE
    /prop_tgt/GNUtoMS
    /prop_tgt/HAS_CXX
+   /prop_tgt/HEADER_DIRS
+   /prop_tgt/HEADER_DIRS_NAME
+   /prop_tgt/HEADER_SET
+   /prop_tgt/HEADER_SET_NAME
+   /prop_tgt/HEADER_SETS
    /prop_tgt/HIP_ARCHITECTURES
    /prop_tgt/HIP_EXTENSIONS
    /prop_tgt/HIP_STANDARD
@@ -239,6 +245,7 @@ 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
@@ -254,6 +261,7 @@ Properties on Targets
    /prop_tgt/INTERFACE_COMPILE_DEFINITIONS
    /prop_tgt/INTERFACE_COMPILE_FEATURES
    /prop_tgt/INTERFACE_COMPILE_OPTIONS
+   /prop_tgt/INTERFACE_HEADER_SETS
    /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES
    /prop_tgt/INTERFACE_LINK_DEPENDS
    /prop_tgt/INTERFACE_LINK_DIRECTORIES
@@ -297,6 +305,7 @@ Properties on Targets
    /prop_tgt/LINK_INTERFACE_MULTIPLICITY
    /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG
    /prop_tgt/LINK_LIBRARIES
+   /prop_tgt/LINK_LIBRARIES_ONLY_TARGETS
    /prop_tgt/LINK_OPTIONS
    /prop_tgt/LINK_SEARCH_END_STATIC
    /prop_tgt/LINK_SEARCH_START_STATIC
@@ -425,6 +434,7 @@ Properties on Targets
    /prop_tgt/XCODE_SCHEME_ARGUMENTS
    /prop_tgt/XCODE_SCHEME_DEBUG_AS_ROOT
    /prop_tgt/XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
+   /prop_tgt/XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
    /prop_tgt/XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
    /prop_tgt/XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
    /prop_tgt/XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE

Help/manual/cmake-variables.7.rst

@@ -49,6 +49,7 @@ Variables that Provide Information
    /variable/CMAKE_DEBUG_TARGET_PROPERTIES
    /variable/CMAKE_DIRECTORY_LABELS
    /variable/CMAKE_DL_LIBS
+   /variable/CMAKE_DOTNET_SDK
    /variable/CMAKE_DOTNET_TARGET_FRAMEWORK
    /variable/CMAKE_DOTNET_TARGET_FRAMEWORK_VERSION
    /variable/CMAKE_EDIT_COMMAND
@@ -118,6 +119,7 @@ Variables that Provide Information
    /variable/CMAKE_VS_DEVENV_COMMAND
    /variable/CMAKE_VS_MSBUILD_COMMAND
    /variable/CMAKE_VS_NsightTegra_VERSION
+   /variable/CMAKE_VS_NUGET_PACKAGE_RESTORE
    /variable/CMAKE_VS_PLATFORM_NAME
    /variable/CMAKE_VS_PLATFORM_NAME_DEFAULT
    /variable/CMAKE_VS_PLATFORM_TOOLSET
@@ -210,6 +212,7 @@ Variables that Change Behavior
    /variable/CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY
    /variable/CMAKE_FRAMEWORK_PATH
    /variable/CMAKE_IGNORE_PATH
+   /variable/CMAKE_IGNORE_PREFIX_PATH
    /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE
    /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE
    /variable/CMAKE_INCLUDE_PATH
@@ -220,6 +223,7 @@ Variables that Change Behavior
    /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
    /variable/CMAKE_LIBRARY_PATH
    /variable/CMAKE_LINK_DIRECTORIES_BEFORE
+   /variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS
    /variable/CMAKE_MFC_FLAG
    /variable/CMAKE_MAXIMUM_RECURSION_DEPTH
    /variable/CMAKE_MESSAGE_CONTEXT
@@ -247,6 +251,7 @@ Variables that Change Behavior
    /variable/CMAKE_SYSTEM_APPBUNDLE_PATH
    /variable/CMAKE_SYSTEM_FRAMEWORK_PATH
    /variable/CMAKE_SYSTEM_IGNORE_PATH
+   /variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH
    /variable/CMAKE_SYSTEM_INCLUDE_PATH
    /variable/CMAKE_SYSTEM_LIBRARY_PATH
    /variable/CMAKE_SYSTEM_PREFIX_PATH
@@ -262,6 +267,7 @@ Variables that Change Behavior
    /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER
    /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
    /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
+   /variable/CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
    /variable/CMAKE_XCODE_SCHEME_DISABLE_MAIN_THREAD_CHECKER
    /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LIBRARY_LOADS
    /variable/CMAKE_XCODE_SCHEME_DYNAMIC_LINKER_API_USAGE
@@ -307,7 +313,7 @@ Variables that Describe the System
    /variable/CMAKE_SYSTEM_PROCESSOR
    /variable/CMAKE_SYSTEM_VERSION
    /variable/CYGWIN
-   /variable/GHS-MULTI
+   /variable/GHSMULTI
    /variable/IOS
    /variable/MINGW
    /variable/MSVC
@@ -466,6 +472,7 @@ Variables that Control the Build
    /variable/CMAKE_PCH_INSTANTIATE_TEMPLATES
    /variable/CMAKE_PDB_OUTPUT_DIRECTORY
    /variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG
+   /variable/CMAKE_PLATFORM_NO_VERSIONED_SONAME
    /variable/CMAKE_POSITION_INDEPENDENT_CODE
    /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY
    /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG
@@ -578,8 +585,6 @@ Variables for Languages
    /variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES
    /variable/CMAKE_LANG_LIBRARY_ARCHITECTURE
    /variable/CMAKE_LANG_LINK_EXECUTABLE
-   /variable/CMAKE_LANG_LINKER_PREFERENCE
-   /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES
    /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG
    /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP
    /variable/CMAKE_LANG_OUTPUT_EXTENSION
@@ -668,6 +673,7 @@ Variables for CTest
    /variable/CTEST_SCP_COMMAND
    /variable/CTEST_SCRIPT_DIRECTORY
    /variable/CTEST_SITE
+   /variable/CTEST_SUBMIT_INACTIVITY_TIMEOUT
    /variable/CTEST_SUBMIT_URL
    /variable/CTEST_SOURCE_DIRECTORY
    /variable/CTEST_SVN_COMMAND
@@ -723,6 +729,8 @@ are subject to change, and not recommended for use in project code.
    /variable/CMAKE_LANG_COMPILER_ABI
    /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID
    /variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL
+   /variable/CMAKE_LANG_LINKER_PREFERENCE
+   /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES
    /variable/CMAKE_LANG_PLATFORM_ID
    /variable/CMAKE_NOT_USING_CONFIG_FLAGS
    /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION

Help/manual/cmake.1.rst

@@ -151,6 +151,33 @@ source and build trees and generate a buildsystem:
 
 In all cases the ``<options>`` may be zero or more of the `Options`_ below.
 
+The above styles for specifying the source and build trees may be mixed.
+Paths specified with ``-S`` or ``-B`` are always classified as source or
+build trees, respectively.  Paths specified with plain arguments are
+classified based on their content and the types of paths given earlier.
+If only one type of path is given, the current working directory (cwd)
+is used for the other.  For example:
+
+============================== ============ ===========
+ Command Line                   Source Dir   Build Dir
+============================== ============ ===========
+ ``cmake src``                  ``src``      `cwd`
+ ``cmake build`` (existing)     `loaded`     ``build``
+ ``cmake -S src``               ``src``      `cwd`
+ ``cmake -S src build``         ``src``      ``build``
+ ``cmake -S src -B build``      ``src``      ``build``
+ ``cmake -B build``             `cwd`        ``build``
+ ``cmake -B build src``         ``src``      ``build``
+ ``cmake -B build -S src``      ``src``      ``build``
+============================== ============ ===========
+
+.. versionchanged:: 3.23
+
+  CMake warns when multiple source paths are specified.  This has never
+  been officially documented or supported, but older versions accidentally
+  accepted multiple source paths and used the last path specified.
+  Avoid passing multiple source path arguments.
+
 After generating a buildsystem one may use the corresponding native
 build tool to build the project.  For example, after using the
 :generator:`Unix Makefiles` generator one may run ``make`` directly:
@@ -250,6 +277,21 @@ Options
  See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging
  a more local part of the project.
 
+``--debug-find-pkg=<pkg>[,...]``
+ 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
+ names.
+
+ Like ``--debug-find``, but limiting scope to the specified packages.
+
+``--debug-find-var=<var>[,...]``
+ 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.
+
+ Like ``--debug-find``, but limiting scope to the specified variable names.
+
 ``--trace``
  Put cmake in trace mode.
 
@@ -449,6 +491,29 @@ following options:
   Build target ``clean`` first, then build.
   (To clean only, use ``--target clean``.)
 
+``--resolve-package-references=<on|off|only>``
+  .. versionadded:: 3.23
+
+  Resolve remote package references from external package managers (e.g. NuGet)
+  before build. When set to ``on`` (default), packages will be restored before
+  building a target. When set to ``only``, the packages will be restored, but no
+  build will be performed. When set to ``off``, no packages will be restored.
+
+  If the target does not define any package references, this option does nothing.
+
+  This setting can be specified in a build preset (using
+  ``resolvePackageReferences``). The preset setting will be ignored, if this
+  command line option is specified.
+
+  If no command line parameter or preset option are provided, an environment-
+  specific cache variable will be evaluated to decide, if package restoration
+  should be performed.
+
+  When using the Visual Studio generator, package references are defined
+  using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references
+  are restored using NuGet. It can be disabled by setting the
+  ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``.
+
 ``--use-stderr``
   Ignored.  Behavior is default in CMake >= 3.0.
 
@@ -547,6 +612,8 @@ Run ``cmake -E`` or ``cmake -E help`` for a summary of commands.
 Available commands are:
 
 ``capabilities``
+  .. versionadded:: 3.7
+
   Report cmake capabilities in JSON format. The output is a JSON object
   with the following keys:
 
@@ -607,6 +674,8 @@ Available commands are:
     Always false since CMake 3.20.
 
 ``cat <files>...``
+  .. versionadded:: 3.18
+
   Concatenate files and print on the standard output.
 
 ``chdir <dir> <cmd> [<arg>...]``
@@ -615,8 +684,11 @@ Available commands are:
 ``compare_files [--ignore-eol] <file1> <file2>``
   Check if ``<file1>`` is same as ``<file2>``. If files are the same,
   then returns ``0``, if not it returns ``1``.  In case of invalid
-  arguments, it returns 2. The ``--ignore-eol`` option
+  arguments, it returns 2.
-  implies line-wise comparison and ignores LF/CRLF differences.
+
+  .. versionadded:: 3.14
+    The ``--ignore-eol`` option implies line-wise comparison and ignores
+    LF/CRLF differences.
 
 ``copy <file>... <destination>``
   Copy files to ``<destination>`` (either file or directory).
@@ -625,11 +697,21 @@ Available commands are:
   ``copy`` does follow symlinks. That means it does not copy symlinks,
   but the files or directories it point to.
 
+  .. versionadded:: 3.5
+    Support for multiple input files.
+
 ``copy_directory <dir>... <destination>``
   Copy content of ``<dir>...`` directories to ``<destination>`` directory.
   If ``<destination>`` directory does not exist it will be created.
   ``copy_directory`` does follow symlinks.
 
+  .. versionadded:: 3.5
+    Support for multiple input directories.
+
+  .. versionadded:: 3.15
+    The command now fails when the source directory does not exist.
+    Previously it succeeded by creating an empty destination directory.
+
 ``copy_if_different <file>... <destination>``
   Copy files to ``<destination>`` (either file or directory) if
   they have changed.
@@ -637,13 +719,21 @@ Available commands are:
   directory and it must exist.
   ``copy_if_different`` does follow symlinks.
 
+  .. versionadded:: 3.5
+    Support for multiple input files.
+
 ``create_symlink <old> <new>``
   Create a symbolic link ``<new>`` naming ``<old>``.
 
+  .. versionadded:: 3.13
+    Support for creating symlinks on Windows.
+
   .. note::
     Path to where ``<new>`` symbolic link will be created has to exist beforehand.
 
 ``create_hardlink <old> <new>``
+  .. versionadded:: 3.19
+
   Create a hard link ``<new>`` naming ``<old>``.
 
   .. note::
@@ -657,12 +747,16 @@ Available commands are:
   Displays arguments as text but no new line.
 
 ``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...``
+  .. versionadded:: 3.1
+
   Run command in a modified environment.
 
 ``environment``
   Display the current environment variables.
 
 ``false``
+  .. versionadded:: 3.16
+
   Do nothing, with an exit code of 1.
 
 ``make_directory <dir>...``
@@ -670,6 +764,9 @@ Available commands are:
   directories too.  If a directory already exists it will be
   silently ignored.
 
+  .. versionadded:: 3.5
+    Support for multiple input directories.
+
 ``md5sum <file>...``
   Create MD5 checksum of files in ``md5sum`` compatible format::
 
@@ -677,30 +774,40 @@ Available commands are:
      052f86c15bbde68af55c7f7b340ab639  file2.txt
 
 ``sha1sum <file>...``
+  .. versionadded:: 3.10
+
   Create SHA1 checksum of files in ``sha1sum`` compatible format::
 
      4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
      1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt
 
 ``sha224sum <file>...``
+  .. versionadded:: 3.10
+
   Create SHA224 checksum of files in ``sha224sum`` compatible format::
 
      b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930  file1.txt
      6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24  file2.txt
 
 ``sha256sum <file>...``
+  .. versionadded:: 3.10
+
   Create SHA256 checksum of files in ``sha256sum`` compatible format::
 
      76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc  file1.txt
      15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea  file2.txt
 
 ``sha384sum <file>...``
+  .. versionadded:: 3.10
+
   Create SHA384 checksum of files in ``sha384sum`` compatible format::
 
      acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434  file1.txt
      668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d  file2.txt
 
 ``sha512sum <file>...``
+  .. versionadded:: 3.10
+
   Create SHA512 checksum of files in ``sha512sum`` compatible format::
 
      2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89  file1.txt
@@ -723,16 +830,24 @@ Available commands are:
   .. deprecated:: 3.17
 
   Remove ``<dir>`` directories and their contents. If a directory does
-  not exist it will be silently ignored.  If ``<dir>`` is a symlink to
+  not exist it will be silently ignored.
-  a directory, just the symlink will be removed.
   Use ``rm`` instead.
 
+  .. versionadded:: 3.15
+    Support for multiple directories.
+
+  .. versionadded:: 3.16
+    If ``<dir>`` is a symlink to a directory, just the symlink will be removed.
+
 ``rename <oldname> <newname>``
   Rename a file or directory (on one volume). If file with the ``<newname>`` name
   already exists, then it will be silently replaced.
 
 ``rm [-rRf] <file> <dir>...``
-  Remove the files ``<file>`` or directories ``dir``.
+  .. versionadded:: 3.17
+
+  Remove the files ``<file>`` or directories ``<dir>``.
+
   Use ``-r`` or ``-R`` to remove directories and their contents recursively.
   If any of the listed files/directories do not exist, the command returns a
   non-zero exit code, but no message is logged. The ``-f`` option changes
@@ -743,6 +858,8 @@ Available commands are:
   Launch :manual:`cmake-server(7)` mode.
 
 ``sleep <number>...``
+  .. versionadded:: 3.0
+
   Sleep for given number of seconds.
 
 ``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]``
@@ -751,45 +868,85 @@ Available commands are:
   ``c``
     Create a new archive containing the specified files.
     If used, the ``<pathname>...`` argument is mandatory.
+
   ``x``
     Extract to disk from the archive.
-    The ``<pathname>...`` argument could be used to extract only selected files
+
-    or directories.
+    .. versionadded:: 3.15
-    When extracting selected files or directories, you must provide their exact
+      The ``<pathname>...`` argument could be used to extract only selected files
-    names including the path, as printed by list (``-t``).
+      or directories.
+      When extracting selected files or directories, you must provide their exact
+      names including the path, as printed by list (``-t``).
+
   ``t``
     List archive contents.
-    The ``<pathname>...`` argument could be used to list only selected files
+
-    or directories.
+    .. versionadded:: 3.15
+      The ``<pathname>...`` argument could be used to list only selected files
+      or directories.
+
   ``v``
     Produce verbose output.
+
   ``z``
     Compress the resulting archive with gzip.
+
   ``j``
     Compress the resulting archive with bzip2.
+
   ``J``
+    .. versionadded:: 3.1
+
     Compress the resulting archive with XZ.
+
   ``--zstd``
+    .. versionadded:: 3.15
+
     Compress the resulting archive with Zstandard.
+
   ``--files-from=<file>``
+    .. versionadded:: 3.1
+
     Read file names from the given file, one per line.
     Blank lines are ignored.  Lines may not start in ``-``
     except for ``--add-file=<name>`` to add files whose
     names start in ``-``.
+
   ``--format=<format>``
+    .. versionadded:: 3.3
+
     Specify the format of the archive to be created.
     Supported formats are: ``7zip``, ``gnutar``, ``pax``,
     ``paxr`` (restricted pax, default), and ``zip``.
+
   ``--mtime=<date>``
+    .. versionadded:: 3.1
+
     Specify modification time recorded in tarball entries.
+
   ``--``
+    .. versionadded:: 3.1
+
     Stop interpreting options and treat all remaining arguments
     as file names, even if they start with ``-``.
 
+  .. versionadded:: 3.1
+    LZMA (7zip) support.
+
+  .. versionadded:: 3.15
+    The command now continues adding files to an archive even if some of the
+    files are not readable.  This behavior is more consistent with the classic
+    ``tar`` tool. The command now also parses all flags, and if an invalid flag
+    was provided, a warning is issued.
 
 ``time <command> [<args>...]``
   Run command and display elapsed time.
 
+  .. versionadded:: 3.5
+    The command now properly passes arguments with spaces or special characters
+    through to the child process. This may break scripts that worked around the
+    bug with their own extra quoting or escaping.
+
 ``touch <file>...``
   Creates ``<file>`` if file do not exist.
   If ``<file>`` exists, it is changing ``<file>`` access and modification times.
@@ -799,6 +956,8 @@ Available commands are:
   not exist it will be silently ignored.
 
 ``true``
+  .. versionadded:: 3.16
+
   Do nothing, with an exit code of 0.
 
 Windows-specific Command-Line Tools
@@ -810,10 +969,14 @@ The following ``cmake -E`` commands are available only on Windows:
   Delete Windows registry value.
 
 ``env_vs8_wince <sdkname>``
+  .. versionadded:: 3.2
+
   Displays a batch file which sets the environment for the provided
   Windows CE SDK installed in VS2005.
 
 ``env_vs9_wince <sdkname>``
+  .. versionadded:: 3.2
+
   Displays a batch file which sets the environment for the provided
   Windows CE SDK installed in VS2008.
 

Help/manual/ctest.1.rst

@@ -1353,6 +1353,13 @@ Configuration settings include:
   * :module:`CTest` module variable: ``SUBMIT_URL`` if set,
     else ``CTEST_SUBMIT_URL``
 
+``SubmitInactivityTimeout``
+  The time to wait for the submission after which it is canceled
+  if not completed. Specify a zero value to disable timeout.
+
+  * `CTest Script`_ variable: :variable:`CTEST_SUBMIT_INACTIVITY_TIMEOUT`
+  * :module:`CTest` module variable: ``CTEST_SUBMIT_INACTIVITY_TIMEOUT``
+
 ``TriggerSite``
   Legacy option.  Not used.
 

Help/manual/presets/example.json

@@ -1,10 +1,14 @@
 {
-  "version": 3,
+  "version": 4,
   "cmakeMinimumRequired": {
     "major": 3,
-    "minor": 21,
+    "minor": 23,
     "patch": 0
   },
+  "include": [
+    "otherThings.json",
+    "moreThings.json"
+  ],
   "configurePresets": [
     {
       "name": "default",

Help/manual/presets/schema.json

@@ -42,6 +42,21 @@
         "testPresets": { "$ref": "#/definitions/testPresetsV3"}
       },
       "additionalProperties": false
+    },
+    {
+      "properties": {
+        "version": {
+          "const": 4,
+          "description": "A required integer representing the version of the JSON schema."
+        },
+        "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
+        "vendor": { "$ref": "#/definitions/vendor" },
+        "configurePresets": { "$ref": "#/definitions/configurePresetsV3"},
+        "buildPresets": { "$ref": "#/definitions/buildPresetsV4"},
+        "testPresets": { "$ref": "#/definitions/testPresetsV3"},
+        "include": { "$ref": "#/definitions/include"}
+      },
+      "additionalProperties": false
     }
   ],
   "required": [
@@ -412,9 +427,25 @@
         "additionalProperties": false
       }
     },
+    "buildPresetsItemsV4": {
+      "type": "array",
+      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "resolvePackageReferences": {
+            "type": "string",
+            "description": "An optional string specifying the package resolve behavior. Valid values are \"on\" (packages are resolved prior to the build), \"off\" (packages are not resolved prior to the build), and \"only\" (packages are resolved, but no build will be performed).",
+            "enum": [
+              "on", "off", "only"
+            ]
+          }
+        }
+      }
+    },
     "buildPresetsItemsV3": {
       "type": "array",
-      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
+      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 and higher.",
       "items": {
         "type": "object",
         "properties": {
@@ -543,9 +574,44 @@
         ]
       }
     },
+    "buildPresetsV4": {
+      "type": "array",
+      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.",
+      "allOf": [
+        { "$ref": "#/definitions/buildPresetsItemsV4" },
+        { "$ref": "#/definitions/buildPresetsItemsV3" },
+        { "$ref": "#/definitions/buildPresetsItemsV2" }
+      ],
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {},
+          "hidden": {},
+          "inherits": {},
+          "configurePreset": {},
+          "vendor": {},
+          "displayName": {},
+          "description": {},
+          "inheritConfigureEnvironment": {},
+          "environment": {},
+          "jobs": {},
+          "targets": {},
+          "configuration": {},
+          "cleanFirst": {},
+          "resolvePackageReferences": {},
+          "verbose": {},
+          "nativeToolOptions": {},
+          "condition": {}
+        },
+        "required": [
+          "name"
+        ],
+        "additionalProperties": false
+      }
+    },
     "buildPresetsV3": {
       "type": "array",
-      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
+      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 and higher.",
       "allOf": [
         { "$ref": "#/definitions/buildPresetsItemsV3" },
         { "$ref": "#/definitions/buildPresetsItemsV2" }
@@ -609,7 +675,7 @@
     },
     "testPresetsItemsV3": {
       "type": "array",
-      "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
+      "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.",
       "items": {
         "type": "object",
         "properties": {
@@ -934,7 +1000,7 @@
     },
     "testPresetsV3": {
       "type": "array",
-      "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
+      "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.",
       "allOf": [
         { "$ref": "#/definitions/testPresetsItemsV2" },
         { "$ref": "#/definitions/testPresetsItemsV3" }
@@ -1235,6 +1301,13 @@
           "description": "Null indicates that the condition always evaluates to true and is not inherited."
         }
       ]
+    },
+    "include": {
+      "type": "array",
+      "description": "An optional array of strings representing files to include. If the filenames are not absolute, they are considered relative to the current file.",
+      "items": {
+        "type": "string"
+      }
     }
   }
 }

Help/policy/CMP0028.rst

@@ -13,6 +13,8 @@ on disk.  Previously, if a target was not found with a matching name, the name
 was considered to refer to a file on disk.  This can lead to confusing error
 messages if there is a typo in what should be a target name.
 
+See also the :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` target property.
+
 The ``OLD`` behavior for this policy is to search for targets, then files on
 disk, even if the search term contains double-colons.  The ``NEW`` behavior
 for this policy is to issue a ``FATAL_ERROR`` if a link dependency contains

Help/policy/CMP0126.rst

@@ -14,6 +14,9 @@ current scope in the following situations:
   This can occur when the variable was set on the command line using a form
   like ``cmake -DMYVAR=blah`` instead of ``cmake -DMYVAR:STRING=blah``.
 
+* The ``FORCE`` or ``INTERNAL`` keywords were used when setting the cache
+  variable.
+
 Note that the ``NEW`` behavior has an important difference to the similar
 ``NEW`` behavior of policy :policy:`CMP0077`.  The :command:`set(CACHE)`
 command always sets the cache variable if it did not exist previously,

Help/policy/CMP0129.rst

@@ -0,0 +1,34 @@
+CMP0129
+-------
+
+.. versionadded:: 3.23
+
+Compiler id for MCST LCC compilers is now ``LCC``, not ``GNU``.
+
+CMake 3.23 and above recognize MCST LCC compiler as a different from ``GNU``,
+with its own command line and set of capabilities.
+CMake now prefers to present this to projects by setting the
+:variable:`CMAKE_<LANG>_COMPILER_ID` variable to ``LCC`` instead
+of ``GNU``. However, existing projects may assume the compiler id for
+LCC is ``GNU`` as it was in CMake versions prior to 3.23.
+Therefore this policy determines for MCST LCC compiler which
+compiler id to report in the :variable:`CMAKE_<LANG>_COMPILER_ID`
+variable after language ``<LANG>`` is enabled by the :command:`project`
+or :command:`enable_language` command.  The policy must be set prior
+to the invocation of either command.
+
+The ``OLD`` behavior for this policy is to use compiler id ``GNU`` (and set
+:variable:`CMAKE_<LANG>_COMPILER_VERSION` to the supported GNU compiler version.)
+``NEW`` behavior for this policy is to use compiler id ``LCC``, and set
+:variable:`CMAKE_<LANG>_SIMULATE_ID` to ``GNU``, and
+:variable:`CMAKE_<LANG>_SIMULATE_VERSION` to the supported GNU compiler version.
+
+This policy was introduced in CMake version 3.23.  Use the
+:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` explicitly.
+Unlike most policies, CMake version |release| does *not* warn
+by default when this policy is not set and simply uses ``OLD`` behavior.
+See documentation of the
+:variable:`CMAKE_POLICY_WARNING_CMP0129 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
+variable to control the warning.
+
+.. include:: DEPRECATED.txt

Help/prop_gbl/CMAKE_CUDA_KNOWN_FEATURES.rst

@@ -35,3 +35,5 @@ The features known to this version of CMake are:
   .. versionadded:: 3.20
 
   Compiler mode is at least CUDA/C++ 23.
+
+.. include:: CMAKE_LANG_STD_FLAGS.txt

Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst

@@ -46,6 +46,8 @@ but it does not necessarily imply complete conformance to that standard.
 
   Compiler mode is at least C++ 23.
 
+.. include:: CMAKE_LANG_STD_FLAGS.txt
+
 Low level individual compile features
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst

@@ -39,6 +39,8 @@ High level meta features indicating C standard support
 
   Compiler mode is at least C 23.
 
+.. include:: CMAKE_LANG_STD_FLAGS.txt
+
 Low level individual compile features
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

Help/prop_gbl/CMAKE_LANG_STD_FLAGS.txt

@@ -0,0 +1,7 @@
+.. note::
+
+  If the compiler's default standard level is at least that
+  of the requested feature, CMake may omit the ``-std=`` flag.
+  The flag may still be added if the compiler's default extensions mode
+  does not match the :prop_tgt:`<LANG>_EXTENSIONS` target property,
+  or if the :prop_tgt:`<LANG>_STANDARD` target property is set.

Help/prop_sf/LANGUAGE.rst

@@ -7,8 +7,8 @@ A property that can be set to indicate what programming language the
 source file is.  If it is not set the language is determined based on
 the file extension.  Typical values are ``CXX`` (i.e.  C++), ``C``,
 ``CSharp``, ``CUDA``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``.  Setting
-this property for a file means this file will be compiled.  Do not set this
+this property for a file means this file will be compiled, unless
-for headers or files that should not be compiled.
+:prop_sf:`HEADER_FILE_ONLY` is set.
 
 .. versionchanged:: 3.20
   Setting this property causes the source file to be compiled as the

Help/prop_test/ENVIRONMENT.rst

@@ -3,7 +3,7 @@ ENVIRONMENT
 
 Specify environment variables that should be defined for running a test.
 
-If set to a list of environment variables and values of the form
+Set to a :ref:`semicolon-separated list <CMake Language Lists>` list
-``MYVAR=value`` those environment variables will be defined while running
+of environment variables and values of the form ``MYVAR=value``.
-the test.  The environment changes from this property do not affect other
+Those environment variables will be defined while running the test.
-tests.
+The environment changes from this property do not affect other tests.

Help/prop_test/ENVIRONMENT_MODIFICATION.rst

@@ -7,10 +7,11 @@ Specify environment variables that should be modified for running a test. Note
 that the operations performed by this property are performed after the
 :prop_test:`ENVIRONMENT` property is already applied.
 
-If set to a list of environment variables and values of the form
+Set to a :ref:`semicolon-separated list <CMake Language Lists>` of
-``MYVAR=OP:VALUE``, where ``MYVAR`` is the case-sensitive name of an
+environment variables and values of the form ``MYVAR=OP:VALUE``,
-environment variable to be modified. Entries are considered in the
+where ``MYVAR`` is the case-sensitive name of an environment variable
-order specified in the property's value. The ``OP`` may be one of:
+to be modified.  Entries are considered in the order specified in the
+property's value.  The ``OP`` may be one of:
 
   - ``reset``: Reset to the unmodified value, ignoring all modifications to
     ``MYVAR`` prior to this entry. Note that this will reset the variable to

Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst

@@ -8,9 +8,10 @@ This command will be added as a prefix to :command:`add_test`,
 :command:`add_custom_command`, and :command:`add_custom_target` commands
 for built target system executables.
 
-If this property contains a :ref:`semicolon-separated list <CMake Language
+.. versionadded:: 3.15
-Lists>`, then the first value is the command and remaining values are its
+  If this property contains a :ref:`semicolon-separated list <CMake Language
-arguments.
+  Lists>`, then the first value is the command and remaining values are its
+  arguments.
 
 This property is initialized by the value of the
 :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable if it is set when a target

Help/prop_tgt/CUDA_ARCHITECTURES.rst

@@ -20,6 +20,20 @@ variable if it is set when a target is created.
 The ``CUDA_ARCHITECTURES`` target property must be set to a non-empty value on targets
 that compile CUDA sources, or it is an error.  See policy :policy:`CMP0104`.
 
+The ``CUDA_ARCHITECTURES`` may be set to one of the following special values:
+
+``all``
+  .. versionadded:: 3.23
+
+  Compile for all supported major and minor real architectures,
+  and the highest major virtual architecture.
+
+``all-major``
+  .. versionadded:: 3.23
+
+  Compile for all supported major real architectures, and the highest
+  major virtual architecture.
+
 Examples
 ^^^^^^^^
 

Help/prop_tgt/DEPRECATION.rst

@@ -7,3 +7,8 @@ Deprecation message from imported target's developer.
 
 ``DEPRECATION`` is the message regarding a deprecation status to be displayed
 to downstream users of a target.
+
+The message is formatted as follows:
+
+* Lines that do not start in whitespace are wrapped as paragraph text.
+* Lines that start in whitespace are preserved as preformatted text.

Help/prop_tgt/DOTNET_SDK.rst

@@ -0,0 +1,25 @@
+DOTNET_SDK
+----------
+
+.. versionadded:: 3.23
+
+Specify the .NET SDK for C# projects.  For example: ``Microsoft.NET.Sdk``.
+
+This property tells :ref:`Visual Studio Generators` for VS 2019 and
+above to generate a .NET SDK-style project using the specified SDK.
+The property is meaningful only to these generators, and only in C#
+targets.  It is ignored for C++ projects, even if they are managed
+(e.g. using :prop_tgt:`COMMON_LANGUAGE_RUNTIME`).
+
+This property must be a non-empty string to generate .NET SDK-style projects.
+CMake does not perform any validations for the value of the property.
+
+This property may be initialized for all targets using the
+:variable:`CMAKE_DOTNET_SDK` variable.
+
+.. note::
+
+  The :ref:`Visual Studio Generators` in this version of CMake have not
+  yet learned to support :command:`add_custom_command` in .NET SDK-style
+  projects.  It is currently an error to attach a custom command to a
+  target with the ``DOTNET_SDK`` property set.

Help/prop_tgt/HEADER_DIRS.rst

@@ -0,0 +1,14 @@
+HEADER_DIRS
+-----------
+
+.. versionadded:: 3.23
+
+Semicolon-separated list of base directories of the target's default
+header set (i.e. the file set with name and type ``HEADERS``). The property
+supports :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+This property is normally only set by :command:`target_sources(FILE_SET)`
+rather than being manipulated directly.
+
+See :prop_tgt:`HEADER_DIRS_<NAME>` for the list of base directories in
+other header sets.

Help/prop_tgt/HEADER_DIRS_NAME.rst

@@ -0,0 +1,15 @@
+HEADER_DIRS_<NAME>
+------------------
+
+.. versionadded:: 3.23
+
+Semicolon-separated list of base directories of the target's ``<NAME>``
+header set, which has the set type ``HEADERS``. The property supports
+:manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+This property is normally only set by :command:`target_sources(FILE_SET)`
+rather than being manipulated directly.
+
+See :prop_tgt:`HEADER_DIRS` for the list of base directories in the
+default header set. See :prop_tgt:`HEADER_SETS` for the file set names of all
+header sets.

Help/prop_tgt/HEADER_SET.rst

@@ -0,0 +1,15 @@
+HEADER_SET
+----------
+
+.. versionadded:: 3.23
+
+Semicolon-separated list of files in the target's default header set,
+(i.e. the file set with name and type ``HEADERS``). If any of the paths
+are relative, they are computed relative to the target's source directory.
+The property supports
+:manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+This property is normally only set by :command:`target_sources(FILE_SET)`
+rather than being manipulated directly.
+
+See :prop_tgt:`HEADER_SET_<NAME>` for the list of files in other header sets.

Help/prop_tgt/HEADER_SETS.rst

@@ -0,0 +1,16 @@
+HEADER_SETS
+-----------
+
+.. versionadded:: 3.23
+
+List of the target's ``PRIVATE`` and ``PUBLIC`` header sets (i.e. all
+file sets with the type ``HEADERS``). Files listed in these file sets
+are treated as source files for the purpose of IDE integration.
+The files also have their :prop_sf:`HEADER_FILE_ONLY` property set to
+``TRUE``.
+
+This property is normally only set by :command:`target_sources(FILE_SET)`
+rather than being manipulated directly.
+
+See also :prop_tgt:`HEADER_SET_<NAME>`, :prop_tgt:`HEADER_SET` and
+:prop_tgt:`INTERFACE_HEADER_SETS`.

Help/prop_tgt/HEADER_SET_NAME.rst

@@ -0,0 +1,15 @@
+HEADER_SET_<NAME>
+-----------------
+
+.. versionadded:: 3.23
+
+Semicolon-separated list of files in the target's ``<NAME>`` header set,
+which has the set type ``HEADERS``. If any of the paths are relative,
+they are computed relative to the target's source directory. The property
+supports :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+This property is normally only set by :command:`target_sources(FILE_SET)`
+rather than being manipulated directly.
+
+See :prop_tgt:`HEADER_SET` for the list of files in the default header set.
+See :prop_tgt:`HEADER_SETS` for the file set names of all header sets.

Help/prop_tgt/IMPORTED_NO_SYSTEM.rst

@@ -0,0 +1,21 @@
+IMPORTED_NO_SYSTEM
+------------------
+
+.. versionadded:: 3.23
+
+Specifies that an :ref:`Imported Target <Imported Targets>` is not
+a ``SYSTEM`` library.  This has the following effects:
+
+* Entries of :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` are not treated
+  as ``SYSTEM`` include directories when compiling consumers, as they
+  would be by default.   Entries of
+  :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected,
+  and will always be treated as ``SYSTEM`` include directories.
+
+This property can also be enabled on a non-imported target.  Doing so does
+not affect the build system, but does tell the :command:`install(EXPORT)` and
+:command:`export` commands to enable it on the imported targets they generate.
+
+See the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property to set this
+behavior on the target consuming the include directories rather than
+providing them.

Help/prop_tgt/INTERFACE_HEADER_SETS.rst

@@ -0,0 +1,14 @@
+INTERFACE_HEADER_SETS
+---------------------
+
+.. versionadded:: 3.23
+
+List of the target's ``INTERFACE`` and ``PUBLIC`` header sets (i.e. all
+file sets with the type ``HEADERS``). Files listed in these header sets
+can be installed with :command:`install(TARGETS)` and exported with
+:command:`install(EXPORT)` and :command:`export`.
+
+This property is normally only set by :command:`target_sources(FILE_SET)`
+rather than being manipulated directly.
+
+See also :prop_tgt:`HEADER_SETS`.

Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst

@@ -12,6 +12,13 @@ other target also.  This property is overridden by the
 :prop_tgt:`LINK_INTERFACE_LIBRARIES_<CONFIG>` property if policy
 :policy:`CMP0022` is ``OLD`` or unset.
 
+The value of this property is used by the generators when constructing
+the link rule for a dependent target.  A dependent target's direct
+link dependencies, specified by its :prop_tgt:`LINK_LIBRARIES` target
+property, are linked first, followed by indirect dependencies from the
+transitive closure of the direct dependencies'
+``INTERFACE_LINK_LIBRARIES`` properties.  See policy :policy:`CMP0022`.
+
 Contents of ``INTERFACE_LINK_LIBRARIES`` may use "generator expressions"
 with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`

Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst

@@ -5,9 +5,12 @@ List of public system include directories for a library.
 
 Targets may populate this property to publish the include directories
 which contain system headers, and therefore should not result in
-compiler warnings.  The :command:`target_include_directories(SYSTEM)`
+compiler warnings.  Additionally, system include directories are searched
-command signature populates this property with values given to the
+after normal include directories regardless of the order specified.
-``PUBLIC`` and ``INTERFACE`` keywords.
+
+The :command:`target_include_directories(SYSTEM)` command signature
+populates this property with values given to the ``PUBLIC`` and
+``INTERFACE`` keywords.
 
 Projects may also get and set the property directly, but must be aware that
 adding directories to this property does not make those directories used

Help/prop_tgt/LANG_STANDARD.rst

@@ -15,6 +15,13 @@ newer standard is specified than is supported by the compiler, then it will
 fallback to the latest supported standard. This "decay" behavior may be
 controlled with the :prop_tgt:`<LANG>_STANDARD_REQUIRED` target property.
 
+Note that the actual language standard used may be higher than that specified
+by ``<LANG>_STANDARD``, regardless of the value of
+:prop_tgt:`<LANG>_STANDARD_REQUIRED`.  In particular,
+:ref:`transitive usage requirements <Target Usage Requirements>` or the use of
+:manual:`compile features <cmake-compile-features(7)>` can raise the required
+language standard above what ``<LANG>_STANDARD`` specifies.
+
 These properties are initialized by the value of the
 :variable:`CMAKE_<LANG>_STANDARD` variable if it is set when a target is
 created.

Help/prop_tgt/LANG_STANDARD_REQUIRED.rst

@@ -11,16 +11,22 @@ The variations are:
 * :prop_tgt:`OBJCXX_STANDARD_REQUIRED`
 
 These properties specify whether the value of :prop_tgt:`<LANG>_STANDARD` is a
-requirement. When ``OFF`` or unset, the :prop_tgt:`<LANG>_STANDARD` target
+requirement.  When false or unset, the :prop_tgt:`<LANG>_STANDARD` target
 property is treated as optional and may "decay" to a previous standard if the
-requested is not available.
+requested standard is not available.  When ``<LANG>_STANDARD_REQUIRED`` is set
+to true, :prop_tgt:`<LANG>_STANDARD` becomes a hard requirement and a fatal
+error will be issued if that requirement cannot be met.
+
+Note that the actual language standard used may be higher than that specified
+by :prop_tgt:`<LANG>_STANDARD`, regardless of the value of
+``<LANG>_STANDARD_REQUIRED``.  In particular,
+:ref:`transitive usage requirements <Target Usage Requirements>` or the use of
+:manual:`compile features <cmake-compile-features(7)>` can raise the required
+language standard above what :prop_tgt:`<LANG>_STANDARD` specifies.
 
 These properties are initialized by the value of the
 :variable:`CMAKE_<LANG>_STANDARD_REQUIRED` variable if it is set when a target
 is created.
 
-For supported CMake versions see the respective pages.
-To control language standard versions see :prop_tgt:`<LANG>_STANDARD`.
-
 See the :manual:`cmake-compile-features(7)` manual for information on
 compile features and a list of supported compilers.

Help/prop_tgt/LINKER_LANGUAGE.rst

@@ -7,8 +7,10 @@ For executables, shared libraries, and modules, this sets the language
 whose compiler is used to link the target (such as "C" or "CXX").  A
 typical value for an executable is the language of the source file
 providing the program entry point (main).  If not set, the language
-with the highest linker preference value is the default.  See
+with the highest linker preference value is the default.  Details of
-documentation of :variable:`CMAKE_<LANG>_LINKER_PREFERENCE` variables.
+the linker preferences are considered internal, but some limited
+discussion can be found under the internal
+:variable:`CMAKE_<LANG>_LINKER_PREFERENCE` variables.
 
 If this property is not set by the user, it will be calculated at
 generate-time by CMake.

Help/prop_tgt/LINK_LIBRARIES.rst

@@ -8,8 +8,11 @@ used for linking.  In addition to accepting values from the
 :command:`target_link_libraries` command, values may be set directly on
 any target using the :command:`set_property` command.
 
-The value of this property is used by the generators to set the link
+The value of this property is used by the generators to construct the
-libraries for the compiler.
+link rule for the target.  The direct link dependencies are linked first,
+followed by indirect dependencies from the transitive closure of the
+direct dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
+See policy :policy:`CMP0022`.
 
 Contents of ``LINK_LIBRARIES`` may use "generator expressions" with the
 syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)` manual

Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst

@@ -0,0 +1,54 @@
+LINK_LIBRARIES_ONLY_TARGETS
+---------------------------
+
+.. versionadded:: 3.23
+
+Enforce that link items that can be target names are actually existing targets.
+
+Set this property to a true value to enable additional checks on the contents
+of the :prop_tgt:`LINK_LIBRARIES` and :prop_tgt:`INTERFACE_LINK_LIBRARIES`
+target properties, typically populated by :command:`target_link_libraries`.
+CMake will verify that link items that might be target names actually name
+existing targets.  An item is considered a possible target name if:
+
+* it does not contain a ``/`` or ``\``, and
+* it does not start in ``-``, and
+* (for historical reasons) it does not start in ``$`` or `````.
+
+This property is initialized by the value of the
+:variable:`CMAKE_LINK_LIBRARIES_ONLY_TARGETS` variable when a non-imported
+target is created.  The property may be explicitly enabled on an imported
+target to check its link interface.
+
+In the following example, CMake will halt with an error at configure time
+because ``miLib`` is not a target:
+
+.. code-block:: cmake
+
+  set(CMAKE_LINK_LIBRARIES_ONLY_TARGETS ON)
+  add_library(myLib STATIC myLib.c)
+  add_executable(myExe myExe.c)
+  target_link_libraries(myExe PRIVATE miLib) # typo for myLib
+
+In order to link toolchain-provided libraries by name while still
+enforcing ``LINK_LIBRARIES_ONLY_TARGETS``, use an
+:ref:`imported <Imported Targets>`
+:ref:`Interface Library <Interface Libraries>` with the
+:prop_tgt:`IMPORTED_LIBNAME` target property:
+
+.. code-block:: cmake
+
+  add_library(toolchain::m INTERFACE IMPORTED)
+  set_property(TARGET toolchain::m PROPERTY IMPORTED_LIBNAME "m")
+  target_link_libraries(myExe PRIVATE toolchain::m)
+
+See also policy :policy:`CMP0028`.
+
+.. note::
+
+  If :prop_tgt:`INTERFACE_LINK_LIBRARIES` contains generator expressions,
+  its actual list of link items may depend on the type and properties of
+  the consuming target.  In such cases CMake may not always detect names
+  of missing targets that only appear for specific consumers.
+  A future version of CMake with improved heuristics may start triggering
+  errors on projects accepted by previous versions of CMake.

Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst

@@ -8,8 +8,13 @@ The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property
 of imported targets are treated as ``SYSTEM`` includes by default.  If this
 property is enabled on a target, compilation of sources in that target will
 not treat the contents of the ``INTERFACE_INCLUDE_DIRECTORIES`` of consumed
-imported targets as system includes.
+imported targets as system includes.  Either way, entries of
+:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` are not affected,
+and will always be treated as ``SYSTEM`` include directories.
 
 This property is initialized by the value of the
 :variable:`CMAKE_NO_SYSTEM_FROM_IMPORTED` variable if it is set when a target
 is created.
+
+See the :prop_tgt:`IMPORTED_NO_SYSTEM` target property to set this behavior
+on the target providing the include directories rather than consuming them.

Help/prop_tgt/SOURCES.rst

@@ -1,6 +1,38 @@
 SOURCES
 -------
 
-Source names specified for a target.
+This specifies the list of paths to source files for the target.
+The following commands all set or add to the ``SOURCES`` target property
+and are the usual way to manipulate it:
 
-List of sources specified for a target.
+* :command:`add_executable`
+* :command:`add_library`
+* :command:`add_custom_target`
+* :command:`target_sources`
+
+Contents of ``SOURCES`` may use
+:manual:`generator expressions <cmake-generator-expressions(7)>`.
+If a path starts with a generator expression, it is expected to
+evaluate to an absolute path. Not doing so is considered undefined behavior.
+
+Paths that are for files generated by the build will be treated
+as relative to the build directory of the target, if the path is not
+already specified as an absolute path.  Note that whether a file is seen as
+generated may be affected by policy :policy:`CMP0118`.
+
+If a path does not start with a generator expression, is not an
+absolute path and is not a generated file, it will be treated as relative to
+the location selected by the first of the following that matches:
+
+* If a file by the specified path exists relative to the target's source
+  directory, use that file.
+* If policy :policy:`CMP0115` is not set to ``NEW``, try appending each
+  known source file extension to the path and check if that exists
+  relative to the target's source directory.
+* Repeat the above two steps, this time relative to the target's binary
+  directory instead.
+
+Note that the above decisions are made at generation time, not build time.
+
+See the :manual:`cmake-buildsystem(7)` manual for more on defining
+buildsystem properties.

Help/prop_tgt/XCODE_EMBED_type.rst

@@ -19,6 +19,12 @@ The supported values for ``<type>`` are:
   The specified items will be added to the ``Embed App Extensions`` build phase.
   They must be CMake target names.
 
+``PLUGINS``
+  .. versionadded:: 3.23
+
+  The specified items will be added to the ``Embed PlugIns`` build phase.
+  They must be CMake target names.
+
 See also :prop_tgt:`XCODE_EMBED_<type>_PATH`,
 :prop_tgt:`XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY` and
 :prop_tgt:`XCODE_EMBED_<type>_CODE_SIGN_ON_COPY`.

Help/prop_tgt/XCODE_EMBED_type_CODE_SIGN_ON_COPY.rst

@@ -14,5 +14,8 @@ The supported values for ``<type>`` are:
 ``APP_EXTENSIONS``
   .. versionadded:: 3.21
 
+``PLUGINS``
+  .. versionadded:: 3.23
+
 If a ``XCODE_EMBED_<type>_CODE_SIGN_ON_COPY`` property is not defined on the
 target, no code signing on copy will be performed for that ``<type>``.

Help/prop_tgt/XCODE_EMBED_type_PATH.rst

@@ -16,3 +16,6 @@ The supported values for ``<type>`` are:
 
 ``APP_EXTENSIONS``
   .. versionadded:: 3.21
+
+``PLUGINS``
+  .. versionadded:: 3.23

Help/prop_tgt/XCODE_EMBED_type_REMOVE_HEADERS_ON_COPY.rst

@@ -18,3 +18,6 @@ The supported values for ``<type>`` are:
 
   If the ``XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY`` property is not
   defined, headers WILL be removed on copy by default.
+
+``PLUGINS``
+  .. versionadded:: 3.23

Help/prop_tgt/XCODE_GENERATE_SCHEME.rst

@@ -38,6 +38,7 @@ The following target properties will be applied on the
 - :prop_tgt:`XCODE_SCHEME_ARGUMENTS`
 - :prop_tgt:`XCODE_SCHEME_DEBUG_AS_ROOT`
 - :prop_tgt:`XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING`
+- :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE`
 - :prop_tgt:`XCODE_SCHEME_ENVIRONMENT`
 - :prop_tgt:`XCODE_SCHEME_EXECUTABLE`
 - :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY`

Help/prop_tgt/XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.rst

@@ -0,0 +1,15 @@
+XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE
+------------------------------------------
+
+.. versionadded:: 3.23
+
+Property value for ``GPU Frame Capture`` in the Options section of
+the generated Xcode scheme. Example values are `Metal` and
+`Disabled`.
+
+This property is initialized by the value of the variable
+:variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE`
+if it is set when a target is created.
+
+Please refer to the :prop_tgt:`XCODE_GENERATE_SCHEME` target property
+documentation to see all Xcode schema related properties.

Help/release/3.21.rst

@@ -334,3 +334,10 @@ Changes made since CMake 3.21.0 include the following.
 * The :generator:`Visual Studio 17 2022` generator is now based on the
   "Visual Studio 2022" release candidates.  Previously it was based on
   preview versions.
+
+3.21.5, 3.21.6
+--------------
+
+These versions made no changes to documented features or interfaces.
+Some implementation updates were made to support ecosystem changes
+and/or fix regressions.

Help/release/3.22.rst

@@ -142,3 +142,25 @@ Other Changes
   This became available as of VS 16.10 (toolchain version 14.29.30037).
 
 * The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.03 or later.
+
+3.22.1
+------
+
+This version made no changes to documented features or interfaces.
+Some implementation updates were made to support ecosystem changes
+and/or fix regressions.
+
+3.22.2
+------
+
+* The ``OLD`` behavior of :policy:`CMP0128` was fixed to add flags even when
+  the specified standard matches the compiler default.
+
+3.22.3
+------
+
+* The :command:`while` command again ignores errors in condition evaluation
+  as CMake 3.21 and below did.  This bug was fixed in 3.22.0, but exposed
+  errors in existing projects.  The fix has been reverted to restore
+  compatibility.  The fix may be restored in a future version of CMake
+  via a policy.

Help/release/3.23.rst

@@ -0,0 +1,266 @@
+CMake 3.23 Release Notes
+************************
+
+.. only:: html
+
+  .. contents::
+
+Changes made since CMake 3.22 include the following.
+
+New Features
+============
+
+Presets
+-------
+
+* :manual:`cmake-presets(7)` files now support schema version ``4``.
+
+* :manual:`cmake-presets(7)` files now have an optional ``include`` field,
+  which allows the files to include other files.
+
+* :manual:`cmake-presets(7)` files now support a ``${fileDir}`` macro, which
+  contains the directory containing the preset file.
+
+* :manual:`cmake-presets(7)` gained support for specifying the
+  ``resolvePackageReferences`` command line option in a build preset to control
+  restoration behavior of package references from external package managers.
+  Currently this is only supported by the Visual Studio generator to support
+  restoring packages from NuGet. Other generators ignore this option.
+
+Generators
+----------
+
+* The :ref:`Visual Studio Generators` for VS 2019 and above learned to
+  support .NET SDK-style project files (``.csproj``) for C# projects.
+  See the :prop_tgt:`DOTNET_SDK` target property and corresponding
+  :variable:`CMAKE_DOTNET_SDK` variable.  :command:`add_custom_command`
+  is not yet supported in .NET SDK-style projects.
+
+* The :ref:`Visual Studio Generators` for VS 2017 and above learned to
+  use portable instances of Visual Studio not known to the VS installer.
+  See the :variable:`CMAKE_GENERATOR_INSTANCE` variable.
+
+Command-Line
+------------
+
+* The :manual:`cmake(1)` ``--build`` command, when used with
+  :ref:`Visual Studio Generators` on projects that set the
+  :prop_tgt:`VS_PACKAGE_REFERENCES` target property, now automatically
+  restores package references from NuGet.  The cache variable
+  :variable:`CMAKE_VS_NUGET_PACKAGE_RESTORE` may be set to toggle this behavior
+  in a build tree.  Use the ``--resolve-package-references=<on|off|only>``
+  command-line option to control the behavior on one invocation.
+
+* The :manual:`cmake(1)` command line tool gained a ``--debug-find-pkg=``
+  option to enable debug messages under specific :command:`find_package`
+  calls.
+
+* The :manual:`cmake(1)` command line tool gained a ``--debug-find-var=``
+  option to enable debug messages for ``find_*`` calls that use specific
+  result variables.
+
+Compilers
+---------
+
+* The IBM Open XL C/C++ compiler, based on LLVM, is now supported with
+  compiler id ``IBMClang``.
+
+* The MCST LCC compiler is now supported with compiler id ``LCC``.
+  See policy :policy:`CMP0129`.
+
+File-Based API
+--------------
+
+* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field
+  has been updated to ``2.4``.
+
+* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``directory``
+  object ``installers`` field gained a new ``fileSet`` installer type.
+
+Commands
+--------
+
+* The :command:`define_property` command gained a new
+  ``INITIALIZE_FROM_VARIABLE`` option to cause a target property to be
+  initialized from a variable when a target is created.
+
+* The :command:`install(TARGETS)` command gained a new ``FILE_SET`` argument,
+  which can be used to install header file sets associated with a target.
+
+* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` commands now
+  support the ``%f`` specifier for microseconds.
+
+* The :command:`target_sources` command gained a new ``FILE_SET`` mode, which
+  can be used to add headers as header-only source files of a target.
+
+Variables
+---------
+
+* The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated
+  :prop_tgt:`CUDA_ARCHITECTURES` target property now support the
+  ``all``, and ``all-major`` values for CUDA toolkit 7.0+.
+
+* The :variable:`CMAKE_IGNORE_PREFIX_PATH` and
+  :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables were added
+  to tell the :command:`find_package`, :command:`find_program`,
+  :command:`find_library`, :command:`find_path`, and :command:`find_file`
+  commands to ignore specified prefixes.
+
+* The :variable:`CMAKE_LINK_LIBRARIES_ONLY_TARGETS` variable and
+  corresponding :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` target
+  property were added to optionally require that all link items
+  that can be target names are actually names of existing targets.
+
+Properties
+----------
+
+* The :prop_tgt:`HEADER_SETS` and :prop_tgt:`INTERFACE_HEADER_SETS` target
+  properties were added to list header sets associated with a target.
+
+* The :prop_tgt:`HEADER_SET` and :prop_tgt:`HEADER_SET_<NAME>` target
+  properties were added to list files in the default header set
+  and named header sets, respectively.
+
+* The :prop_tgt:`HEADER_DIRS` and :prop_tgt:`HEADER_DIRS_<NAME>` target
+  properties were added to specify the base directories of the default
+  header set and named header sets, respectively.
+
+* The :prop_tgt:`IMPORTED_NO_SYSTEM` target property was added to
+  specify that an :ref:`Imported Target <Imported Targets>` should
+  not be treated as a system library (i.e. its include directories
+  are not automatically ``SYSTEM``).
+
+* The :prop_tgt:`XCODE_EMBED_PLUGINS <XCODE_EMBED_<type>>` target property
+  was added to tell the :generator:`Xcode` generator what targets to put in
+  the ``Embed PlugIns`` build phase.
+
+* The :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` target property
+  and supporting :variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE`
+  variable were added to tell the :generator:`Xcode` generator to enable
+  specifying the Xcode scheme option property ``GPU Frame Capture``.
+
+Modules
+-------
+
+* The :module:`CheckPIESupported` module now supports the ``OBJC``,
+  ``OBJCXX``, ``CUDA``, and ``HIP`` languages.  It also now honors
+  :variable:`CMAKE_SYSROOT` and :variable:`CMAKE_OSX_SYSROOT`.
+
+* The :module:`ExternalProject` module's :command:`ExternalProject_Add`
+  command gained support for a ``USES_TERMINAL_PATCH`` option to give
+  the patch step exclusive terminal access.
+
+* The :module:`FindCUDAToolkit` module now provides a target for
+  ``libcufft_static_nocallback``, if found.
+
+* The :module:`FindGLUT` module now provides the ``GLUT_INCLUDE_DIRS``
+  result variable to conform with naming conventions documented in the
+  :manual:`cmake-developer(7)` manual.  This supersedes the legacy
+  ``GLUT_INCLUDE_DIR`` variable.
+
+* The :module:`FindGTest` module now provides a target for GMock, if found.
+
+* The :module:`FindVulkan` module now provides a ``Vulkan_VERSION`` result
+  variable reporting the version number.
+
+CTest
+-----
+
+* :manual:`ctest(1)` gained a new :variable:`CTEST_SUBMIT_INACTIVITY_TIMEOUT`
+  variable, which can be used to specify a timeout for submission inactivity.
+
+CPack
+-----
+
+* The :cpack_gen:`CPack productbuild Generator` gained the new
+  :variable:`CPACK_PRODUCTBUILD_DOMAINS`,
+  :variable:`CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE`,
+  :variable:`CPACK_PRODUCTBUILD_DOMAINS_USER`, and
+  :variable:`CPACK_PRODUCTBUILD_DOMAINS_ROOT` variables for
+  adding the domains element to the Distribution XML. With these variables,
+  it is now possible to install products to the user's home directory
+  without requiring administrative privileges.
+
+* The :cpack_gen:`CPack productbuild Generator` gained a new variable,
+  :variable:`CPACK_PRODUCTBUILD_IDENTIFIER`, used to customize the unique
+  product identifier associated with the product.
+
+* The :cpack_gen:`CPack IFW Generator` gained the new
+  :variable:`CPACK_IFW_ARCHIVE_FORMAT` and
+  :variable:`CPACK_IFW_ARCHIVE_COMPRESSION` variables for setting the
+  format used when packaging new component data archives, and choosing
+  the compression level used.
+  These features are available for QtIFW 4.2 and newer.
+
+* The :cpack_gen:`CPack IFW Generator` gained new
+  :variable:`CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE` variable to
+  prevent the user from passing any consumer command to the installer, like
+  ``install``, ``update``, and ``remove``.
+  This feature is available for QtIFW 4.0 and newer.
+
+* The :cpack_gen:`CPack IFW Generator` gained the new
+  :variable:`CPACK_IFW_PACKAGE_PRODUCT_IMAGES` variable for adding a
+  list of images to be shown on the ``PerformInstallationPage``.
+  This feature is available for QtIFW 4.0 and newer.
+
+* The :cpack_gen:`CPack IFW Generator` gained the new
+  :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM`,
+  :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM_ARGUMENTS`, and
+  :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM_DESCRIPTION` variables for
+  executing a command after the installer is done if the user accepts
+  the action.  This feature is available for QtIFW 4.0 and newer.
+
+* The :cpack_gen:`CPack IFW Generator` gained the new
+  :variable:`CPACK_IFW_PACKAGE_SIGNING_IDENTITY` variable for specifying a
+  code signing identity to be used for signing the generated app bundle.
+  This feature is available on macOS only, and for QtIFW 3.0 and newer.
+
+* The :cpack_gen:`CPack WIX Generator` gained a new variable,
+  :variable:`CPACK_WIX_SKIP_WIX_UI_EXTENSION`, to skip the inclusion
+  of WixUIExtensions.
+
+Deprecated and Removed Features
+===============================
+
+* :manual:`cmake(1)` now warns when multiple source paths are specified,
+  as in ``cmake -S src1 src2``.  This has never been officially documented
+  or supported, but older versions accidentally accepted multiple source
+  paths and used the last path specified.  Update scripts to avoid
+  passing multiple source path arguments.
+
+* The :manual:`cpack(1)` undocumented ``OSXX11`` generator has been removed.
+
+Other Changes
+=============
+
+* The :cpack_gen:`CPack DragNDrop Generator` no longer attaches
+  :variable:`CPACK_RESOURCE_FILE_LICENSE` as the license agreement in
+  the generated ``.dmg`` unless explicitly activated by a
+  :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option.
+  In CMake projects, the :module:`CPack` module enables the option
+  by default for compatibility.
+
+* ``CUDA`` targets may now enable both :prop_tgt:`CUDA_SEPARABLE_COMPILATION`
+  and :prop_tgt:`CUDA_PTX_COMPILATION`.
+
+* ``CUDA`` compiler detection now:
+
+  * issues an error in all cases when it's unable to compute the default
+    architecture(s) if required (see :policy:`CMP0104`),
+
+  * handles ``OFF`` for :variable:`CMAKE_CUDA_ARCHITECTURES` on Clang,
+
+  * supports the theoretical case of multiple default architectures, and
+
+  * tries to detect invalid architectures and issue an error.
+
+* ``CUDA`` with Clang now implements policy :policy:`CMP0105` and
+  the ``$<DEVICE_LINK:...>`` and ``$<HOST_LINK:...>``
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+* The :command:`define_property` command's ``BRIEF_DOCS`` and ``FULL_DOCS``
+  arguments are now optional.
+
+* :manual:`ccmake(1)` may now be enabled on Windows when building
+  CMake from source.  This is experimental, and so is not included
+  in official distributions.

Help/release/index.rst

@@ -13,6 +13,7 @@ Releases
 .. toctree::
    :maxdepth: 1
 
+   3.23 <3.23>
    3.22 <3.22>
    3.21 <3.21>
    3.20 <3.20>