Update upstream source from tag 'upstream/3.24.0'

Update to upstream version '3.24.0'
with Debian dir 9b1611105a9a6601aea795fdc55d653d69ee6017

.clang-tidy

@@ -7,7 +7,6 @@ bugprone-*,\
 -bugprone-misplaced-widening-cast,\
 -bugprone-narrowing-conversions,\
 -bugprone-too-small-loop-variable,\
-google-readability-casting,\
 misc-*,\
 -misc-no-recursion,\
 -misc-non-private-member-variables-in-classes,\
@@ -24,6 +23,7 @@ readability-*,\
 -readability-convert-member-functions-to-static,\
 -readability-function-cognitive-complexity,\
 -readability-function-size,\
+-readability-identifier-length,\
 -readability-identifier-naming,\
 -readability-implicit-bool-conversion,\
 -readability-inconsistent-declaration-parameter-name,\

Auxiliary/bash-completion/cmake

@@ -96,7 +96,15 @@ _cmake()
             _filedir
             return
             ;;
-        --build|--install|--open)
+        --build)
+            # Seed the reply with non-directory arguments that we know are
+            # allowed to follow --build. _filedir will then prepend any valid
+            # directory matches to these.
+            COMPREPLY=( $( compgen -W "--preset --list-presets" -- "$cur" ) )
+            _filedir -d
+            return
+            ;;
+        --install|--open)
             _filedir -d
             return
             ;;
@@ -149,6 +157,34 @@ _cmake()
                 2>/dev/null | grep -v "^cmake version " )' -- "$cur" ) )
             return
             ;;
+        --list-presets)
+            local IFS=$'\n'
+            local quoted
+            printf -v quoted %q "$cur"
+
+            if [[ ! "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then
+                COMPREPLY=( $( compgen -W "configure${IFS}build${IFS}test${IFS}all" -- "$quoted" ) )
+            fi
+            return
+            ;;
+         --preset)
+            local IFS=$'\n'
+            local quoted
+            printf -v quoted %q "$cur"
+
+            local build_or_configure="configure"
+            if [[ "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then
+                build_or_configure="build"
+            fi
+
+            local presets=$( cmake --list-presets="$build_or_configure" 2>/dev/null |
+                grep -o "^  \".*\"" | sed \
+                -e "s/^  //g" \
+                -e "s/\"//g" \
+                -e 's/ /\\\\ /g' )
+            COMPREPLY=( $( compgen -W "$presets" -- "$quoted" ) )
+            return
+            ;;
     esac
 
     $split && return

Auxiliary/bash-completion/ctest

@@ -103,6 +103,17 @@ _ctest()
                 2>/dev/null | grep -v "^ctest version " )' -- "$cur" ) )
             return
             ;;
+         --preset)
+            local IFS=$'\n'
+            local quoted
+            printf -v quoted %q "$cur"
+            COMPREPLY=( $( compgen -W '$( ctest --list-presets 2>/dev/null |
+                grep -o "^  \".*\"" | sed \
+                -e "s/^  //g" \
+                -e "s/\"//g" \
+                -e "s/ /\\\\ /g" )' -- "$quoted" ) )
+            return
+            ;;
     esac
 
     if [[ "$cur" == -* ]]; then

Auxiliary/cmake-mode.el

@@ -53,6 +53,9 @@ set the path with these commands:
 (defconst cmake-regex-comment "#.*")
 (defconst cmake-regex-paren-left "(")
 (defconst cmake-regex-paren-right ")")
+(defconst cmake-regex-closing-parens-line (concat "^[[:space:]]*\\("
+                                                  cmake-regex-paren-right
+                                                  "+\\)[[:space:]]*$"))
 (defconst cmake-regex-argument-quoted
   (rx ?\" (* (or (not (any ?\" ?\\)) (and ?\\ anything))) ?\"))
 (defconst cmake-regex-argument-unquoted
@@ -74,6 +77,8 @@ set the path with these commands:
 (defconst cmake-regex-close
   (rx-to-string `(and bol (* space) (regexp ,cmake-regex-block-close)
                       (* space) (regexp ,cmake-regex-paren-left))))
+(defconst cmake-regex-token-paren-left (concat "^" cmake-regex-paren-left "$"))
+(defconst cmake-regex-token-paren-right (concat "^" cmake-regex-paren-right "$"))
 
 ;------------------------------------------------------------------------------
 
@@ -130,30 +135,47 @@ set the path with these commands:
         (save-excursion
           (beginning-of-line)
           (let ((point-start (point))
+                (closing-parens-only (looking-at cmake-regex-closing-parens-line))
                 (case-fold-search t)  ;; case-insensitive
                 token)
-            ; Search back for the last indented line.
+            ;; Search back for the last indented line.
             (cmake-find-last-indented-line)
-            ; Start with the indentation on this line.
+            ;; Start with the indentation on this line.
             (setq cur-indent (current-indentation))
-            ; Search forward counting tokens that adjust indentation.
+            (if closing-parens-only
-            (while (re-search-forward cmake-regex-token point-start t)
+                (let ((open-parens 0))
-              (setq token (match-string 0))
+                  (while (re-search-forward cmake-regex-token point-start t)
-              (when (or (string-match (concat "^" cmake-regex-paren-left "$") token)
+                    (setq token (match-string 0))
-                        (and (string-match cmake-regex-block-open token)
+                    (cond
-                             (looking-at (concat "[ \t]*" cmake-regex-paren-left))))
+                     ((string-match cmake-regex-token-paren-left token)
-                (setq cur-indent (+ cur-indent cmake-tab-width)))
+                      (setq open-parens (+ open-parens 1)))
-              (when (string-match (concat "^" cmake-regex-paren-right "$") token)
+                     ((string-match cmake-regex-token-paren-right token)
-                (setq cur-indent (- cur-indent cmake-tab-width)))
+                      (setq open-parens (- open-parens 1)))))
-              )
+                  ;; Don't outdent if last indented line has open parens
-            (goto-char point-start)
+                  (unless (> open-parens 0)
-            ;; If next token closes the block, decrease indentation
+                    (setq cur-indent (- cur-indent cmake-tab-width))))
-            (when (looking-at cmake-regex-close)
+              ;; Skip detailed analysis if last indented line is a 'closing
-              (setq cur-indent (- cur-indent cmake-tab-width))
+              ;; parens only line'
+              (unless (looking-at cmake-regex-closing-parens-line)
+                ;; Search forward counting tokens that adjust indentation.
+                (while (re-search-forward cmake-regex-token point-start t)
+                  (setq token (match-string 0))
+                  (when (or (string-match cmake-regex-token-paren-left token)
+                            (and (string-match cmake-regex-block-open token)
+                                 (looking-at (concat "[ \t]*" cmake-regex-paren-left))))
+                    (setq cur-indent (+ cur-indent cmake-tab-width)))
+                  (when (string-match cmake-regex-token-paren-right token)
+                    (setq cur-indent (- cur-indent cmake-tab-width)))
+                  ))
+              (goto-char point-start)
+              ;; If next token closes the block, decrease indentation
+              (when (looking-at cmake-regex-close)
+                (setq cur-indent (- cur-indent cmake-tab-width))
+                )
               )
             )
           )
-        ; Indent this line by the amount selected.
+        ;; Indent this line by the amount selected.
         (cmake-indent-line-to (max cur-indent 0))
         )
       )

Auxiliary/vim/indent/cmake.vim

@@ -3,7 +3,7 @@
 " Author:       Andy Cedilnik <andy.cedilnik@kitware.com>
 " Maintainer:   Dimitri Merejkowsky <d.merej@gmail.com>
 " Former Maintainer: Karthik Krishnan <karthik.krishnan@kitware.com>
-" Last Change:  2017 Aug 30
+" Last Change:  2022 Mar 22
 "
 " License:      The CMake license applies to this file. See
 "               https://cmake.org/licensing
@@ -14,9 +14,6 @@ if exists("b:did_indent")
 endif
 let b:did_indent = 1
 
-let s:keepcpo= &cpo
-set cpo&vim
-
 setlocal indentexpr=CMakeGetIndent(v:lnum)
 setlocal indentkeys+==ENDIF(,ENDFOREACH(,ENDMACRO(,ELSE(,ELSEIF(,ENDWHILE(
 
@@ -24,6 +21,8 @@ setlocal indentkeys+==ENDIF(,ENDFOREACH(,ENDMACRO(,ELSE(,ELSEIF(,ENDWHILE(
 if exists("*CMakeGetIndent")
   finish
 endif
+let s:keepcpo= &cpo
+set cpo&vim
 
 fun! CMakeGetIndent(lnum)
   let this_line = getline(a:lnum)
@@ -54,32 +53,41 @@ fun! CMakeGetIndent(lnum)
   let cmake_indent_open_regex = '^\s*' . cmake_regex_identifier .
                     \           '\s*(' . cmake_regex_arguments .
                     \           '\(' . cmake_regex_comment . '\)\?$'
-
   let cmake_indent_close_regex = '^' . cmake_regex_arguments .
                     \            ')\s*' .
                     \            '\(' . cmake_regex_comment . '\)\?$'
 
+  let cmake_closing_parens_line = '^\s*\()\+\)\s*$'
+
   let cmake_indent_begin_regex = '^\s*\(IF\|MACRO\|FOREACH\|ELSE\|ELSEIF\|WHILE\|FUNCTION\)\s*('
   let cmake_indent_end_regex = '^\s*\(ENDIF\|ENDFOREACH\|ENDMACRO\|ELSE\|ELSEIF\|ENDWHILE\|ENDFUNCTION\)\s*('
 
-  " Add
+  if this_line =~? cmake_closing_parens_line
-  if previous_line =~? cmake_indent_comment_line " Handle comments
+    if previous_line !~? cmake_indent_open_regex
-    let ind = ind
+      let ind = ind - shiftwidth()
+    endif
   else
-    if previous_line =~? cmake_indent_begin_regex
+    " Add
-      let ind = ind + shiftwidth()
+    if previous_line =~? cmake_indent_comment_line " Handle comments
+      let ind = ind
+    else
+      if previous_line =~? cmake_indent_begin_regex
+        let ind = ind + shiftwidth()
+      endif
+      if previous_line =~? cmake_indent_open_regex
+        let ind = ind + shiftwidth()
+      endif
     endif
-    if previous_line =~? cmake_indent_open_regex
-      let ind = ind + shiftwidth()
-    endif
-  endif
 
-  " Subtract
+    " Subtract
-  if this_line =~? cmake_indent_end_regex
+    if this_line =~? cmake_indent_end_regex
-    let ind = ind - shiftwidth()
+      let ind = ind - shiftwidth()
-  endif
+    endif
-  if previous_line =~? cmake_indent_close_regex
+    if previous_line !~? cmake_closing_parens_line
-    let ind = ind - shiftwidth()
+      if previous_line =~? cmake_indent_close_regex
+        let ind = ind - shiftwidth()
+      endif
+    endif
   endif
 
   return ind

Auxiliary/vim/syntax/cmake.vim

@@ -370,6 +370,7 @@ syn keyword cmakeProperty contained
             \ VS_DOTNET_DOCUMENTATION_FILE
             \ VS_DOTNET_REFERENCES
             \ VS_DOTNET_REFERENCES_COPY_LOCAL
+            \ VS_DOTNET_STARTUP_OBJECT
             \ VS_DOTNET_TARGET_FRAMEWORK_VERSION
             \ VS_DPI_AWARE
             \ VS_GLOBAL_KEYWORD
@@ -381,6 +382,7 @@ syn keyword cmakeProperty contained
             \ VS_JUST_MY_CODE_DEBUGGING
             \ VS_KEYWORD
             \ VS_MOBILE_EXTENSIONS_VERSION
+            \ VS_NO_COMPILE_BATCHING
             \ VS_NO_SOLUTION_DEPLOY
             \ VS_PACKAGE_REFERENCES
             \ VS_PLATFORM_TOOLSET
@@ -704,6 +706,7 @@ syn keyword cmakeVariable contained
             \ CMAKE_CODEBLOCKS_COMPILER_ID
             \ CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES
             \ CMAKE_CODELITE_USE_TARGETS
+            \ CMAKE_COLOR_DIAGNOSTICS
             \ CMAKE_COLOR_MAKEFILE
             \ CMAKE_COMMAND
             \ CMAKE_COMPILER_2005
@@ -1044,6 +1047,7 @@ syn keyword cmakeVariable contained
             \ CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
             \ CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
             \ CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
+            \ CMAKE_FIND_USE_INSTALL_PREFIX
             \ CMAKE_FIND_USE_CMAKE_PATH
             \ CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
             \ CMAKE_FIND_USE_PACKAGE_REGISTRY
@@ -1572,6 +1576,7 @@ syn keyword cmakeVariable contained
             \ CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS
             \ CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS
             \ CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE
+            \ CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION
             \ CTEST_CUSTOM_MEMCHECK_IGNORE
             \ CTEST_CUSTOM_POST_MEMCHECK
             \ CTEST_CUSTOM_POST_TEST
@@ -3776,6 +3781,7 @@ syn keyword cmakeGeneratorExpressions contained
             \ STREQUAL
             \ TARGET_BUNDLE_CONTENT_DIR
             \ TARGET_BUNDLE_DIR
+            \ TARGET_BUNDLE_DIR_NAME
             \ TARGET_EXISTS
             \ TARGET_FILE
             \ TARGET_FILE_BASE_NAME

CMakeCPack.cmake

@@ -22,6 +22,7 @@ set(CPACK_PACKAGE_NAME "${CMAKE_PROJECT_NAME}")
 set(CPACK_PACKAGE_VERSION "${CMake_VERSION}")
 set(CPACK_PACKAGE_INSTALL_DIRECTORY "${CPACK_PACKAGE_NAME}")
 set(CPACK_SOURCE_PACKAGE_FILE_NAME "cmake-${CMake_VERSION}")
+set(CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE OFF)
 
 # Installers for 32- vs. 64-bit CMake:
 #  - Root install directory (displayed to end user at installer-run time)

CMakeCPackOptions.cmake.in

@@ -198,14 +198,6 @@ if(CPACK_GENERATOR MATCHES "IFW")
 
 endif()
 
-if("${CPACK_GENERATOR}" STREQUAL "PackageMaker")
-  if(CMAKE_PACKAGE_QTGUI)
-    set(CPACK_PACKAGE_DEFAULT_LOCATION "/Applications")
-  else()
-    set(CPACK_PACKAGE_DEFAULT_LOCATION "/usr")
-  endif()
-endif()
-
 if("${CPACK_GENERATOR}" STREQUAL "DragNDrop")
   set(CPACK_DMG_BACKGROUND_IMAGE
       "@CMake_SOURCE_DIR@/Packaging/CMakeDMGBackground.tif")
@@ -256,6 +248,13 @@ if("${CPACK_GENERATOR}" STREQUAL "WIX")
 
   set(CPACK_WIX_LIGHT_EXTRA_FLAGS "-dcl:high")
 
+  if(NOT "$ENV{CMAKE_CI_PACKAGE}" STREQUAL "")
+    # Suppress validation.  It does not work without
+    # an interactive session or an admin account.
+    # https://github.com/wixtoolset/issues/issues/3968
+    list(APPEND CPACK_WIX_LIGHT_EXTRA_FLAGS "-sval")
+  endif()
+
   set(CPACK_WIX_UI_BANNER
     "@CMake_SOURCE_DIR@/Utilities/Release/WiX/ui_banner.jpg"
   )

CMakeLists.txt

@@ -1,7 +1,7 @@
 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
 # file Copyright.txt or https://cmake.org/licensing for details.
 
-cmake_minimum_required(VERSION 3.1...3.21 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.13...3.22 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)
 
@@ -606,25 +606,40 @@ macro (CMAKE_BUILD_UTILITIES)
     set(ZLIB_INCLUDE_DIR ${CMAKE_ZLIB_INCLUDES})
     set(ZLIB_LIBRARY ${CMAKE_ZLIB_LIBRARIES})
     add_definitions(-DLIBARCHIVE_STATIC)
-    set(ENABLE_MBEDTLS OFF CACHE INTERNAL "Enable use of mbed TLS")
+    set(ENABLE_MBEDTLS OFF)
-    set(ENABLE_NETTLE OFF CACHE INTERNAL "Enable use of Nettle")
+    set(ENABLE_NETTLE OFF)
-    set(ENABLE_OPENSSL ${CMAKE_USE_OPENSSL} CACHE INTERNAL "Enable use of OpenSSL")
+    if(DEFINED CMAKE_USE_OPENSSL)
-    set(ENABLE_LIBB2 OFF CACHE INTERNAL "Enable the use of the system LIBB2 library if found")
+      set(ENABLE_OPENSSL "${CMAKE_USE_OPENSSL}")
-    set(ENABLE_LZMA ON CACHE INTERNAL "Enable the use of the system LZMA library if found")
+    else()
-    set(ENABLE_LZ4 OFF CACHE INTERNAL "Enable the use of the system LZ4 library if found")
+      set(ENABLE_OPENSSL OFF)
-    set(ENABLE_LZO OFF CACHE INTERNAL "Enable the use of the system LZO library if found")
+    endif()
-    set(ENABLE_ZLIB ON CACHE INTERNAL "Enable the use of the system ZLIB library if found")
+    set(ENABLE_LIBB2 OFF)
-    set(ENABLE_BZip2 ON CACHE INTERNAL "Enable the use of the system BZip2 library if found")
+    set(ENABLE_LZ4 OFF)
-    set(ENABLE_ZSTD ON CACHE INTERNAL "Enable the use of the system zstd library if found")
+    set(ENABLE_LZO OFF)
-    set(ENABLE_LIBXML2 OFF CACHE INTERNAL "Enable the use of the system libxml2 library if found")
+    set(ENABLE_LZMA ON)
-    set(ENABLE_EXPAT OFF CACHE INTERNAL "Enable the use of the system EXPAT library if found")
+    set(ENABLE_ZSTD ON)
-    set(ENABLE_PCREPOSIX OFF CACHE INTERNAL "Enable the use of the system PCREPOSIX library if found")
+    set(ENABLE_ZLIB ON)
-    set(ENABLE_LibGCC OFF CACHE INTERNAL "Enable the use of the system LibGCC library if found")
+    set(ENABLE_BZip2 ON)
-    set(ENABLE_XATTR OFF CACHE INTERNAL "Enable extended attribute support")
+    set(ENABLE_LIBXML2 OFF)
-    set(ENABLE_ACL OFF CACHE INTERNAL "Enable ACL support")
+    set(ENABLE_EXPAT OFF)
-    set(ENABLE_ICONV OFF CACHE INTERNAL "Enable iconv support")
+    set(ENABLE_PCREPOSIX OFF)
-    set(ENABLE_CNG OFF CACHE INTERNAL "Enable the use of CNG(Crypto Next Generation)")
+    set(ENABLE_LibGCC OFF)
-    SET(POSIX_REGEX_LIB "" CACHE INTERNAL "Choose what library should provide POSIX regular expression support")
+    set(ENABLE_CNG OFF)
+    set(ENABLE_TAR OFF)
+    set(ENABLE_TAR_SHARED OFF)
+    set(ENABLE_CPIO OFF)
+    set(ENABLE_CPIO_SHARED OFF)
+    set(ENABLE_CAT OFF)
+    set(ENABLE_CAT_SHARED OFF)
+    set(ENABLE_XATTR OFF)
+    set(ENABLE_ACL OFF)
+    set(ENABLE_ICONV OFF)
+    set(ENABLE_TEST OFF)
+    set(ENABLE_COVERAGE OFF)
+    set(ENABLE_INSTALL OFF)
+    set(POSIX_REGEX_LIB "" CACHE INTERNAL "libarchive: No POSIX regular expression support")
+    set(ENABLE_SAFESEH "" CACHE INTERNAL "libarchive: No /SAFESEH linker flag")
+    set(WINDOWS_VERSION "WIN7" CACHE INTERNAL "libarchive: Set Windows version to use (Windows only)")
     add_subdirectory(Utilities/cmlibarchive)
     CMAKE_SET_TARGET_FOLDER(cmlibarchive "Utilities/3rdParty")
     set(CMAKE_TAR_LIBRARIES cmlibarchive ${BZIP2_LIBRARIES})

CTestCustom.cmake.in

@@ -98,6 +98,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Value stored to '[^']+' is never read"
   "zstd/lib/.*:[0-9]+:[0-9]+: warning: Assigned value is garbage or undefined"
   "zstd/lib/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
+  "zstd/lib/.*:[0-9]+:[0-9]+: warning: The right operand of .* is a garbage value due to array index out of bounds"
   )
 
 if(NOT "@CMAKE_GENERATOR@" MATCHES "Xcode")

Copyright.txt

@@ -78,6 +78,7 @@ The following individuals and institutions are among the Contributors:
 * Michael Hirsch, Ph.D. <www.scivision.co>
 * Michael Stürmer
 * Miguel A. Figueroa-Villanueva
+* Mike Durso <rbprogrammer@gmail.com>
 * Mike Jackson
 * Mike McQuaid <mike@mikemcquaid.com>
 * Nicolas Bock <nicolasbock@gmail.com>

Help/command/FIND_XXX.txt

@@ -13,6 +13,7 @@ The general signature is:
              name | |NAMES|
              [HINTS [path | ENV var]... ]
              [PATHS [path | ENV var]... ]
+             [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
              [PATH_SUFFIXES suffix1 [suffix2 ...]]
              [DOC "cache documentation string"]
              [NO_CACHE]
@@ -23,6 +24,7 @@ The general signature is:
              [NO_CMAKE_ENVIRONMENT_PATH]
              [NO_SYSTEM_ENVIRONMENT_PATH]
              [NO_CMAKE_SYSTEM_PATH]
+             [NO_CMAKE_INSTALL_PREFIX]
              [CMAKE_FIND_ROOT_PATH_BOTH |
               ONLY_CMAKE_FIND_ROOT_PATH |
               NO_CMAKE_FIND_ROOT_PATH]
@@ -50,6 +52,16 @@ Options include:
   The ``ENV var`` sub-option reads paths from a system environment
   variable.
 
+  .. versionchanged:: 3.24
+    On ``Windows`` platform, it is possible to include registry queries as part
+    of the directories, using a :ref:`dedicated syntax <Find Using Windows Registry>`.
+    Such specifications will be ignored on all other platforms.
+
+``REGISTRY_VIEW``
+  .. versionadded:: 3.24
+
+  .. include:: FIND_XXX_REGISTRY_VIEW.txt
+
 ``PATH_SUFFIXES``
   Specify additional subdirectories to check below each directory
   location otherwise considered.
@@ -154,9 +166,11 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
    * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX|
 
 6. Search cmake variables defined in the Platform files
-   for the current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH``
+   for the current system.  The searching of ``CMAKE_INSTALL_PREFIX`` can be
-   is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`
+   skipped if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the
-   to ``FALSE``.
+   :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE``. All these locations
+   can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the
+   :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` to ``FALSE``.
 
    * |CMAKE_SYSTEM_PREFIX_PATH_XXX|
    * |CMAKE_SYSTEM_XXX_PATH|

Help/command/FIND_XXX_REGISTRY_VIEW.txt

@@ -0,0 +1,41 @@
+Specify which registry views must be queried. This option is only meaningful
+on ``Windows`` platform and will be ignored on other ones. When not
+specified, |FIND_XXX_REGISTRY_VIEW_DEFAULT| view is used when :policy:`CMP0134`
+policy is ``NEW``. Refer to :policy:`CMP0134` policy for default view when
+policy is ``OLD`` or undefined.
+
+``64``
+  Query the 64bit registry. On ``32bit Windows``, returns always the string
+  ``/REGISTRY-NOTFOUND``.
+
+``32``
+  Query the 32bit registry.
+
+``64_32``
+  Query both views (``64`` and ``32``) and generate a path for each.
+
+``32_64``
+  Query both views (``32`` and ``64``) and generate a path for each.
+
+``HOST``
+  Query the registry matching the architecture of the host: ``64`` on ``64bit
+  Windows`` and ``32`` on ``32bit Windows``.
+
+``TARGET``
+  Query the registry matching the architecture specified by
+  :variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fallback to
+  ``HOST`` view.
+
+``BOTH``
+  Query both views (``32`` and ``64``). The order depends of the following
+  rules: If :variable:`CMAKE_SIZEOF_VOID_P` variable is defined. Use the
+  following view depending of the content of this variable:
+
+  * ``8``: ``64_32``
+  * ``4``: ``32_64``
+
+  If :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on
+  architecture of the host:
+
+  * ``64bit``: ``64_32``
+  * ``32bit``: ``32``

Help/command/add_custom_command.rst

@@ -288,12 +288,12 @@ The options are:
 
   .. productionlist:: depfile
     depfile: `rule`*
-    rule: `targets` (`:` (`separator` `dependencies`?)?)? `eol`
+    rule: `targets` (':' (`separator` `dependencies`?)?)? `eol`
     targets: `target` (`separator` `target`)* `separator`*
     target: `pathname`
     dependencies: `dependency` (`separator` `dependency`)* `separator`*
     dependency: `pathname`
-    separator: (space | line_continue)+
+    separator: (`space` | `line_continue`)+
     line_continue: '\' `eol`
     space: ' ' | '\t'
     pathname: `character`+
@@ -425,6 +425,11 @@ of the following is specified:
 ``POST_BUILD``
   Run after all other rules within the target have been executed.
 
+Projects should always specify one of the above three keywords when using
+the ``TARGET`` form.  For backward compatibility reasons, ``POST_BUILD`` is
+assumed if no such keyword is given, but projects should explicitly provide
+one of the keywords to make clear the behavior they expect.
+
 .. note::
   Because generator expressions can be used in custom commands,
   it is possible to define ``COMMAND`` lines or whole custom commands

Help/command/cmake_host_system_information.rst

@@ -1,9 +1,23 @@
 cmake_host_system_information
 -----------------------------
 
-Query host system specific information.
+Query various host system information.
 
-.. code-block:: cmake
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+  `Query host system specific information`_
+    cmake_host_system_information(RESULT <variable> QUERY <key> ...)
+
+  `Query Windows registry`_
+    cmake_host_system_information(RESULT <variable> QUERY WINDOWS_REGISTRY <key> ...)
+
+Query host system specific information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
 
   cmake_host_system_information(RESULT <variable> QUERY <key> ...)
 
@@ -180,7 +194,7 @@ distribution-specific files`_ to collect OS identification data and map it
 into `man 5 os-release`_ variables.
 
 Fallback Interface Variables
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""""
 
 .. variable:: CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS
 
@@ -246,3 +260,137 @@ Example:
 
 .. _man 5 os-release: https://www.freedesktop.org/software/systemd/man/os-release.html
 .. _various distribution-specific files: http://linuxmafia.com/faq/Admin/release-files.html
+
+.. _Query Windows registry:
+
+Query Windows registry
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.24
+
+::
+
+  cmake_host_system_information(RESULT <variable>
+                                QUERY WINDOWS_REGISTRY <key> [VALUE_NAMES|SUBKEYS|VALUE <name>]
+                                [VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
+                                [SEPARATOR <separator>]
+                                [ERROR_VARIABLE <result>])
+
+Performs query operations on local computer registry subkey. Returns a list of
+subkeys or value names that are located under the specified subkey in the
+registry or the data of the specified value name. The result of the queried
+entity is stored in ``<variable>``.
+
+.. note::
+
+  Querying registry for any other platforms than ``Windows``, including
+  ``CYGWIN``, will always returns an empty string and sets an error message in
+  the variable specified with sub-option ``ERROR_VARIABLE``.
+
+``<key>`` specify the full path of a subkey on the local computer. The
+``<key>`` must include a valid root key. Valid root keys for the local computer
+are:
+
+* ``HKLM`` or ``HKEY_LOCAL_MACHINE``
+* ``HKCU`` or ``HKEY_CURRENT_USER``
+* ``HKCR`` or ``HKEY_CLASSES_ROOT``
+* ``HKU`` or ``HKEY_USERS``
+* ``HKCC`` or ``HKEY_CURRENT_CONFIG``
+
+And, optionally, the path to a subkey under the specified root key. The path
+separator can be the slash or the backslash. ``<key>`` is not case sensitive.
+For example:
+
+.. code-block:: cmake
+
+  cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM")
+  cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")
+  cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKCU\\SOFTWARE\\Kitware")
+
+``VALUE_NAMES``
+  Request the list of value names defined under ``<key>``. If a default value
+  is defined, it will be identified with the special name ``(default)``.
+
+``SUBKEYS``
+  Request the list of subkeys defined under ``<key>``.
+
+``VALUE <name>``
+  Request the data stored in value named ``<name>``. If ``VALUE`` is not
+  specified or argument is the special name ``(default)``, the content of the
+  default value, if any, will be returned.
+
+  .. code-block:: cmake
+
+     # query default value for HKLM/SOFTWARE/Kitware key
+     cmake_host_system_information(RESULT result
+                                   QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")
+
+     # query default value for HKLM/SOFTWARE/Kitware key using special value name
+     cmake_host_system_information(RESULT result
+                                   QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware"
+                                   VALUE "(default)")
+
+  Supported types are:
+
+  * ``REG_SZ``.
+  * ``REG_EXPAND_SZ``. The returned data is expanded.
+  * ``REG_MULTI_SZ``. The returned is expressed as a CMake list. See also
+    ``SEPARATOR`` sub-option.
+  * ``REG_DWORD``.
+  * ``REG_QWORD``.
+
+  For all other types, an empty string is returned.
+
+``VIEW``
+  Specify which registry views must be queried. When not specified, ``BOTH``
+  view is used.
+
+  ``64``
+    Query the 64bit registry. On ``32bit Windows``, returns always an empty
+    string.
+
+  ``32``
+    Query the 32bit registry.
+
+  ``64_32``
+    For ``VALUE`` sub-option or default value, query the registry using view
+    ``64``, and if the request failed, query the registry using view ``32``.
+    For ``VALUE_NAMES`` and ``SUBKEYS`` sub-options, query both views (``64``
+    and ``32``) and merge the results (sorted and duplicates removed).
+
+  ``32_64``
+    For ``VALUE`` sub-option or default value, query the registry using view
+    ``32``, and if the request failed, query the registry using view ``64``.
+    For ``VALUE_NAMES`` and ``SUBKEYS`` sub-options, query both views (``32``
+    and ``64``) and merge the results (sorted and duplicates removed).
+
+  ``HOST``
+    Query the registry matching the architecture of the host: ``64`` on ``64bit
+    Windows`` and ``32`` on ``32bit Windows``.
+
+  ``TARGET``
+    Query the registry matching the architecture specified by
+    :variable:`CMAKE_SIZEOF_VOID_P` variable. If not defined, fallback to
+    ``HOST`` view.
+
+  ``BOTH``
+    Query both views (``32`` and ``64``). The order depends of the following
+    rules: If :variable:`CMAKE_SIZEOF_VOID_P` variable is defined. Use the
+    following view depending of the content of this variable:
+
+    * ``8``: ``64_32``
+    * ``4``: ``32_64``
+
+    If :variable:`CMAKE_SIZEOF_VOID_P` variable is not defined, rely on
+    architecture of the host:
+
+    * ``64bit``: ``64_32``
+    * ``32bit``: ``32``
+
+``SEPARATOR``
+  Specify the separator character for ``REG_MULTI_SZ`` type. When not
+  specified, the character ``\0`` is used.
+
+``ERROR_VARIABLE <result>``
+  Returns any error raised during query operation. In case of success, the
+  variable holds an empty string.

Help/command/cmake_language.rst

@@ -13,6 +13,7 @@ Synopsis
   cmake_language(`CALL`_ <command> [<arg>...])
   cmake_language(`EVAL`_ CODE <code>...)
   cmake_language(`DEFER`_ <options>... CALL <command> [<arg>...])
+  cmake_language(`SET_DEPENDENCY_PROVIDER`_ <command> SUPPORTED_METHODS <methods>...)
 
 Introduction
 ^^^^^^^^^^^^
@@ -225,3 +226,268 @@ also prints::
   Immediate Message
   Deferred Message 1
   Deferred Message 2
+
+
+.. _SET_DEPENDENCY_PROVIDER:
+.. _dependency_providers:
+
+Dependency Providers
+^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 3.24
+
+.. note:: A high-level introduction to this feature can be found in the
+          :ref:`Using Dependencies Guide <dependency_providers_overview>`.
+
+.. code-block:: cmake
+
+  cmake_language(SET_DEPENDENCY_PROVIDER <command>
+                 SUPPORTED_METHODS <methods>...)
+
+When a call is made to :command:`find_package` or
+:command:`FetchContent_MakeAvailable`, the call may be forwarded to a
+dependency provider which then has the opportunity to fulfill the request.
+If the request is for one of the ``<methods>`` specified when the provider
+was set, CMake calls the provider's ``<command>`` with a set of
+method-specific arguments.  If the provider does not fulfill the request,
+or if the provider doesn't support the request's method, or no provider
+is set, the built-in :command:`find_package` or
+:command:`FetchContent_MakeAvailable` implementation is used to fulfill
+the request in the usual way.
+
+One or more of the following values can be specified for the ``<methods>``
+when setting the provider:
+
+``FIND_PACKAGE``
+  The provider command accepts :command:`find_package` requests.
+
+``FETCHCONTENT_MAKEAVAILABLE_SERIAL``
+  The provider command accepts :command:`FetchContent_MakeAvailable`
+  requests.  It expects each dependency to be fed to the provider command
+  one at a time, not the whole list in one go.
+
+Only one provider can be set at any point in time.  If a provider is already
+set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new
+provider replaces the previously set one.  The specified ``<command>`` must
+already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called.
+As a special case, providing an empty string for the ``<command>`` and no
+``<methods>`` will discard any previously set provider.
+
+The dependency provider can only be set while processing one of the files
+specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable.
+Thus, dependency providers can only be set as part of the first call to
+:command:`project`.  Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)``
+outside of that context will result in an error.
+
+.. note::
+  The choice of dependency provider should always be under the user's control.
+  As a convenience, a project may choose to provide a file that users can
+  list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but
+  the use of such a file should always be the user's choice.
+
+Provider commands
+"""""""""""""""""
+
+Providers define a single ``<command>`` to accept requests.  The name of
+the command should be specific to that provider, not something overly
+generic that another provider might also use.  This enables users to compose
+different providers in their own custom provider.  The recommended form is
+``xxx_provide_dependency()``, where ``xxx`` is the provider-specific part
+(e.g. ``vcpkg_provide_dependency()``, ``conan_provide_dependency()``,
+``ourcompany_provide_dependency()``, and so on).
+
+.. code-block:: cmake
+
+  xxx_provide_dependency(<method> [<method-specific-args>...])
+
+Because some methods expect certain variables to be set in the calling scope,
+the provider command should typically be implemented as a macro rather than a
+function.  This ensures it does not introduce a new variable scope.
+
+The arguments CMake passes to the dependency provider depend on the type of
+request.  The first argument is always the method, and it will only ever
+be one of the ``<methods>`` that was specified when setting the provider.
+
+``FIND_PACKAGE``
+  The ``<method-specific-args>`` will be everything passed to the
+  :command:`find_package` call that requested the dependency.  The first of
+  these ``<method-specific-args>`` will therefore always be the name of the
+  dependency.  Dependency names are case-sensitive for this method because
+  :command:`find_package` treats them case-sensitively too.
+
+  If the provider command fulfills the request, it must set the same variable
+  that :command:`find_package` expects to be set.  For a dependency named
+  ``depName``, the provider must set ``depName_FOUND`` to true if it fulfilled
+  the request.  If the provider returns without setting this variable, CMake
+  will assume the request was not fulfilled and will fall back to the
+  built-in implementation.
+
+  If the provider needs to call the built-in :command:`find_package`
+  implementation as part of its processing, it can do so by including the
+  ``BYPASS_PROVIDER`` keyword as one of the arguments.
+
+``FETCHCONTENT_MAKEAVAILABE_SERIAL``
+  The ``<method-specific-args>`` will be everything passed to the
+  :command:`FetchContent_Declare` call that corresponds to the requested
+  dependency, with the following exceptions:
+
+  * If ``SOURCE_DIR`` or ``BINARY_DIR`` were not part of the original
+    declared arguments, they will be added with their default values.
+  * If :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` is set to ``NEVER``,
+    any ``FIND_PACKAGE_ARGS`` will be omitted.
+  * The ``OVERRIDE_FIND_PACKAGE`` keyword is always omitted.
+
+  The first of the ``<method-specific-args>`` will always be the name of the
+  dependency.  Dependency names are case-insensitive for this method because
+  :module:`FetchContent` also treats them case-insensitively.
+
+  If the provider fulfills the request, it should call
+  :command:`FetchContent_SetPopulated`, passing the name of the dependency as
+  the first argument.  The ``SOURCE_DIR`` and ``BINARY_DIR`` arguments to that
+  command should only be given if the provider makes the dependency's source
+  and build directories available in exactly the same way as the built-in
+  :command:`FetchContent_MakeAvailable` command.
+
+  If the provider returns without calling :command:`FetchContent_SetPopulated`
+  for the named dependency, CMake will assume the request was not fulfilled
+  and will fall back to the built-in implementation.
+
+  Note that empty arguments may be significant for this method (e.g. an empty
+  string following a ``GIT_SUBMODULES`` keyword).  Therefore, if forwarding
+  these arguments on to another command, extra care must be taken to avoid such
+  arguments being silently dropped.
+
+  If ``FETCHCONTENT_SOURCE_DIR_<uppercaseDepName>`` is set, then the
+  dependency provider will never see requests for the ``<depName>`` dependency
+  for this method. When the user sets such a variable, they are explicitly
+  overriding where to get that dependency from and are taking on the
+  responsibility that their overriding version meets any requirements for that
+  dependency and is compatible with whatever else in the project uses it.
+  Depending on the value of :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE`
+  and whether the ``OVERRIDE_FIND_PACKAGE`` option was given to
+  :command:`FetchContent_Declare`, having
+  ``FETCHCONTENT_SOURCE_DIR_<uppercaseDepName>`` set may also prevent the
+  dependency provider from seeing requests for a ``find_package(depName)``
+  call too.
+
+Provider Examples
+"""""""""""""""""
+
+This first example only intercepts :command:`find_package` calls.  The
+provider command runs an external tool which copies the relevant artifacts
+into a provider-specific directory, if that tool knows about the dependency.
+It then relies on the built-in implementation to then find those artifacts.
+:command:`FetchContent_MakeAvailable` calls would not go through the provider.
+
+.. code-block:: cmake
+  :caption: mycomp_provider.cmake
+
+  # Always ensure we have the policy settings this provider expects
+  cmake_minimum_required(VERSION 3.24)
+
+  set(MYCOMP_PROVIDER_INSTALL_DIR ${CMAKE_BINARY_DIR}/mycomp_packages
+    CACHE PATH "The directory this provider installs packages to"
+  )
+  # Tell the built-in implementation to look in our area first, unless
+  # the find_package() call uses NO_..._PATH options to exclude it
+  list(APPEND CMAKE_MODULE_PATH ${MYCOMP_PROVIDER_INSTALL_DIR}/cmake)
+  list(APPEND CMAKE_PREFIX_PATH ${MYCOMP_PROVIDER_INSTALL_DIR})
+
+  macro(mycomp_provide_dependency method package_name)
+    execute_process(
+      COMMAND some_tool ${package_name} --installdir ${MYCOMP_PROVIDER_INSTALL_DIR}
+      COMMAND_ERROR_IS_FATAL ANY
+    )
+  endmacro()
+
+  cmake_language(
+    SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
+    SUPPORTED_METHODS FIND_PACKAGE
+  )
+
+The user would then typically use the above file like so::
+
+  cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/mycomp_provider.cmake ...
+
+The next example demonstrates a provider that accepts both methods, but
+only handles one specific dependency.  It enforces providing Google Test
+using :module:`FetchContent`, but leaves all other dependencies to be
+fulfilled by CMake's built-in implementation.  It accepts a few different
+names, which demonstrates one way of working around projects that hard-code
+an unusual or undesirable way of adding this particular dependency to the
+build.  The example also demonstrates how to use the :command:`list` command
+to preserve variables that may be overwritten by a call to
+:command:`FetchContent_MakeAvailable`.
+
+.. code-block:: cmake
+  :caption: mycomp_provider.cmake
+
+  cmake_minimum_required(VERSION 3.24)
+
+  # Because we declare this very early, it will take precedence over any
+  # details the project might declare later for the same thing
+  include(FetchContent)
+  FetchContent_Declare(
+    googletest
+    GIT_REPOSITORY https://github.com/google/googletest.git
+    GIT_TAG        e2239ee6043f73722e7aa812a459f54a28552929 # release-1.11.0
+  )
+
+  # Both FIND_PACKAGE and FETCHCONTENT_MAKEAVAILABLE_SERIAL methods provide
+  # the package or dependency name as the first method-specific argument.
+  macro(mycomp_provide_dependency method dep_name)
+    if("${dep_name}" MATCHES "^(gtest|googletest)$")
+      # Save our current command arguments in case we are called recursively
+      list(APPEND mycomp_provider_args ${method} ${dep_name})
+
+      # This will forward to the built-in FetchContent implementation,
+      # which detects a recursive call for the same thing and avoids calling
+      # the provider again if dep_name is the same as the current call.
+      FetchContent_MakeAvailable(googletest)
+
+      # Restore our command arguments
+      list(POP_BACK mycomp_provider_args dep_name method)
+
+      # Tell the caller we fulfilled the request
+      if("${method}" STREQUAL "FIND_PACKAGE")
+        # We need to set this if we got here from a find_package() call
+        # since we used a different method to fulfill the request.
+        # This example assumes projects only use the gtest targets,
+        # not any of the variables the FindGTest module may define.
+        set(${dep_name}_FOUND TRUE)
+      elseif(NOT "${dep_name}" STREQUAL "googletest")
+        # We used the same method, but were given a different name to the
+        # one we populated with. Tell the caller about the name it used.
+        FetchContent_SetPopulated(${dep_name}
+          SOURCE_DIR "${googletest_SOURCE_DIR}"
+          BINARY_DIR "${googletest_BINARY_DIR}"
+        )
+      endif()
+    endif()
+  endmacro()
+
+  cmake_language(
+    SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
+    SUPPORTED_METHODS
+      FIND_PACKAGE
+      FETCHCONTENT_MAKEAVAILABLE_SERIAL
+  )
+
+The final example demonstrates how to modify arguments to a
+:command:`find_package` call.  It forces all such calls to have the
+``QUIET`` keyword.  It uses the ``BYPASS_PROVIDER`` keyword to prevent
+calling the provider command recursively for the same dependency.
+
+.. code-block:: cmake
+  :caption: mycomp_provider.cmake
+
+  cmake_minimum_required(VERSION 3.24)
+
+  macro(mycomp_provide_dependency method)
+    find_package(${ARGN} BYPASS_PROVIDER QUIET)
+  endmacro()
+
+  cmake_language(
+    SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
+    SUPPORTED_METHODS FIND_PACKAGE
+  )

Help/command/cmake_path.rst

@@ -96,6 +96,8 @@ The following conventions are used in this command's documentation:
   The name of a variable into which the result of a command will be written.
 
 
+.. _Path Structure And Terminology:
+
 Path Structure And Terminology
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -216,6 +218,8 @@ normalize a path is as follows:
    is ``.``).
 
 
+.. _Path Decomposition:
+
 Decomposition
 ^^^^^^^^^^^^^
 
@@ -385,6 +389,8 @@ Path traversal examples
   Parent path is "c:/"
 
 
+.. _Path Query:
+
 Query
 ^^^^^
 
@@ -467,6 +473,7 @@ are :ref:`normalized <Normalization>` before the check.
   set(path "/a/b")
   cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result)   # result = true
 
+.. _Path COMPARE:
 .. _COMPARE:
 
 ::
@@ -475,8 +482,9 @@ are :ref:`normalized <Normalization>` before the check.
   cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)
 
 Compares the lexical representations of two paths provided as string literals.
-No normalization is performed on either path.  Equality is determined
+No normalization is performed on either path, except multiple consecutive
-according to the following pseudo-code logic:
+directory separators are effectively collapsed into a single separator.
+Equality is determined according to the following pseudo-code logic:
 
 ::
 
@@ -495,6 +503,8 @@ according to the following pseudo-code logic:
   takes literal strings as input, not the names of variables.
 
 
+.. _Path Modification:
+
 Modification
 ^^^^^^^^^^^^
 
@@ -509,7 +519,7 @@ path, it is converted into a cmake-style path with forward-slashes
 (``/``). On Windows, the long filename marker is taken into account.
 
 When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
-<Normalization>` before the conversion.
+<Normalization>` after the conversion.
 
 For example:
 
@@ -644,6 +654,8 @@ is equivalent to the following:
   cmake_path(APPEND_STRING path "input")
 
 
+.. _Path Generation:
+
 Generation
 ^^^^^^^^^^
 

Help/command/ctest_test.rst

@@ -172,8 +172,9 @@ The options are:
   affected.  Summary info detailing the percentage of passing tests is also
   unaffected by the ``QUIET`` option.
 
-See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`
+See also the :variable:`CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE`,
-and :variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` variables.
+:variable:`CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE` and
+:variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variables.
 
 .. _`Additional Test Measurements`:
 

Help/command/execute_process.rst

@@ -37,8 +37,15 @@ Options:
 ``COMMAND``
  A child process command line.
 
- CMake executes the child process using operating system APIs directly.
+ CMake executes the child process using operating system APIs directly:
- All arguments are passed VERBATIM to the child process.
+
+ * On POSIX platforms, the command line is passed to the
+   child process in an ``argv[]`` style array.
+
+ * On Windows platforms, the command line is encoded as a string such
+   that child processes using ``CommandLineToArgvW`` will decode the
+   original arguments.
+
  No intermediate shell is used, so shell operators such as ``>``
  are treated as normal arguments.
  (Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to

Help/command/file.rst

@@ -1128,6 +1128,18 @@ Additional options to ``DOWNLOAD`` are:
   Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error to
   specify this if ``DOWNLOAD`` is not given a ``<file>``.
 
+``RANGE_START <value>``
+  .. versionadded:: 3.24
+
+  Offset of the start of the range in file in bytes. Could be omitted to
+  download up to the specified ``RANGE_END``.
+
+``RANGE_END <value>``
+  .. versionadded:: 3.24
+
+  Offset of the end of the range in file in bytes. Could be omitted to
+  download everything from the specified ``RANGE_START`` to the end of file.
+
 Locking
 ^^^^^^^
 
@@ -1215,7 +1227,8 @@ the ``MTIME`` option.
     [DESTINATION <dir>]
     [PATTERNS <patterns>...]
     [LIST_ONLY]
-    [VERBOSE])
+    [VERBOSE]
+    [TOUCH])
 
 .. versionadded:: 3.18
 
@@ -1233,4 +1246,8 @@ extracted.
 
 ``LIST_ONLY`` will list the files in the archive rather than extract them.
 
+.. versionadded:: 3.24
+  The ``TOUCH`` option gives extracted files a current local
+  timestamp instead of extracting file timestamps from the archive.
+
 With ``VERBOSE``, the command will produce verbose output.

Help/command/find_file.rst

@@ -8,6 +8,8 @@ find_file
 .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
 .. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
 
+.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
+
 .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
    ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
    is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|

Help/command/find_library.rst

@@ -8,6 +8,8 @@ find_library
 .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib``
 .. |entry_XXX_SUBDIR| replace:: ``<entry>/lib``
 
+.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
+
 .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
    ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
    and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|

Help/command/find_package.rst

@@ -1,17 +1,30 @@
 find_package
 ------------
 
+.. |FIND_XXX| replace:: find_package
+.. |FIND_ARGS_XXX| replace:: <PackageName>
+.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
+.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
+   :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE`
+
 .. only:: html
 
    .. contents::
 
+.. note:: The :guide:`Using Dependencies Guide` provides a high-level
+  introduction to this general topic. It provides a broader overview of
+  where the ``find_package()`` command fits into the bigger picture,
+  including its relationship to the :module:`FetchContent` module.
+  The guide is recommended pre-reading before moving on to the details below.
+
 Find a package (usually provided by something external to the project),
-and load its package-specific details.
+and load its package-specific details.  Calls to this command can also
+be intercepted by :ref:`dependency providers <dependency_providers>`.
 
 Search Modes
 ^^^^^^^^^^^^
 
-The command has two very distinct ways of conducting the search:
+The command has a few modes by which it searches for packages:
 
 **Module mode**
   In this mode, CMake searches for a file called ``Find<PackageName>.cmake``,
@@ -54,7 +67,17 @@ The command has two very distinct ways of conducting the search:
   Config mode is supported by both the :ref:`basic <Basic Signature>` and
   :ref:`full <Full Signature>` command signatures.
 
-The command arguments determine which of the above modes is used.  When the
+**FetchContent redirection mode**
+  .. versionadded:: 3.24
+    A call to ``find_package()`` can be redirected internally to a package
+    provided by the :module:`FetchContent` module.  To the caller, the behavior
+    will appear similar to Config mode, except that the search logic is
+    by-passed and the component information is not used.  See
+    :command:`FetchContent_Declare` and :command:`FetchContent_MakeAvailable`
+    for further details.
+
+When not redirected to a package provided by :module:`FetchContent`, the
+command arguments determine whether Module or Config mode is used.  When the
 `basic signature`_ is used, the command searches in Module mode first.
 If the package is not found, the search falls back to Config mode.
 A user may set the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable
@@ -64,7 +87,7 @@ forced to use only Module mode with a ``MODULE`` keyword.  If the
 `full signature`_ is used, the command only searches in Config mode.
 
 Where possible, user code should generally look for packages using the
-`basic signature`_, since that allows the package to be found with either mode.
+`basic signature`_, since that allows the package to be found with any mode.
 Project maintainers wishing to provide a config package should understand
 the bigger picture, as explained in :ref:`Full Signature` and all subsequent
 sections on this page.
@@ -74,12 +97,15 @@ sections on this page.
 Basic Signature
 ^^^^^^^^^^^^^^^
 
-.. code-block:: cmake
+.. parsed-literal::
 
   find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
                [REQUIRED] [[COMPONENTS] [components...]]
                [OPTIONAL_COMPONENTS components...]
-               [NO_POLICY_SCOPE])
+               [REGISTRY_VIEW  (64|32|64_32|32_64|HOST|TARGET|BOTH)]
+               [GLOBAL]
+               [NO_POLICY_SCOPE]
+               [BYPASS_PROVIDER])
 
 The basic signature is supported by both Module and Config modes.
 The ``MODULE`` keyword implies that only Module mode can be used to find
@@ -115,6 +141,18 @@ define what occurs in such cases.  Common arrangements include assuming it
 should find all components, no components or some well-defined subset of the
 available components.
 
+.. versionadded:: 3.24
+  The ``REGISTRY_VIEW`` keyword enables to specify which registry views must be
+  queried. This keyword is only meaningful on ``Windows`` platform and will be
+  ignored on all other ones. Formally, it is up to the target package how to
+  interpret the registry view information given to it.
+
+.. versionadded:: 3.24
+  Specifying the ``GLOBAL`` keyword will promote all imported targets to
+  a global scope in the importing project. Alternatively, this functionality
+  can be enabled by setting the :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL`
+  variable.
+
 .. _FIND_PACKAGE_VERSION_FORMAT:
 
 The ``[version]`` argument requests a version with which the package found
@@ -144,22 +182,33 @@ only take the single version at the lower end of the range into account.
 See the :command:`cmake_policy` command documentation for discussion
 of the ``NO_POLICY_SCOPE`` option.
 
+.. versionadded:: 3.24
+  The ``BYPASS_PROVIDER`` keyword is only allowed when ``find_package()`` is
+  being called by a :ref:`dependency provider <dependency_providers>`.
+  It can be used by providers to call the built-in ``find_package()``
+  implementation directly and prevent that call from being re-routed back to
+  itself.  Future versions of CMake may detect attempts to use this keyword
+  from places other than a dependency provider and halt with a fatal error.
+
 .. _`full signature`:
 
 Full Signature
 ^^^^^^^^^^^^^^
 
-.. code-block:: cmake
+.. parsed-literal::
 
   find_package(<PackageName> [version] [EXACT] [QUIET]
                [REQUIRED] [[COMPONENTS] [components...]]
                [OPTIONAL_COMPONENTS components...]
                [CONFIG|NO_MODULE]
+               [GLOBAL]
                [NO_POLICY_SCOPE]
+               [BYPASS_PROVIDER]
                [NAMES name1 [name2 ...]]
                [CONFIGS config1 [config2 ...]]
                [HINTS path1 [path2 ... ]]
                [PATHS path1 [path2 ... ]]
+               [REGISTRY_VIEW  (64|32|64_32|32_64|HOST|TARGET|BOTH)]
                [PATH_SUFFIXES suffix1 [suffix2 ...]]
                [NO_DEFAULT_PATH]
                [NO_PACKAGE_ROOT_PATH]
@@ -169,6 +218,7 @@ Full Signature
                [NO_CMAKE_PACKAGE_REGISTRY]
                [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
                [NO_CMAKE_SYSTEM_PATH]
+               [NO_CMAKE_INSTALL_PREFIX]
                [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
                [CMAKE_FIND_ROOT_PATH_BOTH |
                 ONLY_CMAKE_FIND_ROOT_PATH |
@@ -181,9 +231,12 @@ proceeds at once with Config mode search.
 
 Config mode search attempts to locate a configuration file provided by the
 package to be found.  A cache entry called ``<PackageName>_DIR`` is created to
-hold the directory containing the file.  By default the command
+hold the directory containing the file.  By default, the command searches for
-searches for a package with the name ``<PackageName>``.  If the ``NAMES`` option
+a package with the name ``<PackageName>``.  If the ``NAMES`` option is given,
-is given the names following it are used instead of ``<PackageName>``.
+the names following it are used instead of ``<PackageName>``.  The names are
+also considered when determining whether to redirect the call to a package
+provided by :module:`FetchContent`.
+
 The command searches for a file called ``<PackageName>Config.cmake`` or
 ``<lowercasePackageName>-config.cmake`` for each name specified.
 A replacement set of possible configuration file names may be given
@@ -220,6 +273,14 @@ Config Mode Search Procedure
   whether the :ref:`full <full signature>` or :ref:`basic <basic signature>`
   signature was given.
 
+.. versionadded:: 3.24
+  All calls to ``find_package()`` (even in Module mode) first look for a config
+  package file in the :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` directory.
+  The :module:`FetchContent` module, or even the project itself, may write files
+  to that location to redirect ``find_package()`` calls to content already
+  provided by the project.  If no config package file is found in that location,
+  the search proceeds with the logic described below.
+
 CMake constructs a set of possible installation prefixes for the
 package.  Under each prefix several directories are searched for a
 configuration file.  The tables below show the directories searched.
@@ -264,6 +325,18 @@ that order).
   if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``.
 * The ``lib`` path is always searched.
 
+.. versionchanged:: 3.24
+  On ``Windows`` platform, it is possible to include registry queries as part
+  of the directories specified through ``HINTS`` and ``PATHS`` keywords, using
+  a :ref:`dedicated syntax <Find Using Windows Registry>`. Such specifications
+  will be ignored on all other platforms.
+
+.. versionadded:: 3.24
+  ``REGISTRY_VIEW`` can be specified to manage ``Windows`` registry queries
+  specified as part of ``PATHS`` and ``HINTS``.
+
+.. include:: FIND_XXX_REGISTRY_VIEW.txt
+
 If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each
 (``W``) or (``U``) directory entry one-by-one.
 
@@ -339,9 +412,11 @@ enabled.
    package registry.
 
 7. Search cmake variables defined in the Platform files for the
-   current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
+   current system. The searching of :variable:`CMAKE_INSTALL_PREFIX` can be
-   passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`
+   skipped if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the
-   to ``FALSE``:
+   :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE``. All these locations
+   can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the
+   :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` to ``FALSE``:
 
    * :variable:`CMAKE_SYSTEM_PREFIX_PATH`
    * :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
@@ -372,11 +447,6 @@ of the above locations to be ignored.
    Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable
    various search locations.
 
-.. |FIND_XXX| replace:: find_package
-.. |FIND_ARGS_XXX| replace:: <PackageName>
-.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
-   :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE`
-
 .. include:: FIND_XXX_ROOT.txt
 .. include:: FIND_XXX_ORDER.txt
 
@@ -388,7 +458,8 @@ to resolve symbolic links and store the real path to the file.
 Every non-REQUIRED ``find_package`` call can be disabled or made REQUIRED:
 
 * Setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable
-  to ``TRUE`` disables the package.
+  to ``TRUE`` disables the package.  This also disables redirection to a
+  package provided by :module:`FetchContent`.
 
 * Setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable
   to ``TRUE`` makes the package REQUIRED.
@@ -411,8 +482,8 @@ version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If the
 ``EXACT`` option is given, only a version of the package claiming an exact match
 of the requested version may be found.  CMake does not establish any
 convention for the meaning of version numbers.  Package version
-numbers are checked by "version" files provided by the packages
+numbers are checked by "version" files provided by the packages themselves
-themselves.  For a candidate package configuration file
+or by :module:`FetchContent`.  For a candidate package configuration file
 ``<config-file>.cmake`` the corresponding version file is located next
 to it and named either ``<config-file>-version.cmake`` or
 ``<config-file>Version.cmake``.  If no such version file is available
@@ -547,6 +618,8 @@ restores their original state before returning):
   True if ``REQUIRED`` option was given
 ``<PackageName>_FIND_QUIETLY``
   True if ``QUIET`` option was given
+``<PackageName>_FIND_REGISTRY_VIEW``
+  The requested view if ``REGISTRY_VIEW`` option was given
 ``<PackageName>_FIND_VERSION``
   Full requested version string
 ``<PackageName>_FIND_VERSION_MAJOR``

Help/command/find_path.rst

@@ -8,6 +8,8 @@ find_path
 .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
 .. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
 
+.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
+
 .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
    ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
    is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|

Help/command/find_program.rst

@@ -8,6 +8,8 @@ find_program
 .. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin``
 .. |entry_XXX_SUBDIR| replace:: ``<entry>/[s]bin``
 
+.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``BOTH``
+
 .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
    |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
 .. |CMAKE_PREFIX_PATH_XXX| replace::

Help/command/get_filename_component.rst

@@ -4,10 +4,16 @@ get_filename_component
 Get a specific component of a full filename.
 
 .. versionchanged:: 3.20
-  This command been superseded by :command:`cmake_path` command, except
+  This command has been superseded by :command:`cmake_path` command, except
-  ``REALPATH`` now offered by :ref:`file(REAL_PATH) <REAL_PATH>` command and
+  ``REALPATH`` now offered by :ref:`file(REAL_PATH)<REAL_PATH>` command and
   ``PROGRAM`` now available in :command:`separate_arguments(PROGRAM)` command.
 
+.. versionchanged:: 3.24
+  The undocumented feature offering the capability to query the ``Windows``
+  registry is superseded by
+  :ref:`cmake_host_system_information(QUERY WINDOWS_REGISTRY)<Query Windows registry>`
+  command.
+
 .. code-block:: cmake
 
   get_filename_component(<var> <FileName> <mode> [CACHE])

Help/command/if.rst

@@ -47,7 +47,7 @@ Compound conditions are evaluated in the following order of precedence:
    `GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_,
    `STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_,
    `VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_,
-   and `MATCHES`_.
+   `PATH_EQUAL`_, and `MATCHES`_.
 
 4. Unary logical operator `NOT`_.
 
@@ -71,8 +71,9 @@ Basic Expressions
  True if given a variable that is defined to a value that is not a false
  constant.  False otherwise, including if the variable is undefined.
  Note that macro arguments are not variables.
- Environment variables also cannot be tested this way, e.g.
+ :ref:`Environment Variables <CMake Language Environment Variables>` also
- ``if(ENV{some_var})`` will always evaluate to false.
+ cannot be tested this way, e.g. ``if(ENV{some_var})`` will always evaluate
+ to false.
 
 ``if(<string>)``
  A quoted string always evaluates to false unless:
@@ -313,6 +314,39 @@ Version Comparisons
   Any non-integer version component or non-integer trailing part of a version
   component effectively truncates the string at that point.
 
+Path Comparisons
+""""""""""""""""
+
+.. _PATH_EQUAL:
+
+``if(<variable|string> PATH_EQUAL <variable|string>)``
+  .. versionadded:: 3.24
+
+  Compares the two paths component-by-component.  Only if every component of
+  both paths match will the two paths compare equal.  Multiple path separators
+  are effectively collapsed into a single separator, but note that backslashes
+  are not converted to forward slashes.  No other
+  :ref:`path normalization <Normalization>` is performed.
+
+  Component-wise comparison is superior to string-based comparison due to the
+  handling of multiple path separators.  In the following example, the
+  expression evaluates to true using ``PATH_EQUAL``, but false with
+  ``STREQUAL``:
+
+  .. code-block:: cmake
+
+    # comparison is TRUE
+    if ("/a//b/c" PATH_EQUAL "/a/b/c")
+       ...
+    endif()
+
+    # comparison is FALSE
+    if ("/a//b/c" STREQUAL "/a/b/c")
+       ...
+    endif()
+
+  See :ref:`cmake_path(COMPARE) <Path COMPARE>` for more details.
+
 Variable Expansion
 ^^^^^^^^^^^^^^^^^^
 

Help/command/install.rst

@@ -85,7 +85,7 @@ signatures that specify them.  The common options are:
 
 ``COMPONENT``
   Specify an installation component name with which the install rule
-  is associated, such as "runtime" or "development".  During
+  is associated, such as ``Runtime`` or ``Development``.  During
   component-specific installation only install rules associated with
   the given component name will be executed.  During a full installation
   all components are installed unless marked with ``EXCLUDE_FROM_ALL``.

Help/command/message.rst

@@ -32,6 +32,9 @@ influences the way the message is handled:
 ``FATAL_ERROR``
   CMake Error, stop processing and generation.
 
+  The :manual:`cmake(1)` executable will return a non-zero
+  :ref:`exit code <CMake Exit Code>`.
+
 ``SEND_ERROR``
   CMake Error, continue processing, but skip generation.
 

Help/command/option.rst

@@ -1,16 +1,18 @@
 option
 ------
 
-Provide an option that the user can optionally select.
+Provide a boolean option that the user can optionally select.
 
 .. code-block:: cmake
 
   option(<variable> "<help_text>" [value])
 
-Provides an option for the user to select as ``ON`` or ``OFF``.
+If no initial ``<value>`` is provided, boolean ``OFF`` is the default value.
-If no initial ``<value>`` is provided, ``OFF`` is used.
 If ``<variable>`` is already set as a normal or cache variable,
 then the command does nothing (see policy :policy:`CMP0077`).
 
-If you have options that depend on the values of other options, see
+For options that depend on the values of other options, see
 the module help for :module:`CMakeDependentOption`.
+
+In CMake project mode, a boolean cache variable is created with the option
+value. In CMake script mode, a boolean variable is set with the option value.

Help/command/project.rst

@@ -123,28 +123,56 @@ The options are:
 The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL``
 options are intended for use as default values in package metadata and documentation.
 
+.. _`Code Injection`:
+
 Code Injection
 ^^^^^^^^^^^^^^
 
-If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` or
+A number of variables can be defined by the user to specify files to include
-:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables are set,
+at different points during the execution of the ``project()`` command.
-the files they point to will be included as the first step of the
+The following outlines the steps performed during a ``project()`` call:
-``project()`` command.
-If both are set, then :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` will be
-included before :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`.
 
-If the :variable:`CMAKE_PROJECT_INCLUDE` or
+* .. versionadded:: 3.15
-:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files
+    For every ``project()`` call regardless of the project
-they point to will be included as the last step of the ``project()`` command.
+    name, include the file named by :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`,
-If both are set, then :variable:`CMAKE_PROJECT_INCLUDE` will be included before
+    if set.
-:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`.
 
-.. versionadded:: 3.15
+* .. versionadded:: 3.17
-  Added the ``CMAKE_PROJECT_INCLUDE`` and ``CMAKE_PROJECT_INCLUDE_BEFORE``
+    If the ``project()`` command specifies ``<PROJECT-NAME>`` as its project
-  variables.
+    name, include the file named by
+    :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`, if set.
 
-.. versionadded:: 3.17
+* Set the various project-specific variables detailed in the `Synopsis`_
-  Added the ``CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`` variable.
+  and `Options`_ sections above.
+
+* For the very first ``project()`` call only:
+
+  * If :variable:`CMAKE_TOOLCHAIN_FILE` is set, read it at least once.
+    It may be read multiple times and it may also be read again when
+    enabling languages later (see below).
+
+  * Set the variables describing the host and target platforms.
+    Language-specific variables might or might not be set at this point.
+    On the first run, the only language-specific variables that might be
+    defined are those a toolchain file may have set. On subsequent runs,
+    language-specific variables cached from a previous run may be set.
+
+  * .. versionadded:: 3.24
+      Include each file listed in :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES`,
+      if set. The variable is ignored by CMake thereafter.
+
+* Enable any languages specified in the call, or the default languages if
+  none were provided. The toolchain file may be re-read when enabling a
+  language for the first time.
+
+* .. versionadded:: 3.15
+    For every ``project()`` call regardless of the project
+    name, include the file named by :variable:`CMAKE_PROJECT_INCLUDE`,
+    if set.
+
+* If the ``project()`` command specifies ``<PROJECT-NAME>`` as its project
+  name, include the file named by
+  :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, if set.
 
 Usage
 ^^^^^

Help/command/target_sources.rst

@@ -52,10 +52,10 @@ 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>")
+  target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:dbgsrc.cpp>")
 
   # CORRECT: absolute path used inside the generator expression
-  target_sources(MyTarget "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>")
+  target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>")
 
 See the :manual:`cmake-buildsystem(7)` manual for more on defining
 buildsystem properties.

Help/command/try_compile.rst

@@ -7,6 +7,8 @@ try_compile
 
 Try building some code.
 
+.. _`Try Compiling Whole Projects`:
+
 Try Compiling Whole Projects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -25,6 +27,15 @@ will not be deleted after this command is run.  Specify ``<targetName>`` to
 build a specific target instead of the ``all`` or ``ALL_BUILD`` target.  See
 below for the meaning of other options.
 
+.. versionchanged:: 3.24
+  CMake variables describing platform settings, and those listed by the
+  :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable, are propagated
+  into the project's build configuration.  See policy :policy:`CMP0137`.
+  Previously this was only done by the
+  :ref:`source file <Try Compiling Source Files>` signature.
+
+.. _`Try Compiling Source Files`:
+
 Try Compiling Source Files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -150,6 +161,7 @@ Other Behavior Settings
   * :variable:`CMAKE_LINK_SEARCH_END_STATIC`
   * :variable:`CMAKE_MSVC_RUNTIME_LIBRARY`
   * :variable:`CMAKE_POSITION_INDEPENDENT_CODE`
+  * :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY`
 
   If :policy:`CMP0056` is set to ``NEW``, then
   :variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well.
@@ -204,3 +216,7 @@ a build configuration.
 .. versionchanged:: 3.14
   For the :generator:`Green Hills MULTI` generator the GHS toolset and target
   system customization cache variables are also propagated into the test project.
+
+.. versionadded:: 3.24
+  The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be
+  set to disable passing platform variables into the test project.

Help/cpack_gen/archive.rst

@@ -49,6 +49,8 @@ Variables specific to CPack Archive generator
 
   Package file name without extension. The extension is determined from the
   archive format (see list above) and automatically appended to the file name.
+  Note that ``<component>`` is all uppercase in the variable name.
+
   The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces
   replaced by '-'.
 

Help/cpack_gen/dmg.rst

@@ -65,8 +65,8 @@ on macOS:
 
  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
+ must be explicitly enabled by the project to activate the SLA.
- :variable:`CPACK_RESOURCE_FILE_LICENSE` is set to a non-default value.
+ See policy :policy:`CMP0133`.
 
  .. note::
 

Help/cpack_gen/packagemaker.rst

@@ -1,87 +1,7 @@
 CPack PackageMaker Generator
 ----------------------------
 
-PackageMaker CPack generator (macOS).
+Removed.  This once generated PackageMaker installers, but the
-
+generator has been removed since CMake 3.24.  Xcode no longer distributes
-.. deprecated:: 3.17
+the PackageMaker tools.  Use the :cpack_gen:`CPack productbuild Generator`
-
+instead.
-  Xcode no longer distributes the PackageMaker tools.
-  This CPack generator will be removed in a future version of CPack.
-
-Variables specific to CPack PackageMaker generator
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following variable is specific to installers built on Mac
-macOS using PackageMaker:
-
-.. variable:: CPACK_OSX_PACKAGE_VERSION
-
- The version of macOS that the resulting PackageMaker archive should be
- compatible with. Different versions of macOS support different
- features. For example, CPack can only build component-based installers for
- macOS 10.4 or newer, and can only build installers that download
- components on-the-fly for macOS 10.5 or newer. If left blank, this value
- will be set to the minimum version of macOS that supports the requested
- features. Set this variable to some value (e.g., 10.4) only if you want to
- guarantee that your installer will work on that version of macOS, and
- don't mind missing extra features available in the installer shipping with
- later versions of macOS.
-
-Background Image
-""""""""""""""""
-
-.. versionadded:: 3.17
-
-This group of variables controls the background image of the generated
-installer.
-
-.. variable:: CPACK_PACKAGEMAKER_BACKGROUND
-
- Adds a background to Distribution XML if specified. The value contains the
- path to image in ``Resources`` directory.
-
-.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT
-
- Adds an ``alignment`` attribute to the background in Distribution XML.
- Refer to Apple documentation for valid values.
-
-.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_SCALING
-
- Adds a ``scaling`` attribute to the background in Distribution XML.
- Refer to Apple documentation for valid values.
-
-.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE
-
- Adds a ``mime-type`` attribute to the background in Distribution XML.
- The option contains MIME type of an image.
-
-.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_UTI
-
- Adds an ``uti`` attribute to the background in Distribution XML.
- The option contains UTI type of an image.
-
-.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA
-
- Adds a background for the Dark Aqua theme to Distribution XML if
- specified. The value contains the path to image in ``Resources``
- directory.
-
-.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_ALIGNMENT
-
- Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_ALIGNMENT` option,
- but for the dark theme.
-
-.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_SCALING
-
- Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_SCALING` option,
- but for the dark theme.
-
-.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_MIME_TYPE
-
- Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_MIME_TYPE` option,
- but for the dark theme.
-
-.. variable:: CPACK_PACKAGEMAKER_BACKGROUND_DARKAQUA_UTI
-
- Does the same as :variable:`CPACK_PACKAGEMAKER_BACKGROUND_UTI` option,
- but for the dark theme.

Help/cpack_gen/wix.rst

@@ -328,3 +328,12 @@ Windows using WiX.
  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.
+
+.. variable:: CPACK_WIX_ARCHITECTURE
+
+ .. versionadded:: 3.24
+
+ This variable can be optionally set to specify the target architecture
+ of the installer. May for example be set to ``x64`` or ``arm64``.
+
+ When unspecified, CPack will default to ``x64`` or ``x86``.

Help/dev/experimental.rst

@@ -36,7 +36,14 @@ For example, add code like the following to a test project:
 The tool specified by ``CMAKE_EXPERIMENTAL_CXX_SCANDEP_SOURCE`` is
 expected to process the translation unit, write preprocessor dependencies
 to the file specified by the ``<DEP_FILE>`` placeholder, and write module
-dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder.
+dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder. The
+``CMAKE_EXPERIMENTAL_CXX_SCANDEP_DEPFILE_FORMAT`` file may be set to ``msvc``
+for scandep rules which use ``msvc``-style dependency reporting.
+
+For tools which need to know the file set the source belongs to, the
+``CMAKE_EXPERIMENTAL_CXX_MODULE_SOURCE_TYPE_FLAG_<FILE_SET_TYPE>`` flag may
+be provided so that different source types can be distinguished prior to
+scanning.
 
 The module dependencies should be written in the format described
 by the `P1689r4`_ paper.

Help/dev/source.rst

@@ -35,6 +35,18 @@ Available features are:
 
 * From ``C++14``:
 
+  * ``<cm/array>``:
+    ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
+    ``cm::crbegin``, ``cm::crend``
+
+  * ``<cm/deque>``:
+    ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
+    ``cm::crbegin``, ``cm::crend``
+
+  * ``<cm/forward_list>``:
+    ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
+    ``cm::crbegin``, ``cm::crend``
+
   * ``<cm/iomanip>``:
     ``cm::quoted``
 
@@ -42,68 +54,142 @@ Available features are:
     ``cm::make_reverse_iterator``, ``cm::cbegin``, ``cm::cend``,
     ``cm::rbegin``, ``cm::rend``, ``cm::crbegin``, ``cm::crend``
 
+  * ``<cm/list>``:
+    ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
+    ``cm::crbegin``, ``cm::crend``
+
+  * ``<cm/map>``:
+    ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
+    ``cm::crbegin``, ``cm::crend``
+
   * ``<cm/memory>``:
     ``cm::make_unique``
 
+  * ``<cm/set>``:
+    ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
+    ``cm::crbegin``, ``cm::crend``
+
+  * ``<cm/string>``:
+    ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
+    ``cm::crbegin``, ``cm::crend``
+
+  * ``<cm/string_view>``:
+    ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
+    ``cm::crbegin``, ``cm::crend``
+
   * ``<cm/shared_mutex>``:
     ``cm::shared_lock``
 
   * ``<cm/type_traits>``:
     ``cm::enable_if_t``
 
+  * ``<cm/unordered_map>``:
+    ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
+    ``cm::crbegin``, ``cm::crend``
+
+  * ``<cm/unordered_set>``:
+    ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
+    ``cm::crbegin``, ``cm::crend``
+
+  * ``<cm/vector>``:
+    ``cm::cbegin``, ``cm::cend``, ``cm::rbegin``, ``cm::rend``,
+    ``cm::crbegin``, ``cm::crend``
+
 * From ``C++17``:
 
   * ``<cm/algorithm>``:
     ``cm::clamp``
 
+  * ``<cm/array>``:
+    ``cm::size``, ``cm::empty``, ``cm::data``
+
+  * ``<cm/deque>``:
+    ``cm::size``, ``cm::empty``, ``cm::data``
+
   * ``cm/filesystem>``:
     ``cm::filesystem::path``
 
+  * ``<cm/forward_list>``:
+    ``cm::size``, ``cm::empty``, ``cm::data``
+
   * ``<cm/iterator>``:
     ``cm::size``, ``cm::empty``, ``cm::data``
 
+  * ``<cm/list>``:
+    ``cm::size``, ``cm::empty``, ``cm::data``
+
+  * ``<cm/map>``:
+    ``cm::size``, ``cm::empty``, ``cm::data``
+
   * ``<cm/optional>``:
     ``cm::nullopt_t``, ``cm::nullopt``, ``cm::optional``,
     ``cm::make_optional``, ``cm::bad_optional_access``
 
+  * ``<cm/set>``:
+    ``cm::size``, ``cm::empty``, ``cm::data``
+
   * ``<cm/shared_mutex>``:
     ``cm::shared_mutex``
 
+  * ``<cm/string>``:
+    ``cm::size``, ``cm::empty``, ``cm::data``
+
   * ``<cm/string_view>``:
-    ``cm::string_view``
+    ``cm::string_view``, ``cm::size``, ``cm::empty``, ``cm::data``
 
   * ``<cm/type_traits>``:
     ``cm::bool_constant``, ``cm::invoke_result_t``, ``cm::invoke_result``,
     ``cm::void_t``
 
+  * ``<cm/unordered_map>``:
+    ``cm::size``, ``cm::empty``, ``cm::data``
+
+  * ``<cm/unordered_set>``:
+    ``cm::size``, ``cm::empty``, ``cm::data``
+
   * ``<cm/utility>``:
     ``cm::in_place_t``, ``cm::in_place``
 
+  * ``<cm/vector>``:
+    ``cm::size``, ``cm::empty``, ``cm::data``
+
 * From ``C++20``:
 
+  * ``<cm/array>``:
+    ``cm::ssize``
+
   * ``<cm/deque>``:
-    ``cm::erase``, ``cm::erase_if``
+    ``cm::erase``, ``cm::erase_if``, ``cm::ssize``
+
+  * ``<cm/forward_list>``:
+    ``cm::ssize``
+
+  * ``<cm/iterator>``:
+    ``cm::ssize``
 
   * ``<cm/list>``:
-    ``cm::erase``, ``cm::erase_if``
+    ``cm::erase``, ``cm::erase_if``, ``cm::ssize``
 
   * ``<cm/map>`` :
-    ``cm::erase_if``
+    ``cm::erase_if``, ``cm::ssize``
 
   * ``<cm/set>`` :
-    ``cm::erase_if``
+    ``cm::erase_if``, ``cm::ssize``
+
+  * ``<cm/string_view>``:
+    ``cm::ssize``
 
   * ``<cm/string>``:
-    ``cm::erase``, ``cm::erase_if``
+    ``cm::erase``, ``cm::erase_if``, ``cm::ssize``
 
   * ``<cm/unordered_map>``:
-    ``cm::erase_if``
+    ``cm::erase_if``, ``cm::ssize``
 
   * ``<cm/unordered_set>``:
-    ``cm::erase_if``
+    ``cm::erase_if``, ``cm::ssize``
 
   * ``<cm/vector>``:
-    ``cm::erase``, ``cm::erase_if``
+    ``cm::erase``, ``cm::erase_if``, ``cm::ssize``
 
 Additionally, some useful non-standard extensions to the C++ standard library
 are available in headers under the directory ``cmext/`` in namespace ``cm``.
@@ -117,6 +203,11 @@ These are:
   * ``cm::contains``:
     Checks if element or key is contained in container.
 
+* ``<cmext/enum_set>``
+
+  * ``cm::enum_set``:
+    Container to manage set of elements from an ``enum class`` definition.
+
 * ``<cmext/iterator>``:
 
   * ``cm::is_terator``:

Help/envvar/ADSP_ROOT.rst

@@ -0,0 +1,10 @@
+ADSP_ROOT
+---------
+
+.. versionadded:: 3.24
+
+.. include:: ENV_VAR.txt
+
+The ``ADSP_ROOT`` environment variable specifies a default value
+for the :variable:`CMAKE_ADSP_ROOT` variable when there is no explicit
+configuration given on the first run while creating a new build tree.

Help/envvar/CMAKE_COLOR_DIAGNOSTICS.rst

@@ -0,0 +1,9 @@
+CMAKE_COLOR_DIAGNOSTICS
+-----------------------
+
+.. versionadded:: 3.24
+
+.. include:: ENV_VAR.txt
+
+Specifies a default value for the :variable:`CMAKE_COLOR_DIAGNOSTICS` variable
+when there is no explicit value given on the first run.

Help/guide/using-dependencies/index.rst

@@ -8,193 +8,412 @@ Using Dependencies Guide
 Introduction
 ============
 
-For developers wishing to use CMake to consume a third
+Projects will frequently depend on other projects, assets, and artifacts.
-party binary package, there are multiple possibilities
+CMake provides a number of ways to incorporate such things into the build.
-regarding how to optimally do so, depending on how
+Projects and users have the flexibility to choose between methods that
-CMake-aware the third-party library is.
+best suit their needs.
 
-CMake files provided with a software package contain
+The primary methods of bringing dependencies into the build are the
-instructions for finding each build dependency.  Some
+:command:`find_package` command and the :module:`FetchContent` module.
-build dependencies are optional in that the build may
+The :module:`FindPkgConfig` module is also sometimes used, although it
-succeed with a different feature set if the dependency
+lacks some of the integration of the other two and is not discussed any
-is missing, and some dependencies are required.  CMake
+further in this guide.
-searches well-known locations for each dependency, and
-the provided software may supply additional hints or
-locations to CMake to find each dependency.
 
-If a required dependency is not found by
+Dependencies can also be made available by a custom
-:manual:`cmake(1)`, the cache is populated with an entry
+:ref:`dependency provider <dependency_providers>`.
-which contains a ``NOTFOUND`` value.  This value can be
+This might be a third party package manager, or it might be custom code
-replaced by specifying it on the command line, or in
+implemented by the developer.  Dependency providers co-operate with the
-the :manual:`ccmake(1)` or :manual:`cmake-gui(1)` tool.
+primary methods mentioned above to extend their flexibility.
-See the :guide:`User Interaction Guide` for
-more about setting cache entries.
 
-Libraries providing Config-file packages
+.. _prebuilt_find_package:
-========================================
 
-The most convenient way for a third-party to provide library
+Using Pre-built Packages With ``find_package()``
-binaries for use with CMake is to provide
+================================================
-:ref:`Config File Packages`.  These packages are text files
-shipped with the library which instruct CMake how to use the
-library binaries and associated headers, helper tools and
-CMake macros provided by the library.
 
-The config files can usually be found in a directory whose
+A package needed by the project may already be built and available at some
-name matches the pattern ``lib/cmake/<PackageName>``, though
+location on the user's system.  That package might have also been built by
-they may be in other locations instead.  The
+CMake, or it could have used a different build system entirely.  It might
-``<PackageName>`` corresponds to use in CMake code with the
+even just be a collection of files that didn't need to be built at all.
-:command:`find_package` command such as
+CMake provides the :command:`find_package` command for these scenarios.
-``find_package(PackageName REQUIRED)``.
+It searches well-known locations, along with additional hints and paths
+provided by the project or user.  It also supports package components and
+packages being optional.  Result variables are provided to allow the project
+to customize its own behavior according to whether the package or specific
+components were found.
 
-The ``lib/cmake/<PackageName>`` directory will contain a
+In most cases, projects should generally use the :ref:`basic signature`.
-file which is either named ``<PackageName>Config.cmake``
+Most of the time, this will involve just the package name, maybe a version
-or ``<PackageName>-config.cmake``.  This is the entry point
+constraint, and the ``REQUIRED`` keyword if the dependency is not optional.
+A set of package components may also be specified.
+
+.. code-block:: cmake
+  :caption: Examples of ``find_package()`` basic signature
+
+  find_package(Catch2)
+  find_package(GTest REQUIRED)
+  find_package(Boost 1.79 COMPONENTS date_time)
+
+The :command:`find_package` command supports two main methods for carrying
+out the search:
+
+**Config mode**
+  With this method, the command looks for files that are typically provided
+  by the package itself.  This is the more reliable method of the two, since
+  the package details should always be in sync with the package.
+
+**Module mode**
+  Not all packages are CMake-aware. Many don't provide the files needed to
+  support config mode.  For such cases, a Find module file can be provided
+  separately, either by the project or by CMake.  A Find module is typically
+  a heuristic implementation which knows what the package normally provides
+  and how to present that package to the project.  Since Find modules are
+  usually distributed separately from the package, they are not as reliable.
+  They are typically maintained separately, and they are likely to follow
+  different release schedules, so they can easily become out-of-date.
+
+Depending on the arguments used, :command:`find_package` may use one or both
+of the above methods.  By restricting the options to just the basic signature,
+both config mode and module mode can be used to satisfy the dependency.
+The presence of other options may restrict the call to using only one of the
+two methods, potentially reducing the command's ability to find the dependency.
+See the :command:`find_package` documentation for full details about this
+complex topic.
+
+For both search methods, the user can also set cache variables on the
+:manual:`cmake(1)` command line or in the :manual:`ccmake(1)` or
+:manual:`cmake-gui(1)` UI tools to influence and override where to find
+packages. See the :ref:`User Interaction Guide <Setting Build Variables>`
+for more on how to set cache variables.
+
+.. _Libraries providing Config-file packages:
+
+Config-file packages
+--------------------
+
+The preferred way for a third party to provide executables, libraries,
+headers, and other files for use with CMake is to provide
+:ref:`config files <Config File Packages>`.  These are text files shipped
+with the package, which define CMake targets, variables, commands, and so on.
+The config file is an ordinary CMake script, which is read in by the
+:command:`find_package` command.
+
+The config files can usually be found in a directory whose name matches the
+pattern ``lib/cmake/<PackageName>``, although they may be in other locations
+instead (see :ref:`search procedure`).  The ``<PackageName>`` is usually the
+first argument to the :command:`find_package` command, and it may even be the
+only argument.  Alternative names can also be specified with the ``NAMES``
+option:
+
+.. code-block:: cmake
+  :caption: Providing alternative names when finding a package
+
+  find_package(SomeThing
+    NAMES
+      SameThingOtherName   # Another name for the package
+      SomeThing            # Also still look for its canonical name
+  )
+
+The config file must be named either ``<PackageName>Config.cmake`` or
+``<LowercasePackageName>-config.cmake`` (the former is used for the remainder
+of this guide, but both are supported).  This file is the entry point
 to the package for CMake.  A separate optional file named
-``<PackageName>ConfigVersion.cmake`` may also exist in the
+``<PackageName>ConfigVersion.cmake`` or
-directory.  This file is used by CMake to determine whether
+``<LowercasePackageName>-config-version.cmake`` may also exist in the same
-the version of the third party package satisfies uses of the
+directory.  This file is used by CMake to determine whether the version of
-:command:`find_package` command which specify version
+the package satisfies any version constraint included in the call to
-constraints.  It is optional to specify a version when using
+:command:`find_package`.  It is optional to specify a version when calling
-:command:`find_package`, even if a ``ConfigVersion`` file is
+:command:`find_package`, even if a ``<PackageName>ConfigVersion.cmake``
-present.
+file is present.
 
-If the ``Config.cmake`` file is found and the
+If the ``<PackageName>Config.cmake`` file is found and any version constraint
-optionally-specified version is satisfied, then the CMake
+is satisfied, the :command:`find_package` command considers the package to be
-:command:`find_package` command considers the package to be
+found, and the entire package is assumed to be complete as designed.
-found and the entire library package is assumed to be
-complete as designed.
 
-There may be additional files providing CMake macros or
+There may be additional files providing CMake commands or
-:ref:`imported targets` for you to use.  CMake does not
+:ref:`imported targets` for you to use.  CMake does not enforce any naming
-enforce any naming convention for these
+convention for these files.  They are related to the primary
-files.  They are related to the primary ``Config`` file by
+``<PackageName>Config.cmake`` file by use of the CMake :command:`include`
-use of the CMake :command:`include` command.
+command.  The ``<PackageName>Config.cmake`` file would typically include
+these for you, so they won't usually require any additional step other than
+the call to :command:`find_package`.
 
-:guide:`Invoking CMake <User Interaction Guide>` with the
+If the location of the package is in a
-intent of using a package of third party binaries requires
+:ref:`directory known to CMake <search procedure>`, the
-that cmake :command:`find_package` commands succeed in finding
+:command:`find_package` call should succeed.  The directories known to CMake
-the package.  If the location of the package is in a directory
+are platform-specific.  For example, packages installed on Linux with a
-known to CMake, the :command:`find_package` call should
+standard system package manager will be found in the ``/usr`` prefix
-succeed.  The directories known to cmake are platform-specific.
+automatically.  Packages installed in ``Program Files`` on Windows will
-For example, packages installed on Linux with a standard
+similarly be found automatically.
-system package manager will be found in the ``/usr`` prefix
-automatically.  Packages installed in ``Program Files`` on
-Windows will similarly be found automatically.
 
-Packages which are not found automatically are in locations
+Packages will not be found automatically without help if they are in
-not predictable to CMake such as ``/opt/mylib`` or
+locations not known to CMake, such as ``/opt/mylib`` or ``$HOME/dev/prefix``.
-``$HOME/dev/prefix``.  This is a normal situation and CMake
+This is a normal situation, and CMake provides several ways for users to
-provides several ways for users to specify where to find
+specify where to find such libraries.
-such libraries.
 
 The :variable:`CMAKE_PREFIX_PATH` variable may be
 :ref:`set when invoking CMake <Setting Build Variables>`.
-It is treated as a list of paths to search for
+It is treated as a list of base paths in which to search for
-:ref:`Config File Packages`.  A package installed in
+:ref:`config files <Config File Packages>`.  A package installed in
-``/opt/somepackage`` will typically install config files
+``/opt/somepackage`` will typically install config files such as
-such as
 ``/opt/somepackage/lib/cmake/somePackage/SomePackageConfig.cmake``.
 In that case, ``/opt/somepackage`` should be added to
 :variable:`CMAKE_PREFIX_PATH`.
 
-The environment variable ``CMAKE_PREFIX_PATH`` may also be
+The environment variable ``CMAKE_PREFIX_PATH`` may also be populated with
-populated with prefixes to search for packages.  Like the
+prefixes to search for packages.  Like the ``PATH`` environment variable,
-``PATH`` environment variable, this is a list and needs to use
+this is a list, but it needs to use the platform-specific environment variable
-the platform-specific environment variable list item separator
+list item separator (``:`` on Unix and ``;`` on Windows).
-(``:`` on Unix and ``;`` on Windows).
 
-The :variable:`CMAKE_PREFIX_PATH` variable provides convenience
+The :variable:`CMAKE_PREFIX_PATH` variable provides convenience in cases
-in cases where multiple prefixes need to be specified, or when
+where multiple prefixes need to be specified, or when multiple packages
-multiple different package binaries are available in the same
+are available under the same prefix.  Paths to packages may also be
-prefix.  Paths to packages may also be specified by setting
+specified by setting variables matching ``<PackageName>_DIR``, such as
-variables matching ``<PackageName>_DIR``, such as
+``SomePackage_DIR``.  Note that this is not a prefix, but should be a full
-``SomePackage_DIR``.  Note that this is not a prefix but should
+path to a directory containing a config-style package file, such as
-be a full path to a directory containing a config-style package
+``/opt/somepackage/lib/cmake/SomePackage`` in the above example.
-file, such as ``/opt/somepackage/lib/cmake/SomePackage/`` in
+See the :command:`find_package` documentation for other CMake variables and
-the above example.
+environment variables that can affect the search.
 
-Imported Targets from Packages
+.. _Libraries not Providing Config-file Packages:
-==============================
 
-A third-party package which provides config-file packages may
+Find Module Files
-also provide :ref:`Imported targets`. These will be
+-----------------
-specified in files containing configuration-specific file
-paths relevant to the package, such as debug and release
-versions of libraries.
 
-Often the third-party package documentation will point out the
+Packages which do not provide config files can still be found with the
-names of imported targets available after a successful
+:command:`find_package` command, if a ``FindSomePackage.cmake`` file is
-``find_package`` for a library.  Those imported target names
+available.  These Find module files are different to config files in that:
-can be used with the :command:`target_link_libraries` command.
 
-A complete example which makes a simple use of a third party
+#. Find module files should not be provided by the package itself.
-library might look like:
+#. The availability of a ``Find<PackageName>.cmake`` file does not indicate
-
+   the availability of the package, or any particular part of the package.
-.. code-block:: cmake
+#. CMake does not search the locations specified in the
-
+   :variable:`CMAKE_PREFIX_PATH` variable for ``Find<PackageName>.cmake``
-    cmake_minimum_required(VERSION 3.10)
+   files.  Instead, CMake searches for such files in the locations given
-    project(MyExeProject VERSION 1.0.0)
+   by the :variable:`CMAKE_MODULE_PATH` variable.  It is common for users to
-
+   set the :variable:`CMAKE_MODULE_PATH` when running CMake, and it is common
-    find_package(SomePackage REQUIRED)
+   for CMake projects to append to :variable:`CMAKE_MODULE_PATH` to allow use
-    add_executable(MyExe main.cpp)
+   of local Find module files.
-    target_link_libraries(MyExe PRIVATE SomePrefix::LibName)
-
-See :manual:`cmake-buildsystem(7)` for further information
-about developing a CMake buildsystem.
-
-Libraries not Providing Config-file Packages
---------------------------------------------
-
-Third-party libraries which do not provide config-file packages
-can still be found with the :command:`find_package` command, if
-a ``FindSomePackage.cmake`` file is available.
-
-These module-file packages are different to config-file packages
-in that:
-
-#. They should not be provided by the third party, except
-   perhaps in the form of documentation
-#. The availability of a ``Find<PackageName>.cmake`` file does
-   not indicate the availability of the binaries themselves.
-#. CMake does not search the :variable:`CMAKE_PREFIX_PATH` for
-   ``Find<PackageName>.cmake`` files.  Instead CMake searches
-   for such files in the :variable:`CMAKE_MODULE_PATH`
-   variable. It is common for users to set the
-   :variable:`CMAKE_MODULE_PATH` when running CMake, and it is
-   common for CMake projects to append to
-   :variable:`CMAKE_MODULE_PATH` to allow use of local
-   module-file packages.
 #. CMake ships ``Find<PackageName>.cmake`` files for some
-   :manual:`third party packages <cmake-modules(7)>`
+   :manual:`third party packages <cmake-modules(7)>`.  These files are a
-   for convenience in cases where the third party does
+   maintenance burden for CMake, and it is not unusual for these to fall
-   not provide config-file packages directly.  These files are
+   behind the latest releases of the packages they are associated with.
-   a maintenance burden for CMake, so new Find modules are
+   In general, new Find modules are not added to CMake any more.  Projects
-   generally not added to CMake anymore.  Third-parties should
+   should encourage the upstream packages to provide a config file where
-   provide config file packages instead of relying on a Find
+   possible.  If that is unsuccessful, the project should provide its own
-   module to be provided by CMake.
+   Find module for the package.
 
-Module-file packages may also provide :ref:`Imported targets`.
+See :ref:`Find Modules` for a detailed discussion of how to write a
-A complete example which finds such a package might look
+Find module file.
-like:
+
+.. _Imported Targets from Packages:
+
+Imported Targets
+----------------
+
+Both config files and Find module files can define :ref:`Imported targets`.
+These will typically have names of the form ``SomePrefix::ThingName``.
+Where these are available, the project should prefer to use them instead of
+any CMake variables that may also be provided.  Such targets typically carry
+usage requirements and apply things like header search paths, compiler
+definitions, etc. automatically to other targets that link to them (e.g. using
+:command:`target_link_libraries`).  This is both more robust and more
+convenient than trying to apply the same things manually using variables.
+Check the documentation for the package or Find module to see what imported
+targets it defines, if any.
+
+Imported targets should also encapsulate any configuration-specific paths.
+This includes the location of binaries (libraries, executables), compiler
+flags, and any other configuration-dependent quantities.  Find modules may
+be less reliable in providing these details than config files.
+
+A complete example which finds a third party package and uses a library
+from it might look like the following:
 
 .. code-block:: cmake
 
-    cmake_minimum_required(VERSION 3.10)
+  cmake_minimum_required(VERSION 3.10)
-    project(MyExeProject VERSION 1.0.0)
+  project(MyExeProject VERSION 1.0.0)
 
-    find_package(PNG REQUIRED)
+  # Make project-provided Find modules available
+  list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 
-    # Add path to a FindSomePackage.cmake file
+  find_package(SomePackage REQUIRED)
-    list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
+  add_executable(MyExe main.cpp)
-    find_package(SomePackage REQUIRED)
+  target_link_libraries(MyExe PRIVATE SomePrefix::LibName)
 
-    add_executable(MyExe main.cpp)
+Note that the above call to :command:`find_package` could be resolved by
-    target_link_libraries(MyExe PRIVATE
+a config file or a Find module.  It uses only the basic arguments supported
-        PNG::PNG
+by the :ref:`basic signature`.  A ``FindSomePackage.cmake`` file in the
-        SomePrefix::LibName
+``${CMAKE_CURRENT_SOURCE_DIR}/cmake`` directory would allow the
-    )
+:command:`find_package` command to succeed using module mode, for example.
+If no such module file is present, the system would be searched for a config
+file.
 
-The :variable:`<PackageName>_ROOT` variable is also
+
-searched as a prefix for :command:`find_package` calls using
+Downloading And Building From Source With ``FetchContent``
-module-file packages such as ``FindSomePackage``.
+==========================================================
+
+Dependencies do not necessarily have to be pre-built in order to use them
+with CMake.  They can be built from sources as part of the main project.
+The :module:`FetchContent` module provides functionality to download
+content (typically sources, but can be anything) and add it to the main
+project if the dependency also uses CMake.  The dependency's sources will
+be built along with the rest of the project, just as though the sources were
+part of the project's own sources.
+
+The general pattern is that the project should first declare all the
+dependencies it wants to use, then ask for them to be made available.
+The following demonstrates the principle (see :ref:`fetch-content-examples`
+for more):
+
+.. code-block:: cmake
+
+  include(FetchContent)
+  FetchContent_Declare(
+    googletest
+    GIT_REPOSITORY https://github.com/google/googletest.git
+    GIT_TAG        703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
+  )
+  FetchContent_Declare(
+    Catch2
+    GIT_REPOSITORY https://github.com/catchorg/Catch2.git
+    GIT_TAG        de6fe184a9ac1a06895cdd1c9b437f0a0bdf14ad # v2.13.4
+  )
+  FetchContent_MakeAvailable(googletest Catch2)
+
+Various download methods are supported, including downloading and extracting
+archives from a URL (a range of archive formats are supported), and a number
+of repository formats including Git, Subversion, and Mercurial.
+Custom download, update, and patch commands can also be used to support
+arbitrary use cases.
+
+When a dependency is added to the project with :module:`FetchContent`, the
+project links to the dependency's targets just like any other target from the
+project.  If the dependency provides namespaced targets of the form
+``SomePrefix::ThingName``, the project should link to those rather than to
+any non-namespaced targets.  See the next section for why this is recommended.
+
+Not all dependencies can be brought into the project this way.  Some
+dependencies define targets whose names clash with other targets from the
+project or other dependencies.  Concrete executable and library targets
+created by :command:`add_executable` and :command:`add_library` are global,
+so each one must be unique across the whole build.  If a dependency would
+add a clashing target name, it cannot be brought directly into the build
+with this method.
+
+``FetchContent`` And ``find_package()`` Integration
+===================================================
+
+.. versionadded:: 3.24
+
+Some dependencies support being added by either :command:`find_package` or
+:module:`FetchContent`.  Such dependencies must ensure they define the same
+namespaced targets in both installed and built-from-source scenarios.
+A consuming project then links to those namespaced targets and can handle
+both scenarios transparently, as long as the project does not use anything
+else that isn't provided by both methods.
+
+The project can indicate it is happy to accept a dependency by either method
+using the ``FIND_PACKAGE_ARGS`` option to :command:`FetchContent_Declare`.
+This allows :command:`FetchContent_MakeAvailable` to try satisfying the
+dependency with a call to :command:`find_package` first, using the arguments
+after the ``FIND_PACKAGE_ARGS`` keyword, if any.  If that doesn't find the
+dependency, it is built from source as described previously instead.
+
+.. code-block:: cmake
+
+  include(FetchContent)
+  FetchContent_Declare(
+    googletest
+    GIT_REPOSITORY https://github.com/google/googletest.git
+    GIT_TAG        703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
+    FIND_PACKAGE_ARGS NAMES GTest
+  )
+  FetchContent_MakeAvailable(googletest)
+
+  add_executable(ThingUnitTest thing_ut.cpp)
+  target_link_libraries(ThingUnitTest GTest::gtest_main)
+
+The above example calls
+:command:`find_package(googletest NAMES GTest) <find_package>` first.
+CMake provides a :module:`FindGTest` module, so if that finds a GTest package
+installed somewhere, it will make it available, and the dependency will not be
+built from source.  If no GTest package is found, it *will* be built from
+source.  In either case, the ``GTest::gtest_main`` target is expected to be
+defined, so we link our unit test executable to that target.
+
+High-level control is also available through the
+:variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable.  This can be set to
+``NEVER`` to disable all redirection to :command:`find_package`.  It can be
+set to ``ALWAYS`` to try :command:`find_package` even if ``FIND_PACKAGE_ARGS``
+was not specified (this should be used with caution).
+
+The project might also decide that a particular dependency must be built from
+source.  This might be needed if a patched or unreleased version of the
+dependency is required, or to satisfy some policy that requires all
+dependencies to be built from source.  The project can enforce this by adding
+the ``OVERRIDE_FIND_PACKAGE`` keyword to :command:`FetchContent_Declare`.
+A call to :command:`find_package` for that dependency will then be redirected
+to :command:`FetchContent_MakeAvailable` instead.
+
+.. code-block:: cmake
+
+  include(FetchContent)
+  FetchContent_Declare(
+    Catch2
+    URL https://intranet.mycomp.com/vendored/Catch2_2.13.4_patched.tgz
+    URL_HASH MD5=abc123...
+    OVERRIDE_FIND_PACKAGE
+  )
+
+  # The following is automatically redirected to FetchContent_MakeAvailable(Catch2)
+  find_package(Catch2)
+
+For more advanced use cases, see the
+:variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable.
+
+.. _dependency_providers_overview:
+
+Dependency Providers
+====================
+
+.. versionadded:: 3.24
+
+The preceding section discussed techniques that projects can use to specify
+their dependencies.  Ideally, the project shouldn't really care where a
+dependency comes from, as long as it provides the things it expects (often
+just some imported targets).  The project says what it needs and may also
+specify where to get it from, in the absence of any other details, so that it
+can still be built out-of-the-box.
+
+The developer, on the other hand, may be much more interested in controlling
+*how* a dependency is provided to the project.  You might want to use a
+particular version of a package that you built yourself.  You might want
+to use a third party package manager.  You might want to redirect some
+requests to a different URL on a system you control for security or
+performance reasons.  CMake supports these sort of scenarios through
+:ref:`dependency_providers`.
+
+A dependency provider can be set to intercept :command:`find_package` and
+:command:`FetchContent_MakeAvailable` calls.  The provider is given an
+opportunity to satisfy such requests before falling back to the built-in
+implementation if the provider doesn't fulfill it.
+
+Only one dependency provider can be set, and it can only be set at a very
+specific point early in the CMake run.
+The :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable lists CMake files
+that will be read while processing the first :command:`project()` call (and
+only that call).  This is the only time a dependency provider may be set.
+At most, one single provider is expected to be used throughout the whole
+project.
+
+For some scenarios, the user wouldn't need to know the details of how the
+dependency provider is set.  A third party may provide a file that can be
+added to :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES`, which will set up
+the dependency provider on the user's behalf.  This is the recommended
+approach for package managers.  The developer can use such a file like so::
+
+  cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/package_manager/setup.cmake ...
+
+For details on how to implement your own custom dependency provider, see the
+:command:`cmake_language(SET_DEPENDENCY_PROVIDER)` command.

Help/manual/cmake-buildsystem.7.rst

@@ -1040,24 +1040,26 @@ Additionally, IDEs will show the source files as part of the target for
 interactive reading and editing.
 
 A primary use-case for ``INTERFACE`` libraries is header-only libraries.
+Since CMake 3.23, header files may be associated with a library by adding
+them to a header set using the :command:`target_sources` command:
 
 .. code-block:: cmake
 
-  add_library(Eigen INTERFACE
+  add_library(Eigen INTERFACE)
-    src/eigen.h
+
-    src/vector.h
+  target_sources(Eigen INTERFACE
-    src/matrix.h
+    FILE_SET HEADERS
-    )
+      BASE_DIRS src
-  target_include_directories(Eigen INTERFACE
+      FILES src/eigen.h src/vector.h src/matrix.h
-    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
-    $<INSTALL_INTERFACE:include/Eigen>
   )
 
   add_executable(exe1 exe1.cpp)
   target_link_libraries(exe1 Eigen)
 
-Here, the usage requirements from the ``Eigen`` target are consumed and used
+When we specify the ``FILE_SET`` here, the ``BASE_DIRS`` we define automatically
-when compiling, but it has no effect on linking.
+become include directories in the usage requirements for the target ``Eigen``.
+The usage requirements from the target are consumed and used when compiling, but
+have no effect on linking.
 
 Another use-case is to employ an entirely target-focussed design for usage
 requirements:
@@ -1081,26 +1083,25 @@ This way, the build specification of ``exe1`` is expressed entirely as linked
 targets, and the complexity of compiler-specific flags is encapsulated in an
 ``INTERFACE`` library target.
 
-``INTERFACE`` libraries may be installed and exported.  Any content they refer
+``INTERFACE`` libraries may be installed and exported. We can install the
-to must be installed separately:
+default header set along with the target:
 
 .. code-block:: cmake
 
-  set(Eigen_headers
+  add_library(Eigen INTERFACE)
-    src/eigen.h
+
-    src/vector.h
+  target_sources(Eigen INTERFACE
-    src/matrix.h
+    FILE_SET HEADERS
-    )
+      BASE_DIRS src
-  add_library(Eigen INTERFACE ${Eigen_headers})
+      FILES src/eigen.h src/vector.h src/matrix.h
-  target_include_directories(Eigen INTERFACE
-    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
-    $<INSTALL_INTERFACE:include/Eigen>
   )
 
-  install(TARGETS Eigen EXPORT eigenExport)
+  install(TARGETS Eigen EXPORT eigenExport
+    FILE_SET HEADERS DESTINATION include/Eigen)
   install(EXPORT eigenExport NAMESPACE Upstream::
     DESTINATION lib/cmake/Eigen
   )
-  install(FILES ${Eigen_headers}
+
-    DESTINATION include/Eigen
+Here, the headers defined in the header set are installed to ``include/Eigen``.
-  )
+The install destination automatically becomes an include directory that is a
+usage requirement for consumers.

Help/manual/cmake-developer.7.rst

@@ -242,6 +242,69 @@ backwards compatibility for any old names that were actually in use.
 Make sure you comment them as deprecated, so that no-one starts using
 them.
 
+.. _`Find Using Windows Registry`:
+
+Find Using Windows Registry
+---------------------------
+
+.. versionchanged:: 3.24
+
+Options ``HINTS`` and ``PATHS`` of :command:`find_file`,
+:command:`find_library`, :command:`find_path`, :command:`find_program`, and
+:command:`find_package` commands offer the possibility, on ``Windows``
+platform, to query the registry.
+
+The formal syntax, as specified using
+`BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with
+the regular extensions, for registry query is the following:
+
+.. raw:: latex
+
+   \begin{small}
+
+.. productionlist::
+  registry_query: '[' `sep_definition`? `root_key`
+                :     ((`key_separator` `sub_key`)? (`value_separator` `value_name`_)?)? ']'
+  sep_definition: '{' `value_separator` '}'
+  root_key: 'HKLM' | 'HKEY_LOCAL_MACHINE' | 'HKCU' | 'HKEY_CURRENT_USER' |
+          : 'HKCR' | 'HKEY_CLASSES_ROOT' | 'HKCC' | 'HKEY_CURRENT_CONFIG' |
+          : 'HKU' | 'HKEY_USERS'
+  sub_key: `element` (`key_separator` `element`)*
+  key_separator: '/' | '\\'
+  value_separator: `element` | ';'
+  value_name: `element` | '(default)'
+  element: `character`\+
+  character: <any character except `key_separator` and `value_separator`>
+
+.. raw:: latex
+
+   \end{small}
+
+The :token:`sep_definition` optional item offers the possibility to specify
+the string used to separate the :token:`sub_key` from the :token:`value_name`
+item. If not specified, the character ``;`` is used. Multiple
+:token:`registry_query` items can be specified as part of a path.
+
+.. code-block:: cmake
+
+  # example using default separator
+  find_file(... PATHS "/root/[HKLM/Stuff;InstallDir]/lib[HKLM\\\\Stuff;Architecture]")
+
+  # example using different specified separators
+  find_library(... HINTS "/root/[{|}HKCU/Stuff|InstallDir]/lib[{@@}HKCU\\\\Stuff@@Architecture]")
+
+If the :token:`value_name` item is not specified or has the special name
+``(default)``, the content of the default value, if any, will be returned. The
+supported types for the :token:`value_name` are:
+
+* ``REG_SZ``.
+* ``REG_EXPAND_SZ``. The returned data is expanded.
+* ``REG_DWORD``.
+* ``REG_QWORD``.
+
+When the registry query failed, typically because the key does not exist or
+the data type is not supported, the string ``/REGISTRY-NOTFOUND`` is substituted
+to the ``[]`` query expression.
 
 A Sample Find Module
 --------------------

Help/manual/cmake-env-variables.7.rst

@@ -28,9 +28,11 @@ Environment Variables that Control the Build
 .. toctree::
    :maxdepth: 1
 
+   /envvar/ADSP_ROOT
    /envvar/CMAKE_APPLE_SILICON_PROCESSOR
    /envvar/CMAKE_BUILD_PARALLEL_LEVEL
    /envvar/CMAKE_BUILD_TYPE
+   /envvar/CMAKE_COLOR_DIAGNOSTICS
    /envvar/CMAKE_CONFIGURATION_TYPES
    /envvar/CMAKE_CONFIG_TYPE
    /envvar/CMAKE_EXPORT_COMPILE_COMMANDS

Help/manual/cmake-language.7.rst

@@ -582,7 +582,8 @@ Scope
  They are never cached.
 
 References
- `Variable References`_ have the form ``$ENV{<variable>}``.
+ `Variable References`_ have the form ``$ENV{<variable>}``, using the
+ :variable:`ENV` operator.
 
 Initialization
  Initial values of the CMake environment variables are those of
@@ -594,6 +595,13 @@ Initialization
  Changed values are not written back to the calling process,
  and they are not seen by subsequent build or test processes.
 
+ See the :ref:`cmake -E env <Run a Command-Line Tool>` command-line
+ tool to run a command in a modified environment.
+
+Inspection
+ See the :ref:`cmake -E environment <Run a Command-Line Tool>` command-line
+ tool to display all current environment variables.
+
 The :manual:`cmake-env-variables(7)` manual documents environment
 variables that have special meaning to CMake.
 

Help/manual/cmake-modules.7.rst

@@ -317,7 +317,6 @@ used directly.
    /module/CPackFreeBSD
    /module/CPackNSIS
    /module/CPackNuGet
-   /module/CPackPackageMaker
    /module/CPackProductBuild
    /module/CPackRPM
    /module/CPackWIX

Help/manual/cmake-policies.7.rst

@@ -52,6 +52,23 @@ to determine whether to report an error on use of deprecated macros or
 functions.
 
 
+Policies Introduced by CMake 3.24
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0139: The if() command supports path comparisons using PATH_EQUAL operator. </policy/CMP0139>
+   CMP0138: CheckIPOSupported uses flags from calling project. </policy/CMP0138>
+   CMP0137: try_compile() passes platform variables in project mode. </policy/CMP0137>
+   CMP0136: Watcom runtime library flags are selected by an abstraction. </policy/CMP0136>
+   CMP0135: ExternalProject ignores timestamps in archives by default for the URL download method. </policy/CMP0135>
+   CMP0134: Fallback to \"HOST\" Windows registry view when \"TARGET\" view is not usable. </policy/CMP0134>
+   CMP0133: The CPack module disables SLA by default in the CPack DragNDrop Generator. </policy/CMP0133>
+   CMP0132: Do not set compiler environment variables on first run. </policy/CMP0132>
+   CMP0131: LINK_LIBRARIES supports the LINK_ONLY generator expression. </policy/CMP0131>
+   CMP0130: while() diagnoses condition evaluation errors. </policy/CMP0130>
+
 Policies Introduced by CMake 3.23
 =================================
 

Help/manual/cmake-presets.7.rst

@@ -42,7 +42,22 @@ The root object recognizes the following fields:
 ``version``
 
   A required integer representing the version of the JSON schema.
-  The supported versions are ``1``, ``2``, ``3``, and ``4``.
+  The supported versions are:
+
+  ``1``
+    .. versionadded:: 3.19
+
+  ``2``
+    .. versionadded:: 3.20
+
+  ``3``
+    .. versionadded:: 3.21
+
+  ``4``
+    .. versionadded:: 3.23
+
+  ``5``
+    .. versionadded:: 3.24
 
 ``cmakeMinimumRequired``
 
@@ -715,6 +730,12 @@ that may contain the following fields:
     bytes. Equivalent to passing ``--test-output-size-failed`` on the
     command line.
 
+  ``testOutputTruncation``
+
+    An optional string specifying the test output truncation mode. Equivalent
+    to passing ``--test-output-truncation`` on the command line."
+    This is allowed in preset files specifying version ``5`` or above.
+
   ``maxTestNameWidth``
 
     An optional integer specifying the maximum width of a test name to
@@ -1062,6 +1083,17 @@ Recognized macros include:
 
   A literal dollar sign (``$``).
 
+``${pathListSep}``
+
+  Native character for separating lists of paths, such as ``:`` or ``;``.
+
+  For example, by setting ``PATH`` to
+  ``/path/to/ninja/bin${pathListSep}$env{PATH}``, ``${pathListSep}`` will
+  expand to the underlying operating system's character used for
+  concatenation in ``PATH``.
+
+  This is allowed in preset files specifying version ``5`` or above.
+
 ``$env{<variable-name>}``
 
   Environment variable with name ``<variable-name>``. The variable name may

Help/manual/cmake-properties.7.rst

@@ -171,6 +171,7 @@ Properties on Targets
    /prop_tgt/COMPILE_PDB_NAME_CONFIG
    /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY
    /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG
+   /prop_tgt/COMPILE_WARNING_AS_ERROR
    /prop_tgt/CONFIG_OUTPUT_NAME
    /prop_tgt/CONFIG_POSTFIX
    /prop_tgt/CROSSCOMPILING_EMULATOR
@@ -262,10 +263,13 @@ Properties on Targets
    /prop_tgt/INTERFACE_COMPILE_FEATURES
    /prop_tgt/INTERFACE_COMPILE_OPTIONS
    /prop_tgt/INTERFACE_HEADER_SETS
+   /prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY
    /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES
    /prop_tgt/INTERFACE_LINK_DEPENDS
    /prop_tgt/INTERFACE_LINK_DIRECTORIES
    /prop_tgt/INTERFACE_LINK_LIBRARIES
+   /prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT
+   /prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
    /prop_tgt/INTERFACE_LINK_OPTIONS
    /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE
    /prop_tgt/INTERFACE_PRECOMPILE_HEADERS
@@ -306,6 +310,8 @@ Properties on Targets
    /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG
    /prop_tgt/LINK_LIBRARIES
    /prop_tgt/LINK_LIBRARIES_ONLY_TARGETS
+   /prop_tgt/LINK_LIBRARY_OVERRIDE
+   /prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY
    /prop_tgt/LINK_OPTIONS
    /prop_tgt/LINK_SEARCH_END_STATIC
    /prop_tgt/LINK_SEARCH_START_STATIC
@@ -376,6 +382,7 @@ Properties on Targets
    /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE
    /prop_tgt/UNITY_BUILD_MODE
    /prop_tgt/UNITY_BUILD_UNIQUE_ID
+   /prop_tgt/VERIFY_INTERFACE_HEADER_SETS
    /prop_tgt/VERSION
    /prop_tgt/VISIBILITY_INLINES_HIDDEN
    /prop_tgt/VS_CONFIGURATION_TYPE
@@ -389,6 +396,7 @@ Properties on Targets
    /prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname
    /prop_tgt/VS_DOTNET_REFERENCES
    /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL
+   /prop_tgt/VS_DOTNET_STARTUP_OBJECT
    /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION
    /prop_tgt/VS_DPI_AWARE
    /prop_tgt/VS_GLOBAL_KEYWORD
@@ -400,6 +408,7 @@ Properties on Targets
    /prop_tgt/VS_JUST_MY_CODE_DEBUGGING
    /prop_tgt/VS_KEYWORD
    /prop_tgt/VS_MOBILE_EXTENSIONS_VERSION
+   /prop_tgt/VS_NO_COMPILE_BATCHING
    /prop_tgt/VS_NO_SOLUTION_DEPLOY
    /prop_tgt/VS_PACKAGE_REFERENCES
    /prop_tgt/VS_PLATFORM_TOOLSET
@@ -416,6 +425,7 @@ Properties on Targets
    /prop_tgt/VS_WINRT_COMPONENT
    /prop_tgt/VS_WINRT_EXTENSIONS
    /prop_tgt/VS_WINRT_REFERENCES
+   /prop_tgt/WATCOM_RUNTIME_LIBRARY
    /prop_tgt/WIN32_EXECUTABLE
    /prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS
    /prop_tgt/XCODE_ATTRIBUTE_an-attribute
@@ -451,6 +461,7 @@ Properties on Targets
    /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
    /prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY
    /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS
+   /prop_tgt/XCODE_XCCONFIG
    /prop_tgt/XCTEST
 
 .. _`Test Properties`:

Help/manual/cmake-toolchains.7.rst

@@ -301,6 +301,28 @@ Windows Store may look like this:
   set(CMAKE_SYSTEM_NAME WindowsStore)
   set(CMAKE_SYSTEM_VERSION 8.1)
 
+.. _`Cross Compiling for ADSP SHARC/Blackfin`:
+
+Cross Compiling for ADSP SHARC/Blackfin
+---------------------------------------
+
+Cross-compiling for ADSP SHARC or Blackfin can be configured
+by setting the :variable:`CMAKE_SYSTEM_NAME` variable to ``ADSP``
+and the :variable:`CMAKE_SYSTEM_PROCESSOR` variable
+to the "part number", excluding the ``ADSP-`` prefix,
+for example, ``21594``, ``SC589``, etc.
+This value is case insensitive.
+
+CMake will automatically search for CCES or VDSP++ installs
+in their default install locations
+and select the most recent version found.
+CCES will be selected over VDSP++ if both are installed.
+Custom install paths can be set via the :variable:`CMAKE_ADSP_ROOT` variable
+or the :envvar:`ADSP_ROOT` environment variable.
+
+The compiler (``cc21k`` vs. ``ccblkfn``) is selected automatically
+based on the :variable:`CMAKE_SYSTEM_PROCESSOR` value provided.
+
 .. _`Cross Compiling for Android`:
 
 Cross Compiling for Android

Help/manual/cmake-variables.7.rst

@@ -59,6 +59,7 @@ Variables that Provide Information
    /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES
    /variable/CMAKE_FIND_DEBUG_MODE
    /variable/CMAKE_FIND_PACKAGE_NAME
+   /variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR
    /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION
    /variable/CMAKE_FIND_PACKAGE_SORT_ORDER
    /variable/CMAKE_GENERATOR
@@ -172,6 +173,7 @@ Variables that Change Behavior
    /variable/CMAKE_CODEBLOCKS_COMPILER_ID
    /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES
    /variable/CMAKE_CODELITE_USE_TARGETS
+   /variable/CMAKE_COLOR_DIAGNOSTICS
    /variable/CMAKE_COLOR_MAKEFILE
    /variable/CMAKE_CONFIGURATION_TYPES
    /variable/CMAKE_DEPENDS_IN_PROJECT_ONLY
@@ -197,6 +199,7 @@ Variables that Change Behavior
    /variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY
    /variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG
    /variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS
+   /variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL
    /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE
    /variable/CMAKE_FIND_ROOT_PATH
    /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
@@ -204,6 +207,7 @@ Variables that Change Behavior
    /variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
    /variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
    /variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH
+   /variable/CMAKE_FIND_USE_INSTALL_PREFIX
    /variable/CMAKE_FIND_USE_CMAKE_PATH
    /variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH
    /variable/CMAKE_FIND_USE_PACKAGE_REGISTRY
@@ -239,6 +243,7 @@ Variables that Change Behavior
    /variable/CMAKE_PROJECT_INCLUDE_BEFORE
    /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE
    /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE
+   /variable/CMAKE_PROJECT_TOP_LEVEL_INCLUDES
    /variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName
    /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
    /variable/CMAKE_STAGING_PREFIX
@@ -283,6 +288,7 @@ Variables that Change Behavior
    /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP
    /variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY
    /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS
+   /variable/CMAKE_XCODE_XCCONFIG
    /variable/PackageName_ROOT
 
 Variables that Describe the System
@@ -344,6 +350,7 @@ Variables that Control the Build
 .. toctree::
    :maxdepth: 1
 
+   /variable/CMAKE_ADSP_ROOT
    /variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS
    /variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS
    /variable/CMAKE_ANDROID_API
@@ -395,6 +402,7 @@ Variables that Control the Build
    /variable/CMAKE_BUILD_WITH_INSTALL_RPATH
    /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY
    /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG
+   /variable/CMAKE_COMPILE_WARNING_AS_ERROR
    /variable/CMAKE_CONFIG_POSTFIX
    /variable/CMAKE_CROSS_CONFIGS
    /variable/CMAKE_CTEST_ARGUMENTS
@@ -437,7 +445,11 @@ Variables that Control the Build
    /variable/CMAKE_LANG_CPPCHECK
    /variable/CMAKE_LANG_CPPLINT
    /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE
+   /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE
+   /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED
    /variable/CMAKE_LANG_LINKER_LAUNCHER
+   /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE
+   /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED
    /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG
    /variable/CMAKE_LANG_LINK_LIBRARY_FLAG
    /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG
@@ -447,9 +459,13 @@ Variables that Control the Build
    /variable/CMAKE_LIBRARY_PATH_FLAG
    /variable/CMAKE_LINK_DEF_FILE_FLAG
    /variable/CMAKE_LINK_DEPENDS_NO_SHARED
+   /variable/CMAKE_LINK_GROUP_USING_FEATURE
+   /variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED
    /variable/CMAKE_LINK_INTERFACE_LIBRARIES
    /variable/CMAKE_LINK_LIBRARY_FILE_FLAG
    /variable/CMAKE_LINK_LIBRARY_FLAG
+   /variable/CMAKE_LINK_LIBRARY_USING_FEATURE
+   /variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED
    /variable/CMAKE_LINK_WHAT_YOU_USE
    /variable/CMAKE_LINK_WHAT_YOU_USE_CHECK
    /variable/CMAKE_MACOSX_BUNDLE
@@ -487,17 +503,20 @@ Variables that Control the Build
    /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT
    /variable/CMAKE_STATIC_LINKER_FLAGS_INIT
    /variable/CMAKE_TRY_COMPILE_CONFIGURATION
+   /variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES
    /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES
    /variable/CMAKE_TRY_COMPILE_TARGET_TYPE
    /variable/CMAKE_UNITY_BUILD
    /variable/CMAKE_UNITY_BUILD_BATCH_SIZE
    /variable/CMAKE_UNITY_BUILD_UNIQUE_ID
    /variable/CMAKE_USE_RELATIVE_PATHS
+   /variable/CMAKE_VERIFY_INTERFACE_HEADER_SETS
    /variable/CMAKE_VISIBILITY_INLINES_HIDDEN
    /variable/CMAKE_VS_GLOBALS
    /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD
    /variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD
    /variable/CMAKE_VS_JUST_MY_CODE_DEBUGGING
+   /variable/CMAKE_VS_NO_COMPILE_BATCHING
    /variable/CMAKE_VS_SDK_EXCLUDE_DIRECTORIES
    /variable/CMAKE_VS_SDK_EXECUTABLE_DIRECTORIES
    /variable/CMAKE_VS_SDK_INCLUDE_DIRECTORIES
@@ -506,6 +525,7 @@ Variables that Control the Build
    /variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES
    /variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES
    /variable/CMAKE_VS_WINRT_BY_DEFAULT
+   /variable/CMAKE_WATCOM_RUNTIME_LIBRARY
    /variable/CMAKE_WIN32_EXECUTABLE
    /variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS
    /variable/CMAKE_XCODE_ATTRIBUTE_an-attribute
@@ -633,6 +653,7 @@ Variables for CTest
    /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS
    /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS
    /variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE
+   /variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION
    /variable/CTEST_CUSTOM_MEMCHECK_IGNORE
    /variable/CTEST_CUSTOM_POST_MEMCHECK
    /variable/CTEST_CUSTOM_POST_TEST

Help/manual/cmake.1.rst

@@ -197,6 +197,13 @@ Options
 
 .. include:: OPTIONS_BUILD.txt
 
+``--fresh``
+ .. versionadded:: 3.24
+
+ Perform a fresh configuration of the build tree.
+ This removes any existing ``CMakeCache.txt`` file and associated
+ ``CMakeFiles/`` directory, and recreates them from scratch.
+
 ``-L[A][H]``
  List non-advanced cached variables.
 
@@ -326,7 +333,8 @@ Options
          "cmd": "add_executable",
          "args": ["foo", "bar"],
          "time": 1579512535.9687231,
-         "frame": 2
+         "frame": 2,
+         "global_frame": 4
        }
 
      The members are:
@@ -336,7 +344,13 @@ Options
        was called.
 
      ``line``
-       The line in ``file`` of the function call.
+       The line in ``file`` where the function call begins.
+
+     ``line_end``
+       If the function call spans multiple lines, this field will
+       be set to the line where the function call ends. If the function
+       calls spans a single line, this field will be unset. This field
+       was added in minor version 2 of the ``json-v1`` format.
 
      ``defer``
        Optional member that is present when the function call was deferred
@@ -353,7 +367,13 @@ Options
        Timestamp (seconds since epoch) of the function call.
 
      ``frame``
-       Stack frame depth of the function that was called.
+       Stack frame depth of the function that was called, within the
+       context of the  ``CMakeLists.txt`` being processed currently.
+
+     ``global_frame``
+       Stack frame depth of the function that was called, tracked globally
+       across all ``CMakeLists.txt`` files involved in the trace. This field
+       was added in minor version 2 of the ``json-v1`` format.
 
      Additionally, the first JSON document outputted contains the
      ``version`` key for the current major and minor version of the
@@ -365,7 +385,7 @@ Options
        {
          "version": {
            "major": 1,
-           "minor": 1
+           "minor": 2
          }
        }
 
@@ -406,6 +426,11 @@ Options
  in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`.
  This flag tells CMake to warn about other files as well.
 
+``--compile-no-warning-as-error``
+ Ignore target property :prop_tgt:`COMPILE_WARNING_AS_ERROR` and variable
+ :variable:`CMAKE_COMPILE_WARNING_AS_ERROR`, preventing warnings from being
+ treated as errors on compile.
+
 ``--profiling-output=<path>``
  Used in conjunction with ``--profiling-format`` to output to a given path.
 
@@ -599,6 +624,8 @@ in the set of :variable:`CMAKE_ARGV<n> <CMAKE_ARGV0>` variables passed to the
 script (including the ``--`` itself).
 
 
+.. _`Run a Command-Line Tool`:
+
 Run a Command-Line Tool
 =======================
 
@@ -673,11 +700,17 @@ Available commands are:
     ``true`` if cmake supports server-mode and ``false`` otherwise.
     Always false since CMake 3.20.
 
-``cat <files>...``
+``cat [--] <files>...``
   .. versionadded:: 3.18
 
   Concatenate files and print on the standard output.
 
+  .. versionadded:: 3.24
+    Added support for the double dash argument ``--``. This basic implementation
+    of ``cat`` does not support any options, so using a option starting with
+    ``-`` will result in an error. Use ``--`` to indicate the end of options, in
+    case a file starts with ``-``.
+
 ``chdir <dir> <cmd> [<arg>...]``
   Change the current working directory and run a command.
 
@@ -746,11 +779,16 @@ Available commands are:
 ``echo_append [<string>...]``
   Displays arguments as text but no new line.
 
-``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...``
+``env [--unset=NAME ...] [NAME=VALUE ...] [--] <command> [<arg>...]``
   .. versionadded:: 3.1
 
   Run command in a modified environment.
 
+  .. versionadded:: 3.24
+    Added support for the double dash argument ``--``. Use ``--`` to stop
+    interpreting options/environment variables and treat the next argument as
+    the command, even if it start with ``-`` or contains a ``=``.
+
 ``environment``
   Display the current environment variables.
 
@@ -843,16 +881,16 @@ Available commands are:
   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>...``
+``rm [-rRf] [--] <file|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
   the behavior to return a zero exit code (i.e. success) in such
-  situations instead.
+  situations instead. Use ``--`` to stop interpreting options and treat all
+  remaining arguments as paths, even if they start with ``-``.
 
 ``server``
   Launch :manual:`cmake-server(7)` mode.
@@ -924,6 +962,12 @@ Available commands are:
 
     Specify modification time recorded in tarball entries.
 
+  ``--touch``
+    .. versionadded:: 3.24
+
+    Use current local timestamp instead of extracting file timestamps
+    from the archive.
+
   ``--``
     .. versionadded:: 3.1
 
@@ -1022,6 +1066,18 @@ To view the presets available for a project, use
 
   cmake <source-dir> --list-presets
 
+
+.. _`CMake Exit Code`:
+
+Return Value (Exit Code)
+========================
+
+Upon regular termination, the ``cmake`` executable returns the exit code ``0``.
+
+If termination is caused by the command :command:`message(FATAL_ERROR)`,
+or another error condition, then a non-zero exit code is returned.
+
+
 See Also
 ========
 

Help/manual/ctest.1.rst

@@ -357,11 +357,21 @@ See `Build and Test Mode`_.
 Specify the directory in which to look for tests.
 
 ``--test-output-size-passed <size>``
+ .. versionadded:: 3.4
+
  Limit the output for passed tests to ``<size>`` bytes.
 
 ``--test-output-size-failed <size>``
+ .. versionadded:: 3.4
+
  Limit the output for failed tests to ``<size>`` bytes.
 
+``--test-output-truncation <mode>``
+ .. versionadded:: 3.24
+
+ Truncate ``tail`` (default), ``middle`` or ``head`` of test output once
+ maximum output size is reached.
+
 ``--overwrite``
  Overwrite CTest configuration option.
 

Help/manual/presets/example.json

@@ -1,5 +1,5 @@
 {
-  "version": 4,
+  "version": 5,
   "cmakeMinimumRequired": {
     "major": 3,
     "minor": 23,

Help/manual/presets/schema.json

@@ -57,6 +57,21 @@
         "include": { "$ref": "#/definitions/include"}
       },
       "additionalProperties": false
+    },
+    {
+      "properties": {
+        "version": {
+          "const": 5,
+          "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/testPresetsV5"},
+        "include": { "$ref": "#/definitions/include"}
+      },
+      "additionalProperties": false
     }
   ],
   "required": [
@@ -673,6 +688,28 @@
         "additionalProperties": false
       }
     },
+    "testPresetsItemsV5": {
+      "type": "array",
+      "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "output": {
+            "type": "object",
+            "description": "An optional object specifying output options.",
+            "properties": {
+              "testOutputTruncation": {
+                "type": "string",
+                "description": "An optional string specifying the test output truncation mode. Equivalent to passing --test-output-truncation on the command line. Must be one of the following values: \"tail\", \"middle\", or \"head\".",
+                "enum": [
+                  "tail", "middle", "head"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
     "testPresetsItemsV3": {
       "type": "array",
       "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.",
@@ -821,8 +858,7 @@
                 "type": "integer",
                 "description": "An optional integer specifying the maximum width of a test name to output. Equivalent to passing --max-width on the command line."
               }
-            },
+            }
-            "additionalProperties": false
           },
           "filter": {
             "type": "object",
@@ -998,6 +1034,39 @@
         ]
       }
     },
+    "testPresetsV5": {
+      "type": "array",
+      "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.",
+      "allOf": [
+        { "$ref": "#/definitions/testPresetsItemsV2" },
+        { "$ref": "#/definitions/testPresetsItemsV3" },
+        { "$ref": "#/definitions/testPresetsItemsV5" }
+      ],
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {},
+          "hidden": {},
+          "inherits": {},
+          "configurePreset": {},
+          "vendor": {},
+          "displayName": {},
+          "description": {},
+          "inheritConfigureEnvironment": {},
+          "environment": {},
+          "configuration": {},
+          "overwriteConfigurationFile": {},
+          "output": {},
+          "filter": {},
+          "execution": {},
+          "condition": {}
+        },
+        "required": [
+          "name"
+        ],
+        "additionalProperties": false
+      }
+    },
     "testPresetsV3": {
       "type": "array",
       "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.",

Help/module/CPackPackageMaker.rst

@@ -1,4 +0,0 @@
-CPackPackageMaker
------------------
-
-The documentation for the CPack PackageMaker generator has moved here: :cpack_gen:`CPack PackageMaker Generator`

Help/policy/CMP0097.rst

@@ -4,9 +4,11 @@ CMP0097
 .. versionadded:: 3.16
 
 :command:`ExternalProject_Add` with ``GIT_SUBMODULES ""`` initializes no
-submodules.
+submodules.  The policy also applies to :command:`FetchContent_Declare`,
+which uses the same download and update features as
+:command:`ExternalProject_Add`.
 
-The module provides a ``GIT_SUBMODULES`` option which controls what submodules
+The commands provide a ``GIT_SUBMODULES`` option which controls what submodules
 to initialize and update. Starting with CMake 3.16, explicitly setting
 ``GIT_SUBMODULES`` to an empty string means no submodules will be initialized
 or updated.

Help/policy/CMP0112.rst

@@ -18,6 +18,7 @@ file name components no longer add a dependency on the evaluated target.
     - ``TARGET_PDB_FILE_NAME``
     - ``TARGET_PDB_FILE_DIR``
     - ``TARGET_BUNDLE_DIR``
+    - ``TARGET_BUNDLE_DIR_NAME``
     - ``TARGET_BUNDLE_CONTENT_DIR``
 
 

Help/policy/CMP0130.rst

@@ -0,0 +1,32 @@
+CMP0130
+-------
+
+.. versionadded:: 3.24
+
+:command:`while` diagnoses condition evaluation errors.
+
+CMake 3.23 and below accidentally tolerated errors encountered while
+evaluating the condition passed to the :command:`while` command
+(but not the :command:`if` command).  For example, the code
+
+.. code-block:: cmake
+
+  set(paren "(")
+  while(${paren})
+  endwhile()
+
+creates an unbalanced parenthesis during condition evaluation.
+
+CMake 3.24 and above prefer to diagnose such errors.  This policy
+provides compatibility for projects that have not been updated to
+fix their condition errors.
+
+The ``OLD`` behavior for this policy is to ignore errors in
+:command:`while` conditions.  The ``NEW`` behavior for this
+policy is to diagnose errors in :command:`while` conditions.
+
+This policy was introduced in CMake version 3.24.  CMake version |release|
+warns when the policy is not set and uses ``OLD`` behavior.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0131.rst

@@ -0,0 +1,31 @@
+CMP0131
+-------
+
+.. versionadded:: 3.24
+
+:prop_tgt:`LINK_LIBRARIES` supports the :genex:`$<LINK_ONLY:...>`
+generator expression.
+
+CMake 3.23 and below documented the :genex:`$<LINK_ONLY:...>` generator
+expression only for use in :prop_tgt:`INTERFACE_LINK_LIBRARIES`.
+When used in :prop_tgt:`LINK_LIBRARIES`, the content guarded inside
+:genex:`$<LINK_ONLY:...>` was always used, even when collecting non-linking
+usage requirements such as :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`.
+
+CMake 3.24 and above prefer to support :genex:`$<LINK_ONLY:...>`, when
+used in :prop_tgt:`LINK_LIBRARIES`, by using the guarded content only
+for link dependencies and not other usage requirements.  This policy
+provides compatibility for projects that have not been updated to
+account for this change.
+
+The ``OLD`` behavior for this policy is to use :prop_tgt:`LINK_LIBRARIES`
+content guarded by :genex:`$<LINK_ONLY:...>` even for non-linking
+usage requirements.  The ``NEW`` behavior for this policy is to use
+the guarded content only for link dependencies.
+
+This policy was introduced in CMake version 3.24.  Use the
+:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW``
+explicitly.  Unlike many policies, CMake version |release| does *not*
+warn when this policy is not set, and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0132.rst

@@ -0,0 +1,26 @@
+CMP0132
+-------
+
+.. versionadded:: 3.24
+
+Apart from when using the Xcode generator and some Visual Studio generators,
+CMake 3.23 and below will set environment variables like :envvar:`CC`,
+:envvar:`CXX`, etc. when the corresponding language is enabled.
+This only occurs on the very first time CMake is run in a build directory,
+and the environment variables are only defined at configure time, not build
+time. On subsequent CMake runs, these environment variables are not set,
+opening up the opportunity for different behavior between the first and
+subsequent CMake runs. CMake 3.24 and above prefer to not set these
+environment variables when a language is enabled, even on the first run in
+a build directory.
+
+The ``OLD`` behavior for this policy sets the relevant environment variable
+on the first run when a language is enabled. The ``NEW`` behavior for this
+policy does not set any such environment variables.
+
+This policy was introduced in CMake version 3.24. Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0133.rst

@@ -0,0 +1,32 @@
+CMP0133
+-------
+
+.. versionadded:: 3.24
+
+The :module:`CPack` module disables SLA by default in the
+:cpack_gen:`CPack DragNDrop Generator`.
+
+The :cpack_gen:`CPack DragNDrop Generator` in CMake 3.22 and below attach a
+Software License Agreement (SLA) to ``.dmg`` files using the file specified
+by :variable:`CPACK_RESOURCE_FILE_LICENSE`, if set to a non-default value.
+macOS 12.0 deprecated the tools used to do this, so CMake 3.23 added
+the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option to
+control the behavior.  CMake 3.23 enables that option by default for
+compatibility with older versions. CMake 3.24 and above prefer to *not*
+enable the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option by
+default. This policy provides compatibility with projects that have not
+been updated to account for the lack of a SLA in their ``.dmg`` packages.
+
+The ``OLD`` behavior for this policy is to enable
+:variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` by default.
+The ``NEW`` behavior for this policy is to not enable it by default.
+
+This policy was introduced in CMake version 3.24.  Use the
+:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW``
+explicitly. Unlike many 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_CMP0133 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
+variable to control the warning.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0134.rst

@@ -0,0 +1,39 @@
+CMP0134
+-------
+
+.. versionadded:: 3.24
+
+The default registry view is ``TARGET`` for the :command:`find_file`,
+:command:`find_path`, :command:`find_library`, and :command:`find_package`
+commands and ``BOTH`` for the :command:`find_program` command.
+
+The default registry views in CMake 3.23 and below are selected using the
+following rules:
+
+* if :variable:`CMAKE_SIZEOF_VOID_P` has value ``8``:
+
+  * Use view ``64`` for all ``find_*`` commands except :command:`find_program`
+    command.
+  * Use view ``64_32`` for :command:`find_program` command.
+
+* if :variable:`CMAKE_SIZEOF_VOID_P` has value ``4`` or is undefined:
+
+  * Use view ``32`` for all ``find_*`` commands except :command:`find_program`
+    command.
+  * Use view ``32_64`` for :command:`find_program` command.
+
+The ``OLD`` behavior for this policy is to use registry views ``64`` and
+``64_32`` or ``32_64`` and ``32`` as default, depending of
+:variable:`CMAKE_SIZEOF_VOID_P` variable value.
+The ``NEW`` behavior for this policy is to use registry views ``TARGET`` and
+``BOTH`` as default.
+
+This policy was introduced in CMake version 3.24.  Use the
+:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW``
+explicitly. Unlike many 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_CMP0133 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
+variable to control the warning.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0135.rst

@@ -0,0 +1,29 @@
+CMP0135
+-------
+
+.. versionadded:: 3.24
+
+When using the ``URL`` download method with the :command:`ExternalProject_Add`
+command, CMake 3.23 and below sets the timestamps of the extracted contents
+to the same as the timestamps in the archive. When the ``URL`` changes, the
+new archive is downloaded and extracted, but the timestamps of the extracted
+contents might not be newer than the previous contents. Anything that depends
+on the extracted contents might not be rebuilt, even though the contents may
+change.
+
+CMake 3.24 and above prefers to set the timestamps of all extracted contents
+to the time of the extraction. This ensures that anything that depends on the
+extracted contents will be rebuilt whenever the ``URL`` changes.
+
+The ``DOWNLOAD_EXTRACT_TIMESTAMP`` option to the
+:command:`ExternalProject_Add` command can be used to explicitly specify how
+timestamps should be handled. When ``DOWNLOAD_EXTRACT_TIMESTAMP`` is not
+given, this policy controls the default behavior. The ``OLD`` behavior for
+this policy is to restore the timestamps from the archive. The ``NEW``
+behavior sets the timestamps of extracted contents to the time of extraction.
+
+This policy was introduced in CMake version 3.24.  CMake version |release|
+warns when the policy is not set and uses ``OLD`` behavior.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0136.rst

@@ -0,0 +1,50 @@
+CMP0136
+-------
+
+.. versionadded:: 3.24
+
+Watcom runtime library flags are selected by an abstraction.
+
+Compilers targeting the Watcom ABI have flags to select the Watcom runtime
+library.
+
+In CMake 3.23 and below, Watcom runtime library selection flags are added to
+the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake
+automatically.  This allows users to edit their cache entries to adjust the
+flags.  However, the presence of such default flags is problematic for
+projects that want to choose a different runtime library programmatically.
+In particular, it requires string editing of the
+:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the
+CMake builtin defaults so they can be replaced.
+
+CMake 3.24 and above prefer to leave the Watcom runtime library selection flags
+out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead
+offer a first-class abstraction.  The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY`
+variable and :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property may be set to
+select the Watcom runtime library.  If they are not set then CMake uses the
+default value ``MultiThreadedDLL`` on Windows and ``SingleThreaded`` on other
+platforms, which is equivalent to the original flags.
+
+This policy provides compatibility with projects that have not been updated
+to be aware of the abstraction.  The policy setting takes effect as of the
+first :command:`project` or :command:`enable_language` command that enables
+a language whose compiler targets the Watcom ABI.
+
+.. note::
+
+  Once the policy has taken effect at the top of a project, that choice
+  must be used throughout the tree.  In projects that have nested projects
+  in subdirectories, be sure to convert everything together.
+
+The ``OLD`` behavior for this policy is to place Watcom runtime library
+flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache
+entries and ignore the :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` abstraction.
+The ``NEW`` behavior for this policy is to *not* place Watcom runtime
+library flags in the default cache entries and use the abstraction instead.
+
+This policy was introduced in CMake version 3.24.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0137.rst

@@ -0,0 +1,33 @@
+CMP0137
+-------
+
+.. versionadded:: 3.24
+
+:command:`try_compile` passes platform variables in project mode.
+
+The :command:`try_compile` command :ref:`source file <Try Compiling Source
+Files>` signature propagates CMake variables containing platform settings,
+and those specified by the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES`
+variable, into the generated test project.  This helps the test project drive
+the toolchain the same way the calling project will.  In CMake 3.23 and below,
+the :ref:`whole-project <Try Compiling Whole Projects>` signature does not
+propagate platform variables automatically.  CMake 3.24 and above prefer to
+propagate platform variables in the :ref:`whole-project <Try Compiling Whole
+Projects>` signature.  This policy provides compatibility with projects that
+have not been updated to expect the behavior.
+
+The ``OLD`` behavior for this policy is to not pass any additional variables to
+the :ref:`whole-project <Try Compiling Whole Projects>` signature.
+The ``NEW`` behavior for this policy is to pass the same variables that the
+:ref:`source file <Try Compiling Source Files>` signature does.
+
+Regardless of the policy setting, the
+:variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable may be set
+to suppress passing the platform variables through either signature.
+
+This policy was introduced in CMake version 3.24.  Use the
+:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW``
+explicitly. Unlike many policies, CMake version |release| does *not* warn
+by default when this policy is not set and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0138.rst

@@ -0,0 +1,31 @@
+CMP0138
+-------
+
+.. versionadded:: 3.24
+
+:module:`CheckIPOSupported` uses flags from calling project.
+
+The :module:`CheckIPOSupported` module :command:`check_ipo_supported`
+command compiles a test project to determine whether the toolchain
+supports :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION`.  CMake 3.23 and
+below run the check with the default values of the
+:variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`
+variables for the current environment and toolchain settings.
+However, some projects may modify these flag variables to add
+flags that affect availability of the toolchain's IPO features.
+CMake 3.24 and above prefer to honor the calling project's values
+for these variables.  This policy provides compatibility for projects
+that have not been updated to expect this behavior.
+
+The ``OLD`` behavior for this policy is to ignore the calling
+project's values of :variable:`CMAKE_<LANG>_FLAGS` and
+:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`.  The ``NEW`` behavior
+for this policy is to use the values of those variables as
+compiler flags in the test project.
+
+This policy was introduced in CMake version 3.24. Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0139.rst

@@ -0,0 +1,17 @@
+CMP0139
+-------
+
+.. versionadded:: 3.24
+
+The :command:`if` command supports path comparisons using ``PATH_EQUAL``
+operator.
+
+The ``OLD`` behavior for this policy is to ignore the ``PATH_EQUAL`` operator.
+The ``NEW`` behavior is to interpret the ``PATH_EQUAL`` operator.
+
+This policy was introduced in CMake version 3.24.
+CMake version |release| warns when the policy is not set and uses
+``OLD`` behavior.  Use the :command:`cmake_policy` command to set
+it to ``OLD`` or ``NEW`` explicitly.
+
+.. include:: DEPRECATED.txt

Help/prop_dir/RULE_LAUNCH_COMPILE.rst

@@ -3,5 +3,11 @@ RULE_LAUNCH_COMPILE
 
 Specify a launcher for compile rules.
 
-See the global property of the same name for details.  This overrides
+.. note::
-the global property for a directory.
+  This property is intended for internal use by :manual:`ctest(1)`.  Projects
+  and developers should use the :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target
+  properties or the associated :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER`
+  variables instead.
+
+See the :prop_gbl:`global property <RULE_LAUNCH_COMPILE>` of the same name
+for details.  This overrides the global property for a directory.

Help/prop_dir/RULE_LAUNCH_LINK.rst

@@ -3,5 +3,11 @@ RULE_LAUNCH_LINK
 
 Specify a launcher for link rules.
 
-See the global property of the same name for details.  This overrides
+.. note::
-the global property for a directory.
+  This property is intended for internal use by :manual:`ctest(1)`.  Projects
+  and developers should use the :prop_tgt:`<LANG>_LINKER_LAUNCHER` target
+  properties or the associated :variable:`CMAKE_<LANG>_LINKER_LAUNCHER`
+  variables instead.
+
+See the :prop_gbl:`global property <RULE_LAUNCH_LINK>` of the same name for
+details.  This overrides the global property for a directory.

Help/prop_gbl/RULE_LAUNCH_COMPILE.rst

@@ -3,6 +3,12 @@ RULE_LAUNCH_COMPILE
 
 Specify a launcher for compile rules.
 
+.. note::
+  This property is intended for internal use by :manual:`ctest(1)`.  Projects
+  and developers should use the :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target
+  properties or the associated :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER`
+  variables instead.
+
 :ref:`Makefile Generators` and the :generator:`Ninja` generator prefix
 compiler commands with the given launcher command line.
 This is intended to allow launchers to intercept build problems

Help/prop_gbl/RULE_LAUNCH_LINK.rst

@@ -3,6 +3,12 @@ RULE_LAUNCH_LINK
 
 Specify a launcher for link rules.
 
+.. note::
+  This property is intended for internal use by :manual:`ctest(1)`.  Projects
+  and developers should use the :prop_tgt:`<LANG>_LINKER_LAUNCHER` target
+  properties or the associated :variable:`CMAKE_<LANG>_LINKER_LAUNCHER`
+  variables instead.
+
 :ref:`Makefile Generators` and the :generator:`Ninja` generator prefix
 link and archive commands with the given launcher command line.
 This is intended to allow launchers to intercept build problems

Help/prop_sf/VS_CSHARP_tagname.rst

@@ -16,7 +16,7 @@ Example usage:
 
 .. code-block:: cmake
 
-  set_source_files_property(<filename>
+  set_source_files_properties(<filename>
            PROPERTIES
            VS_CSHARP_DependentUpon <other file>
            VS_CSHARP_SubType "Form")

Help/prop_test/ENVIRONMENT_MODIFICATION.rst

@@ -19,17 +19,19 @@ property's value.  The ``OP`` may be one of:
     to its state from the rest of the CTest execution.
   - ``set``: Replaces the current value of ``MYVAR`` with ``VALUE``.
   - ``unset``: Unsets the current value of ``MYVAR``.
-  - ``string_append``: Appends ``VALUE`` to the current value of ``MYVAR``.
+  - ``string_append``: Appends singular ``VALUE`` to the current value of
-  - ``string_prepend``: Prepends ``VALUE`` to the current value of ``MYVAR``.
+    ``MYVAR``.
-  - ``path_list_append``: Appends ``VALUE`` to the current value of ``MYVAR``
+  - ``string_prepend``: Prepends singular ``VALUE`` to the current value of
-    using the host platform's path list separator (``;`` on Windows and ``:``
+    ``MYVAR``.
-    elsewhere).
+  - ``path_list_append``: Appends singular ``VALUE`` to the current value of
-  - ``path_list_prepend``: Prepends ``VALUE`` to the current value of
     ``MYVAR`` using the host platform's path list separator (``;`` on Windows
     and ``:`` elsewhere).
-  - ``cmake_list_append``: Appends ``VALUE`` to the current value of ``MYVAR``
+  - ``path_list_prepend``: Prepends singular ``VALUE`` to the current value of
-    using ``;`` as the separator.
+    ``MYVAR`` using the host platform's path list separator (``;`` on Windows
-  - ``cmake_list_prepend``: Prepends ``VALUE`` to the current value of
+    and ``:`` elsewhere).
+  - ``cmake_list_append``: Appends singular ``VALUE`` to the current value of
+    ``MYVAR`` using ``;`` as the separator.
+  - ``cmake_list_prepend``: Prepends singular ``VALUE`` to the current value of
     ``MYVAR`` using ``;`` as the separator.
 
 Unrecognized ``OP`` values will result in the test failing before it is

Help/prop_tgt/COMPILE_WARNING_AS_ERROR.rst

@@ -0,0 +1,10 @@
+COMPILE_WARNING_AS_ERROR
+------------------------
+
+.. versionadded:: 3.24
+
+Specify whether to treat warnings on compile as errors.
+If enabled, adds a flag to treat warnings on compile as errors.
+
+This property is initialized by the value of the variable
+:variable:`CMAKE_COMPILE_WARNING_AS_ERROR` if it is set when a target is created.

Help/prop_tgt/CUDA_ARCHITECTURES.rst

@@ -34,6 +34,11 @@ The ``CUDA_ARCHITECTURES`` may be set to one of the following special values:
   Compile for all supported major real architectures, and the highest
   major virtual architecture.
 
+``native``
+  .. versionadded:: 3.24
+
+  Compile for the architecture(s) of the host's GPU(s).
+
 Examples
 ^^^^^^^^
 

Help/prop_tgt/INTERFACE_HEADER_SETS_TO_VERIFY.rst

@@ -0,0 +1,13 @@
+INTERFACE_HEADER_SETS_TO_VERIFY
+-------------------------------
+
+.. versionadded:: 3.24
+
+Used to specify which ``PUBLIC`` and ``INTERFACE`` header sets of a target
+should be verified.
+
+This property contains a semicolon-separated list of header sets which
+should be verified if :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` is set to
+``TRUE``. If the list is empty, all ``PUBLIC`` and ``INTERFACE`` header sets
+are verified. (If the project does not want to verify any header sets on the
+target, simply set :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` to ``FALSE``.)

Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst

@@ -26,6 +26,12 @@ manual for more on defining buildsystem properties.
 
 .. include:: LINK_LIBRARIES_INDIRECTION.txt
 
+``INTERFACE_LINK_LIBRARIES`` adds transitive link dependencies for a
+target's dependents.  In advanced use cases, one may update the
+direct link dependencies of a target's dependents by using the
+:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
+:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties.
+
 Creating Relocatable Packages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.rst

@@ -0,0 +1,236 @@
+INTERFACE_LINK_LIBRARIES_DIRECT
+-------------------------------
+
+.. versionadded:: 3.24
+
+List of libraries that consumers of this library should treat
+as direct link dependencies.
+
+This target property may be set to *include* items in a dependent
+target's final set of direct link dependencies.  See the
+:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target property
+to exclude items.
+
+The initial set of a dependent target's direct link dependencies is
+specified by its :prop_tgt:`LINK_LIBRARIES` target property.  Indirect
+link dependencies are specified by the transitive closure of the direct
+link dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
+Any link dependency may specify additional direct link dependencies
+using the ``INTERFACE_LINK_LIBRARIES_DIRECT`` target property.
+The set of direct link dependencies is then filtered to exclude items named
+by any dependency's :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`
+target property.
+
+.. |INTERFACE_PROPERTY_LINK_DIRECT| replace:: ``INTERFACE_LINK_LIBRARIES_DIRECT``
+.. include:: INTERFACE_LINK_LIBRARIES_DIRECT.txt
+
+Direct Link Dependencies as Usage Requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``INTERFACE_LINK_LIBRARIES_DIRECT`` and
+``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target properties
+are :ref:`usage requirements <Target Usage Requirements>`.
+Their effects propagate to dependent targets transitively, and can
+therefore affect the direct link dependencies of every target in a
+chain of dependent libraries.  Whenever some library target ``X`` links
+to another library target ``Y`` whose direct or transitive usage
+requirements contain ``INTERFACE_LINK_LIBRARIES_DIRECT`` or
+``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, the properties may affect
+``X``'s list of direct link dependencies:
+
+* If ``X`` is a shared library or executable, its dependencies are linked.
+  They also affect the usage requirements with which ``X``'s sources are
+  compiled.
+
+* If ``X`` is a static library or object library, it does not actually
+  link, so its dependencies at most affect the usage requirements with
+  which ``X``'s sources are compiled.
+
+The properties may also affect the list of direct link dependencies
+on ``X``'s dependents:
+
+* If ``X`` links ``Y`` publicly:
+
+  .. code-block:: cmake
+
+    target_link_libraries(X PUBLIC Y)
+
+  then ``Y`` is placed in ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
+  so ``Y``'s usage requirements, including ``INTERFACE_LINK_LIBRARIES_DIRECT``,
+  ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, and the usage requirements
+  declared by the direct link dependencies they add, are propagated to
+  ``X``'s dependents.
+
+* If ``X`` is a static library or object library, and links ``Y`` privately:
+
+  .. code-block:: cmake
+
+    target_link_libraries(X PRIVATE Y)
+
+  then ``$<LINK_ONLY:Y>`` is placed in ``X``'s
+  :prop_tgt:`INTERFACE_LINK_LIBRARIES`.  ``Y``'s linking requirements,
+  including ``INTERFACE_LINK_LIBRARIES_DIRECT``,
+  ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, and the transitive link
+  dependencies declared by the direct link dependencies they add, are
+  propagated to ``X``'s dependents.  However, ``Y``'s non-linking
+  usage requirements are blocked by the :genex:`LINK_ONLY` generator
+  expression, and are not propagated to ``X``'s dependents.
+
+* If ``X`` is a shared library or executable, and links ``Y`` privately:
+
+  .. code-block:: cmake
+
+    target_link_libraries(X PRIVATE Y)
+
+  then ``Y`` is not placed in ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
+  so ``Y``'s usage requirements, even ``INTERFACE_LINK_LIBRARIES_DIRECT``
+  and ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``, are not propagated to
+  ``X``'s dependents.
+
+* In all cases, the content of ``X``'s :prop_tgt:`INTERFACE_LINK_LIBRARIES`
+  is not affected by ``Y``'s ``INTERFACE_LINK_LIBRARIES_DIRECT`` or
+  ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``.
+
+One may limit the effects of ``INTERFACE_LINK_LIBRARIES_DIRECT`` and
+``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` to a subset of dependent
+targets by using the :genex:`TARGET_PROPERTY` generator expression.
+For example, to limit the effects to executable targets, use an
+entry of the form::
+
+  "$<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:...>"
+
+Similarly, to limit the effects to specific targets, use an entry
+of the form::
+
+  "$<$<BOOL:$<TARGET_PROPERTY:USE_IT>>:...>"
+
+This entry will only affect targets that set their ``USE_IT``
+target property to a true value.
+
+Direct Link Dependency Ordering
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The list of direct link dependencies for a target is computed from an
+initial ordered list in its :prop_tgt:`LINK_LIBRARIES` target property.
+For each item, additional direct link dependencies are discovered from
+its direct and transitive ``INTERFACE_LINK_LIBRARIES_DIRECT`` usage
+requirements.  Each discovered item is injected before the item that
+specified it.  However, a discovered item is added at most once,
+and only if it did not appear anywhere in the initial list.
+This gives :prop_tgt:`LINK_LIBRARIES` control over ordering of
+those direct link dependencies that it explicitly specifies.
+
+Once all direct link dependencies have been collected, items named by
+all of their :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`
+usage requirements are removed from the final list.  This does not
+affect the order of the items that remain.
+
+Example: Static Plugins
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Consider a static library ``Foo`` that provides a static plugin
+``FooPlugin`` to consuming application executables, where the
+implementation of the plugin depends on ``Foo`` and other things.
+In this case, the application should link to ``FooPlugin`` directly,
+before ``Foo``.  However, the application author only knows about ``Foo``.
+We can express this as follows:
+
+.. code-block:: cmake
+
+  # Core library used by other components.
+  add_library(Core STATIC core.cpp)
+
+  # Foo is a static library for use by applications.
+  # Implementation of Foo depends on Core.
+  add_library(Foo STATIC foo.cpp foo_plugin_helper.cpp)
+  target_link_libraries(Foo PRIVATE Core)
+
+  # Extra parts of Foo for use by its static plugins.
+  # Implementation of Foo's extra parts depends on both Core and Foo.
+  add_library(FooExtras STATIC foo_extras.cpp)
+  target_link_libraries(FooExtras PRIVATE Core Foo)
+
+  # The Foo library has an associated static plugin
+  # that should be linked into the final executable.
+  # Implementation of the plugin depends on Core, Foo, and FooExtras.
+  add_library(FooPlugin STATIC foo_plugin.cpp)
+  target_link_libraries(FooPlugin PRIVATE Core Foo FooExtras)
+
+  # An app that links Foo should link Foo's plugin directly.
+  set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT FooPlugin)
+
+  # An app does not need to link Foo directly because the plugin links it.
+  set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE Foo)
+
+An application ``app`` only needs to specify that it links to ``Foo``:
+
+.. code-block:: cmake
+
+  add_executable(app main.cpp)
+  target_link_libraries(app PRIVATE Foo)
+
+The ``INTERFACE_LINK_LIBRARIES_DIRECT`` target property on ``Foo`` tells
+CMake to pretend that ``app`` also links directly to ``FooPlugin``.
+The ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target property on ``Foo``
+tells CMake to pretend that ``app`` did *not* link directly to ``Foo``.
+Instead, ``Foo`` will be linked as a dependency of ``FooPlugin``.  The
+final link line for ``app`` will link the libraries in the following
+order:
+
+* ``FooPlugin`` as a direct link dependency of ``app``
+  (via ``Foo``'s usage requirements).
+* ``FooExtras`` as a dependency of ``FooPlugin``.
+* ``Foo`` as a dependency of ``FooPlugin`` and ``FooExtras``.
+* ``Core`` as a dependency of ``FooPlugin``, ``FooExtras``, and ``Foo``.
+
+Note that without the ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target
+property, ``Foo`` would be linked twice: once as a direct dependency
+of ``app``, and once as a dependency of ``FooPlugin``.
+
+Example: Opt-In Static Plugins
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the above `Example: Static Plugins`_, the ``app`` executable specifies
+that it links directly to ``Foo``.  In a real application, there might
+be an intermediate library:
+
+.. code-block:: cmake
+
+  add_library(app_impl STATIC app_impl.cpp)
+  target_link_libraries(app_impl PRIVATE Foo)
+
+  add_executable(app main.cpp)
+  target_link_libraries(app PRIVATE app_impl)
+
+In this case we do not want ``Foo``'s ``INTERFACE_LINK_LIBRARIES_DIRECT``
+and ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target properties to affect
+the direct dependencies of ``app_impl``.  To avoid this, we can revise
+the property values to make their effects opt-in:
+
+.. code-block:: cmake
+
+  # An app that links Foo should link Foo's plugin directly.
+  set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT
+    "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:FooPlugin>"
+  )
+
+  # An app does not need to link Foo directly because the plugin links it.
+  set_property(TARGET Foo PROPERTY INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
+    "$<$<BOOL:$<TARGET_PROPERTY:FOO_STATIC_PLUGINS>>:Foo>"
+  )
+
+Now, the ``app`` executable can opt-in to get ``Foo``'s plugin(s):
+
+.. code-block:: cmake
+
+  set_property(TARGET app PROPERTY FOO_STATIC_PLUGINS 1)
+
+The final link line for ``app`` will now link the libraries in the following
+order:
+
+* ``FooPlugin`` as a direct link dependency of ``app``
+  (via ``Foo``'s usage requirements).
+* ``app_impl`` as a direct link dependency of ``app``.
+* ``FooExtras`` as a dependency of ``FooPlugin``.
+* ``Foo`` as a dependency of ``app_impl``, ``FooPlugin``, and ``FooExtras``.
+* ``Core`` as a dependency of ``FooPlugin``, ``FooExtras``, and ``Foo``.

Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT.txt

@@ -0,0 +1,9 @@
+The value of |INTERFACE_PROPERTY_LINK_DIRECT| may use
+:manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+.. note::
+
+  The |INTERFACE_PROPERTY_LINK_DIRECT| target property is intended for
+  advanced use cases such as injection of static plugins into a consuming
+  executable.  It should not be used as a substitute for organizing
+  normal calls to :command:`target_link_libraries`.

Help/prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE.rst

@@ -0,0 +1,34 @@
+INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
+---------------------------------------
+
+.. versionadded:: 3.24
+
+List of libraries that consumers of this library should *not* treat
+as direct link dependencies.
+
+This target property may be set to *exclude* items from a dependent
+target's final set of direct link dependencies.  This property is
+processed after the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT`
+target property of all other dependencies of the dependent target, so
+exclusion from direct link dependence takes priority over inclusion.
+
+The initial set of a dependent target's direct link dependencies is
+specified by its :prop_tgt:`LINK_LIBRARIES` target property.  Indirect
+link dependencies are specified by the transitive closure of the direct
+link dependencies' :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
+Any link dependency may specify additional direct link dependencies
+using the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property.
+The set of direct link dependencies is then filtered to exclude items named
+by any dependency's ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE`` target
+property.
+
+Excluding an item from a dependent target's direct link dependencies
+does not mean the dependent target won't link the item.  The item
+may still be linked as an indirect link dependency via the
+:prop_tgt:`INTERFACE_LINK_LIBRARIES` property on other dependencies.
+
+.. |INTERFACE_PROPERTY_LINK_DIRECT| replace:: ``INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE``
+.. include:: INTERFACE_LINK_LIBRARIES_DIRECT.txt
+
+See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target property
+documentation for more details and examples.

Help/prop_tgt/LINK_LIBRARIES.rst

@@ -14,9 +14,17 @@ 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
+Contents of ``LINK_LIBRARIES`` may use
-syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)` manual
+:manual:`generator expressions <cmake-generator-expressions(7)>` with the
-for available expressions.  See the :manual:`cmake-buildsystem(7)` manual
+syntax ``$<...>``.  Policy :policy:`CMP0131` affects the behavior of the
-for more on defining buildsystem properties.
+:genex:`LINK_ONLY` generator expression for this property.
+
+See the :manual:`cmake-buildsystem(7)` manual for more on defining
+buildsystem properties.
 
 .. include:: LINK_LIBRARIES_INDIRECTION.txt
+
+In advanced use cases, the list of direct link dependencies specified
+by this property may be updated by usage requirements from dependencies.
+See the :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
+:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties.

Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst

@@ -8,6 +8,8 @@ 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`.
+Checks are also applied to libraries added to a target through the
+:prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` properties of its dependencies.
 CMake will verify that link items that might be target names actually name
 existing targets.  An item is considered a possible target name if:
 

Help/prop_tgt/LINK_LIBRARY_OVERRIDE.rst

@@ -0,0 +1,65 @@
+LINK_LIBRARY_OVERRIDE
+---------------------
+
+.. versionadded:: 3.24
+
+Override the library features associated with libraries from
+:genex:`LINK_LIBRARY` generator expressions.  This can be used to resolve
+incompatible library features that result from specifying different features
+for the same library in different :genex:`LINK_LIBRARY` generator expressions.
+
+This property supports overriding multiple libraries and features. It expects
+a :ref:`semicolon-separated list <CMake Language Lists>`, where each list item
+has the following form::
+
+  feature[,link-item]*
+
+For each comma-separated ``link-item``, any existing library feature associated
+with it will be ignored for the target this property is set on.  The item
+will instead be associated with the specified ``feature``.  Each ``link-item``
+can be anything that would be accepted as part of a ``library-list`` in a
+:genex:`LINK_LIBRARY` generator expression.
+
+.. code-block:: cmake
+
+  add_library(lib1 ...)
+  add_library(lib2 ...)
+  add_library(lib3 ...)
+
+  target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
+  target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
+  target_link_libraries(lib3 PRIVATE lib1 lib2)
+
+  # lib1 is associated with both feature2 and no feature. Without any override,
+  # this would result in a fatal error at generation time for lib3.
+  # Define an override to resolve the incompatible feature associations.
+  set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE "feature2,lib1,external")
+
+  # lib1 and external will now be associated with feature2 instead when linking lib3
+
+It is also possible to override any feature with the pre-defined ``DEFAULT``
+library feature.  This effectively discards any feature for that link item,
+for that target only (``lib3`` in this example):
+
+.. code-block:: cmake
+
+  # When linking lib3, discard any library feature for lib1, and use feature2 for external
+  set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE
+    "DEFAULT,lib1"
+    "feature2,external"
+  )
+
+The above example also demonstrates how to specify different feature overrides
+for different link items.  See the :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>`
+target property for an alternative way of overriding library features for
+individual libraries, which may be simpler in some cases.  If both properties
+are defined and specify an override for the same link item,
+:prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` takes precedence over
+``LINK_LIBRARY_OVERRIDE``.
+
+Contents of ``LINK_LIBRARY_OVERRIDE`` may use
+:manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+For more information about library features, see the
+:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
+:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.

Help/prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY.rst

@@ -0,0 +1,51 @@
+LINK_LIBRARY_OVERRIDE_<LIBRARY>
+-------------------------------
+
+.. versionadded:: 3.24
+
+Override the library feature associated with ``<LIBRARY>`` from
+:genex:`LINK_LIBRARY` generator expressions.  This can be used to resolve
+incompatible library features that result from specifying different features
+for ``<LIBRARY>`` in different :genex:`LINK_LIBRARY` generator expressions.
+
+When set on a target, this property holds a single library feature name, which
+will be applied to ``<LIBRARY>`` when linking that target.
+
+.. code-block:: cmake
+
+  add_library(lib1 ...)
+  add_library(lib2 ...)
+  add_library(lib3 ...)
+
+  target_link_libraries(lib1 PUBLIC "$<LINK_LIBRARY:feature1,external>")
+  target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature2,lib1>")
+  target_link_libraries(lib3 PRIVATE lib1 lib2)
+
+  # lib1 is associated with both feature2 and no feature. Without any override,
+  # this would result in a fatal error at generation time for lib3.
+  # Define an override to resolve the incompatible feature associations.
+  set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 feature2)
+
+  # lib1 will now be associated with feature2 instead when linking lib3
+
+It is also possible to override any feature with the pre-defined ``DEFAULT``
+library feature.  This effectively discards any feature for that link item,
+for that target only (``lib3`` in this example):
+
+.. code-block:: cmake
+
+  # When linking lib3, discard any library feature for lib1
+  set_property(TARGET lib3 PROPERTY LINK_LIBRARY_OVERRIDE_lib1 DEFAULT)
+
+See the :prop_tgt:`LINK_LIBRARY_OVERRIDE` target property for an alternative
+way of overriding library features for multiple libraries at once.  If both
+properties are defined and specify an override for the same link item,
+``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` takes precedence over
+:prop_tgt:`LINK_LIBRARY_OVERRIDE`.
+
+Contents of ``LINK_LIBRARY_OVERRIDE_<LIBRARY>`` may use
+:manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+For more information about library features, see the
+:variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
+:variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables.

Help/prop_tgt/RULE_LAUNCH_COMPILE.rst

@@ -3,5 +3,11 @@ RULE_LAUNCH_COMPILE
 
 Specify a launcher for compile rules.
 
-See the global property of the same name for details.  This overrides
+.. note::
-the global and directory property for a target.
+  This property is intended for internal use by :manual:`ctest(1)`.  Projects
+  and developers should use the :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target
+  properties or the associated :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER`
+  variables instead.
+
+See the :prop_gbl:`global property <RULE_LAUNCH_COMPILE>` of the same name
+for details.  This overrides the global and directory property for a target.

Help/prop_tgt/RULE_LAUNCH_LINK.rst

@@ -3,5 +3,11 @@ RULE_LAUNCH_LINK
 
 Specify a launcher for link rules.
 
-See the global property of the same name for details.  This overrides
+.. note::
-the global and directory property for a target.
+  This property is intended for internal use by :manual:`ctest(1)`.  Projects
+  and developers should use the :prop_tgt:`<LANG>_LINKER_LAUNCHER` target
+  properties or the associated :variable:`CMAKE_<LANG>_LINKER_LAUNCHER`
+  variables instead.
+
+See the :prop_gbl:`global property <RULE_LAUNCH_LINK>` of the same name for
+details.  This overrides the global and directory property for a target.

Help/prop_tgt/VERIFY_INTERFACE_HEADER_SETS.rst

@@ -0,0 +1,38 @@
+VERIFY_INTERFACE_HEADER_SETS
+----------------------------
+
+.. versionadded:: 3.24
+
+Used to verify that all headers in a target's ``PUBLIC`` and ``INTERFACE``
+header sets can be included on their own.
+
+When this property is set to true, and the target is an object library, static
+library, shared library, interface library, or executable with exports enabled,
+and the target has one or more ``PUBLIC`` or ``INTERFACE`` header sets, an
+object library target named ``<target_name>_verify_interface_header_sets`` is
+created. This verification target has one source file per header in the
+``PUBLIC`` and ``INTERFACE`` header sets. Each source file only includes its
+associated header file. The verification target links against the original
+target to get all of its usage requirements. The verification target has its
+:prop_tgt:`EXCLUDE_FROM_ALL` and :prop_tgt:`DISABLE_PRECOMPILE_HEADERS`
+properties set to true, and its :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTORCC`,
+:prop_tgt:`AUTOUIC`, and :prop_tgt:`UNITY_BUILD` properties set to false.
+
+If the header's :prop_sf:`LANGUAGE` property is set, the value of that property
+is used to determine the language with which to compile the header file.
+Otherwise, if the target has any C++ sources, the header is compiled as C++.
+Otherwise, if the target has any C sources, the header is compiled as C.
+Otherwise, if C++ is enabled globally, the header is compiled as C++.
+Otherwise, if C is enabled globally, the header is compiled as C. Otherwise,
+the header file is not compiled.
+
+If any verification targets are created, a top-level target called
+``all_verify_interface_header_sets`` is created which depends on all
+verification targets.
+
+This property is initialized by the value of the
+:variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable if it is set when
+a target is created.
+
+If the project wishes to control which header sets are verified by this
+property, it can set :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY`.

Help/prop_tgt/VS_DOTNET_STARTUP_OBJECT.rst

@@ -0,0 +1,21 @@
+VS_DOTNET_STARTUP_OBJECT
+------------------------
+
+.. versionadded:: 3.24
+
+Sets the startup object property in Visual Studio .NET targets.
+The property value defines a full qualified class name (including package
+name), for example: ``MyCompany.Package.MyStarterClass``.
+
+If the property is unset, Visual Studio uses the first matching
+``static void Main(string[])`` function signature by default. When more
+than one ``Main()`` method is available in the current project, the property
+becomes mandatory for building the project.
+
+This property only works for Visual Studio 2010 and above;
+it is ignored on other generators.
+
+.. code-block:: cmake
+
+  set_property(TARGET ${TARGET_NAME} PROPERTY
+    VS_DOTNET_STARTUP_OBJECT "MyCompany.Package.MyStarterClass")

Help/prop_tgt/VS_NO_COMPILE_BATCHING.rst

@@ -0,0 +1,24 @@
+VS_NO_COMPILE_BATCHING
+----------------------
+
+.. versionadded:: 3.24
+
+Turn off compile batching for the target. Usually MSBuild calls the compiler
+with multiple c/cpp files and compiler starts subprocesses for each file to
+make the build parallel. If you want compiler to be invoked with one file at
+a time set ``VS_NO_COMPILE_BATCHING`` to ON. If this flag is set MSBuild will
+call compiler with one c/cpp file at a time. Useful when you want to use tool
+that replaces the compiler, for example some build caching tool.
+
+This property is initialized by the :variable:`CMAKE_VS_NO_COMPILE_BATCHING`
+variable if it is set when a target is created.
+
+Example
+^^^^^^^
+
+This shows setting the property for the target ``foo``.
+
+.. code-block:: cmake
+
+  add_library(foo SHARED foo.cpp)
+  set_property(TARGET foo PROPERTY VS_NO_COMPILE_BATCHING ON)

Help/prop_tgt/WATCOM_RUNTIME_LIBRARY-VALUES.txt

@@ -0,0 +1,20 @@
+``SingleThreaded``
+  Compile without additional flags to use a single-threaded
+  statically-linked runtime library.
+``SingleThreadedDLL``
+  Compile with ``-br`` or equivalent flag(s) to use a single-threaded
+  dynamically-linked runtime library. This is not available for Linux
+  targets.
+``MultiThreaded``
+  Compile with ``-bm`` or equivalent flag(s) to use a multi-threaded
+  statically-linked runtime library.
+``MultiThreadedDLL``
+  Compile with ``-bm -br`` or equivalent flag(s) to use a multi-threaded
+  dynamically-linked runtime library. This is not available for Linux
+  targets.
+
+The value is ignored on non-Watcom compilers but an unsupported value will
+be rejected as an error when using a compiler targeting the Watcom ABI.
+
+The value may also be the empty string (``""``) in which case no runtime
+library selection flag will be added explicitly by CMake.

Help/prop_tgt/WATCOM_RUNTIME_LIBRARY.rst

@@ -0,0 +1,34 @@
+WATCOM_RUNTIME_LIBRARY
+----------------------
+
+.. versionadded:: 3.24
+
+Select the Watcom runtime library for use by compilers targeting the Watcom ABI.
+
+The allowed values are:
+
+.. include:: WATCOM_RUNTIME_LIBRARY-VALUES.txt
+
+Use :manual:`generator expressions <cmake-generator-expressions(7)>` to
+support per-configuration specification.
+
+For example, the code:
+
+.. code-block:: cmake
+
+  add_executable(foo foo.c)
+  set_property(TARGET foo PROPERTY
+    WATCOM_RUNTIME_LIBRARY "MultiThreaded")
+
+selects for the target ``foo`` a multi-threaded statically-linked runtime
+library.
+
+If this property is not set then CMake uses the default value
+``MultiThreadedDLL`` on Windows and ``SingleThreaded`` on other
+platforms to select a Watcom runtime library.
+
+.. note::
+
+  This property has effect only when policy :policy:`CMP0136` is set to ``NEW``
+  prior to the first :command:`project` or :command:`enable_language` command
+  that enables a language using a compiler targeting the Watcom ABI.

Help/prop_tgt/XCODE_XCCONFIG.rst

@@ -0,0 +1,14 @@
+XCODE_XCCONFIG
+--------------
+
+.. versionadded:: 3.24
+
+If set, the :generator:`Xcode` generator will register the specified
+file as a target-level XCConfig file. For global XCConfig files see
+the :variable:`CMAKE_XCODE_XCCONFIG` variable.
+
+This feature is intended to ease migration from native Xcode projects
+to CMake projects.
+
+Contents of ``XCODE_XCCONFIG`` may use
+:manual:`generator expressions <cmake-generator-expressions(7)>`.

Help/release/3.17.rst

@@ -272,7 +272,7 @@ Deprecated and Removed Features
   of all policies are deprecated and that projects should port to the
   NEW behaviors.
 
-* The :cpack_gen:`CPack PackageMaker Generator` generator has been
+* The CPack ``PackageMaker`` generator has been
   deprecated because Xcode no longer distributes the PackageMaker tools.
   The undocumented ``OSXX11`` generator has also been deprecated.
 

Help/release/3.23.rst

@@ -187,7 +187,7 @@ CPack
 
 * The ``CPack.distribution.dist.in`` template used by the
   :cpack_gen:`CPack productbuild Generator` and
-  :cpack_gen:`CPack PackageMaker Generator` was updated to use a new
+  CPack ``PackageMaker`` generator was updated to use a new
   ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable for its main content.
   This replaced the previously undocumented and now deprecated
   ``CPACK_PACKAGEMAKER_CHOICES`` variable.

Help/release/3.24.rst

@@ -0,0 +1,350 @@
+CMake 3.24 Release Notes
+************************
+
+.. only:: html
+
+  .. contents::
+
+Changes made since CMake 3.23 include the following.
+
+New Features
+============
+
+Presets
+-------
+
+* :manual:`cmake-presets(7)` files now support schema version ``5``.
+
+* :manual:`cmake-presets(7)` files now support a ``${pathListSep}`` macro,
+  which expands to ``:`` or ``;`` based on the platform.
+
+* :manual:`cmake-presets(7)` files gained support for specifying a
+  ``testOutputTruncation`` field in test presets, which specifies the
+  truncation mode once the maximum test output size has been reached.
+
+Generators
+----------
+
+* The :generator:`Green Hills MULTI` generator now generates build
+  rules to re-run CMake if any CMake files are updated.
+
+* The :ref:`Visual Studio Generators` now support ``SYSTEM`` headers
+  when using VS 2019 Update 11 or later.
+
+Command-Line
+------------
+
+* :manual:`cmake(1)` gained the ``--fresh`` command-line option to remove
+  any existing ``CMakeCache.txt`` file and associated ``CMakeFiles/``
+  directory, when configuring a build tree, thus starting a new configuration
+  as if the build tree were freshly created.
+
+* :manual:`cmake(1)` gained the ``--compile-no-warning-as-error`` command-line
+  option which causes the effects of the :prop_tgt:`COMPILE_WARNING_AS_ERROR`
+  target property and :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable
+  to be ignored.
+
+* The :manual:`cmake(1)` ``--trace=json-v1`` trace format gained fields
+  ``global_frame`` and ``line_end``.
+
+* The :manual:`cmake(1)` ``-E`` commands ``cat`` and ``env`` learned to respect
+  a double dash (``--``) argument that acts as a delimiter indicating the end of
+  options. Any following arguments are treated as operands/positional arguments,
+  even if they begin with a dash ``-`` character.
+
+* The :manual:`cmake(1)` ``-E tar`` command gained the ``--touch`` option
+  to keep the current local timestamp instead of extracting file timestamps
+  from the archive.
+
+Compilers
+---------
+
+* LLVM's `flang`_ Fortran compiler is now supported on some platforms,
+  with compiler id ``LLVMFlang``.
+
+.. _`flang`: https://github.com/llvm/llvm-project/tree/main/flang
+
+* ADSP compiler support (SHARC and Blackfin) now covers both CCES and
+  VDSP++ installations, with required configuration now done in the
+  compiler module itself rather than the ``Generic-ADSP`` platform module.
+
+Platforms
+---------
+
+* A dedicated ``ADSP`` platform has been added
+  to replace the existing ``Generic-ADSP`` implementation.
+  This features automatic detection of the latest CCES/VDSP++ install
+  and compiler selection (``cc21k`` vs. ``ccblkfn``)
+  based off of the :variable:`CMAKE_SYSTEM_PROCESSOR` variable.
+
+Commands
+--------
+
+* The :command:`cmake_host_system_information` command, on Windows,
+  gained a ``QUERY WINDOWS_REGISTRY`` mode.
+  See its :ref:`Query Windows registry` section.
+
+* The :command:`cmake_language` command gained a new
+  ``SET_DEPENDENCY_PROVIDER`` sub-command.  When a dependency provider is set,
+  calls to :command:`find_package` and :command:`FetchContent_MakeAvailable`
+  can be redirected through a custom command, which can choose to fulfill the
+  request directly, modify how the request is processed, or leave it to be
+  fulfilled by the built-in implementation.  See :ref:`dependency_providers`.
+
+* The :command:`file(DOWNLOAD)` command gained options ``RANGE_START`` and
+  ``RANGE_END`` to specify a range of bytes to download.  This can be
+  useful for downloading parts of big binary files.
+
+* The :command:`find_file`, :command:`find_path`, :command:`find_library`,
+  :command:`find_program`, and :command:`find_package` commands gained the
+  ``NO_CMAKE_INSTALL_PREFIX`` option to control searching
+  :variable:`CMAKE_INSTALL_PREFIX`.
+
+* The :command:`find_file`, :command:`find_path`, :command:`find_library`,
+  :command:`find_program`, and :command:`find_package` commands gained the
+  ability to specify which Windows Registry views must be queried.
+
+* The :command:`find_package` command gained a ``GLOBAL`` option that
+  allows for the promotion of imported targets to global scope for the
+  duration of the :command:`find_package` call.
+
+* The :command:`if` command gained the capability to compare paths by
+  using the ``PATH_EQUAL`` operator.  See policy :policy:`CMP0139`.
+
+Variables
+---------
+
+* The :variable:`CMAKE_COLOR_DIAGNOSTICS` variable was added to control
+  color diagnostics generated by compilers.  This variable also controls
+  color build system messages with :ref:`Makefile Generators`, replacing
+  :variable:`CMAKE_COLOR_MAKEFILE`.
+
+  The :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment variable was added to set
+  a default value for :variable:`CMAKE_COLOR_DIAGNOSTICS`.
+
+* The :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable and corresponding
+  :prop_tgt:`COMPILE_WARNING_AS_ERROR` target property were added to enable
+  compilation with a compiler-specific flag to treat warnings as errors,
+  such as ``-Werror``.
+
+* The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated
+  :prop_tgt:`CUDA_ARCHITECTURES` target property now support the
+  special ``native`` value to compile for the architectures(s)
+  of the host's GPU(s).
+
+* The :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` variable was added to
+  toggle behavior of the :command:`find_package` command's new ``GLOBAL``
+  option.
+
+* The :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` variable was added to toggle
+  behavior of the :command:`find_file`, :command:`find_library`,
+  :command:`find_path`, :command:`find_package`, and :command:`find_program`
+  commands' new ``NO_CMAKE_INSTALL_PREFIX`` option.
+
+* The :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable was added to allow
+  injecting custom code at the site of the first :command:`project` call,
+  after the host and target platform details have been determined.
+
+* The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable
+  was added to tell the :command:`try_compile` command not to
+  pass any platform variables to the test project.
+
+* The :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable and
+  corresponding :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` target property
+  were added to enable build rules that verify all headers in header sets
+  can be used on their own.
+
+* The :variable:`CMAKE_VS_NO_COMPILE_BATCHING` variable and corresponding
+  :prop_tgt:`VS_NO_COMPILE_BATCHING` target property were added to
+  tell :ref:`Visual Studio Generators` whether to disable compiler
+  parallelism and call the compiler with one source file at a time.
+
+* The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` variable and
+  :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property were introduced to
+  select the runtime library used by compilers targeting the Watcom ABI.
+  See policy :policy:`CMP0136`.
+
+* The :variable:`CMAKE_XCODE_XCCONFIG` variable and corresponding
+  :prop_tgt:`XCODE_XCCONFIG` target property were added to tell
+  the :generator:`Xcode` generator to handle ``xcconfig`` files.
+
+Properties
+----------
+
+* The :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
+  :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties
+  were added to express usage requirements affecting a consumer's
+  direct link dependencies.
+
+* The :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY` target property was
+  added to specify which header sets should be verified by
+  :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS`.
+
+* The :prop_tgt:`LINK_LIBRARIES` target property now supports
+  the :genex:`$<LINK_ONLY:...>` generator expression.
+  See policy :policy:`CMP0131`.
+
+* The :prop_tgt:`VS_DOTNET_STARTUP_OBJECT` target property was added to
+  tell :ref:`Visual Studio Generators` which startup class shall be used
+  when the program or project is executed. This is necessary when more
+  than one ``static void Main(string[])`` function signature is available
+  in a managed .NET project.
+
+Modules
+-------
+
+* The :module:`ExternalProject` module :command:`ExternalProject_Add`
+  command gained a new ``DOWNLOAD_EXTRACT_TIMESTAMP`` option for
+  controlling whether the timestamps of extracted contents are set to
+  match those in the archive when the ``URL`` download method is used.
+  Policy :policy:`CMP0135` was added to enable the option by default.
+
+* The :module:`FetchContent` module and the :command:`find_package` command
+  now support integration capabilities:
+
+  * :command:`FetchContent_MakeAvailable` can now try to satisfy a dependency
+    by calling :command:`find_package` first.  A new
+    :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable controls whether
+    this is done by default for all dependencies, is opt-in per dependency,
+    or is disabled entirely.
+
+  * :command:`find_package` can be re-routed to call
+    :command:`FetchContent_MakeAvailable` instead.  A new read-only
+    :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable points to a
+    directory where config package files can be located to facilitate these
+    re-routed calls.
+
+* The :module:`FindJNI` module now provides imported targets.
+
+* The :module:`FindMatlab` module :command:`matlab_add_mex` function
+  gained a ``NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES`` option to disable
+  automatic linking of MATLAB libraries.
+
+* The :module:`FindVulkan` module now supports components to select which
+  VulkanSDK tool and libraries to find in addition to the Vulkan SDK headers
+  and library.
+
+* The :module:`FindZLIB` gained a new ``ZLIB_USE_STATIC_LIBS`` variable to
+  search only for static libraries.
+
+Generator Expressions
+---------------------
+
+* The :genex:`LINK_LIBRARY` generator expression was added to manage how
+  libraries are specified during the link step.
+  The :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
+  :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables are used to define
+  features usable by the :genex:`LINK_LIBRARY` generator expression.
+  Moreover, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
+  :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties are
+  available to resolve incompatible features.
+
+  The :genex:`LINK_LIBRARY` generator expression can link frameworks in
+  various ways when targeting ``Apple`` platforms.
+  The following features were added:
+
+  * ``FRAMEWORK``
+  * ``NEEDED_FRAMEWORK``
+  * ``REEXPORT_FRAMEWORK``
+  * ``WEAK_FRAMEWORK``
+
+  The :genex:`LINK_LIBRARY` generator expression can link libraries in
+  various ways when targeting ``Apple`` platforms.
+  The following features were added:
+
+  * ``NEEDED_LIBRARY``
+  * ``REEXPORT_LIBRARY``
+  * ``WEAK_LIBRARY``
+
+  The :genex:`LINK_LIBRARY` generator expression gained the feature
+  ``WHOLE_ARCHIVE`` to force load of all members in a static library.
+  This feature is supported on the following target platforms:
+
+  * all ``Apple`` variants
+  * ``Linux``
+  * all ``BSD`` variants
+  * ``SunOS``
+  * ``Windows``
+  * ``CYGWIN``
+  * ``MSYS``
+
+* The :genex:`LINK_GROUP` generator expression was added to manage the
+  grouping of libraries during the link step.  The
+  :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` and
+  :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variables are used to define
+  features usable with the :genex:`LINK_GROUP` generator expression.
+  This release defines the ``RESCAN`` feature, which can be used to handle
+  circular references among static libraries when using toolchains for
+  Linux, BSD, SunOS and GNU toolchains for Windows.
+
+* The :genex:`PATH` generator expression was added to manage paths.
+
+* The :genex:`PATH_EQUAL` generator expression was added to manage path
+  comparisons.
+
+* The :genex:`TARGET_BUNDLE_DIR_NAME` generator expression
+  was added to evaluate to the name of the bundle directory
+  for a given bundle target.
+
+CTest
+-----
+
+* :manual:`ctest(1)` gained a ``--test-output-truncation`` option (and
+  corresponding :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable) to
+  specify the truncation mode once the maximum test output size has been
+  reached. Possible values are ``tail`` (default), ``middle`` or ``head``.
+
+CPack
+-----
+
+* The :cpack_gen:`CPack WIX Generator` gained a new variable,
+  :variable:`CPACK_WIX_ARCHITECTURE`, to specify the installer architecture
+  in order to support computers running Windows for ARM.
+
+* CPack now supports the :variable:`CPACK_THREADS` option for ``zstd``
+  compression when compiled with libarchive 3.6 or higher.  It is
+  supported by official CMake binaries available on `cmake.org`_.
+
+Deprecated and Removed Features
+===============================
+
+* The :module:`CPack` module no longer enables the SLA by default in the
+  :cpack_gen:`CPack DragNDrop Generator`.  See policy :policy:`CMP0133`
+  and the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` variable.
+
+* The deprecated :cpack_gen:`CPack PackageMaker Generator` has been removed.
+
+* The :module:`FindGLUT` module no longer provides the undocumented
+  ``GLUT_LIBRARY`` and ``GLUT_INCLUDE_PATH`` result variables.
+
+Other Changes
+=============
+
+* CMake no longer sets environment variables like :envvar:`CC`, :envvar:`CXX`,
+  etc. when enabling the corresponding language during the first CMake run in
+  a build directory.  See policy :policy:`CMP0132`.
+
+* The :module:`CheckIPOSupported` module :command:`check_ipo_supported`
+  command now uses the caller's :variable:`CMAKE_<LANG>_FLAGS`
+  and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values.
+  See policy :policy:`CMP0138`.
+
+* The :generator:`MSYS Makefiles` and :generator:`MinGW Makefiles`
+  generators, when a compiler is not explicitly specified, now select
+  the first compiler (of any name) found in directories listed by the
+  ``PATH`` environment variable.
+
+* The :command:`try_compile` command
+  :ref:`whole-project <Try Compiling Whole Projects>` signature
+  now propagates platform variables.  See policy :policy:`CMP0137`.
+
+* The :command:`while` command now diagnoses errors during condition
+  evaluation.  See policy :policy:`CMP0130`.
+
+* The precompiled macOS binaries provided on `cmake.org`_ no longer attach a
+  SLA to the ``.dmg`` packages.  This was removed because macOS 12 deprecated
+  the tools used to attach ``.dmg`` resources.
+
+* A precompiled Windows ``arm64`` binary is now provided on `cmake.org`_.
+
+.. _`cmake.org`: https://cmake.org/download/

Help/release/index.rst

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

Help/variable/CMAKE_ADSP_ROOT.rst

@@ -0,0 +1,11 @@
+CMAKE_ADSP_ROOT
+---------------
+
+.. versionadded:: 3.24
+
+When :ref:`Cross Compiling for ADSP SHARC/Blackfin`,
+this variable holds the absolute path to the latest CCES or VDSP++ install.
+The directory is expected to contain the ``cc21k.exe`` and ``ccblkfn.exe`` compilers.
+This will be set automatically if a default install of CCES or VDSP++ can be found.
+
+See also the :envvar:`ADSP_ROOT` environment variable.