Update changelog for 3.31.1-1 release

- Drop Fix-ImageMagick_-_ARCH_INCLUDE_DIR-detection.patch
- Drop Recognize-Multi-Arch-libdir-for-musl-linux-any.patch
- Drop LLD-linker-avoid-regression-on-archive-libraries-ded.patch

All patches have been accepted and applied by upstream.

Gbp-Dch: full

.clang-tidy

@@ -2,6 +2,7 @@
 Checks: "-*,\
 bugprone-*,\
 -bugprone-assignment-in-if-condition,\
+-bugprone-crtp-constructor-accessibility,\
 -bugprone-easily-swappable-parameters,\
 -bugprone-empty-catch,\
 -bugprone-implicit-widening-of-multiplication-result,\
@@ -10,19 +11,23 @@ bugprone-*,\
 -bugprone-misplaced-widening-cast,\
 -bugprone-multi-level-implicit-pointer-conversion,\
 -bugprone-narrowing-conversions,\
+-bugprone-return-const-ref-from-parameter,\
+-bugprone-suspicious-stringview-data-usage,\
 -bugprone-switch-missing-default-case,\
 -bugprone-too-small-loop-variable,\
 -bugprone-unchecked-optional-access,\
 -bugprone-unused-local-non-trivial-variable,\
 -bugprone-unused-return-value,\
+-bugprone-use-after-move,\
 misc-*,\
 -misc-confusable-identifiers,\
 -misc-const-correctness,\
 -misc-include-cleaner,\
--misc-no-recursion,\
 -misc-non-private-member-variables-in-classes,\
+-misc-no-recursion,\
 -misc-static-assert,\
 -misc-use-anonymous-namespace,\
+-misc-use-internal-linkage,\
 modernize-*,\
 -modernize-avoid-c-arrays,\
 -modernize-macro-to-enum,\
@@ -36,13 +41,14 @@ modernize-*,\
 performance-*,\
 -performance-avoid-endl,\
 -performance-enum-size,\
--performance-inefficient-vector-operation,\
--performance-noexcept-swap,\
+-performance-unnecessary-copy-initialization,\
+-performance-unnecessary-value-param,\
 readability-*,\
 -readability-avoid-nested-conditional-operator,\
 -readability-avoid-return-with-void-value,\
 -readability-avoid-unconditional-preprocessor-if,\
 -readability-convert-member-functions-to-static,\
+-readability-enum-initial-value,\
 -readability-function-cognitive-complexity,\
 -readability-function-size,\
 -readability-identifier-length,\
@@ -51,6 +57,7 @@ readability-*,\
 -readability-inconsistent-declaration-parameter-name,\
 -readability-magic-numbers,\
 -readability-make-member-function-const,\
+-readability-math-missing-parentheses,\
 -readability-named-parameter,\
 -readability-redundant-casting,\
 -readability-redundant-declaration,\
@@ -61,6 +68,7 @@ readability-*,\
 -readability-static-accessed-through-instance,\
 -readability-suspicious-call-argument,\
 -readability-uppercase-literal-suffix,\
+-readability-use-std-min-max,\
 cmake-*,\
 -cmake-ostringstream-use-cmstrcat,\
 -cmake-string-concatenation-use-cmstrcat,\

Auxiliary/bash-completion/cmake

@@ -173,7 +173,9 @@ _cmake()
             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" ) )
+                COMPREPLY=(
+                    $( compgen -W "configure${IFS}build${IFS}package${IFS}test${IFS}workflow${IFS}all" -- "$quoted" )
+                  )
             fi
             return
             ;;
@@ -182,12 +184,16 @@ _cmake()
             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"
+            local preset_type
+            if [[ "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--workflow${IFS}" ]]; then
+                preset_type="workflow"
+            elif [[ "${IFS}${COMP_WORDS[*]}${IFS}" =~ "${IFS}--build${IFS}" ]]; then
+                preset_type="build"
+            else
+                preset_type="configure"
             fi
 
-            local presets=$( cmake --list-presets="$build_or_configure" 2>/dev/null |
+            local presets=$( cmake --list-presets="$preset_type" 2>/dev/null |
                 grep -o "^  \".*\"" | sed \
                 -e "s/^  //g" \
                 -e "s/\"//g" \
@@ -195,6 +201,24 @@ _cmake()
             COMPREPLY=( $( compgen -W "$presets" -- "$quoted" ) )
             return
             ;;
+        --workflow)
+            local quoted
+            printf -v quoted %q "$cur"
+            # Options allowed right after `--workflow`
+            local workflow_options='--preset --list-presets --fresh'
+
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $( compgen -W "$workflow_options" -- "$quoted" ) )
+            else
+                local presets=$( cmake --list-presets=workflow 2>/dev/null |
+                    grep -o "^  \".*\"" | sed \
+                    -e "s/^  //g" \
+                    -e "s/\"//g" \
+                    -e 's/ /\\\\ /g' )
+                COMPREPLY=( $( compgen -W "$presets $workflow_options" -- "$quoted" ) )
+            fi
+            return
+            ;;
     esac
 
     if  ($is_old_completion || $is_init_completion); then
@@ -204,6 +228,8 @@ _cmake()
     fi
 
     if [[ "$cur" == -* ]]; then
+        # FIXME(#26100): `cmake --help` is missing some options and does not
+        # have any mode-specific options like `cmake --build`'s `--config`.
         COMPREPLY=( $(compgen -W '$( _parse_help "$1" --help )' -- ${cur}) )
         [[ $COMPREPLY == *= ]] && compopt -o nospace
         [[ $COMPREPLY ]] && return

Auxiliary/cmake-mode.el

@@ -183,7 +183,7 @@ set the path with these commands:
   )
 
 (defun cmake-point-in-indendation ()
-  (string-match "^[ \\t]*$" (buffer-substring (point-at-bol) (point))))
+  (string-match "^[ \\t]*$" (buffer-substring (line-beginning-position) (point))))
 
 (defun cmake-indent-line-to (column)
   "Indent the current line to COLUMN.

Auxiliary/vim/syntax/cmake.vim

@@ -416,6 +416,7 @@ syn keyword cmakeProperty contained
             \ VS_DOTNET_STARTUP_OBJECT
             \ VS_DOTNET_TARGET_FRAMEWORK_VERSION
             \ VS_DPI_AWARE
+            \ VS_FRAMEWORK_REFERENCES
             \ VS_GLOBAL_KEYWORD
             \ VS_GLOBAL_PROJECT_TYPES
             \ VS_GLOBAL_ROOTNAMESPACE

CMakeLists.txt

@@ -1,7 +1,7 @@
 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
 # file Copyright.txt or https://cmake.org/licensing for details.
 
-cmake_minimum_required(VERSION 3.13...3.28 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.13...3.29 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)
 
@@ -267,9 +267,7 @@ macro(CMAKE_SETUP_TESTING)
   endif()
 
   # configure some files for testing
-  configure_file(Templates/CTestScript.cmake.in CTestScript.cmake @ONLY)
   configure_file(Tests/.NoDartCoverage Tests/.NoDartCoverage)
-  configure_file(Tests/.NoDartCoverage Modules/.NoDartCoverage)
   configure_file(CTestCustom.cmake.in CTestCustom.cmake @ONLY)
 endmacro()
 

CONTRIBUTING.rst

@@ -26,7 +26,8 @@ To contribute patches:
 #. Fork the upstream `CMake Repository`_ into a personal account.
 #. Run `Utilities/SetupForDevelopment.sh`_ for local git configuration.
 #. See `Building CMake`_ for building CMake locally.
-#. See the `CMake Source Code Guide`_ for coding guidelines.
+#. See the `CMake Source Code Guide`_ for coding guidelines
+   and the `CMake Testing Guide`_ for testing instructions.
 #. Create a topic branch named suitably for your work.
    Base all new work on the upstream ``master`` branch.
    Base work on the upstream ``release`` branch only if it fixes a
@@ -49,6 +50,7 @@ The merge request will enter the `CMake Review Process`_ for consideration.
 .. _`Utilities/SetupForDevelopment.sh`: Utilities/SetupForDevelopment.sh
 .. _`Building CMake`: README.rst#building-cmake
 .. _`CMake Source Code Guide`: Help/dev/source.rst
+.. _`CMake Testing Guide`: Help/dev/testing.rst
 .. _`commit messages`: Help/dev/review.rst#commit-messages
 .. _`CMake Review Process`: Help/dev/review.rst
 
@@ -61,10 +63,10 @@ drive testing and submit results to the `CMake CDash Page`_.  Anyone is
 welcome to provide testing machines in order to help keep support for their
 platforms working.
 
-See documentation on `CMake Testing Process`_ for more information.
+See documentation on `CMake Integration Testing`_ for more information.
 
 .. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
-.. _`CMake Testing Process`: Help/dev/testing.rst
+.. _`CMake Integration Testing`: Help/dev/integration-testing.rst
 
 License
 =======

CTestCustom.cmake.in

@@ -86,7 +86,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "[0-9]+ Warning\\(s\\) detected" # SunPro
 
   # Ignore false positive on `cm::optional` usage from GCC
-  "cmFileCommand.cxx:[0-9]*:[0-9]*: warning: '\\*\\(\\(void\\*\\)& tls_verify \\+2\\)' may be used uninitialized in this function \\[-Wmaybe-uninitialized\\]"
+  "cmFileCommand.cxx:[0-9]*:[0-9]*: warning: '\\*\\(\\(void\\*\\)& tlsVerifyOpt \\+2\\)' may be used uninitialized in this function \\[-Wmaybe-uninitialized\\]"
   "cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: warning: '.*cm::optional<CxxModuleMapFormat>::_mem\\)\\)' may be used uninitialized \\[-Wmaybe-uninitialized\\]"
   "cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: note: '.*cm::optional<CxxModuleMapFormat>::_mem\\)\\)' was declared here"
   "cmGlobalNinjaGenerator.cxx:[0-9]*:[0-9]*: warning: '\\*\\(\\(void\\*\\)& modmap_fmt \\+4\\)' may be used uninitialized in this function \\[-Wmaybe-uninitialized\\]"
@@ -101,6 +101,7 @@ list(APPEND CTEST_CUSTOM_WARNING_EXCEPTION
   "libuv/src/.*:[0-9]+:[0-9]+: warning: 1st function call argument is an uninitialized value"
   "libuv/src/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
   "libuv/src/.*:[0-9]+:[0-9]+: warning: The left operand of '[^']+' is a garbage value"
+  "libuv/src/.*:[0-9]+:[0-9]+: warning: Value of '[^']+' was not checked and may be overwritten by function '[^']+'"
   "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Access to field '[^']+' results in a dereference of a null pointer"
   "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Dereference of null pointer"
   "nghttp2/lib/.*:[0-9]+:[0-9]+: warning: Value stored to '[^']+' is never read"

CompileFlags.cmake

@@ -37,7 +37,13 @@ elseif(_CLANG_MSVC_WINDOWS AND "x${CMAKE_CXX_COMPILER_FRONTEND_VARIANT}" STREQUA
   string(APPEND CMAKE_EXE_LINKER_FLAGS " -Xlinker -stack:20000000")
 endif()
 
-#silence duplicate symbol warnings on AIX
+# Silence "Additional optimization may be attained by recompiling and
+# specifying MAXMEM option" warning on XLC (AIX)
+if(CMAKE_CXX_COMPILER_ID MATCHES "^(XL|XLClang)$")
+  string(APPEND CMAKE_CXX_FLAGS " -qmaxmem=-1")
+endif()
+
+# Silence duplicate symbol warnings on AIX
 if(CMAKE_SYSTEM_NAME MATCHES "AIX")
   if(NOT CMAKE_COMPILER_IS_GNUCXX)
     set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -bhalt:5 ")

Help/command/DEPRECATED_POLICY_VERSIONS.txt

@@ -1,3 +1,11 @@
+.. versionchanged:: 3.31
+
+  Compatibility with versions of CMake older than 3.10 is deprecated.
+  Calls to :command:`cmake_minimum_required(VERSION)` or
+  :command:`cmake_policy(VERSION)` that do not specify at least
+  3.10 as their policy version (optionally via ``...<max>``)
+  will produce a deprecation warning in CMake 3.31 and above.
+
 .. versionchanged:: 3.27
 
   Compatibility with versions of CMake older than 3.5 is deprecated.

Help/command/add_custom_command.rst

@@ -5,6 +5,8 @@ Add a custom build rule to the generated build system.
 
 There are two main signatures for ``add_custom_command``.
 
+.. _`add_custom_command(OUTPUT)`:
+
 Generating Files
 ^^^^^^^^^^^^^^^^
 
@@ -26,6 +28,7 @@ The first signature is for adding a custom command to produce an output:
                      [JOB_POOL job_pool]
                      [JOB_SERVER_AWARE <bool>]
                      [VERBATIM] [APPEND] [USES_TERMINAL]
+                     [CODEGEN]
                      [COMMAND_EXPAND_LISTS]
                      [DEPENDS_EXPLICIT_ONLY])
 
@@ -53,7 +56,7 @@ The options are:
   the appended commands and dependencies apply to all configurations.
 
   The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY``
-  options are currently ignored when APPEND is given, but may be
+  options are currently ignored when ``APPEND`` is given, but may be
   used in the future.
 
 ``BYPRODUCTS``
@@ -81,6 +84,10 @@ The options are:
   The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
   :prop_sf:`GENERATED` files during ``make clean``.
 
+  This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
+  All byproducts must be set in the first call to
+  ``add_custom_command(OUTPUT...)`` for the output files.
+
   .. versionadded:: 3.20
     Arguments to ``BYPRODUCTS`` may use a restricted set of
     :manual:`generator expressions <cmake-generator-expressions(7)>`.
@@ -94,11 +101,15 @@ The options are:
 
 ``COMMAND``
   Specify the command-line(s) to execute at build time.
-  If more than one ``COMMAND`` is specified they will be executed in order,
+  At least one ``COMMAND`` would normally be given, but certain patterns
+  may omit it, such as adding commands in separate calls using `APPEND`.
+
+  If more than one ``COMMAND`` is specified, they will be executed in order,
   but *not* necessarily composed into a stateful shell or batch script.
-  (To run a full script, use the :command:`configure_file` command or the
+  To run a full script, use the :command:`configure_file` command or the
   :command:`file(GENERATE)` command to create it, and then specify
-  a ``COMMAND`` to launch it.)
+  a ``COMMAND`` to launch it.
+
   The optional ``ARGS`` argument is for backward compatibility and
   will be ignored.
 
@@ -143,7 +154,8 @@ The options are:
 
 ``COMMENT``
   Display the given message before the commands are executed at
-  build time.
+  build time.  This will be ignored if ``APPEND`` is given, although a future
+  version may use it.
 
   .. versionadded:: 3.26
     Arguments to ``COMMENT`` may use
@@ -203,6 +215,26 @@ The options are:
   ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
   to be properly expanded.
 
+  This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
+  If the appended commands need this option to be set, it must be set on the
+  first call to ``add_custom_command(OUTPUT...)`` for the output files.
+
+``CODEGEN``
+  .. versionadded:: 3.31
+
+  Adds the custom command to a global ``codegen`` target that can be
+  used to execute the custom command while avoiding the majority of the
+  build graph.
+
+  This option is supported only by :ref:`Ninja Generators` and
+  :ref:`Makefile Generators`, and is ignored by other generators.
+  Furthermore, this option is allowed only if policy :policy:`CMP0171`
+  is set to ``NEW``.
+
+  This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
+  It can only be set on the first call to ``add_custom_command(OUTPUT...)``
+  for the output files.
+
 ``IMPLICIT_DEPENDS``
   Request scanning of implicit dependencies of an input file.
   The language given specifies the programming language whose
@@ -227,6 +259,10 @@ The options are:
   Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
   an error by ninja at build time.
 
+  This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
+  Job pools can only be specified in the first call to
+  ``add_custom_command(OUTPUT...)`` for the output files.
+
 ``JOB_SERVER_AWARE``
   .. versionadded:: 3.28
 
@@ -238,6 +274,10 @@ The options are:
 
   This option is silently ignored by other generators.
 
+  This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
+  Job server awareness can only be specified in the first call to
+  ``add_custom_command(OUTPUT...)`` for the output files.
+
 .. _`GNU Make Documentation`: https://www.gnu.org/software/make/manual/html_node/MAKE-Variable.html
 
 ``MAIN_DEPENDENCY``
@@ -249,6 +289,9 @@ The options are:
   library or an executable) counts as an implicit main dependency which
   gets silently overwritten by a custom command specification.
 
+  This option is currently ignored if ``APPEND`` is given, but a future
+  version may use it.
+
 ``OUTPUT``
   Specify the output files the command is expected to produce.
   Each output file will be marked with the :prop_sf:`GENERATED`
@@ -293,6 +336,10 @@ The options are:
   With the :generator:`Ninja` generator, this places the command in
   the ``console`` :prop_gbl:`pool <JOB_POOLS>`.
 
+  This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
+  If the appended commands need access to the terminal, it must be set on
+  the first call to ``add_custom_command(OUTPUT...)`` for the output files.
+
 ``VERBATIM``
   All arguments to the commands will be escaped properly for the
   build tool so that the invoked command receives each argument
@@ -303,11 +350,18 @@ The options are:
   is platform specific because there is no protection of
   tool-specific special characters.
 
+  This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
+  If the appended commands need to be treated as ``VERBATIM``, it must be set
+  on the first call to ``add_custom_command(OUTPUT...)`` for the output files.
+
 ``WORKING_DIRECTORY``
   Execute the command with the given current working directory.
-  If it is a relative path it will be interpreted relative to the
+  If it is a relative path, it will be interpreted relative to the
   build tree directory corresponding to the current source directory.
 
+  This option is currently ignored if ``APPEND`` is given, but a future
+  version may use it.
+
   .. versionadded:: 3.13
     Arguments to ``WORKING_DIRECTORY`` may use
     :manual:`generator expressions <cmake-generator-expressions(7)>`.
@@ -393,6 +447,10 @@ The options are:
   :ref:`Makefile Generators`, :ref:`Visual Studio Generators`,
   and the :generator:`Xcode` generator.
 
+  This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
+  Depfiles can only be set on the first call to
+  ``add_custom_command(OUTPUT...)`` for the output files.
+
 ``DEPENDS_EXPLICIT_ONLY``
 
   .. versionadded:: 3.27
@@ -408,6 +466,10 @@ The options are:
   This option can be enabled on all custom commands by setting
   :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` to ``ON``.
 
+  This keyword cannot be used with ``APPEND`` (see policy :policy:`CMP0175`).
+  It can only be set on the first call to ``add_custom_command(OUTPUT...)``
+  for the output files.
+
   Only the :ref:`Ninja Generators` actually use this information to remove
   unnecessary implicit dependencies.
 
@@ -454,6 +516,25 @@ will re-run whenever ``in.txt`` changes.
   where ``<config>`` is the build configuration, and then compile the generated
   source as part of a library.
 
+.. versionadded:: 3.31
+  Use the ``CODEGEN`` option to add a custom command's outputs to the builtin
+  ``codegen`` target.  This is useful to make generated code available for
+   static analysis without building the entire project.  For example:
+
+  .. code-block:: cmake
+
+    add_executable(someTool someTool.c)
+
+    add_custom_command(
+      OUTPUT out.c
+      COMMAND someTool -o out.c
+      CODEGEN)
+
+    add_library(myLib out.c)
+
+  A user may build the ``codegen`` target to generate ``out.c``.
+  ``someTool`` is built as dependency, but ``myLib`` is not built at all.
+
 Example: Generating Files for Multiple Targets
 """"""""""""""""""""""""""""""""""""""""""""""
 
@@ -518,7 +599,8 @@ target is already built, the command will not execute.
                      [WORKING_DIRECTORY dir]
                      [COMMENT comment]
                      [VERBATIM]
-                     [COMMAND_EXPAND_LISTS])
+                     [COMMAND_EXPAND_LISTS]
+                     [USES_TERMINAL])
 
 This defines a new command that will be associated with building the
 specified ``<target>``.  The ``<target>`` must be defined in the current
@@ -543,15 +625,17 @@ of the following is specified:
   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.
+the ``TARGET`` form.  See policy :policy:`CMP0175`.
+
+All other keywords shown in the signature above have the same meaning as they
+do for the :command:`add_custom_command(OUTPUT)` form of the command.
+At least one ``COMMAND`` must be given, see policy :policy:`CMP0175`.
 
 .. note::
   Because generator expressions can be used in custom commands,
   it is possible to define ``COMMAND`` lines or whole custom commands
   which evaluate to empty strings for certain configurations.
-  For **Visual Studio 12 2013 (and newer)** generators these command
+  For :ref:`Visual Studio Generators` these command
   lines or custom commands will be omitted for the specific
   configuration and no "empty-string-command" will be added.
 

Help/command/cmake_parse_arguments.rst

@@ -20,48 +20,49 @@ It processes the arguments given to that macro or function,
 and defines a set of variables which hold the values of the
 respective options.
 
-The first signature reads processes arguments passed in the ``<args>...``.
+The first signature reads arguments passed in the ``<args>...``.
 This may be used in either a :command:`macro` or a :command:`function`.
 
 .. versionadded:: 3.7
   The ``PARSE_ARGV`` signature is only for use in a :command:`function`
-  body.  In this case the arguments that are parsed come from the
+  body.  In this case, the arguments that are parsed come from the
   ``ARGV#`` variables of the calling function.  The parsing starts with
   the ``<N>``-th argument, where ``<N>`` is an unsigned integer.
   This allows for the values to have special characters like ``;`` in them.
 
-The ``<options>`` argument contains all options for the respective macro,
-i.e.  keywords which can be used when calling the macro without any value
-following, like e.g.  the ``OPTIONAL`` keyword of the :command:`install`
-command.
+The ``<options>`` argument contains all options for the respective function
+or macro. These are keywords that have no value following them, like the
+``OPTIONAL`` keyword of the :command:`install` command.
 
-The ``<one_value_keywords>`` argument contains all keywords for this macro
-which are followed by one value, like e.g. ``DESTINATION`` keyword of the
-:command:`install` command.
+The ``<one_value_keywords>`` argument contains all keywords for this function
+or macro which are followed by one value, like the ``DESTINATION`` keyword of
+the :command:`install` command.
 
 The ``<multi_value_keywords>`` argument contains all keywords for this
-macro which can be followed by more than one value, like e.g. the
+function or macro which can be followed by more than one value, like the
 ``TARGETS`` or ``FILES`` keywords of the :command:`install` command.
 
 .. versionchanged:: 3.5
-  All keywords shall be unique. I.e. every keyword shall only be specified
-  once in either ``<options>``, ``<one_value_keywords>`` or
+  All keywords must be unique.  Each keyword can only be specified
+  once in any of the ``<options>``, ``<one_value_keywords>``, or
   ``<multi_value_keywords>``. A warning will be emitted if uniqueness is
   violated.
 
 When done, ``cmake_parse_arguments`` will consider for each of the
-keywords listed in ``<options>``, ``<one_value_keywords>`` and
-``<multi_value_keywords>`` a variable composed of the given ``<prefix>``
-followed by ``"_"`` and the name of the respective keyword.  These
-variables will then hold the respective value from the argument list
-or be undefined if the associated option could not be found.
-For the ``<options>`` keywords, these will always be defined,
-to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not.
+keywords listed in ``<options>``, ``<one_value_keywords>``, and
+``<multi_value_keywords>``, a variable composed of the given ``<prefix>``
+followed by ``"_"`` and the name of the respective keyword.  For
+``<one_value_keywords>`` and ``<multi_value_keywords>``, these variables
+will then hold the respective value(s) from the argument list, or be undefined
+if the associated keyword was not given (policy :policy:`CMP0174` can also
+affect the behavior for ``<one_value_keywords>``).  For the ``<options>``
+keywords, these variables will always be defined, and they will be set to
+``TRUE`` if the keyword is present, or ``FALSE`` if it is not.
 
 All remaining arguments are collected in a variable
 ``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all arguments
 were recognized. This can be checked afterwards to see
-whether your macro was called with unrecognized parameters.
+whether your macro or function was called with unrecognized parameters.
 
 .. versionadded:: 3.15
    ``<one_value_keywords>`` and ``<multi_value_keywords>`` that were given no
@@ -70,8 +71,47 @@ whether your macro was called with unrecognized parameters.
    received values. This can be checked to see if there were keywords without
    any values given.
 
-Consider the following example macro, ``my_install()``, which takes similar
-arguments to the real :command:`install` command:
+.. versionchanged:: 3.31
+   If a ``<one_value_keyword>`` is followed by an empty string as its value,
+   policy :policy:`CMP0174` controls whether a corresponding
+   ``<prefix>_<keyword>`` variable is defined or not.
+
+Choose a ``<prefix>`` carefully to avoid clashing with existing variable names.
+When used inside a function, it is usually suitable to use the prefix ``arg``.
+There is a very strong convention that all keywords are fully uppercase, so
+this prefix results in variables of the form ``arg_SOME_KEYWORD``.  This makes
+the code more readable, and it minimizes the chance of clashing with cache
+variables, which also have a strong convention of being all uppercase.
+
+.. code-block:: cmake
+
+   function(my_install)
+       set(options OPTIONAL FAST)
+       set(oneValueArgs DESTINATION RENAME)
+       set(multiValueArgs TARGETS CONFIGURATIONS)
+       cmake_parse_arguments(PARSE_ARGV 0 arg
+           "${options}" "${oneValueArgs}" "${multiValueArgs}"
+       )
+
+       # The above will set or unset variables with the following names:
+       #   arg_OPTIONAL
+       #   arg_FAST
+       #   arg_DESTINATION
+       #   arg_RENAME
+       #   arg_TARGETS
+       #   arg_CONFIGURATIONS
+       #
+       # The following will also be set or unset:
+       #   arg_UNPARSED_ARGUMENTS
+       #   arg_KEYWORDS_MISSING_VALUES
+
+When used inside a macro, ``arg`` might not be a suitable prefix because the
+code will affect the calling scope.  If another macro also called in the same
+scope were to use ``arg`` in its own call to ``cmake_parse_arguments()``,
+and if there are any common keywords between the two macros, the later call's
+variables can overwrite or remove those of the earlier macro's call.
+Therefore, it is advisable to incorporate something unique from the macro name
+in the ``<prefix>``, such as ``arg_lowercase_macro_name``.
 
 .. code-block:: cmake
 
@@ -79,40 +119,63 @@ arguments to the real :command:`install` command:
        set(options OPTIONAL FAST)
        set(oneValueArgs DESTINATION RENAME)
        set(multiValueArgs TARGETS CONFIGURATIONS)
-       cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
-                             "${multiValueArgs}" ${ARGN} )
+       cmake_parse_arguments(arg_my_install
+           "${options}" "${oneValueArgs}" "${multiValueArgs}"
+           ${ARGN}
+       )
+       # ...
+   endmacro()
 
+   macro(my_special_install)
+       # NOTE: Has the same keywords as my_install()
+       set(options OPTIONAL FAST)
+       set(oneValueArgs DESTINATION RENAME)
+       set(multiValueArgs TARGETS CONFIGURATIONS)
+       cmake_parse_arguments(arg_my_special_install
+           "${options}" "${oneValueArgs}" "${multiValueArgs}"
+           ${ARGN}
+       )
        # ...
+   endmacro()
 
-Assume ``my_install()`` has been called like this:
+Suppose the above macros are called one after the other, like so:
 
 .. code-block:: cmake
 
    my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
-
-After the ``cmake_parse_arguments`` call the macro will have set or undefined
-the following variables::
-
-   MY_INSTALL_OPTIONAL = TRUE
-   MY_INSTALL_FAST = FALSE # was not used in call to my_install
-   MY_INSTALL_DESTINATION = "bin"
-   MY_INSTALL_RENAME <UNDEFINED> # was not used
-   MY_INSTALL_TARGETS = "foo;bar"
-   MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
-   MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
-   MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
-            # No value for "CONFIGURATIONS" given
-
-You can then continue and process these variables.
-
-Keywords terminate lists of values, e.g. if directly after a
-``one_value_keyword`` another recognized keyword follows, this is
-interpreted as the beginning of the new option.  E.g.
-``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in
-``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL``
-is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added
-to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will
-therefore be set to ``TRUE``.
+   my_special_install(TARGETS barry DESTINATION sbin RENAME FAST)
+
+After these two calls, the following describes the variables that will be
+set or unset::
+
+   arg_my_install_OPTIONAL = TRUE
+   arg_my_install_FAST = FALSE # was not present in call to my_install
+   arg_my_install_DESTINATION = "bin"
+   arg_my_install_RENAME <UNSET> # was not present
+   arg_my_install_TARGETS = "foo;bar"
+   arg_my_install_CONFIGURATIONS <UNSET> # was not present
+   arg_my_install_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
+   arg_my_install_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS" # value was missing
+
+   arg_my_special_install_OPTIONAL = FALSE # was not present
+   arg_my_special_install_FAST = TRUE
+   arg_my_special_install_DESTINATION = "sbin"
+   arg_my_special_install_RENAME <UNSET> # value was missing
+   arg_my_special_install_TARGETS = "barry"
+   arg_my_special_install_CONFIGURATIONS <UNSET> # was not present
+   arg_my_special_install_UNPARSED_ARGUMENTS <UNSET>
+   arg_my_special_install_KEYWORDS_MISSING_VALUES = "RENAME"
+
+Keywords terminate lists of values. If a keyword is given directly after a
+``<one_value_keyword>``, that preceding ``<one_value_keyword>`` receives no
+value and the keyword is added to the ``<prefix>_KEYWORDS_MISSING_VALUES``
+variable. In the above example, the call to ``my_special_install()`` contains
+the ``RENAME`` keyword immediately followed by the ``FAST`` keyword.
+In this case, ``FAST`` terminates processing of the ``RENAME`` keyword.
+``arg_my_special_install_FAST`` is set to ``TRUE``,
+``arg_my_special_install_RENAME`` is unset, and
+``arg_my_special_install_KEYWORDS_MISSING_VALUES`` contains the value
+``RENAME``.
 
 See Also
 ^^^^^^^^

Help/command/cmake_pkg_config.rst

@@ -0,0 +1,263 @@
+cmake_pkg_config
+----------------
+
+.. versionadded:: 3.31
+
+.. only:: html
+
+   .. contents::
+
+Process pkg-config format package files.
+
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+  cmake_pkg_config(EXTRACT <package> [<version>] [...])
+
+Introduction
+^^^^^^^^^^^^
+
+This command generates CMake variables and targets from pkg-config format
+package files natively, without needing to invoke or even require the presence
+of a pkg-config implementation. A ``<package>`` is either an absolute path to a
+package file, or a package name to be searched for using the typical pkg-config
+search patterns. The optional ``<version>`` string has the same format and
+semantics as a pkg-config style version specifier, with the exception that if
+no comparison operator is specified ``=`` is assumed.
+
+.. _`common options`:
+
+There are multiple signatures for this command, and some of the options are
+common between them. They are:
+
+``EXACT`` / ``QUIET`` / ``REQUIRED``
+  The ``EXACT`` option requests that the version string be matched exactly
+  (including empty string, if no version is provided), overriding the typical
+  pkg-config version comparison algorithm. This will ignore any comparison
+  operator attached to the version string.
+
+  The ``QUIET`` option disables informational messages, including those
+  indicating that the package cannot be found if it is not ``REQUIRED``. The
+  ``REQUIRED`` option stops processing with an error message if the package
+  cannot be found.
+
+``STRICTNESS <mode>``
+  Specify how strictly the contents of the package files will be verified during
+  parsing and resolution. An invalid file, under the provided strictness mode,
+  will cause the command to fail. Possible modes are:
+
+  * ``STRICT``: Closely mirrors the behavior of the original FDO pkg-config.
+    Variables and keywords must be unique. Variables must be defined before
+    they are used. The Name, Description, and Version keywords must be present.
+    The overall structure of the file must be valid and parsable.
+
+  * ``PERMISSIVE``: Closely mirrors the behavior of the pkgconf implementation.
+    Duplicate variables are overridden. Duplicate keywords are appended.
+    Undefined variables resolve to empty strings. The Name, Description, and
+    Version keywords must be present. The overall structure of the file must be
+    valid and parsable.
+
+  * ``BEST_EFFORT``: Same behavior as ``PERMISSIVE`` with regards to duplicate
+    or uninitialized variables and keywords, but will not fail under any
+    conditions. Package files which require BEST_EFFORT will fail validation
+    under all other major implementations and should be fixed.
+
+  The default strictness is ``PERMISSIVE``.
+
+``ENV_MODE``
+  Specifies which environment variables will be queried when running a given
+  command. Possible modes are:
+
+  * ``FDO``: Queries only the original set of ``PKG_CONFIG_*`` environment
+    variables used by the freedesktop.org ``pkg-config`` implementation.
+
+  * ``PKGCONF``: Queries the more extensive set of environment variables used
+    by the ``pkgconf`` implementation.
+
+  * ``IGNORE``: Ignores the presence, absence, and value of environment
+    variables entirely. In all cases an environment variable would be queried
+    its treated as defined, but with a value of empty string for the purpose
+    of the operation. This does not modify the current environment. For boolean
+    environment variables, such as ``PKG_CONFIG_ALLOW_*``, this means they are
+    evaluated as truthy.
+
+    ``PKG_CONFIG_SYSROOT_PATH`` is a minor exception. When ``ENV_MODE IGNORE``
+    is used, no root path prepending will occur by default and ``pc_sysrootdir``
+    remains defaulted to ``/``.
+
+  Target-generating subcommands always ignore flag-filtering environment
+  variables. The default environment mode is ``PKGCONF``.
+
+``PC_LIBDIR <path>...``
+  Overrides the default search location for package files; also used to derive
+  the ``pc_path`` package variable.
+
+  When this option is not provided, the default library directory is the first
+  available of the following values:
+
+  #. ``CMAKE_PKG_CONFIG_PC_LIB_DIRS``
+  #. The ``PKG_CONFIG_LIBDIR`` environment variable
+  #. The output of ``pkg-config --variable pc_path pkg-config``
+  #. A platform-dependent default value
+
+``PC_PATH <path>...``
+  Overrides the supplemental package file directories which will be prepended
+  to the search path; also used to derive the ``pc_path`` package variable.
+
+  When this option is not provided, the default paths are the first available of
+  the following values:
+
+  #. ``CMAKE_PKG_CONFIG_PC_PATH``
+  #. The ``PKG_CONFIG_PATH`` environment variable
+  #. Empty list
+
+``DISABLE_UNINSTALLED <bool>``
+  Overrides the search behavior for "uninstalled" package files. These are
+  package files with an "-uninstalled" suffix which describe packages integrated
+  directly from a build tree.
+
+  Normally such package files have higher priority than "installed" packages.
+  When ``DISABLE_UNINSTALLED`` is true, searching for "uninstalled" packages
+  is disabled.
+
+  When this option is not provided, the default search behavior is determined
+  by the first available of the following values:
+
+  #. ``CMAKE_PKG_CONFIG_DISABLE_UNINSTALLED``
+  #. If the ``PKG_CONFIG_DISABLE_UNINSTALLED`` environment variable is defined
+     the search is disabled, otherwise it is enabled.
+
+``PC_SYSROOT_DIR <path>``
+  Overrides the root path which will be prepended to paths specified by ``-I``
+  compile flags and ``-L`` library search locations; also used to derive the
+  ``pc_sysrootdir`` package variable.
+
+  When this option is not provided, the default root path is provided by the
+  first available of the following values:
+
+  #. ``CMAKE_PKG_CONFIG_SYSROOT_DIR``
+  #. The ``PKG_CONFIG_SYSROOT_DIR`` environment variable
+  #. If no root path is available, nothing will be prepended to include or
+     library directory paths and ``pc_sysrootdir`` will be set to ``/``
+
+``TOP_BUILD_DIR <path>``
+  Overrides the top build directory path used to derived the ``pc_top_builddir``
+  package variable.
+
+  When this option is not provided, the default top build directory path is
+  the first available of the following values:
+
+  #. ``CMAKE_PKG_CONFIG_TOP_BUILD_DIR``
+  #. The ``PKG_CONFIG_TOP_BUILD_DIR`` environment variable
+  #. If no top build directory path is available, the ``pc_top_builddir``
+     package variable is not set
+
+Signatures
+^^^^^^^^^^
+
+.. signature::
+  cmake_pkg_config(EXTRACT <package> [<version>] [...])
+
+  Extract the contents of the package into variables.
+
+  .. code-block:: cmake
+
+    cmake_pkg_config(EXTRACT <package> [<version>]
+                    [REQUIRED] [EXACT] [QUIET]
+                    [STRICTNESS <mode>]
+                    [ENV_MODE <mode>]
+                    [PC_LIBDIR <path>...]
+                    [PC_PATH <path>...]
+                    [DISABLE_UNINSTALLED <bool>]
+                    [PC_SYSROOT_DIR <path>]
+                    [TOP_BUILD_DIR <path>]
+                    [SYSTEM_INCLUDE_DIRS <path>...]
+                    [SYSTEM_LIBRARY_DIRS <path>...]
+                    [ALLOW_SYSTEM_INCLUDES <bool>]
+                    [ALLOW_SYSTEM_LIBS <bool>])
+
+The following variables will be populated from the contents of package file:
+
+==================================== ====== ========================================================================================
+              Variable                Type                       Definition
+==================================== ====== ========================================================================================
+``CMAKE_PKG_CONFIG_NAME``            String Value of the ``Name`` keyword
+``CMAKE_PKG_CONFIG_DESCRIPTION``     String Value of the ``Description`` keyword
+``CMAKE_PKG_CONFIG_VERSION``         String Value of the ``Version`` keyword
+``CMAKE_PKG_CONFIG_PROVIDES``        List   Value of the ``Provides`` keyword
+``CMAKE_PKG_CONFIG_REQUIRES``        List   Value of the ``Requires`` keyword
+``CMAKE_PKG_CONFIG_CONFLICTS``       List   Value of the ``Conflicts`` keyword
+``CMAKE_PKG_CONFIG_CFLAGS``          String Value of the ``CFlags`` / ``Cflags`` keyword
+``CMAKE_PKG_CONFIG_INCLUDES``        List   All ``-I`` prefixed flags from ``CMAKE_PKG_CONFIG_CFLAGS``
+``CMAKE_PKG_CONFIG_COMPILE_OPTIONS`` List   All flags not prefixed with ``-I`` from ``CMAKE_PKG_CONFIG_CFLAGS``
+``CMAKE_PKG_CONFIG_LIBS``            String Value of the ``Libs`` keyword
+``CMAKE_PKG_CONFIG_LIBDIRS``         List   All ``-L`` prefixed flags from ``CMAKE_PKG_CONFIG_LIBS``
+``CMAKE_PKG_CONFIG_LIBNAMES``        List   All ``-l`` prefixed flags from ``CMAKE_PKG_CONFIG_LIBS``
+``CMAKE_PKG_CONFIG_LINK_OPTIONS``    List   All flags not prefixed with ``-L`` or ``-l`` from ``CMAKE_PKG_CONFIG_LIBS``
+``CMAKE_PKG_CONFIG_*_PRIVATE``       \*     ``CFLAGS`` / ``LIBS`` / ``REQUIRES`` and derived, but in their ``.private`` suffix forms
+==================================== ====== ========================================================================================
+
+``SYSTEM_INCLUDE_DIRS``
+  Overrides the "system" directories for the purpose of flag mangling include
+  directories in ``CMAKE_PKG_CONFIG_CFLAGS`` and derived variables.
+
+  When this option is not provided, the default directories are provided by the
+  first available of the following values:
+
+  #. ``CMAKE_PKG_CONFIG_SYS_INCLUDE_DIRS``
+  #. The ``PKG_CONFIG_SYSTEM_INCLUDE_PATH`` environment variable
+  #. The output of ``pkgconf --variable pc_system_includedirs pkg-config``
+  #. A platform-dependent default value
+
+  Additionally, when the ``ENV_MODE`` is ``PKGCONF`` the
+  ``CMAKE_PKG_CONFIG_PKGCONF_INCLUDES`` variable will be concatenated to the
+  list if available. If it is not available, the following environment variables
+  will be queried and concatenated:
+
+  * ``CPATH``
+  * ``C_INCLUDE_PATH``
+  * ``CPLUS_INCLUDE_PATH``
+  * ``OBJC_INCLUDE_PATH``
+  * ``INCLUDE`` (Windows Only)
+
+``SYSTEM_LIBRARY_DIRS``
+  Overrides the "system" directories for the purpose of flag mangling library
+  directories in ``CMAKE_PKG_CONFIG_LIBS`` and derived variables.
+
+  When this option is not provided, the default directories are provided by the
+  first available of the following values:
+
+  #. ``CMAKE_PKG_CONFIG_SYS_LIB_DIRS``
+  #. The ``PKG_CONFIG_SYSTEM_LIBRARY_PATH`` environment variable
+  #. The output of ``pkgconf --variable pc_system_libdirs pkg-config``
+  #. A platform-dependent default value
+
+  Additionally, when the ``ENV_MODE`` is ``PKGCONF`` the
+  ``CMAKE_PKG_CONFIG_PKGCONF_LIB_DIRS`` variable will be concatenated to the
+  list if available. If it is not available, the ``LIBRARY_PATH`` environment
+  variable will be queried and concatenated.
+
+``ALLOW_SYSTEM_INCLUDES``
+  Preserves "system" directories during flag mangling of include directories
+  in ``CMAKE_PKG_CONFIG_CFLAGS`` and derived variables.
+
+  When this option is not provided, the default value is determined by the first
+  available of the following values:
+
+  #. ``CMAKE_PKG_CONFIG_ALLOW_SYS_INCLUDES``
+  #. If the ``PKG_CONFIG_ALLOW_SYSTEM_CFLAGS`` environment variable is defined
+     the flags are preserved, otherwise they are filtered during flag mangling.
+
+
+``ALLOW_SYSTEM_LIBS``
+  Preserves "system" directories during flag mangling of library directories
+  in ``CMAKE_PKG_CONFIG_LIBS`` and derived variables.
+
+  When this option is not provided, the default value is determined by the first
+  available of the following values:
+
+  #. ``CMAKE_PKG_CONFIG_ALLOW_SYS_LIBS``
+  #. If the ``PKG_CONFIG_ALLOW_SYSTEM_LIBS`` environment variable is defined
+     the flags are preserved, otherwise they are filtered during flag mangling.

Help/command/execute_process.rst

@@ -140,20 +140,32 @@ Options:
  ``NONE``
    Perform no decoding.  This assumes that the process output is encoded
    in the same way as CMake's internal encoding (UTF-8).
-   This is the default.
+
+   This was the default in CMake 3.14 and older.
+
  ``AUTO``
    Use the current active console's codepage or if that isn't
    available then use ANSI.
+
+   This was the default in CMake 3.15 through 3.30.
+
  ``ANSI``
    Use the ANSI codepage.
+
  ``OEM``
    Use the original equipment manufacturer (OEM) code page.
- ``UTF8`` or ``UTF-8``
-   Use the UTF-8 codepage.
 
+ ``UTF-8``
    .. versionadded:: 3.11
-     Accept ``UTF-8`` spelling for consistency with the
-     `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention.
+
+   Use the UTF-8 codepage.
+
+   This is the default.  See policy :policy:`CMP0176`.
+
+ ``UTF8``
+   Use the UTF-8 codepage.  Use of this name is discouraged in favor
+   of ``UTF-8`` to match the `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_
+   naming convention.
 
 ``COMMAND_ERROR_IS_FATAL <ANY|LAST>``
   .. versionadded:: 3.19

Help/command/file.rst

@@ -400,10 +400,19 @@ Filesystem
   ============== ======================================================
 
 .. signature::
-  file(MAKE_DIRECTORY <directories>...)
+  file(MAKE_DIRECTORY <directories>... [RESULT <result>])
 
   Create the given directories and their parents as needed.
 
+  The options are:
+
+    ``RESULT <result>``
+      .. versionadded:: 3.31
+
+      Set ``<result>`` variable to ``0`` on success or an error message
+      otherwise. If ``RESULT`` is not specified and the operation fails,
+      an error is emitted.
+
   .. versionchanged:: 3.30
     ``<directories>`` can be an empty list. CMake 3.29 and earlier required
     at least one directory to be given.
@@ -802,10 +811,21 @@ Transfer
       environment variable will be used instead.
       See :variable:`CMAKE_TLS_VERSION` for allowed values.
 
+      .. versionchanged:: 3.31
+        The default is TLS 1.2.
+        Previously, no minimum version was enforced by default.
+
     ``TLS_VERIFY <ON|OFF>``
       Specify whether to verify the server certificate for ``https://`` URLs.
-      The default is to *not* verify. If this option is not specified, the
-      value of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead.
+      If this option is not specified, the value of the
+      :variable:`CMAKE_TLS_VERIFY` variable or :envvar:`CMAKE_TLS_VERIFY`
+      environment variable will be used instead.
+      If neither is set, the default is *on*.
+
+      .. versionchanged:: 3.31
+        The default is on.  Previously, the default was off.
+        Users may set the :envvar:`CMAKE_TLS_VERIFY` environment
+        variable to ``0`` to restore the old default.
 
       .. versionadded:: 3.18
         Added support to ``file(UPLOAD)``.
@@ -818,9 +838,7 @@ Transfer
       .. versionadded:: 3.18
         Added support to ``file(UPLOAD)``.
 
-  For ``https://`` URLs CMake must be built with OpenSSL support.  ``TLS/SSL``
-  certificates are not checked by default.  Set ``TLS_VERIFY`` to ``ON`` to
-  check certificates.
+  For ``https://`` URLs CMake must be built with SSL/TLS support.
 
   Additional options to ``DOWNLOAD`` are:
 
@@ -892,8 +910,9 @@ Archiving
     PATHS <paths>...
     [FORMAT <format>]
     [COMPRESSION <compression>
-     [COMPRESSION_LEVEL <compression-level>]]
+    [COMPRESSION_LEVEL <compression-level>]]
     [MTIME <mtime>]
+    [WORKING_DIRECTORY <dir>]
     [VERBOSE])
   :target: ARCHIVE_CREATE
   :break: verbatim
@@ -904,40 +923,55 @@ Archiving
   listed in ``<paths>``.  Note that ``<paths>`` must list actual files or
   directories; wildcards are not supported.
 
-  Use the ``FORMAT`` option to specify the archive format.  Supported values
-  for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and
-  ``zip``.  If ``FORMAT`` is not given, the default format is ``paxr``.
+  The options are:
 
-  Some archive formats allow the type of compression to be specified.
-  The ``7zip`` and ``zip`` archive formats already imply a specific type of
-  compression.  The other formats use no compression by default, but can be
-  directed to do so with the ``COMPRESSION`` option.  Valid values for
-  ``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.
+  ``FORMAT <format>``
+    Specify the archive format.  Supported values for ``<format>`` are
+    ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and ``zip``.
+    If ``FORMAT`` is not given, the default format is ``paxr``.
+
+  ``COMPRESSION <compression>``
+    Some archive formats allow the type of compression to be specified.
+    The ``7zip`` and ``zip`` archive formats already imply a specific type of
+    compression.  The other formats use no compression by default, but can be
+    directed to do so with the ``COMPRESSION`` option.  Valid values for
+    ``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.
+
+    .. note::
+      With ``FORMAT`` set to ``raw``, only one file will be compressed
+      with the compression type specified by ``COMPRESSION``.
+
+  ``COMPRESSION_LEVEL <compression-level>``
+    .. versionadded:: 3.19
 
-  .. versionadded:: 3.19
     The compression level can be specified with the ``COMPRESSION_LEVEL``
     option.  The ``<compression-level>`` should be between 0-9, with the
     default being 0.  The ``COMPRESSION`` option must be present when
     ``COMPRESSION_LEVEL`` is given.
 
-  .. versionadded:: 3.26
-    The ``<compression-level>`` of the ``Zstd`` algorithm can be set
-    between 0-19.
+    .. versionadded:: 3.26
+      The ``<compression-level>`` of the ``Zstd`` algorithm can be set
+      between 0-19.
 
-  .. note::
-    With ``FORMAT`` set to ``raw``, only one file will be compressed with the
-    compression type specified by ``COMPRESSION``.
+  ``MTIME <mtime>``
+    Specify the modification time recorded in tarball entries.
 
-  The ``VERBOSE`` option enables verbose output for the archive operation.
+  ``WORKING_DIRECTORY <dir>``
+    .. versionadded:: 3.31
 
-  To specify the modification time recorded in tarball entries, use
-  the ``MTIME`` option.
+    Specify the directory in which the archive creation operation will
+    be executed.  Paths in the ``<paths>`` argument can be relative to
+    this directory.  If this option is not provided, the current working
+    directory will be used by default.
+
+  ``VERBOSE``
+    Enable verbose output from the archive operation.
 
 .. signature::
   file(ARCHIVE_EXTRACT
     INPUT <archive>
     [DESTINATION <dir>]
-    [PATTERNS <patterns>...]
+    [PATTERNS <pattern>...]
     [LIST_ONLY]
     [VERBOSE]
     [TOUCH])
@@ -947,17 +981,30 @@ Archiving
 
   Extracts or lists the content of the specified ``<archive>``.
 
-  The directory where the content of the archive will be extracted to can
-  be specified using the ``DESTINATION`` option.  If the directory does not
-  exist, it will be created.  If ``DESTINATION`` is not given, the current
-  binary directory will be used.
+  The options are:
+
+  ``DESTINATION <dir>``
+    Specify the directory under which the content of the archive will be
+    extracted.  If the directory does not exist, it will be created.
+    If ``DESTINATION`` is not given, the current binary directory will
+    be used.
 
-  If required, you may select which files and directories to list or extract
-  from the archive using the specified ``<patterns>``.  Wildcards are
-  supported.  If the ``PATTERNS`` option is not given, the entire archive will
-  be listed or extracted.
+  ``PATTERNS <pattern>...``
+    Extract/list only files and directories that match one of the given
+    patterns.  Wildcards are supported.  If the ``PATTERNS`` option is
+    not given, the entire archive will be listed or extracted.
 
-  ``LIST_ONLY`` will list the files in the archive rather than extract them.
+  ``LIST_ONLY``
+    List the files in the archive rather than extract them.
+
+  ``TOUCH``
+    .. versionadded:: 3.24
+
+    Give extracted files a current local timestamp instead of extracting
+    file timestamps from the archive.
+
+  ``VERBOSE``
+    Enable verbose output from the extraction operation.
 
   .. note::
     The working directory for this subcommand is the ``DESTINATION`` directory
@@ -966,12 +1013,6 @@ Archiving
     ``INPUT`` archives as they are unlikely to be extracted where a relative
     path works.
 
-  .. 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.
-
 Handling Runtime Binaries
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1162,6 +1203,14 @@ Handling Runtime Binaries
 
   5. Otherwise, the dependency is unresolved.
 
+  .. versionchanged:: 3.31
+
+    Resolution of each encountered library file name occurs at most once
+    while processing a given root ELF file (executable or shared object).
+    If a library file name is encountered again in the dependency tree,
+    the original resolution is assumed.  This behavior more closely matches
+    the dynamic loader's behavior on Linux.
+
   On Windows platforms, library resolution works as follows:
 
   1. DLL dependency names are converted to lowercase for matching filters.

Help/command/find_package.rst

@@ -503,6 +503,42 @@ The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`,
 :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some
 of the above locations to be ignored.
 
+Paths are searched in the order described above.  The first viable package
+configuration file found is used, even if a newer version of the package
+resides later in the list of search paths.
+
+For search paths which contain ``<name>*``, the order among matching paths
+is unspecified unless the :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` variable
+is set.  This variable, along with the
+:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable, determines the order
+in which CMake considers paths that match a single search path containing
+``<name>*``.  For example, if the file system contains the package
+configuration files
+
+::
+
+  <prefix>/example-1.2/example-config.cmake
+  <prefix>/example-1.10/example-config.cmake
+  <prefix>/share/example-2.0/example-config.cmake
+
+it is unspecified (when the aforementioned variables are unset) whether
+``find_package(example)`` will find ``example-1.2`` or ``example-1.10``
+(assuming that both are viable), but ``find_package`` will *not* find
+``example-2.0``, because one of the other two will be found first.
+
+To control the order in which ``find_package`` searches directories that match
+a glob expression, use :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
+:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
+For instance, to cause the above example to select ``example-1.10``,
+one can set
+
+.. code-block:: cmake
+
+  SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
+  SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
+
+before calling ``find_package``.
+
 .. versionadded:: 3.16
    Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable
    various search locations.
@@ -648,22 +684,6 @@ is acceptable the following variables are set:
   Number of version components, 0 to 4
 
 and the corresponding package configuration file is loaded.
-When multiple package configuration files are available whose version files
-claim compatibility with the version requested it is unspecified which
-one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`
-is set no attempt is made to choose a highest or closest version number.
-
-To control the order in which ``find_package`` checks for compatibility use
-the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
-:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
-For instance in order to select the highest version one can set
-
-.. code-block:: cmake
-
-  SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
-  SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
-
-before calling ``find_package``.
 
 Package File Interface Variables
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Help/command/find_program.rst

@@ -41,3 +41,23 @@ When more than one value is given to the ``NAMES`` option this command by
 default will consider one name at a time and search every directory
 for it.  The ``NAMES_PER_DIR`` option tells this command to consider one
 directory at a time and search for all names in it.
+
+The set of files considered to be programs is platform-specific:
+
+* On Windows, filename suffixes are considered in order ``.com``, ``.exe``,
+  and no suffix.
+
+* On non-Windows systems, no filename suffix is considered, but files
+  must have execute permission (see policy :policy:`CMP0109`).
+
+To search for scripts, specify an extension explicitly:
+
+.. code-block:: cmake
+
+  if(WIN32)
+    set(_script_suffix .bat)
+  else()
+    set(_script_suffix .sh)
+  endif()
+
+  find_program(MY_SCRIPT NAMES my_script${_script_suffix})

Help/command/get_property.rst

@@ -29,7 +29,7 @@ It must be one of the following:
   Scope is unique and does not accept a name.
 
 ``DIRECTORY``
-  Scope defaults to the current directory but another
+  Scope defaults to the current directory, but another
   directory (already processed by CMake) may be named by the
   full or relative path ``<dir>``.
   Relative paths are treated as relative to the current source directory.
@@ -79,10 +79,10 @@ It must be one of the following:
 
     ``DIRECTORY <dir>``
       The test property will be read from the ``<dir>`` directory's
-      scope.  CMake must already know about the directory, either by having added
-      it through a call to :command:`add_subdirectory` or ``<dir>`` being the top
-      level directory. Relative paths are treated as relative to the current
-      source directory. ``<dir>`` may reference a binary directory.
+      scope.  CMake must already know about the directory, either by having
+      added it through a call to :command:`add_subdirectory` or ``<dir>`` being
+      the top level directory. Relative paths are treated as relative to the
+      current source directory. ``<dir>`` may reference a binary directory.
 
 ``CACHE``
   Scope must name one cache entry.
@@ -91,19 +91,20 @@ It must be one of the following:
   Scope is unique and does not accept a name.
 
 The required ``PROPERTY`` option is immediately followed by the name of
-the property to get.  If the property is not set an empty value is
-returned, although some properties support inheriting from a parent scope
-if defined to behave that way (see :command:`define_property`).
+the property to get.  If the property is not set, the named ``<variable>``
+will be unset in the calling scope upon return, although some properties
+support inheriting from a parent scope if defined to behave that way
+(see :command:`define_property`).
 
-If the ``SET`` option is given the variable is set to a boolean
+If the ``SET`` option is given, the variable is set to a boolean
 value indicating whether the property has been set.  If the ``DEFINED``
-option is given the variable is set to a boolean value indicating
-whether the property has been defined such as with the
+option is given, the variable is set to a boolean value indicating
+whether the property has been defined, such as with the
 :command:`define_property` command.
 
-If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a
+If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given, then the variable is set to a
 string containing documentation for the requested property.  If
-documentation is requested for a property that has not been defined
+documentation is requested for a property that has not been defined,
 ``NOTFOUND`` is returned.
 
 .. note::

Help/command/if.rst

@@ -41,13 +41,15 @@ Compound conditions are evaluated in the following order of precedence:
 
 1. `Parentheses`_.
 
-2. Unary tests such as `EXISTS`_, `COMMAND`_, and `DEFINED`_.
+2. Unary tests such as `COMMAND`_, `POLICY`_, `TARGET`_, `TEST`_,
+   `EXISTS`_, `IS_READABLE`_, `IS_WRITABLE`_, `IS_EXECUTABLE`_,
+   `IS_DIRECTORY`_, `IS_SYMLINK`_, `IS_ABSOLUTE`_, and `DEFINED`_.
 
 3. Binary tests such as `EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_,
    `GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_,
    `STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_,
    `VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_,
-   `PATH_EQUAL`_, and `MATCHES`_.
+   `PATH_EQUAL`_, `IN_LIST`_, `IS_NEWER_THAN`_, and `MATCHES`_.
 
 4. Unary logical operator `NOT`_.
 
@@ -471,6 +473,10 @@ above-documented condition syntax accepts ``<variable|string>``:
   variables.  If so, their defined values are used otherwise the original value
   is used.
 
+* The left hand argument to `IN_LIST`_ is tested to see if it is a defined
+  variable.  If so, the variable's value is used, otherwise the original
+  value is used.
+
 * The right hand argument to `NOT`_ is tested to see if it is a boolean
   constant.  If so, the value is used, otherwise it is assumed to be a
   variable and it is dereferenced.

Help/command/include_external_msproject.rst

@@ -1,7 +1,8 @@
 include_external_msproject
 --------------------------
 
-Include an external Microsoft project file in a workspace.
+Include an external Microsoft project file in the solution file produced
+by :ref:`Visual Studio Generators`. Ignored on other generators.
 
 .. code-block:: cmake
 
@@ -11,9 +12,9 @@ Include an external Microsoft project file in a workspace.
                              [PLATFORM platformName]
                              dep1 dep2 ...)
 
-Includes an external Microsoft project in the generated workspace
-file.  Currently does nothing on UNIX.  This will create a target
-named ``[projectname]``.  This can be used in the :command:`add_dependencies`
+Includes an external Microsoft project in the generated solution file.
+This will create a target named ``[projectname]``.
+This can be used in the :command:`add_dependencies`
 command to make things depend on the external project.
 
 ``TYPE``, ``GUID`` and ``PLATFORM`` are optional parameters that allow one to

Help/command/install.rst

@@ -19,6 +19,7 @@ Synopsis
   install(`SCRIPT`_ <file> [...])
   install(`CODE`_ <code> [...])
   install(`EXPORT`_ <export-name> [...])
+  install(`PACKAGE_INFO`_ <package-name> [...])
   install(`RUNTIME_DEPENDENCY_SET`_ <set-name> [...])
 
 Introduction
@@ -38,6 +39,13 @@ are executed in order during installation.
   The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the
   default copying behavior of ``install()``.
 
+.. versionchanged:: 3.31
+  Projects can enable :prop_gbl:`INSTALL_PARALLEL` to enable a parallel
+  installation. When using the parallel install, subdirectories added by calls
+  to the :command:`add_subdirectory` command are installed independently
+  and the order that install rules added in different subdirectories will run is
+  not guaranteed.
+
 .. _`common options`:
 
 There are multiple signatures for this command.  Some of them define
@@ -50,7 +58,7 @@ signatures that specify them.  The common options are:
   ``<dir>`` should be a relative path.  An absolute path is allowed,
   but not recommended.
 
-  When a relative path is given it is interpreted relative to the value
+  When a relative path is given, it is interpreted relative to the value
   of the :variable:`CMAKE_INSTALL_PREFIX` variable.
   The prefix can be relocated at install time using the ``DESTDIR``
   mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable
@@ -67,6 +75,11 @@ signatures that specify them.  The common options are:
   If an absolute path (with a leading slash or drive letter) is given
   it is used verbatim.
 
+  .. versionchanged:: 3.31
+    ``<dir>`` will be normalized according to the same
+    :ref:`normalization rules <Normalization>` as the
+    :command:`cmake_path` command.
+
 ``PERMISSIONS <permission>...``
   Specify permissions for installed files.  Valid permissions are
   ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``,
@@ -104,11 +117,6 @@ signatures that specify them.  The common options are:
   Specify that the file is excluded from a full installation and only
   installed as part of a component-specific installation
 
-``RENAME <name>``
-  Specify a name for an installed file that may be different from the
-  original file.  Renaming is allowed only when a single file is
-  installed by the command.
-
 ``OPTIONAL``
   Specify that it is not an error if the file to be installed does
   not exist.
@@ -393,6 +401,12 @@ Signatures
     If a relative path is specified, it is treated as relative to the
     :genex:`$<INSTALL_PREFIX>`.
 
+    Unlike other ``DESTINATION`` arguments for the various ``install()``
+    subcommands, paths given after ``INCLUDES DESTINATION`` are used as
+    given.  They are not normalized, nor assumed to be normalized, although
+    it is recommended that they are given in normalized form (see
+    :ref:`Normalization`).
+
   ``RUNTIME_DEPENDENCY_SET <set-name>``
     .. versionadded:: 3.21
 
@@ -536,6 +550,10 @@ Signatures
   However, if any item begins in a generator expression it must evaluate
   to a full path.
 
+  The optional ``RENAME <name>`` argument is used to specify a name for the
+  installed file that is different from the original file name.  Renaming
+  is allowed only when a single file is installed by the command.
+
   Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
   A ``TYPE`` argument specifies the generic file type of the files being
   installed.  A destination will then be set automatically by taking the
@@ -561,6 +579,7 @@ Signatures
   ``LOCALE``              ``${CMAKE_INSTALL_LOCALEDIR}``     ``<DATAROOT dir>/locale``
   ``MAN``                 ``${CMAKE_INSTALL_MANDIR}``        ``<DATAROOT dir>/man``
   ``DOC``                 ``${CMAKE_INSTALL_DOCDIR}``        ``<DATAROOT dir>/doc``
+  ``LIBEXEC``             ``${CMAKE_INSTALL_LIBEXECDIR}``    ``libexec``
   ======================= ================================== =========================
 
   Projects wishing to follow the common practice of installing headers into a
@@ -599,6 +618,9 @@ Signatures
     use "generator expressions" with the syntax ``$<...>``.  See the
     :manual:`cmake-generator-expressions(7)` manual for available expressions.
 
+  .. versionadded:: 3.31
+    The ``TYPE`` argument now supports type ``LIBEXEC``.
+
 .. signature::
   install(DIRECTORY <dir>... [...])
 
@@ -713,6 +735,7 @@ Signatures
   ``LOCALE``              ``${CMAKE_INSTALL_LOCALEDIR}``     ``<DATAROOT dir>/locale``
   ``MAN``                 ``${CMAKE_INSTALL_MANDIR}``        ``<DATAROOT dir>/man``
   ``DOC``                 ``${CMAKE_INSTALL_DOCDIR}``        ``<DATAROOT dir>/doc``
+  ``LIBEXEC``             ``${CMAKE_INSTALL_LIBEXECDIR}``    ``libexec``
   ======================= ================================== =========================
 
   Note that some of the types' built-in defaults use the ``DATAROOT`` directory as
@@ -736,6 +759,9 @@ Signatures
     The list of ``dirs...`` given to ``DIRECTORY`` may use
     "generator expressions" too.
 
+  .. versionadded:: 3.31
+    The ``TYPE`` argument now supports type ``LIBEXEC``.
+
 .. signature::
   install(SCRIPT <file> [...])
   install(CODE <code> [...])
@@ -800,6 +826,7 @@ Signatures
   the generated file will be called ``<export-name>.cmake`` but the ``FILE``
   option may be used to specify a different name.  The value given to
   the ``FILE`` option must be a file name with the ``.cmake`` extension.
+
   If a ``CONFIGURATIONS`` option is given then the file will only be installed
   when one of the named configurations is installed.  Additionally, the
   generated import file will reference only the matching target
@@ -898,6 +925,61 @@ Signatures
   executable from the installation tree using the imported target name
   ``mp_myexe`` as if the target were built in its own tree.
 
+.. signature::
+  install(PACKAGE_INFO <package-name> [...])
+
+  .. versionadded:: 3.31
+  .. note::
+
+    Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO``.
+
+  Installs a |CPS|_ file exporting targets for dependent projects:
+
+  .. code-block:: cmake
+
+    install(PACKAGE_INFO <package-name> EXPORT <export-name>
+            [APPENDIX <appendix-name>]
+            [DESTINATION <dir>]
+            [LOWER_CASE_FILE]
+            [VERSION <version>
+             [COMPAT_VERSION <version>]
+             [VERSION_SCHEMA <string>]]
+            [DEFAULT_TARGETS <target>...]
+            [DEFAULT_CONFIGURATIONS <config>...]
+            [PERMISSIONS <permission>...]
+            [CONFIGURATIONS <config>...]
+            [COMPONENT <component>]
+            [EXCLUDE_FROM_ALL])
+
+  The ``PACKAGE_INFO`` form generates and installs a |CPS| file which describes
+  installed targets such that they can be consumed by another project.
+  Target installations are associated with the export ``<export-name>``
+  using the ``EXPORT`` option of the :command:`install(TARGETS)` signature
+  documented above.  Unlike :command:`install(EXPORT)`, this information is not
+  expressed in CMake code, and can be consumed by tools other than CMake.  When
+  imported into another CMake project, the imported targets will be prefixed
+  with ``<package-name>::``.  By default, the generated file will be called
+  ``<package-name>[-<appendix-name>].cps``.  If ``LOWER_CASE_FILE`` is given,
+  the package name as it appears on disk (in both the file name and install
+  destination) will be first converted to lower case.
+
+  If ``DESTINATION`` is not specified, a platform-specific default is used.
+
+  If ``APPENDIX`` is specified, rather than generating a top level package
+  specification, the specified targets will be exported as an appendix to the
+  named package.  Appendices may be used to separate less commonly used targets
+  (along with their external dependencies) from the rest of a package.  This
+  enables consumers to ignore transitive dependencies for targets that they
+  don't use, and also allows a single logical "package" to be composed of
+  artifacts produced by multiple build trees.
+
+  Appendices are not permitted to change basic package metadata; therefore,
+  none of ``VERSION``, ``COMPAT_VERSION``, ``VERSION_SCHEMA``,
+  ``DEFAULT_TARGETS`` or ``DEFAULT_CONFIGURATIONS`` may be specified in
+  combination with ``APPENDIX``.  Additionally, it is strongly recommended that
+  use of ``LOWER_CASE_FILE`` should be consistent between the main package and
+  any appendices.
+
 .. signature::
   install(RUNTIME_DEPENDENCY_SET <set-name> [...])
 
@@ -1090,3 +1172,6 @@ and by CPack. You can also invoke this script manually with
   This is an environment variable rather than a CMake variable. It allows you
   to change the installation prefix on UNIX systems. See :envvar:`DESTDIR` for
   details.
+
+.. _CPS: https://cps-org.github.io/cps/
+.. |CPS| replace:: Common Package Specification

Help/command/project.rst

@@ -44,27 +44,18 @@ Projects should not rely on ``<PROJECT-NAME>_SOURCE_DIR`` or
 ``<PROJECT-NAME>_BINARY_DIR`` holding a particular value outside of the scope
 of the call to ``project()`` or one of its child scopes.
 
-.. versionchanged:: 3.30.3
+.. versionchanged:: 3.30
   ``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``, and
-  ``<PROJECT-NAME>_IS_TOP_LEVEL`` are always set as non-cache variables by
-  ``project(<PROJECT-NAME> ...)``.
-
-.. versionchanged:: 3.30.4
-  The variables ``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``,
-  and ``<PROJECT-NAME>_IS_TOP_LEVEL`` are only set as non-cache variables if
-  they are already set as cache or non-cache variables when
-  ``project(<PROJECT-NAME> ...)`` is called.
-  Note that this logic is flawed, as it can result in different behavior
-  between the first and subsequent runs because cache variables won't exist
-  on the first run, but they will on subsequent runs.
-
-.. versionchanged:: 3.30.5
-  The variables ``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``,
-  and ``<PROJECT-NAME>_IS_TOP_LEVEL`` are only set as non-cache variables if
-  they are already set as non-cache variables when
-  ``project(<PROJECT-NAME> ...)`` is called.
-  Unlike the flawed behavior of 3.30.4, non-cache variables will not be set
-  if only cache variables of the same name are set.
+  ``<PROJECT-NAME>_IS_TOP_LEVEL``, if already set as normal variables when
+  ``project(<PROJECT-NAME> ...)`` is called, are updated by the call.
+  Cache entries by the same names are always set as before.
+  See release notes for 3.30.3, 3.30.4, and 3.30.5 for details.
+
+.. versionchanged:: 3.31
+  ``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``, and
+  ``<PROJECT-NAME>_IS_TOP_LEVEL`` are always set as normal variables by
+  ``project(<PROJECT-NAME> ...)``.  See policy :policy:`CMP0180`.
+  Cache entries by the same names are always set as before.
 
 Options
 ^^^^^^^

Help/command/target_link_libraries.rst

@@ -140,6 +140,11 @@ Items containing ``::``, such as ``Foo::Bar``, are assumed to be
 target names and will cause an error if no such target exists.
 See policy :policy:`CMP0028`.
 
+See the :variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable and
+corresponding :prop_tgt:`LINK_LIBRARIES_STRATEGY` target property
+for details on how CMake orders direct link dependencies on linker
+command lines.
+
 See the :manual:`cmake-buildsystem(7)` manual for more on defining
 buildsystem properties.
 

Help/cpack_gen/archive.rst

@@ -91,14 +91,10 @@ CPack generators which are essentially archives at their core. These include:
 
   .. versionadded:: 3.18
 
-  :Default: ``1``
+  :Default: value of :variable:`CPACK_THREADS`
 
   If set to ``0``, the number of available cores on the machine will be used instead.
-  The default is ``1`` which limits compression to a single thread. Note that
-  not all compression modes support threading in all environments. Currently,
-  only the XZ compression may support it.
-
-  See also the :variable:`CPACK_THREADS` variable.
+  Note that not all compression modes support threading in all environments.
 
   .. versionadded:: 3.21
 

Help/cpack_gen/deb.rst

@@ -182,11 +182,22 @@ List of CPack DEB generator specific variables:
    only the automatically discovered dependencies will be set for this
    component.
 
+ .. versionchanged:: 3.31
+
+   The variable is always expanded as a list. Before it was expanded only
+   if used in cooperation with :variable:`CPACK_DEB_COMPONENT_INSTALL`,
+   :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` or
+   :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`.
+   This meant that if a component had no shared libraries discovered
+   (e.g. a package composed only of scripts) you had to join the list
+   by yourself to obtain a valid Depends field.
+
  Example:
 
  .. code-block:: cmake
 
    set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)")
+   list(APPEND CPACK_DEBIAN_PACKAGE_DEPENDS cmake)
 
 .. variable:: CPACK_DEBIAN_ENABLE_COMPONENT_DEPENDS
 
@@ -654,6 +665,31 @@ List of CPack DEB generator specific variables:
    This value is not interpreted. It is possible to pass an optional
    revision number of the referenced source package as well.
 
+.. variable:: CPACK_DEBIAN_PACKAGE_MULTIARCH
+              CPACK_DEBIAN_<COMPONENT>_PACKAGE_MULTIARCH
+
+ Sets the `Multi-Arch` field of the Debian package.
+ Packages can declare in their control file how they should handle
+ situations, where packages for different architectures are being installed
+ on the same machine.
+
+ :Mandatory: No
+ :Default:
+
+   - An empty string for non-component based installations
+   - :variable:`CPACK_DEBIAN_PACKAGE_MULTIARCH` for component-based
+     installations.
+
+ .. versionadded:: 3.31
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_MULTIARCH` variables.
+
+ See https://wiki.debian.org/MultiArch/Hints
+
+ .. note::
+
+   This value is validated. It must be one of the following values:
+   ``same``, ``foreign``, ``allowed``.
+
 Packaging of debug information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

Help/cpack_gen/ifw.rst

@@ -275,6 +275,16 @@ Package
 
  This feature is available for QtIFW 4.0.0 and later.
 
+.. variable:: CPACK_IFW_PACKAGE_PRODUCT_IMAGE_URLS
+
+ .. versionadded:: 3.31
+
+ A list of URLs associated with the ProductImages.
+ Only used if  ``CPACK_IFW_PACKAGE_PRODUCT_IMAGES`` is defined
+ and it has the same size.
+
+ This feature is available for QtIFW 4.0.0 and later.
+
 .. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM
 
  .. versionadded:: 3.23

Help/cpack_gen/rpm.rst

@@ -246,9 +246,8 @@ List of CPack RPM generator specific variables:
  :Default: (system default)
 
  May be used to override RPM compression type to be used to build the
- RPM. For example some Linux distribution now default to ``lzma`` or ``xz``
- compression whereas older cannot use such RPM. Using this one can enforce
- compression type to be used.
+ RPM. For example some Linux distributions default to ``xz`` or ``zstd``.
+ Using this, one can specify a specific compression type to be used.
 
  Possible values are:
 
@@ -264,6 +263,11 @@ List of CPack RPM generator specific variables:
   ``gzip``
     GNU Gzip compression
 
+  ``zstd``
+    .. versionadded:: 3.31
+
+    Zstandard compression
+
 .. variable:: CPACK_RPM_PACKAGE_AUTOREQ
               CPACK_RPM_<component>_PACKAGE_AUTOREQ
 

Help/cpack_gen/wix.rst

@@ -458,8 +458,7 @@ Windows using WiX.
    administrative privileges.  Start menu entries created by the
    installer are visible to all users.
 
-   This is the default if :variable:`CPACK_WIX_VERSION` is set to any
-   value other than ``3``.
+   This is the default.  See policy :policy:`CMP0172`.
 
  ``perUser``
    Not yet supported. This is reserved for future use.
@@ -467,9 +466,8 @@ Windows using WiX.
  ``NONE``
    Create an installer without any ``InstallScope`` attribute.
 
-   If :variable:`CPACK_WIX_VERSION` is not set, or is set to ``3``, this
-   value is the default to preserve compatibility with 3.28 and lower.
-   Otherwise, this value is not supported.
+   This is supported only if :variable:`CPACK_WIX_VERSION` is not set,
+   or is set to ``3``.
 
    .. deprecated:: 3.29
 

Help/dev/README.rst

@@ -23,12 +23,13 @@ branches and tags.  Upstream development processes are covered by the
 following documents:
 
 * The `CMake Review Process`_ manages integration of changes.
-* The `CMake Testing Process`_ drives integration testing.
+* The `CMake Integration Testing`_ infrastructure tests changes
+  before and after merging.
 
 .. _`Kitware's GitLab Instance`: https://gitlab.kitware.com
 .. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake
 .. _`CMake Review Process`: review.rst
-.. _`CMake Testing Process`: testing.rst
+.. _`CMake Integration Testing`: integration-testing.rst
 
 Developer Documentation
 =======================
@@ -37,10 +38,12 @@ CMake developer documentation is provided by the following documents:
 
 * The `CMake Source Code Guide`_.
 * The `CMake Documentation Guide`_.
+* The `CMake Testing Guide`_.
 * The `CMake Experimental Features Guide`_.
 
 .. _`CMake Source Code Guide`: source.rst
 .. _`CMake Documentation Guide`: documentation.rst
+.. _`CMake Testing Guide`: testing.rst
 .. _`CMake Experimental Features Guide`: experimental.rst
 
 Maintainer Documentation

Help/dev/documentation.rst

@@ -310,17 +310,17 @@ are suppressed inside of square- or angle-brackets.  This behavior can be
 controlled using the ``:break:`` option; note, however, that there is no way
 to *force* a line break.  The default value is 'smart'.  Allowable values are:
 
-  ``all``
-    Allow line breaks at any whitespace.
+``all``
+  Allow line breaks at any whitespace.
 
-  ``smart`` (default)
-    Allow line breaks at whitespace, except between matched square- or
-    angle-brackets.  For example, if a signature contains the text
-    ``<input>... [OUTPUT_VARIABLE <out-var>]``, a line break would be allowed
-    after ``<input>...`` but not between ``OUTPUT_VARIABLE`` and ``<out-var>``.
+``smart`` (default)
+  Allow line breaks at whitespace, except between matched square- or
+  angle-brackets.  For example, if a signature contains the text
+  ``<input>... [OUTPUT_VARIABLE <out-var>]``, a line break would be allowed
+  after ``<input>...`` but not between ``OUTPUT_VARIABLE`` and ``<out-var>``.
 
-  ``verbatim``
-    Allow line breaks only where the source document contains a newline.
+``verbatim``
+  Allow line breaks only where the source document contains a newline.
 
 The directive treats its content as the documentation of the signature(s).
 Indent the signature documentation accordingly.

Help/dev/experimental.rst

@@ -39,6 +39,23 @@ When activated, this experimental feature provides the following:
   using the ``CMAKE_EXPORT_FIND_PACKAGE_NAME`` variable and/or
 ``EXPORT_FIND_PACKAGE_NAME`` target property.
 
+Export |CPS| Package Information
+================================
+
+In order to activate support for this experimental feature, set
+
+* variable ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO`` to
+* value ``b80be207-778e-46ba-8080-b23bba22639e``.
+
+This UUID may change in future versions of CMake.  Be sure to use the value
+documented here by the source tree of the version of CMake with which you are
+experimenting.
+
+When activated, this experimental feature provides the following:
+
+* The experimental ``install(PACKAGE_INFO)`` command is available to export
+  package information in the |CPS|_ format.
+
 C++ ``import std`` support
 ==========================
 
@@ -60,3 +77,27 @@ When activated, this experimental feature provides the following:
 
 * Targets with the property set to a true value and at least ``cxx_std_23``
   may use ``import std;`` in any scanned C++ source file.
+
+.. _CPS: https://cps-org.github.io/cps/
+.. |CPS| replace:: Common Package Specification
+
+Build database support
+======================
+
+In order to activate support for exporting build databases, set
+
+* variable ``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` to
+* value ``4bd552e2-b7fb-429a-ab23-c83ef53f3f13``.
+
+This UUID may change in future versions of CMake.  Be sure to use the value
+documented here by the source tree of the version of CMake with which you are
+experimenting.
+
+When activated, this experimental feature provides the following:
+
+* The :prop_tgt:`EXPORT_BUILD_DATABASE` target property and its initializing
+  variable :variable:`CMAKE_EXPORT_BUILD_DATABASE` and environment variable
+  :envvar:`CMAKE_EXPORT_BUILD_DATABASE`.
+
+* Targets with the property set to a true value will have their C++ build
+  information exported to the build database.

Help/dev/integration-testing.rst

@@ -0,0 +1,46 @@
+CMake Integration Testing
+*************************
+
+The following documents how to run integration testing builds.
+See documentation on `CMake Development`_ for more information.
+
+See the `CMake Testing Guide`_ for running the test suite locally.
+
+.. _`CMake Development`: README.rst
+.. _`CMake Testing Guide`: testing.rst
+
+CMake Dashboard Scripts
+=======================
+
+The *integration testing* step of the `CMake Review Process`_ uses a set of
+testing machines that follow an integration branch on their own schedule to
+drive testing and submit results to the `CMake CDash Page`_.  Anyone is
+welcome to provide testing machines in order to help keep support for their
+platforms working.
+
+The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive
+nightly, continuous, and experimental testing of CMake.  Use the following
+commands to set up a new integration testing client:
+
+.. code-block:: console
+
+  $ mkdir -p ~/Dashboards
+  $ cd ~/Dashboards
+  $ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts
+  $ cd CMakeScripts
+
+The `cmake_common.cmake`_ script contains comments at the top with
+instructions to set up a testing client.  As it instructs, create a
+CTest script with local settings and include ``cmake_common.cmake``.
+
+.. _`CMake Review Process`: review.rst
+.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
+.. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts
+.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/-/blob/master/cmake_common.cmake
+
+Nightly Start Time
+------------------
+
+The ``cmake_common.cmake`` script expects its includer to be run from a
+nightly scheduled task (cron job).  Schedule such tasks for sometime after
+``1:00am UTC``, the time at which our nightly testing branches fast-forward.

Help/dev/maint.rst

@@ -306,11 +306,22 @@ Commit with a message such as::
 
   Begin post-$ver development
 
-Push the update to the ``master`` and ``release`` branches:
+Create a topic branch for the update to ``master``:
 
 .. code-block:: shell
 
-  git push --atomic origin master release-$ver:release
+  git branch branch-$ver master
+
+Open a merge request with the ``branch-$ver`` branch for review and CI.
+Add the following trailing lines in the merge request description::
+
+  Fast-forward: true
+  Backport-ff: release:HEAD~1^2
+
+This configures the ``Do: merge`` action to fast-foward the ``master``
+and ``release`` branches to the respective commits created above.
+
+Further steps may proceed after this has been merged.
 
 Announce 'release' Branch
 -------------------------

Help/dev/review.rst

@@ -348,7 +348,7 @@ Integration Testing
 
 The above `topic testing`_ tests the MR topic independent of other
 merge requests and on only a few key platforms and configurations.
-The `CMake Testing Process`_ also has a large number of machines
+`CMake Integration Testing`_ also uses a large number of machines
 provided by Kitware and generous volunteers that cover nearly all
 supported platforms, generators, and configurations.  In order to
 avoid overwhelming these resources, they do not test every MR
@@ -403,7 +403,7 @@ until one of the following occurs:
 Once a MR has been removed from the topic stage a new ``Do: stage``
 command is needed to stage it again.
 
-.. _`CMake Testing Process`: testing.rst
+.. _`CMake Integration Testing`: integration-testing.rst
 
 Resolve
 =======

Help/dev/source.rst

@@ -249,6 +249,14 @@ These are:
   * ``cm::is_unique_ptr``:
     Checks if a type is a ``std::unique_ptr`` type.
 
+  * ``cm::remove_member_pointer``
+    Produces the underlying type of a member-pointer type, ie, given ``T C::*``,
+    returns ``T``.
+
+  * ``cm::member_pointer_class``
+    Produces the class associated with a member-pointer type, ie, given
+    ``T C::*``, returns ``C``.
+
 CMake assumes the compiler supports ``#pragma once``. Use this for all
 hand-written header files.
 
@@ -310,6 +318,7 @@ The CMake source tree is organized as follows.
 
 * ``Tests/``:
   The test suite.  See `Tests/README.rst`_.
+  To run the tests, see the `CMake Testing Guide`_.
 
 * ``Utilities/``:
   Scripts, third-party source code.
@@ -331,5 +340,6 @@ The CMake source tree is organized as follows.
     See `Utilities/Release/README.rst`_.
 
 .. _`CMake Documentation Guide`: documentation.rst
+.. _`CMake Testing Guide`: testing.rst
 .. _`Tests/README.rst`: ../../Tests/README.rst
 .. _`Utilities/Release/README.rst`: ../../Utilities/Release/README.rst

Help/dev/testing.rst

@@ -1,43 +1,111 @@
-CMake Testing Process
-*********************
+CMake Testing Guide
+*******************
 
-The following documents the process for running integration testing builds.
+The following is a guide to the CMake test suite for developers.
 See documentation on `CMake Development`_ for more information.
 
+See `CMake Integration Testing`_ for running integration testing builds.
+
+See `Tests/README.rst`_ for the test suite layout in the source tree.
+
 .. _`CMake Development`: README.rst
+.. _`CMake Integration Testing`: integration-testing.rst
+.. _`Tests/README.rst`: ../../Tests/README.rst
+
+Running Tests in the Build Tree
+===============================
+
+After `Building CMake`_, one may run the test suite in the build tree
+using `ctest(1)`_:
+
+* With a single-configuration CMake generator, such as ``Ninja``
+  or ``Unix Makefiles``, one may simply run ``ctest``:
+
+  .. code-block:: console
+
+    $ ctest
+
+* With a multi-configuration CMake generator, such as
+  ``Ninja Multi-Config``, ``Visual Studio``, or ``Xcode``,
+  one must tell ``ctest`` which configuration to test
+  by passing the ``-C <config>`` option:
+
+  .. code-block:: console
+
+    $ ctest -C Debug
+
+Some useful `ctest(1)`_ options include:
+
+``-N``
+  List test names without running them.
+
+``-V``
+  Show verbose output from each test.
+
+``-j <N>``
+  Run to run up to ``N`` tests concurrently.
 
-CMake Dashboard Scripts
-=======================
+``-R <regex>``
+  Select tests for which the regular expression matches a substring
+  of their name.
 
-The *integration testing* step of the `CMake Review Process`_ uses a set of
-testing machines that follow an integration branch on their own schedule to
-drive testing and submit results to the `CMake CDash Page`_.  Anyone is
-welcome to provide testing machines in order to help keep support for their
-platforms working.
+Cleaning Test Build Trees
+-------------------------
 
-The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive
-nightly, continuous, and experimental testing of CMake.  Use the following
-commands to set up a new integration testing client:
+Many CMake tests create their own test project build trees underneath
+the ``Tests/`` directory at the top of the CMake build tree.  These
+build trees are left behind after testing completes in order to
+facilitate manual investigation of results.  Many of the tests do *not*
+clean their build trees if they are run again, with the exception of
+tests using the `RunCMake`_ infrastructure.
+
+In order to clear test build trees, drive the ``test_clean`` custom target
+in the CMake build tree:
+
+.. code-block:: console
+
+  $ cmake --build . --target test_clean
+
+This removes the ``Tests/`` subdirectories created by individual tests
+so they will use a fresh directory next time they run.
+
+.. _`Building CMake`: ../../README.rst#building-cmake
+.. _`ctest(1)`: https://cmake.org/cmake/help/latest/manual/ctest.1.html
+.. _`RunCMake`: ../../Tests/RunCMake/README.rst
+
+Running Tests with a Different Generator
+========================================
+
+After `Building CMake`_ with one CMake generator, one may configure the
+test suite using a different generator in a separate build tree, without
+building CMake itself again, by defining ``CMake_TEST_EXTERNAL_CMAKE``
+to be the absolute path to the ``bin`` directory containing the ``cmake``,
+``ctest``, and ``cpack`` executables.
+
+For example, after building CMake with the ``Ninja`` generator:
 
 .. code-block:: console
 
-  $ mkdir -p ~/Dashboards
-  $ cd ~/Dashboards
-  $ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts
-  $ cd CMakeScripts
+  $ cmake -B build-ninja -G Ninja -DCMAKE_BUILD_TYPE=Debug
+  $ cmake --build build-ninja
 
-The `cmake_common.cmake`_ script contains comments at the top with
-instructions to set up a testing client.  As it instructs, create a
-CTest script with local settings and include ``cmake_common.cmake``.
+one may configure a second build tree to drive tests with the
+``Ninja Multi-Config`` generator:
+
+.. code-block:: console
 
-.. _`CMake Review Process`: review.rst
-.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake
-.. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts
-.. _`cmake_common.cmake`: https://gitlab.kitware.com/cmake/dashboard-scripts/-/blob/master/cmake_common.cmake
+  $ cmake -B build-nmc-tests -G "Ninja Multi-Config" \
+    -DCMake_TEST_EXTERNAL_CMAKE="$PWD/build-ninja/bin"
+  $ cmake --build build-nmc-tests --config Release
+
+The second build tree does not build CMake itself, but does configure
+the test suite and build test binaries.  One may then run tests normally:
+
+.. code-block:: console
 
-Nightly Start Time
-------------------
+  $ cd build-nmc-tests
+  $ ctest -C Release
 
-The ``cmake_common.cmake`` script expects its includer to be run from a
-nightly scheduled task (cron job).  Schedule such tasks for sometime after
-``1:00am UTC``, the time at which our nightly testing branches fast-forward.
+Note that the configuration with which one drives tests in the second
+build tree is independent of the configuration with which CMake was
+built in the first.

Help/dev/try_compile-linker-language.rst

@@ -1,6 +0,0 @@
-try_compile-linker-language
----------------------------
-
-* The :command:`try_compile` and :command:`try_run` commands gained a
-  ``LINKER_LANGUAGE`` option to specify the :prop_tgt:`LINKER_LANGUAGE`
-  target property in the generated test project.

Help/envvar/CMAKE_CONFIG_DIR.rst

@@ -0,0 +1,18 @@
+CMAKE_CONFIG_DIR
+----------------
+
+.. versionadded:: 3.31
+
+.. include:: ENV_VAR.txt
+
+Specify a CMake user-wide configuration directory for
+:manual:`cmake-file-api(7)` queries.
+
+If this environment variable is not set, the default user-wide
+configuration directory is platform-specific:
+
+- Windows: ``%LOCALAPPDATA%\CMake``
+- macOS: ``$XDG_CONFIG_HOME/CMake`` if set, otherwise
+  ``$HOME/Library/Application Support/CMake``
+- Linux/Other: ``$XDG_CONFIG_HOME/cmake`` if set, otherwise
+  ``$HOME/.config/cmake``

Help/envvar/CMAKE_EXPORT_BUILD_DATABASE.rst

@@ -0,0 +1,17 @@
+CMAKE_EXPORT_BUILD_DATABASE
+---------------------------
+
+.. versionadded:: 3.31
+
+.. include:: ENV_VAR.txt
+
+The default value for :variable:`CMAKE_EXPORT_BUILD_DATABASE` when there is no
+explicit configuration given on the first run while creating a new build tree.
+On later runs in an existing build tree the value persists in the cache as
+:variable:`CMAKE_EXPORT_BUILD_DATABASE`.
+
+.. note ::
+
+   This variable is meaningful only when experimental support for build
+   databases has been enabled by the
+   ``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` gate.

Help/envvar/CMAKE_INSTALL_PARALLEL_LEVEL.rst

@@ -0,0 +1,11 @@
+CMAKE_INSTALL_PARALLEL_LEVEL
+----------------------------
+
+.. versionadded:: 3.31
+
+.. include:: ENV_VAR.txt
+
+Specifies the default maximum number of concurrent processes to use when
+installing using ``cmake --install``.
+
+This has no impact unless :prop_gbl:`INSTALL_PARALLEL` is enabled.

Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst

@@ -4,7 +4,7 @@ CMAKE_MSVCIDE_RUN_PATH
 .. include:: ENV_VAR.txt
 
 Extra PATH locations for custom commands when using
-:generator:`Visual Studio 12 2013` (or above) generators.
+:ref:`Visual Studio Generators`.
 
 The ``CMAKE_MSVCIDE_RUN_PATH`` environment variable sets the default value for
 the :variable:`CMAKE_MSVCIDE_RUN_PATH` variable if not already explicitly set.

Help/generator/Visual Studio 10 2010.rst

@@ -3,6 +3,7 @@ Visual Studio 10 2010
 
 Removed.  This once generated Visual Studio 10 2010 project files, but
 the generator has been removed since CMake 3.25.  It is still possible
-to build with VS 10 2010 tools using the :generator:`Visual Studio 14 2015`
-(or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to
-``v100``, or by using the :generator:`NMake Makefiles` generator.
+to build with the VS 10 2010 toolset by also installing VS 2015 (or above)
+and using the :generator:`Visual Studio 14 2015` (or above) generator with
+:variable:`CMAKE_GENERATOR_TOOLSET` set to ``v100``,
+or by using the :generator:`NMake Makefiles` generator.

Help/generator/Visual Studio 11 2012.rst

@@ -3,6 +3,7 @@ Visual Studio 11 2012
 
 Removed.  This once generated Visual Studio 11 2012 project files, but
 the generator has been removed since CMake 3.28.  It is still possible
-to build with VS 11 2012 tools using the :generator:`Visual Studio 14 2015`
-(or above) generator with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v110``,
+to build with the VS 11 2012 toolset by also installing VS 2015 (or above)
+and using the :generator:`Visual Studio 14 2015` (or above) generator with
+:variable:`CMAKE_GENERATOR_TOOLSET` set to ``v110``,
 or by using the :generator:`NMake Makefiles` generator.

Help/generator/Visual Studio 12 2013.rst

@@ -1,57 +1,9 @@
 Visual Studio 12 2013
 ---------------------
 
-Deprecated.  Generates Visual Studio 12 (VS 2013) project files.
-
-.. note::
-  This generator is deprecated and will be removed in a future version
-  of CMake.  It will still be possible to build with VS 12 2013 tools
-  using the :generator:`Visual Studio 14 2015` (or above) generator
-  with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v120``, or by
-  using the :generator:`NMake Makefiles` generator.
-
-For compatibility with CMake versions prior to 3.0, one may specify this
-generator using the name "Visual Studio 12" without the year component.
-
-Project Types
-^^^^^^^^^^^^^
-
-Only Visual C++ and C# projects may be generated (and Fortran with
-Intel compiler integration).  Other types of projects (JavaScript,
-Powershell, Python, etc.) are not supported.
-
-Platform Selection
-^^^^^^^^^^^^^^^^^^
-
-The default target platform name (architecture) is ``Win32``.
-
-.. versionadded:: 3.1
-  The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
-  via the :option:`cmake -A` option, to specify a target platform
-  name (architecture).  For example:
-
-  * ``cmake -G "Visual Studio 12 2013" -A Win32``
-  * ``cmake -G "Visual Studio 12 2013" -A x64``
-  * ``cmake -G "Visual Studio 12 2013" -A ARM``
-
-For compatibility with CMake versions prior to 3.1, one may specify
-a target platform name optionally at the end of the generator name.
-This is supported only for:
-
-``Visual Studio 12 2013 Win64``
-  Specify target platform ``x64``.
-
-``Visual Studio 12 2013 ARM``
-  Specify target platform ``ARM``.
-
-Toolset Selection
-^^^^^^^^^^^^^^^^^
-
-The ``v120`` toolset that comes with Visual Studio 12 2013 is selected by
-default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
-via the :option:`cmake -T` option, to specify another toolset.
-
-.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
-   By default this generator uses the 32-bit variant even on a 64-bit host.
-
-.. include:: VS_TOOLSET_HOST_ARCH_LEGACY.txt
+Removed.  This once generated Visual Studio 12 2013 project files, but
+the generator has been removed since CMake 3.31.  It is still possible
+to build with the VS 12 2013 toolset by also installing VS 2015 (or above)
+and using the :generator:`Visual Studio 14 2015` (or above) generator with
+:variable:`CMAKE_GENERATOR_TOOLSET` set to ``v120``,
+or by using the :generator:`NMake Makefiles` generator.

Help/generator/Visual Studio 9 2008.rst

@@ -3,7 +3,7 @@ Visual Studio 9 2008
 
 Removed.  This once generated Visual Studio 9 2008 project files, but
 the generator has been removed since CMake 3.30.  It is still possible
-to build with VS 9 2008 tools using the :generator:`Visual Studio 14 2015`
-generator (or above, and with VS 10 2010 also installed) with
-:variable:`CMAKE_GENERATOR_TOOLSET` set to ``v90``, or by using
-the :generator:`NMake Makefiles` generator.
+to build with the VS 9 2008 toolset by also installing VS 10 2010 and
+VS 2015 (or above) and using the :generator:`Visual Studio 14 2015`
+generator (or above) with :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v90``,
+or by using the :generator:`NMake Makefiles` generator.

Help/guide/user-interaction/index.rst

@@ -300,6 +300,8 @@ the table below:
                                             commands used without a type
  :variable:`CMAKE_EXPORT_COMPILE_COMMANDS`  Generate a ``compile_commands.json``
                                             file for use with clang-based tools
+ :variable:`CMAKE_EXPORT_BUILD_DATABASE`    Generate a ``build_database.json``
+                                            file for use with clang-based tools
 ========================================== ============================================================
 
 Other project-specific variables may be available

Help/manual/cmake-commands.7.rst

@@ -22,6 +22,7 @@ These commands are always available.
    /command/cmake_minimum_required
    /command/cmake_parse_arguments
    /command/cmake_path
+   /command/cmake_pkg_config
    /command/cmake_policy
    /command/configure_file
    /command/continue

Help/manual/cmake-developer.7.rst

@@ -408,7 +408,9 @@ starting point.
 .. code-block:: cmake
 
   find_package(PkgConfig)
-  pkg_check_modules(PC_Foo QUIET Foo)
+  if(PKG_CONFIG_FOUND)
+    pkg_check_modules(PC_Foo QUIET Foo)
+  endif()
 
 This should define some variables starting ``PC_Foo_`` that contain the
 information from the ``Foo.pc`` file.

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

@@ -43,15 +43,18 @@ Environment Variables that Control the Build
    /envvar/CMAKE_BUILD_PARALLEL_LEVEL
    /envvar/CMAKE_BUILD_TYPE
    /envvar/CMAKE_COLOR_DIAGNOSTICS
-   /envvar/CMAKE_CONFIGURATION_TYPES
+   /envvar/CMAKE_CONFIG_DIR
    /envvar/CMAKE_CONFIG_TYPE
+   /envvar/CMAKE_CONFIGURATION_TYPES
    /envvar/CMAKE_CROSSCOMPILING_EMULATOR
+   /envvar/CMAKE_EXPORT_BUILD_DATABASE
    /envvar/CMAKE_EXPORT_COMPILE_COMMANDS
    /envvar/CMAKE_GENERATOR
    /envvar/CMAKE_GENERATOR_INSTANCE
    /envvar/CMAKE_GENERATOR_PLATFORM
    /envvar/CMAKE_GENERATOR_TOOLSET
    /envvar/CMAKE_INSTALL_MODE
+   /envvar/CMAKE_INSTALL_PARALLEL_LEVEL
    /envvar/CMAKE_INSTALL_PREFIX
    /envvar/CMAKE_LANG_COMPILER_LAUNCHER
    /envvar/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES_EXCLUDE

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

@@ -50,6 +50,10 @@ It has the following subdirectories:
   Clients may optionally create the ``reply/`` directory at any time
   and monitor it for the appearance of a new reply index file.
 
+.. versionadded:: 3.31
+  Users can add query files to ``api/v1/query`` inside the
+  :envvar:`CMAKE_CONFIG_DIR` to create user-wide queries for all CMake projects.
+
 v1 Shared Stateless Query Files
 -------------------------------
 

Help/manual/cmake-generator-expressions.7.rst

@@ -1877,6 +1877,14 @@ These expressions look up the values of
     rather than the directory of the consuming target for which the
     expression is being evaluated.
 
+  .. versionchanged:: 3.31
+    Generator expressions for transitive interface properties, such as
+    ``$<TARGET_PROPERTY:target,INTERFACE_*>``, now correctly handle
+    repeated evaluations within nested generator expressions.
+    Previously, these repeated evaluations returned empty values due
+    to an optimization for transitive closures.
+    This change ensures consistent evaluation for non-union operations.
+
 .. genex:: $<TARGET_PROPERTY:prop>
   :target: TARGET_PROPERTY:prop
 

Help/manual/cmake-modules.7.rst

@@ -55,7 +55,6 @@ These modules are loaded using the :command:`include` command.
    /module/CMakeBackwardCompatibilityCXX
    /module/CMakeDependentOption
    /module/CMakeFindDependencyMacro
-   /module/CMakeFindFrameworks
    /module/CMakeFindPackageMode
    /module/CMakeGraphVizOptions
    /module/CMakePackageConfigHelpers
@@ -269,6 +268,7 @@ Deprecated Utility Modules
    /module/AddFileDependencies
    /module/CMakeDetermineVSServicePack
    /module/CMakeExpandImportedTargets
+   /module/CMakeFindFrameworks
    /module/CMakeForceCompiler
    /module/CMakeParseArguments
    /module/Dart

Help/manual/cmake-policies.7.rst

@@ -51,6 +51,23 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
 to determine whether to report an error on use of deprecated macros or
 functions.
 
+Policies Introduced by CMake 3.31
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0180: project() always sets <PROJECT-NAME>_* as normal variables. </policy/CMP0180>
+   CMP0179: De-duplication of static libraries on link lines keeps first occurrence. </policy/CMP0179>
+   CMP0178: Test command lines preserve empty arguments. </policy/CMP0178>
+   CMP0177: install() DESTINATION paths are normalized. </policy/CMP0177>
+   CMP0176: execute_process() ENCODING is UTF-8 by default. </policy/CMP0176>
+   CMP0175: add_custom_command() rejects invalid arguments. </policy/CMP0175>
+   CMP0174: cmake_parse_arguments(PARSE_ARGV) defines a variable for an empty string after a single-value keyword. </policy/CMP0174>
+   CMP0173: The CMakeFindFrameworks module is removed. </policy/CMP0173>
+   CMP0172: The CPack module enables per-machine installation by default in the CPack WIX Generator. </policy/CMP0172>
+   CMP0171: 'codegen' is a reserved target name. </policy/CMP0171>
+
 Policies Introduced by CMake 3.30
 =================================
 

Help/manual/cmake-presets.7.rst

@@ -39,6 +39,9 @@ The files are a JSON document with an object as the root:
 .. literalinclude:: presets/example.json
   :language: json
 
+Preset files specifying version ``10`` or above may include comments using the
+key ``$comment`` at any level within the JSON object to provide documentation.
+
 The root object recognizes the following fields:
 
 ``$schema``
@@ -81,6 +84,9 @@ The root object recognizes the following fields:
   ``9``
     .. versionadded:: 3.30
 
+  ``10``
+    .. versionadded:: 3.31
+
 ``cmakeMinimumRequired``
   An optional object representing the minimum version of CMake needed to
   build this project. This object consists of the following fields:
@@ -261,6 +267,16 @@ that may contain the following fields:
   :variable:`CMAKE_TOOLCHAIN_FILE` value. It is allowed in preset files
   specifying version ``3`` or above.
 
+``graphviz``
+  An optional string representing the path to the graphviz input file,
+  that will contain all the library and executable dependencies
+  in the project. See the documentation for :module:`CMakeGraphVizOptions`
+  for more details.
+
+  This field supports `macro expansion`_. If a relative path is specified,
+  it is calculated relative to the current working directory. It is allowed
+  in preset files specifying version ``10`` or above.
+
 ``binaryDir``
   An optional string representing the path to the output binary directory.
   This field supports `macro expansion`_. If a relative path is specified,
@@ -307,10 +323,14 @@ that may contain the following fields:
   (which may not be an empty string), and the value is either ``null`` or
   a string representing the value of the variable. Each variable is set
   regardless of whether or not a value was given to it by the process's
-  environment. This field supports `macro expansion`_, and environment
-  variables in this map may reference each other, and may be listed in any
-  order, as long as such references do not cause a cycle (for example,
-  if ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
+  environment.
+
+  This field supports `macro expansion`_, and environment variables in this map
+  may reference each other, and may be listed in any order, as long as such
+  references do not cause a cycle (for example, if ``ENV_1`` is
+  ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``).  ``$penv{NAME}``
+  allows one to prepend or append values to existing environment variables by
+  accessing only values from the parent environment.
 
   Environment variables are inherited through the ``inherits`` field, and
   the preset's environment will be the union of its own ``environment`` and
@@ -492,10 +512,14 @@ that may contain the following fields:
   (which may not be an empty string), and the value is either ``null`` or
   a string representing the value of the variable. Each variable is set
   regardless of whether or not a value was given to it by the process's
-  environment. This field supports macro expansion, and environment
-  variables in this map may reference each other, and may be listed in any
-  order, as long as such references do not cause a cycle (for example, if
-  ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
+  environment.
+
+  This field supports `macro expansion`_, and environment variables in this map
+  may reference each other, and may be listed in any order, as long as such
+  references do not cause a cycle (for example, if ``ENV_1`` is
+  ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``).  ``$penv{NAME}``
+  allows one to prepend or append values to existing environment variables by
+  accessing only values from the parent environment.
 
   Environment variables are inherited through the ``inherits`` field, and
   the preset's environment will be the union of its own ``environment``
@@ -653,10 +677,14 @@ that may contain the following fields:
   (which may not be an empty string), and the value is either ``null`` or
   a string representing the value of the variable. Each variable is set
   regardless of whether or not a value was given to it by the process's
-  environment. This field supports macro expansion, and environment
-  variables in this map may reference each other, and may be listed in any
-  order, as long as such references do not cause a cycle (for example, if
-  ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
+  environment.
+
+  This field supports `macro expansion`_, and environment variables in this map
+  may reference each other, and may be listed in any order, as long as such
+  references do not cause a cycle (for example, if ``ENV_1`` is
+  ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``).  ``$penv{NAME}``
+  allows one to prepend or append values to existing environment variables by
+  accessing only values from the parent environment.
 
   Environment variables are inherited through the ``inherits`` field, and
   the preset's environment will be the union of its own ``environment``
@@ -994,10 +1022,14 @@ fields:
   (which may not be an empty string), and the value is either ``null`` or
   a string representing the value of the variable. Each variable is set
   regardless of whether or not a value was given to it by the process's
-  environment. This field supports macro expansion, and environment
-  variables in this map may reference each other, and may be listed in any
-  order, as long as such references do not cause a cycle (for example, if
-  ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
+  environment.
+
+  This field supports `macro expansion`_, and environment variables in this map
+  may reference each other, and may be listed in any order, as long as such
+  references do not cause a cycle (for example, if ``ENV_1`` is
+  ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``).  ``$penv{NAME}``
+  allows one to prepend or append values to existing environment variables by
+  accessing only values from the parent environment.
 
   Environment variables are inherited through the ``inherits`` field, and
   the preset's environment will be the union of its own ``environment``
@@ -1264,7 +1296,7 @@ Recognized macros include:
 ``$penv{<variable-name>}``
   Similar to ``$env{<variable-name>}``, except that the value only comes from
   the parent environment, and never from the ``environment`` field. This
-  allows you to prepend or append values to existing environment variables.
+  allows one to prepend or append values to existing environment variables.
   For example, setting ``PATH`` to ``/path/to/ninja/bin:$penv{PATH}`` will
   prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This
   is needed because ``$env{<variable-name>}`` does not allow circular

Help/manual/cmake-properties.7.rst

@@ -109,6 +109,7 @@ Properties on Targets
 
    /prop_tgt/ADDITIONAL_CLEAN_FILES
    /prop_tgt/AIX_EXPORT_ALL_SYMBOLS
+   /prop_tgt/AIX_SHARED_LIBRARY_ARCHIVE
    /prop_tgt/ALIAS_GLOBAL
    /prop_tgt/ALIASED_TARGET
    /prop_tgt/ANDROID_ANT_ADDITIONAL_OPTIONS
@@ -216,6 +217,7 @@ Properties on Targets
    /prop_tgt/EXCLUDE_FROM_ALL
    /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD
    /prop_tgt/EXCLUDE_FROM_DEFAULT_BUILD_CONFIG
+   /prop_tgt/EXPORT_BUILD_DATABASE
    /prop_tgt/EXPORT_COMPILE_COMMANDS
    /prop_tgt/EXPORT_FIND_PACKAGE_NAME
    /prop_tgt/EXPORT_NAME
@@ -334,6 +336,7 @@ Properties on Targets
    /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG
    /prop_tgt/LINK_LIBRARIES
    /prop_tgt/LINK_LIBRARIES_ONLY_TARGETS
+   /prop_tgt/LINK_LIBRARIES_STRATEGY
    /prop_tgt/LINK_LIBRARY_OVERRIDE
    /prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY
    /prop_tgt/LINK_OPTIONS
@@ -430,6 +433,7 @@ Properties on Targets
    /prop_tgt/VS_DOTNET_STARTUP_OBJECT
    /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION
    /prop_tgt/VS_DPI_AWARE
+   /prop_tgt/VS_FRAMEWORK_REFERENCES
    /prop_tgt/VS_GLOBAL_KEYWORD
    /prop_tgt/VS_GLOBAL_PROJECT_TYPES
    /prop_tgt/VS_GLOBAL_ROOTNAMESPACE

Help/manual/cmake-toolchains.7.rst

@@ -591,14 +591,14 @@ a different SDK (e.g. a simulator) can be selected by setting the
 necessary (see :ref:`Switching Between Device and Simulator` below).
 A list of available SDKs can be obtained by running ``xcodebuild -showsdks``.
 
-========  ================= ==================== ================
-OS        CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK
-========  ================= ==================== ================
-iOS       iOS               iphoneos             iphonesimulator
-tvOS      tvOS              appletvos            appletvsimulator
-visionOS  visionOS          xros                 xrsimulator
-watchOS   watchOS           watchos              watchsimulator
-========  ================= ==================== ================
+========  ================= ==================== ================ ============
+OS        CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK    Catalyst SDK
+========  ================= ==================== ================ ============
+iOS       iOS               iphoneos             iphonesimulator  macosx
+tvOS      tvOS              appletvos            appletvsimulator N/A
+visionOS  visionOS          xros                 xrsimulator      N/A
+watchOS   watchOS           watchos              watchsimulator   N/A
+========  ================= ==================== ================ ============
 
 For example, to create a CMake configuration for iOS, the following
 command is sufficient:

Help/manual/cmake-variables.7.rst

@@ -106,6 +106,7 @@ Variables that Provide Information
    /variable/CMAKE_SCRIPT_MODE_FILE
    /variable/CMAKE_SHARED_LIBRARY_PREFIX
    /variable/CMAKE_SHARED_LIBRARY_SUFFIX
+   /variable/CMAKE_SHARED_LIBRARY_ARCHIVE_SUFFIX
    /variable/CMAKE_SHARED_MODULE_PREFIX
    /variable/CMAKE_SHARED_MODULE_SUFFIX
    /variable/CMAKE_SIZEOF_VOID_P
@@ -142,6 +143,7 @@ Variables that Provide Information
    /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION
    /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
    /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM
+   /variable/CMAKE_WINDOWS_KMDF_VERSION
    /variable/CMAKE_XCODE_BUILD_SYSTEM
    /variable/CMAKE_XCODE_PLATFORM_TOOLSET
    /variable/PROJECT-NAME_BINARY_DIR
@@ -194,6 +196,7 @@ Variables that Change Behavior
    /variable/CMAKE_ERROR_DEPRECATED
    /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
    /variable/CMAKE_EXECUTE_PROCESS_COMMAND_ECHO
+   /variable/CMAKE_EXPORT_BUILD_DATABASE
    /variable/CMAKE_EXPORT_COMPILE_COMMANDS
    /variable/CMAKE_EXPORT_PACKAGE_REGISTRY
    /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY
@@ -320,6 +323,7 @@ Variables that Describe the System
    /variable/CMAKE_COMPILER_2005
    /variable/CMAKE_HOST_APPLE
    /variable/CMAKE_HOST_BSD
+   /variable/CMAKE_HOST_EXECUTABLE_SUFFIX
    /variable/CMAKE_HOST_LINUX
    /variable/CMAKE_HOST_SOLARIS
    /variable/CMAKE_HOST_SYSTEM
@@ -346,6 +350,7 @@ Variables that Describe the System
    /variable/MSVC_VERSION
    /variable/MSYS
    /variable/UNIX
+   /variable/WASI
    /variable/WIN32
    /variable/WINCE
    /variable/WINDOWS_PHONE
@@ -360,6 +365,7 @@ Variables that Control the Build
    :maxdepth: 1
 
    /variable/CMAKE_ADSP_ROOT
+   /variable/CMAKE_AIX_SHARED_LIBRARY_ARCHIVE
    /variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS
    /variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS
    /variable/CMAKE_ANDROID_API
@@ -486,6 +492,7 @@ Variables that Control the Build
    /variable/CMAKE_LINK_GROUP_USING_FEATURE
    /variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED
    /variable/CMAKE_LINK_INTERFACE_LIBRARIES
+   /variable/CMAKE_LINK_LIBRARIES_STRATEGY
    /variable/CMAKE_LINK_LIBRARY_FEATURE_ATTRIBUTES
    /variable/CMAKE_LINK_LIBRARY_FILE_FLAG
    /variable/CMAKE_LINK_LIBRARY_FLAG
@@ -614,6 +621,7 @@ Variables for Languages
    /variable/CMAKE_LANG_COMPILER_TARGET
    /variable/CMAKE_LANG_COMPILER_VERSION
    /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY
+   /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY_ARCHIVE
    /variable/CMAKE_LANG_CREATE_SHARED_MODULE
    /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY
    /variable/CMAKE_LANG_EXTENSIONS
@@ -631,6 +639,8 @@ Variables for Languages
    /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO
    /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT
    /variable/CMAKE_LANG_HOST_COMPILER
+   /variable/CMAKE_LANG_HOST_COMPILER_ID
+   /variable/CMAKE_LANG_HOST_COMPILER_VERSION
    /variable/CMAKE_LANG_IGNORE_EXTENSIONS
    /variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES
    /variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES
@@ -650,6 +660,7 @@ Variables for Languages
    /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES
    /variable/CMAKE_LANG_STANDARD_LATEST
    /variable/CMAKE_LANG_STANDARD_LIBRARIES
+   /variable/CMAKE_LANG_STANDARD_LINK_DIRECTORIES
    /variable/CMAKE_LANG_STANDARD_REQUIRED
    /variable/CMAKE_OBJC_EXTENSIONS
    /variable/CMAKE_OBJC_STANDARD

Help/manual/cmake.1.rst

@@ -31,7 +31,7 @@ Synopsis
   cmake --find-package [<options>]
 
  `Run a Workflow Preset`_
-  cmake --workflow [<options>]
+  cmake --workflow <options>
 
  `View Help`_
   cmake --help[-<topic>]
@@ -232,6 +232,17 @@ Options
  will display also advanced variables.  If ``H`` is specified, it will also
  display help for each variable.
 
+.. option:: -LR[A][H] <regex>
+
+ .. versionadded:: 3.31
+
+ Show specific non-advanced cached variables
+
+ Show non-``INTERNAL`` nor :prop_cache:`ADVANCED` variables from the CMake
+ ``CACHE`` that match the given regex. If ``A`` is specified, then it
+ will also show advanced variables.  If ``H`` is specified, it will also
+ display help for each variable.
+
 .. option:: -N
 
  View mode only.
@@ -255,8 +266,18 @@ Options
  from the top of a binary tree for a CMake project it will dump
  additional information such as the cache, log files etc.
 
+.. option:: --print-config-dir
+
+ .. versionadded:: 3.31
+
+ Print CMake config directory for user-wide FileAPI queries.
+
+ See :envvar:`CMAKE_CONFIG_DIR` for more details.
+
 .. option:: --log-level=<level>
 
+ .. versionadded:: 3.16
+
  Set the log ``<level>``.
 
  The :command:`message` command will only output messages of the specified
@@ -745,6 +766,15 @@ The options are:
 
   This option can be omitted if :envvar:`VERBOSE` environment variable is set.
 
+.. option:: -j <jobs>, --parallel <jobs>
+
+  .. versionadded:: 3.31
+
+  Install in parallel using the given number of jobs. Only available if
+  :prop_gbl:`INSTALL_PARALLEL` is enabled. The
+  :envvar:`CMAKE_INSTALL_PARALLEL_LEVEL` environment variable specifies a
+  default parallel level when this option is not provided.
+
 Run :option:`cmake --install` with no options for quick help.
 
 Open a Project
@@ -1364,7 +1394,7 @@ build steps in order:
 
 .. code-block:: shell
 
-  cmake --workflow [<options>]
+  cmake --workflow <options>
 
 The options are:
 
@@ -1381,6 +1411,15 @@ The options are:
   must contain CMake preset files.
   See :manual:`preset <cmake-presets(7)>` for more details.
 
+  .. versionchanged:: 3.31
+    When following immediately after the ``--workflow`` option,
+    the ``--preset`` argument can be omitted and just the ``<preset>``
+    name can be given.  This means the following syntax is valid:
+
+    .. code-block:: console
+
+      $ cmake --workflow my-preset
+
 .. option:: --list-presets
 
   Lists the available workflow presets. The current working directory must

Help/manual/ctest.1.rst

@@ -1560,6 +1560,10 @@ Configuration settings include:
   * `CTest Script`_ variable: :variable:`CTEST_TLS_VERSION`
   * :module:`CTest` module variable: ``CTEST_TLS_VERSION``
 
+  .. versionchanged:: 3.31
+    The default is TLS 1.2.
+    Previously, no minimum version was enforced by default.
+
 ``TLSVerify``
   .. versionadded:: 3.30
 
@@ -1569,6 +1573,11 @@ Configuration settings include:
   * `CTest Script`_ variable: :variable:`CTEST_TLS_VERIFY`
   * :module:`CTest` module variable: ``CTEST_TLS_VERIFY``
 
+  .. versionchanged:: 3.31
+    The default is on.  Previously, the default was off.
+    Users may set the :envvar:`CMAKE_TLS_VERIFY` environment
+    variable to ``0`` to restore the old default.
+
 ``TriggerSite``
   Legacy option.  Not used.
 

Help/manual/presets/example.json

@@ -1,16 +1,22 @@
 {
-  "version": 6,
+  "version": 10,
   "cmakeMinimumRequired": {
     "major": 3,
     "minor": 23,
     "patch": 0
   },
+  "$comment": "An example CMakePresets.json file",
   "include": [
     "otherThings.json",
     "moreThings.json"
   ],
   "configurePresets": [
     {
+      "$comment": [
+        "This is a comment row.",
+        "This is another comment,",
+        "just because we can do it"
+      ],
       "name": "default",
       "displayName": "Default Config",
       "description": "Default build using Ninja generator",

Help/module/CMAKE_REQUIRED_LINK_DIRECTORIES.txt

@@ -0,0 +1,5 @@
+  ``CMAKE_REQUIRED_LINK_DIRECTORIES``
+    .. versionadded:: 3.31
+
+    A :ref:`;-list <CMake Language Lists>` of libraries search paths to pass to
+    the linker (see :command:`try_compile` for further details).

Help/policy/CMP0132.rst

@@ -3,6 +3,8 @@ CMP0132
 
 .. versionadded:: 3.24
 
+Do not set compiler environment variables on first run.
+
 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.

Help/policy/CMP0156.rst

@@ -34,6 +34,11 @@ are de-duplicated by keeping their first occurrence, thus respecting the
 project-specified order.  This policy provides compatibility with projects
 that have not been updated to expect the latter behavior.
 
+.. note::
+
+  When this policy is set to ``NEW``, the policy :policy:`CMP0179` controls
+  which occurrence of the static libraries is kept when they are de-duplicated.
+
 The ``OLD`` behavior for this policy is to always repeat static libraries
 as if using a traditional linker, and always de-duplicate shared libraries
 by keeping the last occurrence of each.  The ``NEW`` behavior for this policy

Help/policy/CMP0171.rst

@@ -0,0 +1,26 @@
+CMP0171
+-------
+
+.. versionadded:: 3.31
+
+``codegen`` is a reserved target name.
+
+CMake 3.30 and earlier did not reserve ``codegen`` as a builtin target name,
+leaving projects free to create their own target with that name.
+CMake 3.31 and later prefer to reserve ``codegen`` as a builtin target name
+to drive custom commands created with the ``CODEGEN`` option to
+:command:`add_custom_command`.  In order to support building the ``codegen``
+target in scripted environments, e.g., ``cmake --build . --target codegen``,
+the ``codegen`` target needs to be generated even if no custom commands
+use the ``CODEGEN`` option.  This policy provides compatibility for projects
+that have not been updated to avoid creating a target named ``codegen``.
+
+The ``OLD`` behavior of this policy allows projects to create a target
+with the name ``codegen``.  The ``NEW`` behavior halts with a fatal error
+if a target with the name ``codegen`` is created.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
+.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0172.rst

@@ -0,0 +1,39 @@
+CMP0172
+-------
+
+.. versionadded:: 3.31
+
+The :module:`CPack` module enables per-machine installation by default
+in the :cpack_gen:`CPack WIX Generator`.
+
+The :cpack_gen:`CPack WIX Generator`'s :variable:`CPACK_WIX_INSTALL_SCOPE`
+option controls the scope of the generated Windows Installer package.
+When :variable:`CPACK_WIX_VERSION` is set to 4 or higher, the default scope
+is ``perMachine``.  However, when using WIX 3 the default scope is ``NONE``,
+and CPack does not set any ``InstallScope`` in the package specification.
+The resulting installer requires administrative privileges and installs
+into the system-wide ``ProgramFiles`` directory, but the start menu entry
+and uninstaller registration are created only for the current user.
+
+The :module:`CPack` module in CMake 3.30 and older does not specify any
+:variable:`CPACK_WIX_INSTALL_SCOPE` value by default, so CPack uses no
+installation scope by default with WIX 3.  CMake 3.31 and newer instead
+prefer to set :variable:`CPACK_WIX_INSTALL_SCOPE` to ``perMachine`` by
+default to make the behavior consistent across all WIX versions.  This
+policy provides compatibility for projects that have not been updated
+to expect ``perMachine`` behavior.
+
+The ``OLD`` behavior for this policy is to not set
+:variable:`CPACK_WIX_INSTALL_SCOPE` by default.  The ``NEW`` behavior for
+this policy is to set :variable:`CPACK_WIX_INSTALL_SCOPE` to ``perMachine``
+by default.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
+.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn by default
+.. include:: STANDARD_ADVICE.txt
+
+See documentation of the
+:variable:`CMAKE_POLICY_WARNING_CMP0172 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
+variable to control the warning.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0173.rst

@@ -0,0 +1,22 @@
+CMP0173
+-------
+
+.. versionadded:: 3.31
+
+The :module:`CMakeFindFrameworks` module is removed.
+
+CMake's framework handling has evolved well beyond what the
+``CMakeFindFrameworks`` module supports. The module lacks any handling of
+XCFrameworks, it never documented the one command it provides, and
+:command:`find_library` provides superior capabilities in all respects.
+
+The ``OLD`` behavior of this policy is for :module:`CMakeFindFrameworks` to
+continue to provide the undocumented ``cmake_find_frameworks()`` command.
+The ``NEW`` behavior halts with a fatal error if anything tries to include
+the module.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
+.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0174.rst

@@ -0,0 +1,37 @@
+CMP0174
+-------
+
+.. versionadded:: 3.31
+
+:command:`cmake_parse_arguments(PARSE_ARGV)` defines a variable for an empty
+string after a single-value keyword.
+
+One of the main reasons for using the ``PARSE_ARGV`` form of the
+:command:`cmake_parse_arguments` command is to more robustly handle corner
+cases related to empty values.  The non-``PARSE_ARGV`` form doesn't preserve
+empty arguments, but the ``PARSE_ARGV`` form does.  For each single-value
+keyword given, a variable should be defined if the keyword is present, even
+if it is followed by an empty string.
+
+Prior to CMake 3.31, no variable would be defined if the value given after a
+single-value keyword was an empty string.  This meant the code could not detect
+the difference between the keyword not being given, and it being given but with
+an empty value, except by iterating over all the arguments and checking if the
+keyword is present.
+
+For the ``OLD`` behavior of this policy,
+:command:`cmake_parse_arguments(PARSE_ARGV)` does not define a variable for a
+single-value keyword followed by an empty string, or followed by no value at
+all.
+
+For the ``NEW`` behavior, :command:`cmake_parse_arguments(PARSE_ARGV)` always
+defines a variable for each keyword given in the arguments, even a single-value
+keyword with an empty string as its value or no value at all.  With the
+``NEW`` behavior, the code can robustly check if a single-value keyword was
+given using just ``if(DEFINED <prefix>_<keyword>)``.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
+.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0175.rst

@@ -0,0 +1,40 @@
+CMP0175
+-------
+
+.. versionadded:: 3.31
+
+:command:`add_custom_command` rejects invalid arguments.
+
+CMake 3.30 and earlier silently ignored unsupported keywords and missing or
+invalid arguments for the different forms of the :command:`add_custom_command`
+command. CMake 3.31 implements more rigorous argument checking and will flag
+invalid or missing arguments as errors.
+
+The ``OLD`` behavior of this policy will accept the same invalid keywords or
+arguments as CMake 3.30 and earlier. The ``NEW`` behavior will flag the
+following as errors that previously went unreported:
+
+* The ``OUTPUT`` form does not accept ``PRE_BUILD``, ``PRE_LINK``, or
+  ``POST_BUILD`` keywords.
+* When the ``APPEND`` keyword is given, the ``OUTPUT`` form also does not
+  accept ``BYPRODUCTS``, ``COMMAND_EXPAND_LISTS``, ``DEPENDS_EXPLICIT_ONLY``,
+  ``DEPFILE``, ``JOB_POOL``, ``JOB_SERVER_AWARE``, ``USES_TERMINAL``, or
+  ``VERBATIM`` keywords.
+* The ``TARGET`` form requires exactly one of ``PRE_BUILD``, ``PRE_LINK``, or
+  ``POST_BUILD`` to be given.  Previously, if none were given, ``POST_BUILD``
+  was assumed, or if multiple keywords were given, the last one was used.
+* The ``TARGET`` form does not accept ``DEPENDS``, ``DEPENDS_EXPLICIT_ONLY``,
+  ``DEPFILE``, ``IMPLICIT_DEPENDS``, ``MAIN_DEPENDENCY``, ``JOB_POOL``, or
+  ``JOB_SERVER_AWARE`` keywords.
+* The ``TARGET`` form now requires at least one ``COMMAND`` to be given.
+* If a keyword expects a value to be given after it, but no value is provided,
+  that was previously treated as though the keyword was not given at all.
+* The ``COMMENT`` keyword expects exactly one value after it.  If multiple
+  values are given, or if the ``COMMENT`` keyword is given more than once,
+  this is an error.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
+.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0176.rst

@@ -0,0 +1,27 @@
+CMP0176
+-------
+
+.. versionadded:: 3.31
+
+:command:`execute_process` ``ENCODING`` is ``UTF-8`` by default.
+
+The ``ENCODING`` option is meaningful only on Windows.  It specifies the
+character encoding expected in the process's output on stdout and stderr.
+In CMake 3.14 and below the default encoding was ``NONE``, which corresponds
+to CMake's internal UTF-8 encoding.  In CMake 3.15 through CMake 3.30 the
+default encoding was accidentally changed to ``AUTO``, but the change went
+unnoticed and was not documented.
+
+CMake 3.31 and above prefer the ``ENCODING`` default to be ``UTF-8``.
+This policy provides compatibility with projects that may have been
+relying on the default being ``AUTO``.
+
+The ``OLD`` behavior of this policy is for :command:`execute_process`
+to use ``AUTO`` by default if no ``ENCODING`` is specified.  The ``NEW``
+behavior for this policy is to use ``UTF-8`` as the default ``ENCODING``.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
+.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0177.rst

@@ -0,0 +1,38 @@
+CMP0177
+-------
+
+.. versionadded:: 3.31
+
+:command:`install` ``DESTINATION`` paths are normalized.
+
+The :command:`install` command has a number of different forms, and most of
+them take a ``DESTINATION`` keyword, some in more than one place.
+CMake 3.30 and earlier used the value given after the ``DESTINATION`` keyword
+as provided with no transformations.  The :command:`install(EXPORT)` form
+assumes the path contains no ``..`` or ``.`` path components when computing
+a path relative to the ``DESTINATION``, and if the project provided a path
+that violated that assumption, the computed path would be incorrect.
+
+CMake 3.31 normalizes all ``DESTINATION`` values given in any form of the
+:command:`install` command, except for the ``INCLUDES DESTINATION`` of the
+:command:`install(TARGETS)` form.  The normalization performed is the same
+as for the :command:`cmake_path` command (see :ref:`Normalization`).
+
+The ``OLD`` behavior of this policy performs no translation on the
+``DESTINATION`` values of any :command:`install` command.  They are used
+exactly as provided.  If a destination path contains ``..`` or ``.`` path
+components, :command:`install(EXPORT)` will use the same wrong paths as
+CMake 3.30 and earlier.
+
+The ``NEW`` behavior will normalize all ``DESTINATION`` values except for
+``INCLUDES DESTINATION``.  If a destination path contains a generator
+expression, it will be wrapped in a ``$<PATH:CMAKE_PATH,NORMALIZE,...>``
+generator expression.
+
+This policy was introduced in CMake version 3.31.
+It may be set by :command:`cmake_policy` or :command:`cmake_minimum_required`.
+If it is not set, CMake will warn if it detects a path that would be different
+if normalized, and uses ``OLD`` behavior.  If a destination path contains a
+generator expression, no such warning will be issued regardless of the value.
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0178.rst

@@ -0,0 +1,37 @@
+CMP0178
+-------
+
+.. versionadded:: 3.31
+
+Test command lines preserve empty arguments.
+
+Empty values in the :prop_tgt:`TEST_LAUNCHER` and
+:prop_tgt:`CROSSCOMPILING_EMULATOR` target properties are now preserved
+for tests added by the following:
+
+* The :command:`add_test` command.
+* The :command:`ExternalData_Add_Test` command from the :module:`ExternalData`
+  module.
+* The :command:`gtest_add_tests` or :command:`gtest_discover_tests` commands
+  from the :module:`GoogleTest` module.
+
+For the :command:`gtest_add_tests` and :command:`gtest_discover_tests`
+commands, empty elements in the values passed after the ``EXTRA_ARGS``
+keyword are also now preserved.
+
+The ``OLD`` behavior of this policy silently discards empty list items
+from the :prop_tgt:`TEST_LAUNCHER` and :prop_tgt:`CROSSCOMPILING_EMULATOR`
+target properties in the above-mentioned cases.  It also silently discards
+empty items from the values given after ``EXTRA_ARGS`` for the
+:command:`gtest_add_tests` and :command:`gtest_discover_tests` commands.
+
+The ``NEW`` behavior of this policy preserves empty list items in the
+:prop_tgt:`TEST_LAUNCHER` and :prop_tgt:`CROSSCOMPILING_EMULATOR` target
+properties, and in values given after ``EXTRA_ARGS`` for
+:command:`gtest_add_tests` and :command:`gtest_discover_tests`.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
+.. |WARNS_OR_DOES_NOT_WARN| replace:: warns
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0179.rst

@@ -0,0 +1,28 @@
+CMP0179
+-------
+
+.. versionadded:: 3.31
+
+De-duplication of static libraries on link lines keeps first occurrence.
+This policy is only relevant when policy :policy:`CMP0156` is set to ``NEW``.
+
+Based on the linker capabilities, the static libraries can
+be de-duplicated. See policy :policy:`CMP0156` for more information.
+
+CMake 3.30 and below may choose to keep, on some platforms, the last occurrence
+of the static libraries rather than the fist occurrence when they are
+de-duplicated.
+
+CMake 3.31 and above prefer to keep, on all platforms, the first occurrence of
+the static libraries when they are de-duplicated.
+
+The ``OLD`` behavior for this policy is to keep, on some platforms, the last
+occurrence of the static libraries when they are de-duplicated.  The ``NEW``
+behavior for this policy is to keep the first occurrence of the static
+libraries when they are de-duplicated, regardless of the platform.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
+.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt

Help/policy/CMP0180.rst

@@ -0,0 +1,36 @@
+CMP0180
+-------
+
+.. versionadded:: 3.31
+
+:command:`project` always sets ``<PROJECT-NAME>_*`` as normal variables.
+
+In CMake 3.29 and below, the :command:`project` command set
+:variable:`<PROJECT-NAME>_SOURCE_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR`,
+and :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` as cache entries, but not as
+normal variables.  CMake 3.30 started setting them as normal variables,
+but only if they are already set as normal variables.  This was needed to
+preserve support for some :module:`FetchContent` use cases under policy
+:policy:`CMP0169`'s NEW behavior, while also preserving behavior of nested
+directories that call :command:`project` with the same project name.
+See release notes for 3.30.3, 3.30.4, and 3.30.5 for details.
+
+CMake 3.31 and later prefer to always set ``<PROJECT-NAME>_SOURCE_DIR``,
+``<PROJECT-NAME>_BINARY_DIR``, and ``<PROJECT-NAME>_IS_TOP_LEVEL``, as both
+cache entries and normal variables, regardless of what cache or normal
+variables already exist.  This policy provides compatibility for projects
+that have not been updated to expect this behavior.
+
+The ``OLD`` behavior for this policy will only set normal variables for
+``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``, and
+``<PROJECT-NAME>_IS_TOP_LEVEL`` if there is already a normal variable by that
+name when :command:`project` is called.
+The ``NEW`` behavior for this policy will always set normal variables for
+``<PROJECT-NAME>_SOURCE_DIR``, ``<PROJECT-NAME>_BINARY_DIR``, and
+``<PROJECT-NAME>_IS_TOP_LEVEL`` when :command:`project` is called.
+
+.. |INTRODUCED_IN_CMAKE_VERSION| replace:: 3.31
+.. |WARNS_OR_DOES_NOT_WARN| replace:: does *not* warn
+.. include:: STANDARD_ADVICE.txt
+
+.. include:: DEPRECATED.txt

Help/prop_dir/VS_GLOBAL_SECTION_POST_section.rst

@@ -17,7 +17,7 @@ pairs.  Each such pair will be transformed into an entry in the
 solution global section.  Whitespace around key and value is ignored.
 List elements which do not contain an equal sign are skipped.
 
-This property only works for Visual Studio 12 and above; it is ignored
+This property only works for :ref:`Visual Studio Generators`; it is ignored
 on other generators.  The property only applies when set on a
 directory whose ``CMakeLists.txt`` contains a :command:`project` command.
 

Help/prop_dir/VS_GLOBAL_SECTION_PRE_section.rst

@@ -17,6 +17,6 @@ pairs.  Each such pair will be transformed into an entry in the
 solution global section.  Whitespace around key and value is ignored.
 List elements which do not contain an equal sign are skipped.
 
-This property only works for Visual Studio 12 and above; it is ignored
+This property only works for :ref:`Visual Studio Generators`; it is ignored
 on other generators.  The property only applies when set on a
 directory whose ``CMakeLists.txt`` contains a :command:`project` command.

Help/prop_gbl/INSTALL_PARALLEL.rst

@@ -3,18 +3,22 @@ INSTALL_PARALLEL
 
 .. versionadded:: 3.30
 
-Enables parallel installation option for the Ninja generator.
+Enables parallel installation option for a project. The install code for each
+subdirectory added with ``add_subdirectory`` can run independently.
 
-When this property is ``ON``, ``install/local`` targets have the
-console pool disabled, allowing them to run concurrently.
+When using the Ninja generator, setting this property to ``ON``, causes
+``install/local`` targets have the console pool disabled, allowing them to run
+concurrently.
 
 This property also provides the target ``install/parallel``, which has an
-explicit dependency on the ``install/local`` target for each subdirectory,
-recursing down the project.
+explicit dependency on the ``install/local`` target for each subdirectory.
 
-Setting this property has no affect on the behavior of ``cmake --install``.
-The install must be invoked by building the ``install/parallel`` target
-directly.
+  .. versionadded:: 3.31
+
+  When this property is ``ON``, ``cmake --install`` can be given the ``-j <jobs>``
+  or ``--parallel <jobs>`` option to specify a maximum number of jobs.
+  The :envvar:`CMAKE_INSTALL_PARALLEL_LEVEL` environment variable specifies a
+  default parallel level if this option is not provided.
 
 Calls to :command:`install(CODE)` or :command:`install(SCRIPT)` might depend
 on actions performed by an earlier :command:`install` command in a different

Help/prop_tgt/AIX_SHARED_LIBRARY_ARCHIVE.rst

@@ -0,0 +1,20 @@
+AIX_SHARED_LIBRARY_ARCHIVE
+--------------------------
+
+.. versionadded:: 3.31
+
+On AIX, enable creation of a shared library archive.  This places
+the shared object ``.so`` file inside an archive ``.a`` file.
+
+By default, CMake creates shared libraries on AIX as plain
+shared object ``.so`` files for consistency with other UNIX platforms.
+Alternatively, set this property to a true value to create a shared
+library archive instead, as is AIX convention.
+
+The shared object name in the archive encodes version information from
+the :prop_tgt:`SOVERSION` target property, if set, and otherwise from
+the :prop_tgt:`VERSION` target property, if set.
+
+This property defaults to :variable:`CMAKE_AIX_SHARED_LIBRARY_ARCHIVE`
+if that variable is set when a ``SHARED`` library target is created
+by :command:`add_library`.

Help/prop_tgt/COMPILE_FLAGS.rst

@@ -7,5 +7,8 @@ The ``COMPILE_FLAGS`` property sets additional compiler flags used to
 build sources within the target.  Use :prop_tgt:`COMPILE_DEFINITIONS`
 to pass additional preprocessor definitions.
 
-This property is deprecated.  Use the :prop_tgt:`COMPILE_OPTIONS`
-property or the :command:`target_compile_options` command instead.
+.. note::
+
+  This property has been superseded by the :prop_tgt:`COMPILE_OPTIONS` property.
+  Alternatively, you can also use the :command:`target_compile_options` command
+  instead.

Help/prop_tgt/EXPORT_BUILD_DATABASE.rst

@@ -0,0 +1,15 @@
+EXPORT_BUILD_DATABASE
+---------------------
+
+.. versionadded:: 3.31
+
+Enable/Disable output of a build database for a target.
+
+This property is initialized by the value of the variable
+:variable:`CMAKE_EXPORT_BUILD_DATABASE` if it is set when a target is created.
+
+.. note ::
+
+   This property is meaningful only when experimental support for build
+   databases has been enabled by the
+   ``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` gate.

Help/prop_tgt/LINK_LIBRARIES.rst

@@ -28,3 +28,8 @@ 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.
+
+See the :variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable and
+corresponding :prop_tgt:`LINK_LIBRARIES_STRATEGY` target property
+for details on how CMake orders direct link dependencies on linker
+command lines.

Help/prop_tgt/LINK_LIBRARIES_STRATEGY.rst

@@ -0,0 +1,87 @@
+LINK_LIBRARIES_STRATEGY
+-----------------------
+
+.. versionadded:: 3.31
+
+Specify a strategy for ordering a target's direct link dependencies
+on linker command lines.  This property is initialized by the value of the
+:variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable if it is set when a
+target is created.
+
+CMake generates a target's link line using its :ref:`Target Link Properties`.
+In particular, the :prop_tgt:`LINK_LIBRARIES` target property records the
+target's direct link dependencies, typically populated by calls to
+:command:`target_link_libraries`.  Indirect link dependencies are
+propagated from those entries of :prop_tgt:`LINK_LIBRARIES` that name
+library targets by following the transitive closure of their
+:prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.  CMake supports multiple
+strategies for nominally ordering direct and indirect link dependencies,
+which are then filtered for `Toolchain-Specific Behavior`_.
+
+Consider this example for the strategies below:
+
+.. code-block:: cmake
+
+  add_library(A STATIC ...)
+  add_library(B STATIC ...)
+  add_library(C STATIC ...)
+  add_executable(main ...)
+  target_link_libraries(B PRIVATE A)
+  target_link_libraries(C PRIVATE A)
+  target_link_libraries(main PRIVATE A B C)
+
+The supported strategies are:
+
+``REORDER_MINIMALLY``
+  Entries of :prop_tgt:`LINK_LIBRARIES` always appear first and in their
+  original order.  Indirect link dependencies not satisfied by the
+  original entries may be reordered and de-duplicated with respect to
+  one another, but are always appended after the original entries.
+  This may result in less efficient link lines, but gives projects
+  control of ordering among independent entries.  Such control may be
+  important when intermixing link flags with libraries, or when multiple
+  libraries provide a given symbol.
+
+  This is the default.
+
+  In the above example, this strategy computes a link line for ``main``
+  by starting with its original entries ``A B C``, and then appends
+  another ``A`` to satisfy the dependencies of ``B`` and ``C`` on ``A``.
+  The nominal order produced by this strategy is ``A B C A``.
+
+  Note that additional filtering for `Toolchain-Specific Behavior`_
+  may de-duplicate ``A`` on the actual linker invocation in the
+  generated build system, resulting in either ``A B C`` or ``B C A``.
+
+``REORDER_FREELY``
+  Entries of :prop_tgt:`LINK_LIBRARIES` may be reordered, de-duplicated,
+  and intermixed with indirect link dependencies.  This may result in
+  more efficient link lines, but does not give projects any control of
+  ordering among independent entries.
+
+  In the above example, this strategy computes a link line for ``main``
+  by re-ordering its original entries ``A B C`` to satisfy the
+  dependencies of ``B`` and ``C`` on ``A``.
+  The nominal order produced by this strategy is ``B C A``.
+
+Toolchain-Specific Behavior
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After one of the above strategies produces a nominal order among
+direct and indirect link dependencies, the actual linker invocation
+in the generated build system may de-duplicate entries based on
+platform-specific requirements and linker capabilities.
+See policy :policy:`CMP0156`.
+
+For example, if the ``REORDER_MINIMALLY`` strategy produces ``A B C A``,
+the actual link line may de-duplicate ``A`` as follows:
+
+* If ``A`` is a static library and the linker re-scans automatically,
+  the first occurrence is kept, resulting in ``A B C``.
+  See policy :policy:`CMP0179`
+
+* If ``A`` is a shared library on Windows, the first
+  occurrence is kept, resulting in ``A B C``.
+
+* If ``A`` is a shared library on macOS or UNIX platforms, the last
+  occurrence is kept, resulting in ``B C A``.

Help/prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST.rst

@@ -12,12 +12,20 @@ file name which may be a full path.
 The following target properties may be set to specify content to be
 configured into the file:
 
+``MACOSX_FRAMEWORK_BUNDLE_NAME``
+  .. versionadded:: 3.31
+
+  Sets ``CFBundleName``.
+
 ``MACOSX_FRAMEWORK_BUNDLE_VERSION``
   Sets ``CFBundleVersion``.
+
 ``MACOSX_FRAMEWORK_ICON_FILE``
   Sets ``CFBundleIconFile``.
+
 ``MACOSX_FRAMEWORK_IDENTIFIER``
   Sets ``CFBundleIdentifier``.
+
 ``MACOSX_FRAMEWORK_SHORT_VERSION_STRING``
   Sets ``CFBundleShortVersionString``.
 

Help/prop_tgt/UNITY_BUILD.rst

@@ -38,6 +38,9 @@ Unity builds are supported for the following languages:
 ``CXX``
   .. versionadded:: 3.16
 
+``CUDA``
+  .. versionadded:: 3.31
+
 ``OBJC``
   .. versionadded:: 3.29
 

Help/prop_tgt/VS_DEBUGGER_COMMAND.rst

@@ -11,5 +11,5 @@ project file.  This property is initialized by the value of the variable
 :variable:`CMAKE_VS_DEBUGGER_COMMAND` if it is set when a target is
 created.
 
-This property only works for Visual Studio 12 2013 and above;
+This property only works for :ref:`Visual Studio Generators`;
 it is ignored on other generators.

Help/prop_tgt/VS_DEBUGGER_COMMAND_ARGUMENTS.rst

@@ -11,5 +11,5 @@ project file.  This property is initialized by the value of the variable
 :variable:`CMAKE_VS_DEBUGGER_COMMAND_ARGUMENTS` if it is set when a target is
 created.
 
-This property only works for Visual Studio 12 2013 and above;
+This property only works for :ref:`Visual Studio Generators`;
 it is ignored on other generators.

Help/prop_tgt/VS_DEBUGGER_ENVIRONMENT.rst

@@ -11,5 +11,5 @@ project file.  This property is initialized by the value of the variable
 :variable:`CMAKE_VS_DEBUGGER_ENVIRONMENT` if it is set when a target is
 created.
 
-This property only works for Visual Studio 12 2013 and above;
+This property only works for :ref:`Visual Studio Generators`;
 it is ignored on other generators.

Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst

@@ -11,5 +11,5 @@ project file.  This property is initialized by the value of the variable
 :variable:`CMAKE_VS_DEBUGGER_WORKING_DIRECTORY` if it is set when a target is
 created.
 
-This property only works for Visual Studio 12 2013 and above;
+This property only works for :ref:`Visual Studio Generators`;
 it is ignored on other generators.

Help/prop_tgt/VS_DOTNET_STARTUP_OBJECT.rst

@@ -12,7 +12,7 @@ If the property is unset, Visual Studio uses the first matching
 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 12 2013 and above;
+This property only works for :ref:`Visual Studio Generators`;
 it is ignored on other generators.
 
 .. code-block:: cmake

Help/prop_tgt/VS_FRAMEWORK_REFERENCES.rst

@@ -0,0 +1,12 @@
+VS_FRAMEWORK_REFERENCES
+-----------------------
+
+.. versionadded:: 3.31
+
+Visual Studio framework references.
+Specify a :ref:`semicolon-separated list <CMake Language Lists>` of framework references
+to be added to a generated Visual Studio project. For example:
+
+* "Microsoft.WindowsDesktop.App.WPF" for WPF applications
+* "Microsoft.WindowsDesktop.App.WindowsForms" for WinForms applications
+* "Microsoft.WindowsDesktop.App" for applications using both frameworks

Help/prop_tgt/VS_KEYWORD.rst

@@ -6,4 +6,4 @@ for the :generator:`Visual Studio 9 2008` generator, and older,
 but all of those generators have been removed.
 
 Use the :prop_tgt:`VS_GLOBAL_KEYWORD` target property to set the
-keyword for Visual Studio 12 (2013) and newer.
+keyword for remaining :ref:`Visual Studio Generators`.

Help/release/3.29.rst

@@ -64,6 +64,10 @@ Commands
 * The :command:`if` command gained new tests ``IS_READABLE``, ``IS_WRITABLE``
   and ``IS_EXECUTABLE`` to check file or directory permissions.
 
+* The :command:`try_compile` and :command:`try_run` commands gained a
+  ``LINKER_LANGUAGE`` option to specify the :prop_tgt:`LINKER_LANGUAGE`
+  target property in the generated test project.
+
 Variables
 ---------
 
@@ -231,8 +235,8 @@ Changes made since CMake 3.29.0 include the following.
   to ``perMachine`` on their own schedule by setting
   ``CPACK_WIX_INSTALL_SCOPE``.
 
-3.29.6, 3.29.7, 3.29.8
-----------------------
+3.29.6, 3.29.7, 3.29.8, 3.29.9
+------------------------------
 
 * These versions made no changes to documented features or interfaces.
   Some implementation updates were made to support ecosystem changes

Help/release/3.30.rst

@@ -298,3 +298,10 @@ Changes made since CMake 3.30.0 include the following.
   This refines 3.30.3's behavior change to restore behavior of nested
   directories that call :command:`project` with the same project name,
   and it addresses the bug in the implementation introduced in 3.30.4.
+
+3.30.6
+------
+
+* This version made no changes to documented features or interfaces.
+  Some implementation updates were made to support ecosystem changes
+  and/or fix regressions.

Help/release/3.31.rst

@@ -0,0 +1,271 @@
+CMake 3.31 Release Notes
+************************
+
+.. only:: html
+
+  .. contents::
+
+Changes made since CMake 3.30 include the following.
+
+New Features
+============
+
+Presets
+-------
+
+* :manual:`cmake-presets(7)` files may now include comments using the key
+  ``$comment`` at any level within the JSON object to provide documentation.
+
+* :manual:`cmake-presets(7)` files may now request graphviz output using
+  the ``graphviz`` key in a configure preset.
+
+Generators
+----------
+
+* The :ref:`Ninja Generators` and :ref:`Makefile Generators` now produce
+  a ``codegen`` build target.  See policy :policy:`CMP0171`.  It drives a
+  subset of the build graph sufficient to run custom commands created with
+  :command:`add_custom_command`'s new ``CODEGEN`` option.
+
+Command-Line
+------------
+
+* The :option:`cmake --workflow` mode now accepts a preset name as the first
+  argument, allowing the simpler command line
+  :option:`cmake --workflow \<preset\> <cmake--workflow --preset>`.
+
+* The :option:`cmake -LR[A][H]` option was added to list cache entries
+  whose names match a regular expression.
+
+Compilers
+---------
+
+* The LFortran compiler is now supported with
+  :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``LFortran``.
+
+Commands
+--------
+
+* The :command:`add_custom_command` command gained a ``CODEGEN`` option
+  to mark a custom command's outputs as dependencies of a ``codegen`` target.
+  See policy :policy:`CMP0171`.
+
+* The :command:`cmake_pkg_config` command was added as an endpoint for using
+  CMake's native pkg-config format parser. The only supported option in this
+  release is ``EXTRACT``, which provides low-level access to the values
+  produced by parsing a pkg-config file. For most users, this is not yet a
+  suitable replacement for the :module:`FindPkgConfig` module.
+
+* The :command:`file(ARCHIVE_CREATE)` command gained a ``WORKING_DIRECTORY``
+  option to specify a working directory for the archiving process.
+
+* The :command:`file(MAKE_DIRECTORY)` command gained a ``RESULT`` option
+  to capture failure in a result variable.
+
+* The :command:`install(FILES)` and :command:`install(DIRECTORY)` commands'
+  ``TYPE`` argument gained support for a ``LIBEXEC`` type.
+
+Variables
+---------
+
+* The :variable:`CMAKE_AIX_SHARED_LIBRARY_ARCHIVE` variable and corresponding
+  :prop_tgt:`AIX_SHARED_LIBRARY_ARCHIVE` target property were added to
+  create shared libraries on AIX as shared library archives.
+
+* The :variable:`CMAKE_EXPORT_BUILD_DATABASE` variable, a corresponding
+  :envvar:`CMAKE_EXPORT_BUILD_DATABASE` environment variable, and an
+  :prop_tgt:`EXPORT_BUILD_DATABASE` target property, were added to
+  enable exporting C++ module compile commands.
+  This is only supported with :ref:`Ninja Generators`.
+
+* The :variable:`CMAKE_HOST_EXECUTABLE_SUFFIX` variable was added to
+  provide the suffix for executable names on the host platform.
+
+* The :variable:`CMAKE_<LANG>_HOST_COMPILER_ID` and
+  :variable:`CMAKE_<LANG>_HOST_COMPILER_VERSION` variables were added,
+  where ``<LANG>`` is either ``CUDA`` or ``HIP``.  They are populated
+  when :variable:`CMAKE_<LANG>_COMPILER_ID` is ``NVIDIA`` to identify
+  NVCC's host compiler.
+
+* The :variable:`CMAKE_<LANG>_STANDARD_LINK_DIRECTORIES` variable was added.
+  Toolchain files can set this variable to control which link library directory
+  paths are always passed to the compiler for the specified language.
+
+* The :variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable and
+  corresponding :prop_tgt:`LINK_LIBRARIES_STRATEGY` target
+  property were added to optionally specify the strategy
+  CMake uses to generate link lines.
+
+Properties
+----------
+
+* The :prop_tgt:`MACOSX_FRAMEWORK_BUNDLE_NAME <MACOSX_FRAMEWORK_INFO_PLIST>`
+  target property was added to set the ``CFBundleName`` key in an Apple
+  :prop_tgt:`FRAMEWORK`'s ``Info.plist`` file.
+
+* The :prop_tgt:`UNITY_BUILD` target property now supports the
+  ``CUDA`` language.
+
+* The :prop_tgt:`VS_FRAMEWORK_REFERENCES` target property was added
+  to tell :ref:`Visual Studio Generators` to add framework references.
+
+Modules
+-------
+
+* Check modules now support a ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
+  The following modules gained this support:
+
+  * :module:`CMakePushCheckState`
+  * :module:`CheckCCompilerFlag`
+  * :module:`CheckCSourceCompiles`
+  * :module:`CheckCSourceRuns`
+  * :module:`CheckCXXCompilerFlag`
+  * :module:`CheckCXXSourceCompiles`
+  * :module:`CheckCXXSourceRuns`
+  * :module:`CheckCXXSymbolExists`
+  * :module:`CheckCompilerFlag`
+  * :module:`CheckFortranCompilerFlag`
+  * :module:`CheckFortranFunctionExists`
+  * :module:`CheckFortranSourceCompiles`
+  * :module:`CheckFortranSourceRuns`
+  * :module:`CheckFunctionExists`
+  * :module:`CheckIncludeFile`
+  * :module:`CheckIncludeFileCXX`
+  * :module:`CheckIncludeFiles`
+  * :module:`CheckOBJCCompilerFlag`
+  * :module:`CheckLibraryExists`
+  * :module:`CheckOBJCCompilerFlag`
+  * :module:`CheckOBJCSourceCompiles`
+  * :module:`CheckOBJCSourceRuns`
+  * :module:`CheckOBJCXXCompilerFlag`
+  * :module:`CheckOBJCXXSourceCompiles`
+  * :module:`CheckOBJCXXSourceRuns`
+  * :module:`CheckPrototypeDefinition`
+  * :module:`CheckSourceCompiles`
+  * :module:`CheckSourceRuns`
+  * :module:`CheckStructHasMember`
+  * :module:`CheckSymbolExists`
+  * :module:`CheckTypeSize`
+  * :module:`CheckVariableExists`
+
+* The :module:`CMakePackageConfigHelpers` module's
+  :command:`generate_apple_platform_selection_file` function
+  gained support for iOS Mac Catalyst.
+
+* The :module:`GoogleTest` module :command:`gtest_discover_tests` command
+  gained a new ``DISCOVERY_EXTRA_ARGS`` keyword.  It allows extra arguments
+  to be appended to the command line when querying for the list of tests.
+
+* The :module:`FindCUDAToolkit` module now provides a ``CUDA::nvml_static``
+  target.
+
+* The :module:`FindOpenMP` module gained support for the ``CUDA`` language.
+
+CTest
+-----
+
+* The :command:`ctest_submit` command and :option:`ctest -T Submit <ctest -T>`
+  step now verify TLS server certificates for connections to ``https://`` URLs
+  by default.  See the :variable:`CTEST_TLS_VERIFY` variable for details.
+
+* The :command:`ctest_submit` command and :option:`ctest -T Submit <ctest -T>`
+  step now require TLS 1.2 or higher for connections to ``https://`` URLs by
+  default.  See the :variable:`CTEST_TLS_VERSION` variable for details.
+
+CPack
+-----
+
+* The :cpack_gen:`CPack DEB Generator` gained a
+  :variable:`CPACK_DEBIAN_PACKAGE_MULTIARCH` option
+  to support multi-arch packages.
+
+* The :cpack_gen:`CPack IFW Generator` gained the new
+  :variable:`CPACK_IFW_PACKAGE_PRODUCT_IMAGE_URLS` variable to
+  specify images associated with entries of
+  :variable:`CPACK_IFW_PACKAGE_PRODUCT_IMAGES`.
+  This feature is available for QtIFW 4.0 and newer.
+
+* The :cpack_gen:`CPack RPM Generator` gained support for ``zstd`` as a
+  :variable:`CPACK_RPM_COMPRESSION_TYPE` value.
+
+* The :module:`CPack` module enables per-machine installation by default
+  in the :cpack_gen:`CPack WIX Generator`.  See policy :policy:`CMP0172`
+  and the :variable:`CPACK_WIX_INSTALL_SCOPE` variable.
+
+Deprecated and Removed Features
+===============================
+
+* Compatibility with versions of CMake older than 3.10 is now deprecated
+  and will be removed from a future version.  Calls to
+  :command:`cmake_minimum_required` or :command:`cmake_policy` that set
+  the policy version to an older value now issue a deprecation diagnostic.
+
+* The :module:`CMakeFindFrameworks` module has been deprecated via
+  :policy:`CMP0173`. Projects should use :command:`find_library` instead.
+
+* The :generator:`Visual Studio 12 2013` generator has been removed.
+
+Other Changes
+=============
+
+* When static libraries on link lines are de-duplicated (by policy
+  :policy:`CMP0156`), the first occurrence is now kept on all platforms.
+  See policy :policy:`CMP0179`.
+
+* Empty list elements in the :prop_tgt:`TEST_LAUNCHER` and
+  :prop_tgt:`CROSSCOMPILING_EMULATOR` target properties are now preserved by:
+
+  * The :command:`add_test` command.
+  * The :command:`ExternalData_Add_Test` command from the
+    :module:`ExternalData` module.
+  * The :command:`gtest_add_tests` and :command:`gtest_discover_tests`
+    commands from the :module:`GoogleTest` module.
+    Empty list elements after the ``EXTRA_ARGS`` keyword of these
+    two commands are also now preserved.
+
+  See policy :policy:`CMP0178`.
+
+* The :command:`execute_process` command's ``ENCODING`` option,
+  meaningful on Windows, now defaults to ``UTF-8``.
+  See policy :policy:`CMP0176`.
+
+* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands now
+  verify TLS server certificates for connections to ``https://`` URLs by
+  default.  See the :variable:`CMAKE_TLS_VERIFY` variable for details.
+  This change was made without a policy so that users are protected
+  even when building projects that have not been updated.
+  Users may set the :envvar:`CMAKE_TLS_VERIFY` environment
+  variable to ``0`` to restore the old default.
+
+* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands now
+  require TLS 1.2 or higher for connections to ``https://`` URLs by default.
+  See the :variable:`CMAKE_TLS_VERSION` variable for details.
+
+* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command was updated
+  to more closely match the dynamic loader's behavior on Linux.
+
+* The :command:`install` command's ``DESTINATION`` arguments are
+  now :ref:`normalized <Normalization>`, with the exception
+  of ``INCLUDES DESTINATION`` arguments in :command:`install(TARGETS)`.
+  See policy :policy:`CMP0177`.
+
+* The :command:`project` command now always sets
+  :variable:`<PROJECT-NAME>_SOURCE_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR`,
+  and :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` as both normal variables and
+  cache entries.  See policy :policy:`CMP0180`.
+
+* The :command:`cmake_parse_arguments(PARSE_ARGV)` command now defines a
+  variable for an empty string after a single-value keyword. See policy
+  :policy:`CMP0174`.
+
+Updates
+=======
+
+Changes made since CMake 3.31.0 include the following.
+
+3.31.1
+------
+
+* This version made no changes to documented features or interfaces.
+  Some implementation updates were made to support ecosystem changes
+  and/or fix regressions.

Help/release/index.rst

@@ -13,6 +13,7 @@ Releases
 .. toctree::
    :maxdepth: 1
 
+   3.31 <3.31>
    3.30 <3.30>
    3.29 <3.29>
    3.28 <3.28>

Help/variable/CMAKE_AIX_SHARED_LIBRARY_ARCHIVE.rst

@@ -0,0 +1,10 @@
+CMAKE_AIX_SHARED_LIBRARY_ARCHIVE
+--------------------------------
+
+.. versionadded:: 3.31
+
+On AIX, enable creation of shared library archives.
+
+This variable initializes the :prop_tgt:`AIX_SHARED_LIBRARY_ARCHIVE`
+target property on ``SHARED`` library targets as they are created
+by :command:`add_library`.  See that target property for details.

Help/variable/CMAKE_CFG_INTDIR.rst

@@ -18,7 +18,7 @@ Example values:
 
 ::
 
-  $(Configuration)     = Visual Studio 12 and above
+  $(Configuration)     = Visual Studio
   $(CONFIGURATION)     = Xcode
   .                    = Make-based tools
   .                    = Ninja

Help/variable/CMAKE_EXECUTABLE_SUFFIX.rst

@@ -1,10 +1,14 @@
 CMAKE_EXECUTABLE_SUFFIX
 -----------------------
 
-The suffix for executables on this platform.
+The suffix for executables on the target platform.
 
 The suffix to use for the end of an executable filename if any, ``.exe``
 on Windows.
 
 :variable:`CMAKE_EXECUTABLE_SUFFIX_<LANG>` overrides this for
 language ``<LANG>``.
+
+
+See the :variable:`CMAKE_HOST_EXECUTABLE_SUFFIX` variable for the
+executable suffix on the host platform.

Help/variable/CMAKE_EXPORT_BUILD_DATABASE.rst

@@ -0,0 +1,86 @@
+CMAKE_EXPORT_BUILD_DATABASE
+---------------------------
+
+.. versionadded:: 3.31
+
+.. note ::
+
+   This variable is meaningful only when experimental support for build
+   databases has been enabled by the
+   ``CMAKE_EXPERIMENTAL_EXPORT_BUILD_DATABASE`` gate.
+
+Enable/Disable output of module compile commands during the build.
+
+If enabled, generates a ``build_database.json`` file containing the
+information necessary to compile a target's C++ module sources with any
+tooling. The format of the JSON file looks like:
+
+.. code-block:: javascript
+
+  {
+    "version": 1,
+    "revision": 0,
+    "sets": [
+      {
+        "family-name" : "export_build_database",
+        "name" : "export_build_database@Debug",
+        "translation-units" : [
+          {
+            "arguments": [
+              "/path/to/compiler",
+              "...",
+            ],
+            "baseline-arguments" :
+            [
+              "...",
+            ],
+            "local-arguments" :
+            [
+              "...",
+            ],
+            "object": "CMakeFiles/target.dir/source.cxx.o",
+            "private": true,
+            "provides": {
+              "importable": "path/to/bmi"
+            },
+            "requires" : [],
+            "source": "path/to/source.cxx",
+            "work-directory": "/path/to/working/directory"
+          }
+        ],
+        "visible-sets" : []
+      }
+    ]
+  }
+
+This is initialized by the :envvar:`CMAKE_EXPORT_BUILD_DATABASE` environment
+variable, and initializes the :prop_tgt:`EXPORT_BUILD_DATABASE` target
+property for all targets.
+
+.. note::
+  This option is implemented only by the :ref:`Ninja Generators`.  It is
+  ignored on other generators.
+
+When supported and enabled, numerous targets are created in order to make it
+possible to build a file containing just the commands that are needed for the
+tool in question.
+
+``cmake_build_database-<CONFIG>``
+  Writes ``build_database_<CONFIG>.json``. Writes a build database for the
+  entire build for the given configuration and all languages. Not available if
+  the configuration name is the empty string.
+
+``cmake_build_database-<LANG>-<CONFIG>``
+  Writes ``build_database_<LANG>_<CONFIG>.json``. Writes build database for
+  the entire build for the given configuration and language. Not available if
+  the configuration name is the empty string.
+
+``cmake_build_database-<LANG>``
+  Writes ``build_database_<LANG>.json``. Writes build database for the entire
+  build for the given language and all configurations. In a multi-config
+  generator, other build configuration database may be assumed to exist.
+
+``cmake_build_database``
+  Writes to ``build_database.json``. Writes build database for all languages
+  and configurations. In a multi-config generator, other build configuration
+  database may be assumed to exist.

Help/variable/CMAKE_FIND_PACKAGE_SORT_ORDER.rst

@@ -3,23 +3,26 @@ CMAKE_FIND_PACKAGE_SORT_ORDER
 
 .. versionadded:: 3.7
 
-The default order for sorting packages found using :command:`find_package`.
-It can assume one of the following values:
+The default order for sorting directories which match a search path containing
+a glob expression found using :command:`find_package`.  It can assume one of
+the following values:
 
 ``NONE``
-  Default.  No attempt is done to sort packages.
+  Default.  No attempt is done to sort directories.
   The first valid package found will be selected.
 
 ``NAME``
-  Sort packages lexicographically before selecting one.
+  Sort directories lexicographically before searching.
 
 ``NATURAL``
-  Sort packages using natural order (see ``strverscmp(3)`` manual),
+  Sort directories using natural order (see ``strverscmp(3)`` manual),
   i.e. such that contiguous digits are compared as whole numbers.
 
 Natural sorting can be employed to return the highest version when multiple
-versions of the same library are found by :command:`find_package`.  For
-example suppose that the following libraries have been found:
+versions of the same library are available to be found by
+:command:`find_package`.  For example suppose that the following libraries
+have package configuration files on disk, in a directory of the same name,
+with all such directories residing in the same parent directory:
 
 * libX-1.1.0
 * libX-1.2.9
@@ -35,4 +38,4 @@ version number ``libX-1.2.10``.
 
 The sort direction can be controlled using the
 :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION` variable
-(by default decrescent, e.g. lib-B will be tested before lib-A).
+(by default descending, e.g. lib-B will be tested before lib-A).

Help/variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL.rst

@@ -3,7 +3,7 @@ CMAKE_FIND_PACKAGE_TARGETS_GLOBAL
 
 .. versionadded:: 3.24
 
-Setting to ``TRUE`` promotes all :prop_tgt:`IMPORTED` targets discoverd
+Setting to ``TRUE`` promotes all :prop_tgt:`IMPORTED` targets discovered
 by :command:`find_package` to a ``GLOBAL`` scope.