Update upstream source from tag 'upstream/3.26.4'

Update to upstream version '3.26.4'
with Debian dir d320e8793824f6218b7cfa9ba0cbe460d47c5ae1

.clang-format

@@ -1,5 +1,5 @@
 ---
-# This configuration requires clang-format version 6.0 exactly.
+# This configuration requires clang-format version 15 exactly.
 BasedOnStyle: Mozilla
 AlignOperands: false
 AllowShortFunctionsOnASingleLine: InlineOnly

.clang-tidy

@@ -1,24 +1,31 @@
 ---
 Checks: "-*,\
 bugprone-*,\
+-bugprone-assignment-in-if-condition,\
 -bugprone-easily-swappable-parameters,\
 -bugprone-implicit-widening-of-multiplication-result,\
 -bugprone-macro-parentheses,\
 -bugprone-misplaced-widening-cast,\
 -bugprone-narrowing-conversions,\
 -bugprone-too-small-loop-variable,\
+-bugprone-unchecked-optional-access,\
 misc-*,\
+-misc-confusable-identifiers,\
+-misc-const-correctness,\
 -misc-no-recursion,\
 -misc-non-private-member-variables-in-classes,\
 -misc-static-assert,\
 modernize-*,\
 -modernize-avoid-c-arrays,\
+-modernize-macro-to-enum,\
 -modernize-return-braced-init-list,\
+-modernize-use-emplace,\
 -modernize-use-nodiscard,\
 -modernize-use-noexcept,\
 -modernize-use-trailing-return-type,\
 -modernize-use-transparent-functors,\
 performance-*,\
+-performance-inefficient-vector-operation,\
 readability-*,\
 -readability-convert-member-functions-to-static,\
 -readability-function-cognitive-complexity,\
@@ -28,11 +35,17 @@ readability-*,\
 -readability-implicit-bool-conversion,\
 -readability-inconsistent-declaration-parameter-name,\
 -readability-magic-numbers,\
+-readability-make-member-function-const,\
 -readability-named-parameter,\
 -readability-redundant-declaration,\
 -readability-redundant-member-init,\
+-readability-simplify-boolean-expr,\
 -readability-suspicious-call-argument,\
 -readability-uppercase-literal-suffix,\
+cmake-*,\
+-cmake-ostringstream-use-cmstrcat,\
+-cmake-string-concatenation-use-cmstrcat,\
+-cmake-use-bespoke-enum-class,\
 "
 HeaderFilterRegex: 'Source/cm[^/]*\.(h|hxx|cxx)$'
 CheckOptions:

Auxiliary/vim/syntax/cmake.vim

@@ -2013,6 +2013,7 @@ syn keyword cmakeKWExternalProject contained
             \ IGNORED
             \ INACTIVITY_TIMEOUT
             \ INDEPENDENT_STEP_TARGETS
+            \ INSTALL_BYPRODUCTS
             \ INSTALL_COMMAND
             \ INSTALL_DIR
             \ JOB_POOLS

CMakeCPack.cmake

@@ -264,5 +264,9 @@ set(CPACK_SOURCE_IGNORE_FILES
   "~$"
   )
 
+if(CMake_CPACK_CUSTOM_SCRIPT)
+  include(${CMake_CPACK_CUSTOM_SCRIPT})
+endif()
+
 # include CPack model once all variables are set
 include(CPack)

CMakeLists.txt

@@ -1,14 +1,10 @@
 # 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.23 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.13...3.24 FATAL_ERROR)
 set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake)
 set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake)
 
-if(POLICY CMP0129)
-  cmake_policy(SET CMP0129 NEW) # CMake 3.23
-endif()
-
 project(CMake)
 unset(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX)
 unset(CMAKE_USER_MAKE_RULES_OVERRIDE_C)
@@ -73,11 +69,7 @@ if(NOT DEFINED CMAKE_CXX_STANDARD AND NOT CMake_NO_CXX_STANDARD)
   if(CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.14)
     set(CMAKE_CXX_STANDARD 98)
   else()
-    if(NOT CMAKE_VERSION VERSION_LESS 3.8)
     include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx17_check.cmake)
-    else()
-      set(CMake_CXX17_BROKEN 1)
-    endif()
     if(NOT CMake_CXX17_BROKEN)
       set(CMAKE_CXX_STANDARD 17)
     else()
@@ -130,7 +122,6 @@ option(CMake_BUILD_DEVELOPER_REFERENCE
 mark_as_advanced(CMake_BUILD_DEVELOPER_REFERENCE)
 
 # option to build using interprocedural optimizations (IPO/LTO)
-if(NOT CMAKE_VERSION VERSION_LESS 3.12.2)
 option(CMake_BUILD_LTO "Compile CMake with link-time optimization if supported" OFF)
 if(CMake_BUILD_LTO)
   include(CheckIPOSupported)
@@ -139,7 +130,6 @@ if(NOT CMAKE_VERSION VERSION_LESS 3.12.2)
     set(CMAKE_INTERPROCEDURAL_OPTIMIZATION TRUE)
   endif()
 endif()
-endif()
 
 #-----------------------------------------------------------------------
 # a macro to deal with system libraries, implemented as a macro
@@ -251,10 +241,6 @@ macro(CMAKE_SETUP_TESTING)
   configure_file(Tests/.NoDartCoverage Tests/.NoDartCoverage)
   configure_file(Tests/.NoDartCoverage Modules/.NoDartCoverage)
   configure_file(CTestCustom.cmake.in CTestCustom.cmake @ONLY)
-  if(BUILD_TESTING AND DART_ROOT)
-    configure_file(CMakeLogo.gif Testing/HTML/TestingResults/Icons/Logo.gif COPYONLY)
-  endif()
-  mark_as_advanced(DART_ROOT)
 endmacro()
 
 
@@ -277,6 +263,25 @@ if(CMake_RUN_CLANG_TIDY)
   endif()
   set(CMAKE_CXX_CLANG_TIDY "${CLANG_TIDY_COMMAND}")
 
+  option(CMake_USE_CLANG_TIDY_MODULE "Use CMake's clang-tidy module." OFF)
+  if(CMake_USE_CLANG_TIDY_MODULE)
+    find_library(CMake_CLANG_TIDY_MODULE NAMES cmake-clang-tidy-module DOC "Location of the clang-tidy module")
+    if(NOT CMake_CLANG_TIDY_MODULE)
+      message(FATAL_ERROR "CMake_USE_CLANG_TIDY_MODULE is ON but cmake-clang-tidy-module is not found!")
+    endif()
+    list(APPEND CMAKE_CXX_CLANG_TIDY "--load=${CMake_CLANG_TIDY_MODULE}")
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${CMake_CLANG_TIDY_MODULE}")
+  endif()
+
+  set(CMake_CLANG_TIDY_EXPORT_FIXES_DIR "" CACHE PATH "Directory to put clang-tidy fix files in.")
+  mark_as_advanced(CMake_CLANG_TIDY_EXPORT_FIXES_DIR)
+  if(CMake_CLANG_TIDY_EXPORT_FIXES_DIR)
+    if(NOT IS_ABSOLUTE "${CMake_CLANG_TIDY_EXPORT_FIXES_DIR}")
+      message(FATAL_ERROR "CMake_CLANG_TIDY_EXPORT_FIXES_DIR must be an absolute path!")
+    endif()
+    set(CMAKE_CXX_CLANG_TIDY_EXPORT_FIXES_DIR "${CMake_CLANG_TIDY_EXPORT_FIXES_DIR}")
+  endif()
+
   # Create a preprocessor definition that depends on .clang-tidy content so
   # the compile command will change when .clang-tidy changes.  This ensures
   # that a subsequent build re-runs clang-tidy on all sources even if they
@@ -286,6 +291,11 @@ if(CMake_RUN_CLANG_TIDY)
   file(SHA1 ${CMAKE_CURRENT_SOURCE_DIR}/.clang-tidy clang_tidy_sha1)
   set(CLANG_TIDY_DEFINITIONS "CLANG_TIDY_SHA1=${clang_tidy_sha1}")
   unset(clang_tidy_sha1)
+  if(CMake_USE_CLANG_TIDY_MODULE)
+    file(SHA1 "${CMake_CLANG_TIDY_MODULE}" clang_tidy_module_sha1)
+    list(APPEND CLANG_TIDY_DEFINITIONS "CLANG_TIDY_MODULE_SHA1=${clang_tidy_module_sha1}")
+    unset(clang_tidy_module_sha1)
+  endif()
 
 endif()
 configure_file(.clang-tidy .clang-tidy COPYONLY)
@@ -299,6 +309,11 @@ if(CMake_RUN_IWYU)
   endif()
   set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE
     "${IWYU_COMMAND};-Xiwyu;--mapping_file=${CMake_SOURCE_DIR}/Utilities/IWYU/mapping.imp;-w")
+  option(CMake_IWYU_VERBOSE "Run include-what-you-use in verbose mode" OFF)
+  if (CMake_IWYU_VERBOSE)
+    list(APPEND CMAKE_CXX_INCLUDE_WHAT_YOU_USE
+      -Xiwyu -v7)
+  endif ()
   list(APPEND CMAKE_CXX_INCLUDE_WHAT_YOU_USE ${CMake_IWYU_OPTIONS})
 endif()
 
@@ -342,9 +357,7 @@ endif()
 #-----------------------------------------------------------------------
 include(Source/CMakeVersion.cmake)
 
-# Include the standard Dart testing module
+include(CTest)
-enable_testing()
-include(${CMAKE_ROOT}/Modules/Dart.cmake)
 
 # Set up test-time configuration.
 set_directory_properties(PROPERTIES

CompileFlags.cmake

@@ -87,11 +87,6 @@ if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND
   if (NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.13)
     if (NOT CMAKE_CXX_STANDARD OR CMAKE_CXX_STANDARD EQUAL 98)
       set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++03")
-    elseif(CMAKE_VERSION VERSION_LESS 3.8.20170502)
-      # CMake knows how to add this flag for compilation as C++11,
-      # but has not been taught that SunPro needs it for linking too.
-      # Add it in a place that will be used for both.
-      set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
     endif()
   else()
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -library=stlport4")

Copyright.txt

@@ -1,5 +1,5 @@
 CMake - Cross Platform Makefile Generator
-Copyright 2000-2022 Kitware, Inc. and Contributors
+Copyright 2000-2023 Kitware, Inc. and Contributors
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

Help/command/DEVICE_LINK_OPTIONS.txt

@@ -7,8 +7,6 @@ Host And Device Specific Link Options
   :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`,
   the raw options will be delivered to the host and device link steps (wrapped in
   ``-Xcompiler`` or equivalent for device link). Options wrapped with
-  ``$<DEVICE_LINK:...>``
+  :genex:`$<DEVICE_LINK:...>` generator expression will be used
-  :manual:`generator expression <cmake-generator-expressions(7)>` will be used
+  only for the device link step. Options wrapped with :genex:`$<HOST_LINK:...>`
-  only for the device link step. Options wrapped with ``$<HOST_LINK:...>``
+  generator expression will be used only for the host link step.
-  :manual:`generator expression <cmake-generator-expressions(7)>` will be used
-  only for the host link step.

Help/command/GENEX_NOTE.txt

@@ -0,0 +1,6 @@
+.. |more_see_also| replace:: See the :manual:`cmake-buildsystem(7)` manual
+   for more on defining buildsystem properties.
+
+Arguments to |command_name| may use generator expressions
+with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
+manual for available expressions.  |more_see_also|

Help/command/SUPPORTED_LANGUAGES.txt

@@ -0,0 +1,25 @@
+
+Supported languages are ``C``, ``CXX`` (i.e.  C++), ``CSharp`` (i.e.  C#), ``CUDA``,
+``OBJC`` (i.e. Objective-C), ``OBJCXX`` (i.e. Objective-C++), ``Fortran``, ``HIP``,
+``ISPC``, ``Swift``, ``ASM``, ``ASM_NASM``, ``ASM_MARMASM``, ``ASM_MASM``, and ``ASM-ATT``.
+
+  .. versionadded:: 3.8
+    Added ``CSharp`` and ``CUDA`` support.
+
+  .. versionadded:: 3.15
+    Added ``Swift`` support.
+
+  .. versionadded:: 3.16
+    Added ``OBJC`` and ``OBJCXX`` support.
+
+  .. versionadded:: 3.18
+    Added ``ISPC`` support.
+
+  .. versionadded:: 3.21
+    Added ``HIP`` support.
+
+  .. versionadded:: 3.26
+    Added ``ASM_MARMASM`` support.
+
+If enabling ``ASM``, list it last so that CMake can check whether
+compilers for other languages like ``C`` work for assembly too.

Help/command/add_compile_definitions.rst

@@ -21,7 +21,13 @@ Function-style definitions are not supported. CMake will automatically
 escape the value correctly for the native build system (note that CMake
 language syntax may require escapes to specify some values).
 
-Arguments to ``add_compile_definitions`` may use "generator expressions" with
+.. versionadded:: 3.26
-the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
+  Any leading ``-D`` on an item will be removed.
-manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
+
-manual for more on defining buildsystem properties.
+.. |command_name| replace:: ``add_compile_definitions``
+.. include:: GENEX_NOTE.txt
+
+See Also
+^^^^^^^^
+
+* The command :command:`target_compile_definitions` adds target-specific definitions.

Help/command/add_compile_options.rst

@@ -14,10 +14,8 @@ directory and below.
 Arguments
 ^^^^^^^^^
 
-Arguments to ``add_compile_options`` may use "generator expressions" with
+.. |command_name| replace:: ``add_compile_options``
-the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
+.. include:: GENEX_NOTE.txt
-manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
-manual for more on defining buildsystem properties.
 
 .. include:: OPTIONS_SHELL.txt
 
@@ -30,22 +28,25 @@ this command is in a compiler-specific conditional clause:
 .. code-block:: cmake
 
   if (MSVC)
-      # warning level 4 and all warnings as errors
+      # warning level 4
-      add_compile_options(/W4 /WX)
+      add_compile_options(/W4)
   else()
-      # lots of warnings and all warnings as errors
+      # additional warnings
-      add_compile_options(-Wall -Wextra -pedantic -Werror)
+      add_compile_options(-Wall -Wextra -Wpedantic)
   endif()
 
+To set per-language options, use the :genex:`$<COMPILE_LANGUAGE>`
+or :genex:`$<COMPILE_LANGUAGE:languages>` generator expressions.
+
 See Also
 ^^^^^^^^
 
-This command can be used to add any options. However, for
+* This command can be used to add any options. However, for
   adding preprocessor definitions and include directories it is recommended
   to use the more specific commands :command:`add_compile_definitions`
   and :command:`include_directories`.
 
-The command :command:`target_compile_options` adds target-specific options.
+* The command :command:`target_compile_options` adds target-specific options.
 
-The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one
+* The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one
   source file.

Help/command/add_custom_command.rst

@@ -31,14 +31,12 @@ This defines a command to generate specified ``OUTPUT`` file(s).
 A target created in the same directory (``CMakeLists.txt`` file)
 that specifies any output of the custom command as a source file
 is given a rule to generate the file using the command at build time.
-Do not list the output in more than one independent target that
-may build in parallel or the two instances of the rule may conflict
-(instead use the :command:`add_custom_target` command to drive the
-command and make the other targets depend on that one).
-In makefile terms this creates a new target in the following form::
 
-  OUTPUT: MAIN_DEPENDENCY DEPENDS
+Do not list the output in more than one independent target that
-          COMMAND
+may build in parallel or the instances of the rule may conflict.
+Instead, use the :command:`add_custom_target` command to drive the
+command and make the other targets depend on that one.  See the
+`Example: Generating Files for Multiple Targets`_ below.
 
 The options are:
 
@@ -140,6 +138,10 @@ The options are:
   Display the given message before the commands are executed at
   build time.
 
+  .. versionadded:: 3.26
+    Arguments to ``COMMENT`` may use
+    :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
 ``DEPENDS``
   Specify files on which the command depends.  Each argument is converted
   to a dependency as follows:
@@ -229,15 +231,24 @@ The options are:
 
 ``OUTPUT``
   Specify the output files the command is expected to produce.
-  If an output name is a relative path it will be interpreted
-  relative to the build tree directory corresponding to the
-  current source directory.
   Each output file will be marked with the :prop_sf:`GENERATED`
   source file property automatically.
   If the output of the custom command is not actually created
   as a file on disk it should be marked with the :prop_sf:`SYMBOLIC`
   source file property.
 
+  If an output file name is a relative path, its absolute path is
+  determined by interpreting it relative to:
+
+  1. the build directory corresponding to the current source directory
+     (:variable:`CMAKE_CURRENT_BINARY_DIR`), or
+
+  2. the current source directory (:variable:`CMAKE_CURRENT_SOURCE_DIR`).
+
+  The path in the build directory is preferred unless the path in the
+  source tree is mentioned as an absolute source file path elsewhere
+  in the current directory.
+
   .. versionadded:: 3.20
     Arguments to ``OUTPUT`` may use a restricted set of
     :manual:`generator expressions <cmake-generator-expressions(7)>`.
@@ -385,6 +396,49 @@ will re-run whenever ``in.txt`` changes.
   where ``<config>`` is the build configuration, and then compile the generated
   source as part of a library.
 
+Example: Generating Files for Multiple Targets
+""""""""""""""""""""""""""""""""""""""""""""""
+
+If multiple independent targets need the same custom command output,
+it must be attached to a single custom target on which they all depend.
+Consider the following example:
+
+.. code-block:: cmake
+
+  add_custom_command(
+    OUTPUT table.csv
+    COMMAND makeTable -i ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
+                      -o table.csv
+    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
+    VERBATIM)
+  add_custom_target(generate_table_csv DEPENDS table.csv)
+
+  add_custom_command(
+    OUTPUT foo.cxx
+    COMMAND genFromTable -i table.csv -case foo -o foo.cxx
+    DEPENDS table.csv           # file-level dependency
+            generate_table_csv  # target-level dependency
+    VERBATIM)
+  add_library(foo foo.cxx)
+
+  add_custom_command(
+    OUTPUT bar.cxx
+    COMMAND genFromTable -i table.csv -case bar -o bar.cxx
+    DEPENDS table.csv           # file-level dependency
+            generate_table_csv  # target-level dependency
+    VERBATIM)
+  add_library(bar bar.cxx)
+
+Output ``foo.cxx`` is needed only by target ``foo`` and output ``bar.cxx``
+is needed only by target ``bar``, but *both* targets need ``table.csv``,
+transitively.  Since ``foo`` and ``bar`` are independent targets that may
+build concurrently, we prevent them from racing to generate ``table.csv``
+by placing its custom command in a separate target, ``generate_table_csv``.
+The custom commands generating ``foo.cxx`` and ``bar.cxx`` each specify a
+target-level dependency on ``generate_table_csv``, so the targets using them,
+``foo`` and ``bar``, will not build until after target ``generate_table_csv``
+is built.
+
 .. _`add_custom_command(TARGET)`:
 
 Build Events
@@ -490,3 +544,8 @@ Ninja Multi-Config
   ``add_custom_command`` supports the :generator:`Ninja Multi-Config`
   generator's cross-config capabilities. See the generator documentation
   for more information.
+
+See Also
+^^^^^^^^
+
+* :command:`add_custom_target`

Help/command/add_custom_target.rst

@@ -109,6 +109,10 @@ The options are:
   Display the given message before the commands are executed at
   build time.
 
+  .. versionadded:: 3.26
+    Arguments to ``COMMENT`` may use
+    :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
 ``DEPENDS``
   Reference files and outputs of custom commands created with
   :command:`add_custom_command` command calls in the same directory
@@ -181,3 +185,8 @@ Ninja Multi-Config
   ``add_custom_target`` supports the :generator:`Ninja Multi-Config`
   generator's cross-config capabilities. See the generator documentation
   for more information.
+
+See Also
+^^^^^^^^
+
+* :command:`add_custom_command`

Help/command/add_definitions.rst

@@ -1,7 +1,7 @@
 add_definitions
 ---------------
 
-Add -D define flags to the compilation of source files.
+Add ``-D`` define flags to the compilation of source files.
 
 .. code-block:: cmake
 
@@ -31,5 +31,8 @@ backwards compatibility.  See documentation of the
 properties for details on adding preprocessor definitions to specific
 scopes and configurations.
 
-See the :manual:`cmake-buildsystem(7)` manual for more on defining
+See Also
+^^^^^^^^
+
+* The :manual:`cmake-buildsystem(7)` manual for more on defining
   buildsystem properties.

Help/command/add_dependencies.rst

@@ -20,7 +20,12 @@ transitively in its place since the target itself does not build.
 .. versionadded:: 3.3
   Allow adding dependencies to interface libraries.
 
-See the ``DEPENDS`` option of :command:`add_custom_target` and
+See Also
+^^^^^^^^
+
+* The ``DEPENDS`` option of :command:`add_custom_target` and
   :command:`add_custom_command` commands for adding file-level
-dependencies in custom rules.  See the :prop_sf:`OBJECT_DEPENDS`
+  dependencies in custom rules.
-source file property to add file-level dependencies to object files.
+
+* The :prop_sf:`OBJECT_DEPENDS` source file property to add
+  file-level dependencies to object files.

Help/command/add_executable.rst

@@ -107,3 +107,8 @@ The ``<name>`` may not be used to modify properties of ``<target>``, that
 is, it may not be used as the operand of :command:`set_property`,
 :command:`set_target_properties`, :command:`target_link_libraries` etc.
 An ``ALIAS`` target may not be installed or exported.
+
+See Also
+^^^^^^^^
+
+* :command:`add_library`

Help/command/add_library.rst

@@ -83,10 +83,10 @@ Object Libraries
 
 Creates an :ref:`Object Library <Object Libraries>`.  An object library
 compiles source files but does not archive or link their object files into a
-library.  Instead other targets created by :command:`add_library` or
+library.  Instead other targets created by ``add_library`` or
 :command:`add_executable` may reference the objects using an expression of the
-form ``$<TARGET_OBJECTS:objlib>`` as a source, where ``objlib`` is the
+form :genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>` as a source, where
-object library name.  For example:
+``objlib`` is the object library name.  For example:
 
 .. code-block:: cmake
 
@@ -101,7 +101,7 @@ They may contain custom commands generating such sources, but not
 ``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands.  Some native build
 systems (such as Xcode) may not like targets that have only object files, so
 consider adding at least one real source file to any target that references
-``$<TARGET_OBJECTS:objlib>``.
+:genex:`$\<TARGET_OBJECTS:objlib\> <TARGET_OBJECTS>`.
 
 .. versionadded:: 3.12
   Object libraries can be linked to with :command:`target_link_libraries`.
@@ -261,3 +261,8 @@ to modify properties of ``<target>``, that is, it may not be used as the
 operand of :command:`set_property`, :command:`set_target_properties`,
 :command:`target_link_libraries` etc.  An ``ALIAS`` target may not be
 installed or exported.
+
+See Also
+^^^^^^^^
+
+* :command:`add_executable`

Help/command/add_link_options.rst

@@ -23,13 +23,18 @@ exist to add libraries (:command:`target_link_libraries` or
   since they do not use a linker.  To add archiver or MSVC librarian flags,
   see the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property.
 
-Arguments to ``add_link_options`` may use "generator expressions" with
+.. |command_name| replace:: ``add_link_options``
-the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
+.. include:: GENEX_NOTE.txt
-manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
-manual for more on defining buildsystem properties.
 
 .. include:: DEVICE_LINK_OPTIONS.txt
 
 .. include:: OPTIONS_SHELL.txt
 
 .. include:: LINK_OPTIONS_LINKER.txt
+
+See Also
+^^^^^^^^
+
+* :command:`link_libraries`
+* :command:`target_link_libraries`
+* :command:`target_link_options`

Help/command/add_subdirectory.rst

@@ -7,16 +7,16 @@ Add a subdirectory to the build.
 
   add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL] [SYSTEM])
 
-Adds a subdirectory to the build.  The source_dir specifies the
+Adds a subdirectory to the build.  The ``source_dir`` specifies the
-directory in which the source CMakeLists.txt and code files are
+directory in which the source ``CMakeLists.txt`` and code files are
-located.  If it is a relative path it will be evaluated with respect
+located.  If it is a relative path, it will be evaluated with respect
 to the current directory (the typical usage), but it may also be an
 absolute path.  The ``binary_dir`` specifies the directory in which to
-place the output files.  If it is a relative path it will be evaluated
+place the output files.  If it is a relative path, it will be evaluated
 with respect to the current output directory, but it may also be an
 absolute path.  If ``binary_dir`` is not specified, the value of
 ``source_dir``, before expanding any relative path, will be used (the
-typical usage).  The CMakeLists.txt file in the specified source
+typical usage).  The ``CMakeLists.txt`` file in the specified source
 directory will be processed immediately by CMake before processing in
 the current input file continues beyond this command.
 
@@ -28,15 +28,14 @@ meant for use when the subdirectory contains a separate part of the
 project that is useful but not necessary, such as a set of examples.
 Typically the subdirectory should contain its own :command:`project`
 command invocation so that a full build system will be generated in the
-subdirectory (such as a VS IDE solution file).  Note that inter-target
+subdirectory (such as a Visual Studio IDE solution file).  Note that
-dependencies supersede this exclusion.  If a target built by the
+inter-target dependencies supersede this exclusion.  If a target built by
-parent project depends on a target in the subdirectory, the dependee
+the parent project depends on a target in the subdirectory, the dependee
 target will be included in the parent project build system to satisfy
 the dependency.
 
+.. versionadded:: 3.25
   If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory
   property of the subdirectory will be set to true.  This property is
-used to initialize the :prop_tgt:`SYSTEM` property of each target
+  used to initialize the :prop_tgt:`SYSTEM` property of each non-imported
-created in that subdirectory. The include directories of targets with
+  target created in that subdirectory.
-:prop_tgt:`SYSTEM` set to true will be treated as ``SYSTEM`` when
-compiling consumers.

Help/command/build_name.rst

@@ -5,7 +5,7 @@ Disallowed since version 3.0.  See CMake Policy :policy:`CMP0036`.
 
 Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead.
 
-::
+.. code-block:: cmake
 
   build_name(variable)
 

Help/command/cmake_host_system_information.rst

@@ -17,7 +17,7 @@ Synopsis
 Query host system specific information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: cmake
 
   cmake_host_system_information(RESULT <variable> QUERY <key> ...)
 

Help/command/cmake_minimum_required.rst

@@ -79,3 +79,8 @@ invokes
   cmake_policy(VERSION 2.4[...<max>])
 
 which enables compatibility features for CMake 2.4 and lower.
+
+See Also
+^^^^^^^^
+
+* :command:`cmake_policy`

Help/command/cmake_parse_arguments.rst

@@ -113,3 +113,9 @@ interpreted as the beginning of the new option.  E.g.
 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``.
+
+See Also
+^^^^^^^^
+
+* :command:`function`
+* :command:`macro`

Help/command/cmake_path.rst

@@ -237,7 +237,7 @@ The following forms of the ``GET`` subcommand each retrieve a different
 component or group of components from a path.  See
 `Path Structure And Terminology`_ for the meaning of each path component.
 
-::
+.. code-block:: cmake
 
   cmake_path(GET <path-var> ROOT_NAME <out-var>)
   cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
@@ -408,7 +408,7 @@ meaning of each path component.
 .. _HAS_RELATIVE_PART:
 .. _HAS_PARENT_PATH:
 
-::
+.. code-block:: cmake
 
   cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
   cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
@@ -432,7 +432,7 @@ Note the following special cases:
 
 .. _IS_ABSOLUTE:
 
-::
+.. code-block:: cmake
 
   cmake_path(IS_ABSOLUTE <path-var> <out-var>)
 
@@ -446,7 +446,7 @@ false while ``HAS_ROOT_DIRECTORY`` can be true.
 
 .. _IS_RELATIVE:
 
-::
+.. code-block:: cmake
 
   cmake_path(IS_RELATIVE <path-var> <out-var>)
 
@@ -454,7 +454,7 @@ This will store the opposite of ``IS_ABSOLUTE`` in ``<out-var>``.
 
 .. _IS_PREFIX:
 
-::
+.. code-block:: cmake
 
   cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
 
@@ -476,7 +476,7 @@ are :ref:`normalized <Normalization>` before the check.
 .. _Path COMPARE:
 .. _COMPARE:
 
-::
+.. code-block:: cmake
 
   cmake_path(COMPARE <input1> EQUAL <input2> <out-var>)
   cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)
@@ -510,7 +510,7 @@ Modification
 
 .. _cmake_path-SET:
 
-::
+.. code-block:: cmake
 
   cmake_path(SET <path-var> [NORMALIZE] <input>)
 
@@ -539,7 +539,7 @@ Output::
 
 .. _APPEND:
 
-::
+.. code-block:: cmake
 
   cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
 
@@ -570,7 +570,7 @@ the following algorithm (pseudo-code) applies:
 
 .. _APPEND_STRING:
 
-::
+.. code-block:: cmake
 
   cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
 
@@ -579,7 +579,7 @@ Append all the ``<input>`` arguments to the ``<path-var>`` without adding any
 
 .. _REMOVE_FILENAME:
 
-::
+.. code-block:: cmake
 
   cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
 
@@ -609,7 +609,7 @@ Output::
 
 .. _REPLACE_FILENAME:
 
-::
+.. code-block:: cmake
 
   cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
 
@@ -628,7 +628,7 @@ equivalent to the following:
 
 .. _REMOVE_EXTENSION:
 
-::
+.. code-block:: cmake
 
   cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY]
                                          [OUTPUT_VARIABLE <out-var>])
@@ -637,7 +637,7 @@ Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path-var>``.
 
 .. _REPLACE_EXTENSION:
 
-::
+.. code-block:: cmake
 
   cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input>
                                [OUTPUT_VARIABLE <out-var>])
@@ -661,7 +661,7 @@ Generation
 
 .. _NORMAL_PATH:
 
-::
+.. code-block:: cmake
 
   cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
 
@@ -670,7 +670,7 @@ Normalize ``<path-var>`` according the steps described in :ref:`Normalization`.
 .. _cmake_path-RELATIVE_PATH:
 .. _RELATIVE_PATH:
 
-::
+.. code-block:: cmake
 
   cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>]
                                       [OUTPUT_VARIABLE <out-var>])
@@ -686,7 +686,7 @@ as that used by C++
 
 .. _ABSOLUTE_PATH:
 
-::
+.. code-block:: cmake
 
   cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE]
                                       [OUTPUT_VARIABLE <out-var>])
@@ -713,7 +713,7 @@ target platform when cross-compiling.
 .. _cmake_path-NATIVE_PATH:
 .. _NATIVE_PATH:
 
-::
+.. code-block:: cmake
 
   cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
 
@@ -727,7 +727,7 @@ When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
 .. _cmake_path-TO_CMAKE_PATH_LIST:
 .. _TO_CMAKE_PATH_LIST:
 
-::
+.. code-block:: cmake
 
   cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
 
@@ -749,7 +749,7 @@ When the ``NORMALIZE`` option is specified, the path is :ref:`normalized
 .. _cmake_path-TO_NATIVE_PATH_LIST:
 .. _TO_NATIVE_PATH_LIST:
 
-::
+.. code-block:: cmake
 
   cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])
 
@@ -788,7 +788,7 @@ Hashing
 
 .. _HASH:
 
-::
+.. code-block:: cmake
 
     cmake_path(HASH <path-var> <out-var>)
 

Help/command/cmake_policy.rst

@@ -150,3 +150,8 @@ use the pre-record policies when they are invoked.  If the function or
 macro implementation sets policies, the changes automatically
 propagate up through callers until they reach the closest nested
 policy stack entry.
+
+See Also
+^^^^^^^^
+
+* :command:`cmake_minimum_required`

Help/command/configure_file.rst

@@ -58,7 +58,7 @@ or
   #define VAR 1
 
 Input lines of the form ``#cmakedefine01 VAR ...`` will expand
-as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 0``,
+as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 1``,
 which may lead to undefined behavior.
 
 .. versionadded:: 3.10
@@ -174,11 +174,16 @@ Otherwise it will contain:
   /* #undef FOO_ENABLE */
   /* #undef FOO_STRING */
 
-One may then use the :command:`include_directories` command to
+One may then use the :command:`target_include_directories` command to
 specify the output directory as an include directory:
 
 .. code-block:: cmake
 
-  include_directories(${CMAKE_CURRENT_BINARY_DIR})
+  target_include_directories(<target> [SYSTEM] <INTERFACE|PUBLIC|PRIVATE> "${CMAKE_CURRENT_BINARY_DIR}")
 
 so that sources may include the header as ``#include <foo.h>``.
+
+See Also
+^^^^^^^^
+
+* :command:`file(GENERATE)`

Help/command/ctest_build.rst

@@ -3,7 +3,7 @@ ctest_build
 
 Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`.
 
-::
+.. code-block:: cmake
 
   ctest_build([BUILD <build-dir>] [APPEND]
               [CONFIGURATION <config>]

Help/command/ctest_configure.rst

@@ -3,7 +3,7 @@ ctest_configure
 
 Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`.
 
-::
+.. code-block:: cmake
 
   ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
                   [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]

Help/command/ctest_coverage.rst

@@ -3,7 +3,7 @@ ctest_coverage
 
 Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`.
 
-::
+.. code-block:: cmake
 
   ctest_coverage([BUILD <build-dir>] [APPEND]
                  [LABELS <label>...]

Help/command/ctest_empty_binary_directory.rst

@@ -3,9 +3,9 @@ ctest_empty_binary_directory
 
 empties the binary directory
 
-::
+.. code-block:: cmake
 
-  ctest_empty_binary_directory( directory )
+  ctest_empty_binary_directory(<directory>)
 
 Removes a binary directory.  This command will perform some checks
 prior to deleting the directory in an attempt to avoid malicious or

Help/command/ctest_memcheck.rst

@@ -3,7 +3,7 @@ ctest_memcheck
 
 Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`.
 
-::
+.. code-block:: cmake
 
   ctest_memcheck([BUILD <build-dir>] [APPEND]
                  [START <start-number>]

Help/command/ctest_read_custom_files.rst

@@ -3,9 +3,9 @@ ctest_read_custom_files
 
 read CTestCustom files.
 
-::
+.. code-block:: cmake
 
-  ctest_read_custom_files( directory ... )
+  ctest_read_custom_files(<directory>...)
 
 Read all the CTestCustom.ctest or CTestCustom.cmake files from the
 given directory.

Help/command/ctest_run_script.rst

@@ -3,7 +3,7 @@ ctest_run_script
 
 runs a :option:`ctest -S` script
 
-::
+.. code-block:: cmake
 
   ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
               script_file_name2 ... [RETURN_VALUE var])

Help/command/ctest_sleep.rst

@@ -3,13 +3,13 @@ ctest_sleep
 
 sleeps for some amount of time
 
-::
+.. code-block:: cmake
 
   ctest_sleep(<seconds>)
 
 Sleep for given number of seconds.
 
-::
+.. code-block:: cmake
 
   ctest_sleep(<time1> <duration> <time2>)
 

Help/command/ctest_start.rst

@@ -3,7 +3,7 @@ ctest_start
 
 Starts the testing for a given model
 
-::
+.. code-block:: cmake
 
   ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
 

Help/command/ctest_submit.rst

@@ -3,7 +3,7 @@ ctest_submit
 
 Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`.
 
-::
+.. code-block:: cmake
 
   ctest_submit([PARTS <part>...] [FILES <file>...]
                [SUBMIT_URL <url>]
@@ -96,7 +96,7 @@ Submit to CDash Upload API
 
 .. versionadded:: 3.2
 
-::
+.. code-block:: cmake
 
   ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
                [SUBMIT_URL <url>]

Help/command/ctest_test.rst

@@ -3,7 +3,7 @@ ctest_test
 
 Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
 
-::
+.. code-block:: cmake
 
   ctest_test([BUILD <build-dir>] [APPEND]
              [START <start-number>]
@@ -30,7 +30,7 @@ Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`.
              )
 
 ..
-   _note: If updating the argument list here, please also update the argument
+   NOTE If updating the argument list here, please also update the argument
    list documentation for :command:`ctest_memcheck` as well.
 
 Run tests in the project build tree and store results in

Help/command/ctest_update.rst

@@ -3,7 +3,7 @@ ctest_update
 
 Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`.
 
-::
+.. code-block:: cmake
 
   ctest_update([SOURCE <source-dir>]
                [RETURN_VALUE <result-var>]

Help/command/ctest_upload.rst

@@ -3,7 +3,7 @@ ctest_upload
 
 Upload files to a dashboard server as a :ref:`Dashboard Client`.
 
-::
+.. code-block:: cmake
 
   ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
 

Help/command/define_property.rst

@@ -73,3 +73,9 @@ project via corresponding options to the :command:`get_property` command.
   with ``CMAKE_`` or ``_CMAKE_``. The property name must contain at least one
   underscore. It is recommended that the property name have a prefix specific
   to the project.
+
+See Also
+^^^^^^^^
+
+* :command:`get_property`
+* :command:`set_property`

Help/command/enable_language.rst

@@ -9,24 +9,13 @@ Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc)
 
 Enables support for the named languages in CMake.  This is the same as
 the :command:`project` command but does not create any of the extra
-variables that are created by the project command.  Example languages
+variables that are created by the project command.
-are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``,
-``HIP``, ``ISPC``, and ``ASM``.
 
-.. versionadded:: 3.8
+.. include:: SUPPORTED_LANGUAGES.txt
-  Added ``CUDA`` support.
 
-.. versionadded:: 3.16
+By default ``C`` and ``CXX`` are enabled if no language options are given.
-  Added ``OBJC`` and ``OBJCXX`` support.
+Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages,
-
+to skip enabling any languages.
-.. versionadded:: 3.18
-  Added ``ISPC`` support.
-
-.. versionadded:: 3.21
-  Added ``HIP`` support.
-
-If enabling ``ASM``, enable it last so that CMake can check whether
-compilers for other languages like ``C`` work for assembly too.
 
 This command must be called in file scope, not in a function call.
 Furthermore, it must be called in the highest directory common to all

Help/command/exec_program.rst

@@ -8,7 +8,7 @@ exec_program
 Run an executable program during the processing of the CMakeList.txt
 file.
 
-::
+.. code-block:: cmake
 
   exec_program(Executable [directory in which to run]
                [ARGS <arguments to executable>]

Help/command/execute_process.rst

@@ -32,6 +32,11 @@ Commands are executed concurrently as a pipeline, with the standard
 output of each process piped to the standard input of the next.
 A single standard error pipe is used for all processes.
 
+``execute_process`` runs commands while CMake is configuring the project,
+prior to build system generation.  Use the :command:`add_custom_target` and
+:command:`add_custom_command` commands to create custom commands that run
+at build time.
+
 Options:
 
 ``COMMAND``
@@ -51,8 +56,8 @@ Options:
  (Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to
  redirect stdin, stdout, and stderr.)
 
- If a sequential execution of multiple commands is required, use multiple
+ For **sequential execution** of multiple commands use multiple
- :command:`execute_process` calls with a single ``COMMAND`` argument.
+ ``execute_process`` calls each with a single ``COMMAND`` argument.
 
 ``WORKING_DIRECTORY``
  The named directory will be set as the current working directory of
@@ -76,22 +81,46 @@ Options:
  given ``COMMAND`` arguments.  Each entry will be an integer return code
  from the corresponding child or a string describing an error condition.
 
+``INPUT_FILE <file>``
+ ``<file>`` is attached to the standard input pipe of the *first* ``COMMAND``
+ process.
+
+``OUTPUT_FILE <file>``
+ ``<file>`` is attached to the standard output pipe of the *last* ``COMMAND``
+ process.
+
+``ERROR_FILE <file>``
+ ``<file>`` is attached to the standard error pipe of *all* ``COMMAND``
+ processes.
+
+.. versionadded:: 3.3
+  If the same ``<file>`` is named for both ``OUTPUT_FILE`` and ``ERROR_FILE``
+  then it will be used for both standard output and standard error pipes.
+
+``OUTPUT_QUIET``, ``ERROR_QUIET``
+ The standard output on ``OUTPUT_VARIABLE`` or standard error on
+ ``ERROR_VARIABLE`` are not connected (no variable content).
+ The  ``*_FILE`` and ``ECHO_*_VARIABLE`` options are not affected.
+
 ``OUTPUT_VARIABLE``, ``ERROR_VARIABLE``
  The variable named will be set with the contents of the standard output
  and standard error pipes, respectively.  If the same variable is named
  for both pipes their output will be merged in the order produced.
 
-``INPUT_FILE, OUTPUT_FILE``, ``ERROR_FILE``
+``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE``
- The file named will be attached to the standard input of the first
+  .. versionadded:: 3.18
- process, standard output of the last process, or standard error of
- all processes, respectively.
 
- .. versionadded:: 3.3
+  The standard output or standard error will not be exclusively redirected to
-  If the same file is named for both output and error then it will be used
+  the specified variables.
-  for both.
 
-``OUTPUT_QUIET``, ``ERROR_QUIET``
+  The output will be duplicated into the specified variables and also onto
- The standard output or standard error results will be quietly ignored.
+  standard output or standard error analogous to the ``tee`` Unix command.
+
+.. note::
+  If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
+  same pipe the precedence is *not specified*.
+  If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will
+  be shared with the corresponding pipes of the CMake process itself.
 
 ``COMMAND_ECHO <where>``
  .. versionadded:: 3.15
@@ -126,17 +155,6 @@ Options:
      Accept ``UTF-8`` spelling for consistency with the
      `UTF-8 RFC <https://www.ietf.org/rfc/rfc3629>`_ naming convention.
 
-``ECHO_OUTPUT_VARIABLE``, ``ECHO_ERROR_VARIABLE``
-  .. versionadded:: 3.18
-
-  The standard output or standard error will not be exclusively redirected to
-  the configured variables.
-
-  The output will be duplicated, it will be sent into the configured variables
-  and also on standard output or standard error.
-
-  This is analogous to the ``tee`` Unix command.
-
 ``COMMAND_ERROR_IS_FATAL <ANY|LAST>``
   .. versionadded:: 3.19
 
@@ -151,15 +169,3 @@ Options:
     If the last command in the list of commands fails, the
     ``execute_process()`` command halts with an error.  Commands earlier in the
     list will not cause a fatal error.
-
-If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the
-same pipe the precedence is not specified.
-If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will
-be shared with the corresponding pipes of the CMake process itself.
-
-The :command:`execute_process` command is a newer more powerful version of
-:command:`exec_program`, but the old command has been kept for compatibility.
-Both commands run while CMake is processing the project prior to build
-system generation.  Use :command:`add_custom_target` and
-:command:`add_custom_command` to create custom commands that run at
-build time.

Help/command/export_library_dependencies.rst

@@ -15,7 +15,7 @@ The old-style library dependencies file does not take into account
 per-configuration names of libraries or the
 :prop_tgt:`LINK_INTERFACE_LIBRARIES` target property.
 
-::
+.. code-block:: cmake
 
   export_library_dependencies(<file> [APPEND])
 

Help/command/file.rst

@@ -526,10 +526,10 @@ from the input content to produce the output content.  The options are:
 
 ``OUTPUT <output-file>``
   Specify the output file name to generate.  Use generator expressions
-  such as ``$<CONFIG>`` to specify a configuration-specific output file
+  such as :genex:`$<CONFIG>` to specify a configuration-specific
-  name.  Multiple configurations may generate the same output file only
+  output file name.  Multiple configurations may generate the same output
-  if the generated content is identical.  Otherwise, the ``<output-file>``
+  file only if the generated content is identical.  Otherwise, the
-  must evaluate to an unique name for each configuration.
+  ``<output-file>`` must evaluate to an unique name for each configuration.
 
   .. versionchanged:: 3.10
     A relative path (after evaluating generator expressions) is treated
@@ -540,8 +540,9 @@ from the input content to produce the output content.  The options are:
   .. versionadded:: 3.19
 
   Specify which target to use when evaluating generator expressions that
-  require a target for evaluation (e.g. ``$<COMPILE_FEATURES:...>``,
+  require a target for evaluation (e.g.
-  ``$<TARGET_PROPERTY:prop>``).
+  :genex:`$<COMPILE_FEATURES:...>`,
+  :genex:`$<TARGET_PROPERTY:prop>`).
 
 ``NO_SOURCE_PERMISSIONS``
   .. versionadded:: 3.20
@@ -749,7 +750,8 @@ The options are:
 
   file(COPY_FILE <oldname> <newname>
        [RESULT <result>]
-       [ONLY_IF_DIFFERENT])
+       [ONLY_IF_DIFFERENT]
+       [INPUT_MAY_BE_RECENT])
 
 .. versionadded:: 3.21
 
@@ -768,6 +770,14 @@ The options are:
   contents are already the same as ``<oldname>`` (this avoids updating
   ``<newname>``'s timestamp).
 
+``INPUT_MAY_BE_RECENT``
+  .. versionadded:: 3.26
+
+  Tell CMake that the input file may have been recently created.  This is
+  meaningful only on Windows, where files may be inaccessible for a short
+  time after they are created.  With this option, if permission is denied,
+  CMake will retry reading the input a few times.
+
 This sub-command has some similarities to :command:`configure_file` with the
 ``COPYONLY`` option.  An important difference is that :command:`configure_file`
 creates a dependency on the source file, so CMake will be re-run if it changes.
@@ -1213,6 +1223,9 @@ directed to do so with the ``COMPRESSION`` option.  Valid values for
   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.
+
 .. note::
   With ``FORMAT`` set to ``raw`` only one file will be compressed with the
   compression type specified by ``COMPRESSION``.

Help/command/find_package.rst

@@ -370,7 +370,8 @@ enabled.
 1. .. versionadded:: 3.12
     Search paths specified in the :variable:`<PackageName>_ROOT` CMake
     variable and the :envvar:`<PackageName>_ROOT` environment variable,
-    where ``<PackageName>`` is the package to be found.
+    where ``<PackageName>`` is the package to be found
+    (the case-preserved first argument to ``find_package``).
     The package root variables are maintained as a stack so if
     called from within a find module, root paths from the parent's find
     module will also be searched after paths for the current package.

Help/command/foreach.rst

@@ -74,8 +74,7 @@ processed:
       message(STATUS "X=${X}")
   endforeach()
 
-yields
+yields::
-::
 
   -- X=0
   -- X=1
@@ -119,8 +118,7 @@ iteration variables as follows:
       message(STATUS "en=${en}, ba=${ba}")
   endforeach()
 
-yields
+yields::
-::
 
   -- num_0=one, num_1=satu
   -- num_0=two, num_1=dua

Help/command/function.rst

@@ -77,5 +77,6 @@ extra argument.
 See Also
 ^^^^^^^^
 
+* :command:`cmake_parse_arguments`
 * :command:`endfunction`
 * :command:`return`

Help/command/get_cmake_property.rst

@@ -12,9 +12,12 @@ the ``<property>`` is stored in the variable ``<var>``.
 If the property is not found, ``<var>`` will be set to ``NOTFOUND``.
 See the :manual:`cmake-properties(7)` manual for available properties.
 
-See also the :command:`get_property` command ``GLOBAL`` option.
-
 In addition to global properties, this command (for historical reasons)
 also supports the :prop_dir:`VARIABLES` and :prop_dir:`MACROS` directory
 properties.  It also supports a special ``COMPONENTS`` global property that
 lists the components given to the :command:`install` command.
+
+See Also
+^^^^^^^^
+
+* the :command:`get_property` command ``GLOBAL`` option

Help/command/get_directory_property.rst

@@ -33,4 +33,9 @@ the search will chain to a parent scope as described for the
 Get a variable definition from a directory.  This form is useful to
 get a variable definition from another directory.
 
-See also the more general :command:`get_property` command.
+
+See Also
+^^^^^^^^
+
+* :command:`define_property`
+* the more general :command:`get_property` command

Help/command/get_filename_component.rst

@@ -69,3 +69,8 @@ left as a full path.  If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then
 any command-line arguments present in the ``<FileName>`` string are split
 from the program name and stored in ``<arg_var>``.  This is used to
 separate a program name from its arguments in a command line string.
+
+See Also
+^^^^^^^^
+
+* :command:`cmake_path`

Help/command/get_property.rst

@@ -99,3 +99,9 @@ documentation is requested for a property that has not been defined
 
   The :prop_sf:`GENERATED` source file property may be globally visible.
   See its documentation for details.
+
+See Also
+^^^^^^^^
+
+* :command:`define_property`
+* :command:`set_property`

Help/command/get_source_file_property.rst

@@ -39,9 +39,14 @@ Use :command:`set_source_files_properties` to set property values.  Source
 file properties usually control how the file is built. One property that is
 always there is :prop_sf:`LOCATION`.
 
-See also the more general :command:`get_property` command.
-
 .. note::
 
   The :prop_sf:`GENERATED` source file property may be globally visible.
   See its documentation for details.
+
+See Also
+^^^^^^^^
+
+* :command:`define_property`
+* the more general :command:`get_property` command
+* :command:`set_source_files_properties`

Help/command/get_target_property.rst

@@ -22,6 +22,10 @@ query the target instead.  This command can get properties for any
 target so far created.  The targets do not need to be in the current
 ``CMakeLists.txt`` file.
 
-See also the more general :command:`get_property` command.
+See Also
+^^^^^^^^
 
-See :ref:`Target Properties` for the list of properties known to CMake.
+* :command:`define_property`
+* the more general :command:`get_property` command
+* :command:`set_target_properties`
+* :ref:`Target Properties` for the list of properties known to CMake

Help/command/get_test_property.rst

@@ -19,4 +19,8 @@ an empty string.
 For a list of standard properties you can type
 :option:`cmake --help-property-list`.
 
-See also the more general :command:`get_property` command.
+See Also
+^^^^^^^^
+
+* :command:`define_property`
+* the more general :command:`get_property` command

Help/command/if.rst

@@ -165,6 +165,8 @@ File Operations
  Resolves symbolic links, i.e. if the named file or directory is a
  symbolic link, returns true if the target of the symbolic link exists.
 
+ False if the given path is an empty string.
+
 ``if(file1 IS_NEWER_THAN file2)``
  True if ``file1`` is newer than ``file2`` or if one of the two files doesn't
  exist.  Behavior is well-defined only for full paths.  If the file
@@ -173,10 +175,12 @@ File Operations
  of a tie.  This includes the case of passing the same file name for
  both file1 and file2.
 
-``if(IS_DIRECTORY path-to-directory)``
+``if(IS_DIRECTORY path)``
- True if the given name is a directory.  Behavior is well-defined only
+ True if ``path`` is a directory.  Behavior is well-defined only
  for full paths.
 
+ False if the given path is an empty string.
+
 ``if(IS_SYMLINK file-name)``
  True if the given name is a symbolic link.  Behavior is well-defined
  only for full paths.

Help/command/include_directories.rst

@@ -29,13 +29,16 @@ Signalling this setting might achieve effects such as the compiler
 skipping warnings, or these fixed-install system files not being
 considered in dependency calculations - see compiler docs.
 
-Arguments to ``include_directories`` may use "generator expressions" with
+.. |command_name| replace:: ``include_directories``
-the syntax "$<...>".  See the :manual:`cmake-generator-expressions(7)`
+.. include:: GENEX_NOTE.txt
-manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
-manual for more on defining buildsystem properties.
 
 .. note::
 
   Prefer the :command:`target_include_directories` command to add include
   directories to individual targets and optionally propagate/export them
   to dependents.
+
+See Also
+^^^^^^^^
+
+* :command:`target_include_directories`

Help/command/include_guard.rst

@@ -13,7 +13,7 @@ Sets up an include guard for the current CMake file (see the
 :variable:`CMAKE_CURRENT_LIST_FILE` variable documentation).
 
 CMake will end its processing of the current file at the location of the
-:command:`include_guard` command if the current file has already been
+``include_guard`` command if the current file has already been
 processed for the applicable scope (see below). This provides functionality
 similar to the include guards commonly used in source headers or to the
 ``#pragma once`` directive. If the current file has been processed previously

Help/command/install.rst

@@ -32,7 +32,7 @@ are executed in order during installation.
 
 .. versionchanged:: 3.22
   The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the
-  default copying behavior of :command:`install()`.
+  default copying behavior of ``install()``.
 
 There are multiple signatures for this command.  Some of them define
 installation options for files and targets.  Options common to
@@ -379,7 +379,7 @@ top level:
   :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the
   ``<targets>`` when exported by the `install(EXPORT)`_ command. If a
   relative path is specified, it is treated as relative to the
-  ``$<INSTALL_PREFIX>``.
+  :genex:`$<INSTALL_PREFIX>`.
 
 ``RUNTIME_DEPENDENCY_SET``
   .. versionadded:: 3.21

Help/command/install_files.rst

@@ -11,7 +11,7 @@ directly replaced by the ``FILES`` form of the :command:`install`
 command.  The regexp form can be expressed more clearly using the ``GLOB``
 form of the :command:`file` command.
 
-::
+.. code-block:: cmake
 
   install_files(<dir> extension file file ...)
 
@@ -23,14 +23,14 @@ removed first.  This is useful for providing lists of source files
 such as foo.cxx when you want the corresponding foo.h to be installed.
 A typical extension is ``.h``.
 
-::
+.. code-block:: cmake
 
   install_files(<dir> regexp)
 
 Any files in the current source directory that match the regular
 expression will be installed.
 
-::
+.. code-block:: cmake
 
   install_files(<dir> FILES file file ...)
 

Help/command/install_programs.rst

@@ -11,7 +11,7 @@ directly replaced by the ``PROGRAMS`` form of the :command:`install`
 command.  The regexp form can be expressed more clearly using the ``GLOB``
 form of the :command:`file` command.
 
-::
+.. code-block:: cmake
 
   install_programs(<dir> file1 file2 [file3 ...])
   install_programs(<dir> FILES file1 [file2 ...])
@@ -20,7 +20,7 @@ Create rules to install the listed programs into the given directory.
 Use the ``FILES`` argument to guarantee that the file list version of the
 command will be used even when there is only one argument.
 
-::
+.. code-block:: cmake
 
   install_programs(<dir> regexp)
 

Help/command/install_targets.rst

@@ -8,7 +8,7 @@ install_targets
 This command has been superseded by the :command:`install` command.  It is
 provided for compatibility with older CMake code.
 
-::
+.. code-block:: cmake
 
   install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
 

Help/command/link_directories.rst

@@ -53,3 +53,9 @@ The command will apply only to targets created after it is called.
   where possible by using the :command:`target_link_directories` command
   rather than ``link_directories()``.  The target-specific command can also
   control how the search directories propagate to other dependent targets.
+
+See Also
+^^^^^^^^
+
+* :command:`target_link_directories`
+* :command:`target_link_libraries`

Help/command/load_command.rst

@@ -5,7 +5,7 @@ Disallowed since version 3.0.  See CMake Policy :policy:`CMP0031`.
 
 Load a command into a running CMake.
 
-::
+.. code-block:: cmake
 
   load_command(COMMAND_NAME <loc1> [loc2 ...])
 
@@ -15,7 +15,7 @@ added to the set of available CMake commands.  Usually,
 :command:`try_compile` is used before this command to compile the
 module.  If the command is successfully loaded a variable named
 
-::
+.. code-block:: cmake
 
   CMAKE_LOADED_COMMAND_<COMMAND_NAME>
 

Help/command/macro.rst

@@ -149,3 +149,9 @@ existing variable instead of the arguments. For example:
 Will loop over ``a;b;c`` and not over ``x;y;z`` as one might have expected.
 If you want true CMake variables and/or better CMake scope control you
 should look at the function command.
+
+See Also
+^^^^^^^^
+
+* :command:`cmake_parse_arguments`
+* :command:`endmacro`

Help/command/make_directory.rst

@@ -5,7 +5,7 @@ make_directory
 
   Use the :command:`file(MAKE_DIRECTORY)` command instead.
 
-::
+.. code-block:: cmake
 
   make_directory(directory)
 

Help/command/message.rst

@@ -14,6 +14,8 @@ Synopsis
   `Reporting checks`_
     message(<checkState> "message text" ...)
 
+  `Configure Log`_
+    message(CONFIGURE_LOG <text>...)
 
 General messages
 ^^^^^^^^^^^^^^^^
@@ -193,3 +195,56 @@ Output from the above would appear something like the following::
   --   Finding partB
   --   Finding partB - not found
   -- Finding my things - missing components: B
+
+Configure Log
+^^^^^^^^^^^^^
+
+.. versionadded:: 3.26
+
+.. code-block:: cmake
+
+  message(CONFIGURE_LOG <text>...)
+
+Record a :ref:`configure-log message event <message configure-log event>`
+with the specified ``<text>``.  By convention, if the text contains more
+than one line, the first line should be a summary of the event.
+
+This mode is intended to record the details of a system inspection check
+or other one-time operation guarded by a cache entry, but that is not
+performed using :command:`try_compile` or :command:`try_run`, which
+automatically log their details.  Projects should avoid calling it every
+time CMake runs.  For example:
+
+.. code-block:: cmake
+
+  if (NOT DEFINED MY_CHECK_RESULT)
+    # Print check summary in configure output.
+    message(CHECK_START "My Check")
+
+    # ... perform system inspection, e.g., with execute_process ...
+
+    # Cache the result so we do not run the check again.
+    set(MY_CHECK_RESULT "${MY_CHECK_RESULT}" CACHE INTERNAL "My Check")
+
+    # Record the check details in the cmake-configure-log.
+    message(CONFIGURE_LOG
+      "My Check Result: ${MY_CHECK_RESULT}\n"
+      "${details}"
+    )
+
+    # Print check result in configure output.
+    if(MY_CHECK_RESULT)
+      message(CHECK_PASS "passed")
+    else()
+      message(CHECK_FAIL "failed")
+    endif()
+  endif()
+
+If no project is currently being configured, such as in
+:ref:`cmake -P <Script Processing Mode>` script mode,
+this command does nothing.
+
+See Also
+^^^^^^^^
+
+* :command:`cmake_language(GET_MESSAGE_LOG_LEVEL)`

Help/command/output_required_files.rst

@@ -9,7 +9,7 @@ This command exists only because ancient CMake versions provided it.
 CMake handles preprocessor dependency scanning automatically using a
 more advanced scanner.
 
-::
+.. code-block:: cmake
 
   output_required_files(srcfile outputfile)
 

Help/command/project.rst

@@ -102,23 +102,9 @@ The options are:
   Can also be specified without ``LANGUAGES`` keyword per the first, short signature.
 
   Selects which programming languages are needed to build the project.
-  Supported languages include ``C``, ``CXX`` (i.e.  C++), ``CUDA``,
-  ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``.
-  By default ``C`` and ``CXX`` are enabled if no language options are given.
-  Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages,
-  to skip enabling any languages.
 
-  .. versionadded:: 3.8
+.. include:: SUPPORTED_LANGUAGES.txt
-    Added ``CUDA`` support.
 
-  .. versionadded:: 3.16
-    Added ``OBJC`` and ``OBJCXX`` support.
-
-  .. versionadded:: 3.18
-    Added ``ISPC`` support.
-
-  If enabling ``ASM``, list it last so that CMake can check whether
-  compilers for other languages like ``C`` work for assembly too.
 
 The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL``
 options are intended for use as default values in package metadata and documentation.
@@ -188,5 +174,6 @@ call exists, CMake will issue a warning and pretend there is a
   Call the ``project()`` command near the top of the top-level
   ``CMakeLists.txt``, but *after* calling :command:`cmake_minimum_required`.
   It is important to establish version and policy settings before invoking
-  other commands whose behavior they may affect.
+  other commands whose behavior they may affect and for this reason the
+  ``project()`` command will issue a warning if this order is not kept.
   See also policy :policy:`CMP0000`.

Help/command/remove.rst

@@ -5,7 +5,7 @@ remove
 
   Use the :command:`list(REMOVE_ITEM)` command instead.
 
-::
+.. code-block:: cmake
 
   remove(VAR VALUE VALUE ...)
 

Help/command/return.rst

@@ -30,7 +30,7 @@ command.  All arguments are ignored unless that policy is set to ``NEW``.
   with the :command:`block` command, as described below.
 
   The ``PROPAGATE`` option can be very useful in conjunction with the
-  :command:`block` command.  A :command:`return` will propagate the
+  :command:`block` command.  A ``return`` will propagate the
   specified variables through any enclosing block scopes created by the
   :command:`block` commands.  Inside a function, this ensures the variables
   are propagated to the function's caller, regardless of any blocks within
@@ -89,3 +89,4 @@ See Also
 ^^^^^^^^
 
 * :command:`block`
+* :command:`function`

Help/command/set.rst

@@ -111,3 +111,8 @@ environment variable.
 
 Arguments after ``<value>`` are ignored. If extra arguments are found,
 then an author warning is issued.
+
+See Also
+^^^^^^^^
+
+* :command:`unset`

Help/command/set_directory_properties.rst

@@ -13,3 +13,10 @@ See also the :command:`set_property(DIRECTORY)` command.
 
 See :ref:`Directory Properties` for the list of properties known to CMake
 and their individual documentation for the behavior of each property.
+
+See Also
+^^^^^^^^
+
+* :command:`define_property`
+* :command:`get_directory_property`
+* the more general :command:`set_property` command

Help/command/set_property.rst

@@ -107,10 +107,15 @@ finding the initial value to append to.  If the property is not already
 directly set in the nominated scope, the command will behave as though
 ``APPEND`` or ``APPEND_STRING`` had not been given.
 
-See the :manual:`cmake-properties(7)` manual for a list of properties
-in each scope.
-
 .. note::
 
   The :prop_sf:`GENERATED` source file property may be globally visible.
   See its documentation for details.
+
+See Also
+^^^^^^^^
+
+* :command:`define_property`
+* :command:`get_property`
+* The :manual:`cmake-properties(7)` manual for a list of properties
+  in each scope.

Help/command/set_source_files_properties.rst

@@ -34,10 +34,15 @@ list.
 Use :command:`get_source_file_property` to get property values.
 See also the :command:`set_property(SOURCE)` command.
 
-See :ref:`Source File Properties` for the list of properties known
-to CMake.
-
 .. note::
 
   The :prop_sf:`GENERATED` source file property may be globally visible.
   See its documentation for details.
+
+See Also
+^^^^^^^^
+
+* :command:`define_property`
+* :command:`get_source_file_property`
+* :ref:`Source File Properties` for the list of properties known
+  to CMake

Help/command/set_target_properties.rst

@@ -15,6 +15,10 @@ set next.  You can use any prop value pair you want and extract it
 later with the :command:`get_property` or :command:`get_target_property`
 command.
 
-See also the :command:`set_property(TARGET)` command.
+See Also
+^^^^^^^^
 
-See :ref:`Target Properties` for the list of properties known to CMake.
+* :command:`define_property`
+* :command:`get_target_property`
+* the more general :command:`set_property` command
+* :ref:`Target Properties` for the list of properties known to CMake

Help/command/set_tests_properties.rst

@@ -14,6 +14,10 @@ Test property values may be specified using
 :manual:`generator expressions <cmake-generator-expressions(7)>`
 for tests created by the :command:`add_test(NAME)` signature.
 
-See also the :command:`set_property(TEST)` command.
+See Also
+^^^^^^^^
 
-See :ref:`Test Properties` for the list of properties known to CMake.
+* :command:`add_test`
+* :command:`define_property`
+* the more general :command:`set_property` command
+* :ref:`Target Properties` for the list of properties known to CMake

Help/command/string.rst

@@ -45,16 +45,16 @@ Synopsis
 
   `JSON`_
     string(JSON <out-var> [ERROR_VARIABLE <error-var>]
-           {`GET`_ | `TYPE`_ | :ref:`LENGTH <JSONLENGTH>` | `REMOVE`_}
+           {:ref:`GET <JSON_GET>` | :ref:`TYPE <JSON_TYPE>` | :ref:`LENGTH <JSON_LENGTH>` | :ref:`REMOVE <JSON_REMOVE>`}
            <json-string> <member|index> [<member|index> ...])
     string(JSON <out-var> [ERROR_VARIABLE <error-var>]
-           `MEMBER`_ <json-string>
+           :ref:`MEMBER <JSON_MEMBER>` <json-string>
            [<member|index> ...] <index>)
     string(JSON <out-var> [ERROR_VARIABLE <error-var>]
-           `SET`_ <json-string>
+           :ref:`SET <JSON_SET>` <json-string>
            <member|index> [<member|index> ...] <value>)
     string(JSON <out-var> [ERROR_VARIABLE <error-var>]
-           `EQUAL`_ <json-string1> <json-string2>)
+           :ref:`EQUAL <JSON_EQUAL>` <json-string1> <json-string2>)
 
 Search and Replace
 ^^^^^^^^^^^^^^^^^^
@@ -522,6 +522,17 @@ specifiers:
 ``%Y``
   The current year.
 
+``%z``
+  .. versionadded:: 3.26
+
+  The offset of the time zone from UTC, in hours and minutes,
+  with format ``+hhmm`` or ``-hhmm``.
+
+``%Z``
+  .. versionadded:: 3.26
+
+  The time zone name.
+
 Unknown format specifiers will be ignored and copied to the output
 as-is.
 
@@ -575,7 +586,7 @@ Functionality for querying a JSON string.
   option is not present, a fatal error message is generated.  If no error
   occurs, the ``<error-variable>`` will be set to ``NOTFOUND``.
 
-.. _GET:
+.. _JSON_GET:
 .. code-block:: cmake
 
   string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
@@ -588,7 +599,7 @@ Boolean elements will be returned as ``ON`` or ``OFF``.
 Null elements will be returned as an empty string.
 Number and string types will be returned as strings.
 
-.. _TYPE:
+.. _JSON_TYPE:
 .. code-block:: cmake
 
   string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
@@ -599,7 +610,7 @@ given by the list of ``<member|index>`` arguments. The ``<out-var>``
 will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``,
 ``ARRAY``, or ``OBJECT``.
 
-.. _MEMBER:
+.. _JSON_MEMBER:
 .. code-block:: cmake
 
   string(JSON <out-var> [ERROR_VARIABLE <error-var>]
@@ -610,7 +621,7 @@ Get the name of the ``<index>``-th member in ``<json-string>`` at the location
 given by the list of ``<member|index>`` arguments.
 Requires an element of object type.
 
-.. _JSONLENGTH:
+.. _JSON_LENGTH:
 .. code-block:: cmake
 
   string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
@@ -620,7 +631,7 @@ Get the length of an element in ``<json-string>`` at the location
 given by the list of ``<member|index>`` arguments.
 Requires an element of array or object type.
 
-.. _REMOVE:
+.. _JSON_REMOVE:
 .. code-block:: cmake
 
   string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
@@ -630,7 +641,7 @@ Remove an element from ``<json-string>`` at the location
 given by the list of ``<member|index>`` arguments. The JSON string
 without the removed element will be stored in ``<out-var>``.
 
-.. _SET:
+.. _JSON_SET:
 .. code-block:: cmake
 
   string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
@@ -640,7 +651,7 @@ Set an element in ``<json-string>`` at the location
 given by the list of ``<member|index>`` arguments to ``<value>``.
 The contents of ``<value>`` should be valid JSON.
 
-.. _EQUAL:
+.. _JSON_EQUAL:
 .. code-block:: cmake
 
   string(JSON <out-var> [ERROR_VARIABLE <error-var>]

Help/command/subdir_depends.rst

@@ -5,7 +5,7 @@ Disallowed since version 3.0.  See CMake Policy :policy:`CMP0029`.
 
 Does nothing.
 
-::
+.. code-block:: cmake
 
   subdir_depends(subdir dep1 dep2 ...)
 

Help/command/subdirs.rst

@@ -7,7 +7,7 @@ subdirs
 
 Add a list of subdirectories to the build.
 
-::
+.. code-block:: cmake
 
   subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
           [PREORDER] )

Help/command/target_compile_definitions.rst

@@ -25,10 +25,8 @@ same ``<target>`` append items in the order called.
 .. versionadded:: 3.11
   Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
 
-Arguments to ``target_compile_definitions`` may use "generator expressions"
+.. |command_name| replace:: ``target_compile_definitions``
-with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
+.. include:: GENEX_NOTE.txt
-manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
-manual for more on defining buildsystem properties.
 
 Any leading ``-D`` on an item will be removed.  Empty items are ignored.
 For example, the following are all equivalent:
@@ -48,3 +46,16 @@ Definitions may optionally have values:
 
 Note that many compilers treat ``-DFOO`` as equivalent to ``-DFOO=1``, but
 other tools may not recognize this in all circumstances (e.g. IntelliSense).
+
+See Also
+^^^^^^^^
+
+* :command:`add_compile_definitions`
+* :command:`target_compile_features`
+* :command:`target_compile_options`
+* :command:`target_include_directories`
+* :command:`target_link_libraries`
+* :command:`target_link_directories`
+* :command:`target_link_options`
+* :command:`target_precompile_headers`
+* :command:`target_sources`

Help/command/target_compile_features.rst

@@ -30,8 +30,20 @@ The named ``<target>`` must have been created by a command such as
 :command:`add_executable` or :command:`add_library` and must not be an
 :ref:`ALIAS target <Alias Targets>`.
 
-Arguments to ``target_compile_features`` may use "generator expressions"
+.. |command_name| replace:: ``target_compile_features``
-with the syntax ``$<...>``.
+.. |more_see_also| replace:: See the :manual:`cmake-compile-features(7)`
-See the :manual:`cmake-generator-expressions(7)` manual for available
+   manual for information on compile features and a list of supported compilers.
-expressions.  See the :manual:`cmake-compile-features(7)` manual for
+.. include:: GENEX_NOTE.txt
-information on compile features and a list of supported compilers.
+   :start-line: 1
+
+See Also
+^^^^^^^^
+
+* :command:`target_compile_definitions`
+* :command:`target_compile_options`
+* :command:`target_include_directories`
+* :command:`target_link_libraries`
+* :command:`target_link_directories`
+* :command:`target_link_options`
+* :command:`target_precompile_headers`
+* :command:`target_sources`

Help/command/target_compile_options.rst

@@ -19,7 +19,8 @@ Arguments
 ^^^^^^^^^
 
 If ``BEFORE`` is specified, the content will be prepended to the property
-instead of being appended.
+instead of being appended.  See policy :policy:`CMP0101` which affects
+whether ``BEFORE`` will be ignored in certain cases.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
 specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
@@ -32,21 +33,26 @@ The following arguments specify compile options.  Repeated calls for the same
 .. versionadded:: 3.11
   Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
 
-Arguments to ``target_compile_options`` may use "generator expressions"
+.. |command_name| replace:: ``target_compile_options``
-with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
+.. include:: GENEX_NOTE.txt
-manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
-manual for more on defining buildsystem properties.
 
 .. include:: OPTIONS_SHELL.txt
 
 See Also
 ^^^^^^^^
 
-This command can be used to add any options. However, for adding
+* This command can be used to add any options. However, for adding
   preprocessor definitions and include directories it is recommended
   to use the more specific commands :command:`target_compile_definitions`
   and :command:`target_include_directories`.
 
-For directory-wide settings, there is the command :command:`add_compile_options`.
+* For directory-wide settings, there is the command :command:`add_compile_options`.
 
-For file-specific settings, there is the source file property :prop_sf:`COMPILE_OPTIONS`.
+* For file-specific settings, there is the source file property :prop_sf:`COMPILE_OPTIONS`.
+
+* :command:`target_compile_features`
+* :command:`target_link_libraries`
+* :command:`target_link_directories`
+* :command:`target_link_options`
+* :command:`target_precompile_headers`
+* :command:`target_sources`

Help/command/target_include_directories.rst

@@ -40,10 +40,8 @@ If ``SYSTEM`` is used together with ``PUBLIC`` or ``INTERFACE``, the
 :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be
 populated with the specified directories.
 
-Arguments to ``target_include_directories`` may use "generator expressions"
+.. |command_name| replace:: ``target_include_directories``
-with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
+.. include:: GENEX_NOTE.txt
-manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
-manual for more on defining buildsystem properties.
 
 Specified include directories may be absolute paths or relative paths.
 A relative path will be interpreted as relative to the current source
@@ -74,3 +72,16 @@ Creating Relocatable Packages
 
 .. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
 .. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
+
+See Also
+^^^^^^^^
+
+* :command:`include_directories`
+* :command:`target_compile_definitions`
+* :command:`target_compile_features`
+* :command:`target_compile_options`
+* :command:`target_link_libraries`
+* :command:`target_link_directories`
+* :command:`target_link_options`
+* :command:`target_precompile_headers`
+* :command:`target_sources`

Help/command/target_link_directories.rst

@@ -34,10 +34,8 @@ calls for the same ``<target>`` append items in the order called.
 If ``BEFORE`` is specified, the content will be prepended to the relevant
 property instead of being appended.
 
-Arguments to ``target_link_directories`` may use "generator expressions"
+.. |command_name| replace:: ``target_link_directories``
-with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
+.. include:: GENEX_NOTE.txt
-manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
-manual for more on defining buildsystem properties.
 
 .. note::
 
@@ -56,3 +54,16 @@ manual for more on defining buildsystem properties.
     that expect to be found via ``RPATH`` mechanisms, but some linkers
     are not able to fully decode those paths (e.g. due to the presence
     of things like ``$ORIGIN``).
+
+See Also
+^^^^^^^^
+
+* :command:`link_directories`
+* :command:`target_compile_definitions`
+* :command:`target_compile_features`
+* :command:`target_compile_options`
+* :command:`target_include_directories`
+* :command:`target_link_libraries`
+* :command:`target_link_options`
+* :command:`target_precompile_headers`
+* :command:`target_sources`

Help/command/target_link_libraries.rst

@@ -293,8 +293,8 @@ will be included in the link too.
 
 .. _`Linking Object Libraries via $<TARGET_OBJECTS>`:
 
-Linking Object Libraries via $<TARGET_OBJECTS>
+Linking Object Libraries via ``$<TARGET_OBJECTS>``
-""""""""""""""""""""""""""""""""""""""""""""""
+""""""""""""""""""""""""""""""""""""""""""""""""""
 
 .. versionadded:: 3.21
 
@@ -407,3 +407,15 @@ Creating Relocatable Packages
 
 .. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES`
 .. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt
+
+See Also
+^^^^^^^^
+
+* :command:`target_compile_definitions`
+* :command:`target_compile_features`
+* :command:`target_compile_options`
+* :command:`target_include_directories`
+* :command:`target_link_directories`
+* :command:`target_link_options`
+* :command:`target_precompile_headers`
+* :command:`target_sources`

Help/command/target_link_options.rst

@@ -42,13 +42,23 @@ The following arguments specify link options.  Repeated calls for the same
 .. note::
   :ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.
 
-Arguments to ``target_link_options`` may use "generator expressions"
+.. |command_name| replace:: ``target_link_options``
-with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
+.. include:: GENEX_NOTE.txt
-manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
-manual for more on defining buildsystem properties.
 
 .. include:: DEVICE_LINK_OPTIONS.txt
 
 .. include:: OPTIONS_SHELL.txt
 
 .. include:: LINK_OPTIONS_LINKER.txt
+
+See Also
+^^^^^^^^
+
+* :command:`target_compile_definitions`
+* :command:`target_compile_features`
+* :command:`target_compile_options`
+* :command:`target_include_directories`
+* :command:`target_link_libraries`
+* :command:`target_link_directories`
+* :command:`target_precompile_headers`
+* :command:`target_sources`

Help/command/target_precompile_headers.rst

@@ -70,17 +70,16 @@ included by absolute path.  For example:
       <unordered_map>
   )
 
-Arguments to ``target_precompile_headers()`` may use "generator expressions"
+.. |command_name| replace:: ``target_compile_features``
-with the syntax ``$<...>``.
+.. |more_see_also| replace:: The :genex:`$<COMPILE_LANGUAGE:...>` generator
-See the :manual:`cmake-generator-expressions(7)` manual for available
+   expression is particularly useful for specifying a language-specific header
-expressions.
+   to precompile for only one language (e.g. ``CXX`` and not ``C``).  In this
-The :genex:`$<COMPILE_LANGUAGE:...>` generator expression is particularly
+   case, header file names that are not explicitly in double quotes or angle
-useful for specifying a language-specific header to precompile for
+   brackets must be specified by absolute path.  Also, when specifying angle
-only one language (e.g. ``CXX`` and not ``C``).  In this case, header
+   brackets inside a generator expression, be sure to encode the closing
-file names that are not explicitly in double quotes or angle brackets
+   ``>`` as :genex:`$<ANGLE-R>`.  For example:
-must be specified by absolute path.  Also, when specifying angle brackets
+.. include:: GENEX_NOTE.txt
-inside a generator expression, be sure to encode the closing ``>`` as
+   :start-line: 1
-``$<ANGLE-R>``.  For example:
 
 .. code-block:: cmake
 
@@ -118,8 +117,17 @@ the ``REUSE_FROM`` form is used.
 See Also
 ^^^^^^^^
 
-To disable precompile headers for specific targets, see the
+* To disable precompile headers for specific targets, see the
   :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` target property.
 
-To prevent precompile headers from being used when compiling a specific
+* To prevent precompile headers from being used when compiling a specific
   source file, see the :prop_sf:`SKIP_PRECOMPILE_HEADERS` source file property.
+
+* :command:`target_compile_definitions`
+* :command:`target_compile_features`
+* :command:`target_compile_options`
+* :command:`target_include_directories`
+* :command:`target_link_libraries`
+* :command:`target_link_directories`
+* :command:`target_link_options`
+* :command:`target_sources`

Help/command/target_sources.rst

@@ -202,3 +202,17 @@ Target properties related to include directories are also modified by
   of the file set is ``INTERFACE`` or ``PUBLIC``, all of the ``BASE_DIRS`` of
   the file set are wrapped in :genex:`$<BUILD_INTERFACE>` and appended to this
   property.
+
+See Also
+^^^^^^^^
+
+* :command:`add_executable`
+* :command:`add_library`
+* :command:`target_compile_definitions`
+* :command:`target_compile_features`
+* :command:`target_compile_options`
+* :command:`target_include_directories`
+* :command:`target_link_libraries`
+* :command:`target_link_directories`
+* :command:`target_link_options`
+* :command:`target_precompile_headers`

Help/command/try_compile.rst

@@ -14,18 +14,20 @@ Try Compiling Whole Projects
 
 .. code-block:: cmake
 
-  try_compile(<resultVar> PROJECT <projectName>
+  try_compile(<compileResultVar> PROJECT <projectName>
               SOURCE_DIR <srcdir>
               [BINARY_DIR <bindir>]
               [TARGET <targetName>]
+              [LOG_DESCRIPTION <text>]
               [NO_CACHE]
+              [NO_LOG]
               [CMAKE_FLAGS <flags>...]
               [OUTPUT_VARIABLE <var>])
 
 .. versionadded:: 3.25
 
-Try building a project.  The success or failure of the ``try_compile``,
+Try building a project.  Build success returns ``TRUE`` and build failure
-i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``.
+returns ``FALSE`` in ``<compileResultVar>``.
 
 In this form, ``<srcdir>`` should contain a complete CMake project with a
 ``CMakeLists.txt`` file and all sources.  The ``<bindir>`` and ``<srcdir>``
@@ -40,14 +42,18 @@ below for the meaning of other options.
   Previously this was only done by the
   :ref:`source file <Try Compiling Source Files>` signature.
 
-This command also supports an alternate signature
+.. versionadded:: 3.26
-which was present in older versions of CMake:
+  This command records a
+  :ref:`configure-log try_compile event <try_compile configure-log event>`
+  if the ``NO_LOG`` option is not specified.
+
+This command supports an alternate signature for CMake older than 3.25.
+The signature above is recommended for clarity.
 
 .. code-block:: cmake
 
-  try_compile(<resultVar> <bindir> <srcdir>
+  try_compile(<compileResultVar> <bindir> <srcdir>
               <projectName> [<targetName>]
-              [NO_CACHE]
               [CMAKE_FLAGS <flags>...]
               [OUTPUT_VARIABLE <var>])
 
@@ -58,12 +64,14 @@ Try Compiling Source Files
 
 .. code-block:: cmake
 
-  try_compile(<resultVar>
+  try_compile(<compileResultVar>
               <SOURCES <srcfile...>                 |
                SOURCE_FROM_CONTENT <name> <content> |
                SOURCE_FROM_VAR <name> <var>         |
                SOURCE_FROM_FILE <name> <path>       >...
+              [LOG_DESCRIPTION <text>]
               [NO_CACHE]
+              [NO_LOG]
               [CMAKE_FLAGS <flags>...]
               [COMPILE_DEFINITIONS <defs>...]
               [LINK_OPTIONS <options>...]
@@ -79,8 +87,8 @@ Try Compiling Source Files
 
 Try building an executable or static library from one or more source files
 (which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE`
-variable).  The success or failure of the ``try_compile``, i.e. ``TRUE`` or
+variable). Build success returns ``TRUE`` and build failure returns ``FALSE``
-``FALSE`` respectively, is returned in ``<resultVar>``.
+in ``<compileResultVar>``.
 
 In this form, one or more source files must be provided. Additionally, one of
 ``SOURCES`` and/or ``SOURCE_FROM_*`` must precede other keywords.
@@ -105,17 +113,16 @@ contain something like the following:
 CMake automatically generates, for each ``try_compile`` operation, a
 unique directory under ``${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch``
 with an unspecified name.  These directories are cleaned automatically unless
-:option:`--debug-trycompile <cmake --debug-trycompile>` is passed to ``cmake``.
+:option:`--debug-trycompile <cmake --debug-trycompile>` is passed to :program:`cmake`.
 Such directories from previous runs are also unconditionally cleaned at the
-beginning of any ``cmake`` execution.
+beginning of any :program:`cmake` execution.
 
-This command also supports an alternate signature
+This command supports an alternate signature for CMake older than 3.25.
-which was present in older versions of CMake:
+The signature above is recommended for clarity.
 
 .. code-block:: cmake
 
-  try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
+  try_compile(<compileResultVar> <bindir> <srcfile|SOURCES srcfile...>
-              [NO_CACHE]
               [CMAKE_FLAGS <flags>...]
               [COMPILE_DEFINITIONS <defs>...]
               [LINK_OPTIONS <options>...]
@@ -130,7 +137,7 @@ which was present in older versions of CMake:
 In this version, ``try_compile`` will use ``<bindir>/CMakeFiles/CMakeTmp`` for
 its operation, and all such files will be cleaned automatically.
 For debugging, :option:`--debug-trycompile <cmake --debug-trycompile>` can be
-passed to ``cmake`` to avoid this clean.  However, multiple sequential
+passed to :program:`cmake` to avoid this clean.  However, multiple sequential
 ``try_compile`` operations, if given the same ``<bindir>``, will reuse this
 single output directory, such that you can only debug one such ``try_compile``
 call at a time.  Use of the newer signature is recommended to simplify
@@ -171,6 +178,12 @@ The options are:
   set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated
   project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable.
 
+``LOG_DESCRIPTION <text>``
+  .. versionadded:: 3.26
+
+  Specify a non-empty text description of the purpose of the check.
+  This is recorded in the :manual:`cmake-configure-log(7)` entry.
+
 ``NO_CACHE``
   .. versionadded:: 3.25
 
@@ -191,6 +204,11 @@ The options are:
   the test is part of a larger inspection), ``NO_CACHE`` may be useful to avoid
   leaking the intermediate result variable into the cache.
 
+``NO_LOG``
+  .. versionadded:: 3.26
+
+  Do not record a :manual:`cmake-configure-log(7)` entry for this call.
+
 ``OUTPUT_VARIABLE <var>``
   Store the output from the build process in the given variable.
 
@@ -271,13 +289,18 @@ Other Behavior Settings
   If :policy:`CMP0083` is set to ``NEW``, then in order to obtain correct
   behavior at link time, the ``check_pie_supported()`` command from the
   :module:`CheckPIESupported` module must be called before using the
-  :command:`try_compile` command.
+  ``try_compile`` command.
 
 The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated
 through to the generated test project.
 
-Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose
+Set variable :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` to choose a build
-a build configuration.
+configuration:
+
+* For multi-config generators, this selects which configuration to build.
+
+* For single-config generators, this sets :variable:`CMAKE_BUILD_TYPE` in
+  the test project.
 
 .. versionadded:: 3.6
   Set the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable to specify
@@ -327,3 +350,8 @@ a build configuration.
   If :policy:`CMP0141` is set to ``NEW``, one can use
   :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` to specify the MSVC debug
   information format.
+
+See Also
+^^^^^^^^
+
+* :command:`try_run`

Help/command/try_run.rst

@@ -17,7 +17,9 @@ Try Compiling and Running Source Files
            SOURCE_FROM_CONTENT <name> <content> |
            SOURCE_FROM_VAR <name> <var>         |
            SOURCE_FROM_FILE <name> <path>       >...
+          [LOG_DESCRIPTION <text>]
           [NO_CACHE]
+          [NO_LOG]
           [CMAKE_FLAGS <flags>...]
           [COMPILE_DEFINITIONS <defs>...]
           [LINK_OPTIONS <options>...]
@@ -30,32 +32,36 @@ Try Compiling and Running Source Files
           [RUN_OUTPUT_VARIABLE <var>]
           [RUN_OUTPUT_STDOUT_VARIABLE <var>]
           [RUN_OUTPUT_STDERR_VARIABLE <var>]
-          [OUTPUT_VARIABLE <var>]
           [WORKING_DIRECTORY <var>]
           [ARGS <args>...]
           )
 
 .. versionadded:: 3.25
 
-Try compiling a ``<srcfile>``.  Returns ``TRUE`` or ``FALSE`` for success
+Try building an executable from one or more source files.  Build success
-or failure in ``<compileResultVar>``.  If the compile succeeded, runs the
+returns ``TRUE`` and build failure returns ``FALSE`` in ``<compileResultVar>``.
-executable and returns its exit code in ``<runResultVar>``.  If the
+If the build succeeds, this runs the executable and stores the exit code in
-executable was built, but failed to run, then ``<runResultVar>`` will be
+``<runResultVar>``.  If the executable was built, but failed to run, then
-set to ``FAILED_TO_RUN``.  See the :command:`try_compile` command for
+``<runResultVar>`` will be set to ``FAILED_TO_RUN``.  See command
-documentation of options common to both commands, and for information on how
+:command:`try_compile` for documentation of options common to both commands,
-the test project is constructed to build the source file.
+and for information on how the test project is constructed to build the source
+file.
 
 One or more source files must be provided. Additionally, one of ``SOURCES``
 and/or ``SOURCE_FROM_*`` must precede other keywords.
 
-This command also supports an alternate signature
+.. versionadded:: 3.26
-which was present in older versions of CMake:
+  This command records a
+  :ref:`configure-log try_run event <try_run configure-log event>`
+  if the ``NO_LOG`` option is not specified.
+
+This command supports an alternate signature for CMake older than 3.25.
+The signature above is recommended for clarity.
 
 .. code-block:: cmake
 
   try_run(<runResultVar> <compileResultVar>
           <bindir> <srcfile|SOURCES srcfile...>
-          [NO_CACHE]
           [CMAKE_FLAGS <flags>...]
           [COMPILE_DEFINITIONS <defs>...]
           [LINK_OPTIONS <options>...]
@@ -66,8 +72,6 @@ which was present in older versions of CMake:
           [<LANG>_STANDARD_REQUIRED <bool>]
           [<LANG>_EXTENSIONS <bool>]
           [RUN_OUTPUT_VARIABLE <var>]
-          [RUN_OUTPUT_STDOUT_VARIABLE <var>]
-          [RUN_OUTPUT_STDERR_VARIABLE <var>]
           [OUTPUT_VARIABLE <var>]
           [WORKING_DIRECTORY <var>]
           [ARGS <args>...]
@@ -110,15 +114,19 @@ The options specific to ``try_run`` are:
 Other Behavior Settings
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose
+Set variable :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` to choose a build
-a build configuration.
+configuration:
+
+* For multi-config generators, this selects which configuration to build.
+
+* For single-config generators, this sets :variable:`CMAKE_BUILD_TYPE` in
+  the test project.
 
 Behavior when Cross Compiling
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. versionadded:: 3.3
-  Use ``CMAKE_CROSSCOMPILING_EMULATOR`` when running cross-compiled
+  Use ``CMAKE_CROSSCOMPILING_EMULATOR`` when running cross-compiled binaries.
-  binaries.
 
 When cross compiling, the executable compiled in the first step
 usually cannot be run on the build host.  The ``try_run`` command checks

Help/command/unset.rst

@@ -39,3 +39,8 @@ Subsequent calls of ``$ENV{<variable>}`` will return the empty string.
 This command affects only the current CMake process, not the process
 from which CMake was called, nor the system environment at large,
 nor the environment of subsequent build or test processes.
+
+See Also
+^^^^^^^^
+
+* :command:`set`

Help/command/use_mangled_mesa.rst

@@ -5,7 +5,7 @@ Disallowed since version 3.0.  See CMake Policy :policy:`CMP0030`.
 
 Copy mesa headers for use in combination with system GL.
 
-::
+.. code-block:: cmake
 
   use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
 

Help/command/utility_source.rst

@@ -5,7 +5,7 @@ Disallowed since version 3.0.  See CMake Policy :policy:`CMP0034`.
 
 Specify the source tree of a third-party utility.
 
-::
+.. code-block:: cmake
 
   utility_source(cache_entry executable_name
                  path_to_source [file1 file2 ...])

Help/command/variable_requires.rst

@@ -7,7 +7,7 @@ Use the :command:`if` command instead.
 
 Assert satisfaction of an option's required variables.
 
-::
+.. code-block:: cmake
 
   variable_requires(TEST_VARIABLE RESULT_VARIABLE
                     REQUIRED_VARIABLE1

Help/command/write_file.rst

@@ -5,7 +5,7 @@ write_file
 
   Use the :command:`file(WRITE)` command instead.
 
-::
+.. code-block:: cmake
 
   write_file(filename "message to write"... [APPEND])
 

Help/cpack_gen/archive.rst

@@ -4,19 +4,19 @@ CPack Archive Generator
 CPack generator for packaging files into an archive, which can have
 any of the following formats:
 
-  - 7Z - 7zip - (.7z)
+  - 7Z - 7zip - (``.7z``)
-  - TBZ2 (.tar.bz2)
+  - TBZ2 (``.tar.bz2``)
-  - TGZ (.tar.gz)
+  - TGZ (``.tar.gz``)
-  - TXZ (.tar.xz)
+  - TXZ (``.tar.xz``)
-  - TZ (.tar.Z)
+  - TZ (``.tar.Z``)
-  - TZST (.tar.zst)
+  - TZST (``.tar.zst``)
-  - ZIP (.zip)
+  - ZIP (``.zip``)
 
 .. versionadded:: 3.1
-  ``7Z`` and ``TXZ`` formats support.
+  7Z and TXZ formats support.
 
 .. versionadded:: 3.16
-  ``TZST`` format support.
+  TZST format support.
 
 When this generator is called from ``CPackSourceConfig.cmake`` (or through
 the ``package_source`` target), then the generated archive will contain all
@@ -47,27 +47,34 @@ Variables specific to CPack Archive generator
 .. variable:: CPACK_ARCHIVE_FILE_NAME
               CPACK_ARCHIVE_<component>_FILE_NAME
 
-  Package file name without extension. The extension is determined from the
+  Package file name without extension.
-  archive format (see list above) and automatically appended to the file name.
-  Note that ``<component>`` is all uppercase in the variable name.
 
-  The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces
+  :Default: The default is ``<CPACK_PACKAGE_FILE_NAME>[-<component>]``, with spaces
    replaced by '-'.
 
+  The extension is determined from the archive format (see list above) and
+  automatically appended to the file name. Note that ``<component>`` is all
+  uppercase in the variable name.
+
   .. versionadded:: 3.9
-    Per-component ``CPACK_ARCHIVE_<component>_FILE_NAME`` variables.
+    Per-component :variable:`!CPACK_ARCHIVE_<component>_FILE_NAME` variables.
 
 .. variable:: CPACK_ARCHIVE_FILE_EXTENSION
 
   .. versionadded:: 3.25
 
-  Package file extension. Default values are given in the list above.
+  Package file extension.
+
+  :Default: Default values are given in the list above.
 
 .. variable:: CPACK_ARCHIVE_COMPONENT_INSTALL
 
-  Enable component packaging. If enabled (ON), then the archive generator
+  Enable component packaging.
-  creates  multiple packages. The default is OFF, which means that a single
+
-  package containing files of all components is generated.
+  :Default: ``OFF``
+
+  If enabled (``ON``) multiple packages are generated. By default a single package
+  containing files of all components is generated.
 
 Variables used by CPack Archive generator
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -80,10 +87,13 @@ CPack generators which are essentially archives at their core. These include:
 
 .. variable:: CPACK_ARCHIVE_THREADS
 
+  The number of threads to use when performing the compression.
+
   .. versionadded:: 3.18
 
-  The number of threads to use when performing the compression. If set to
+  :Default: ``1``
-  ``0``, the number of available cores on the machine will be used instead.
+
+  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.

Help/cpack_gen/deb.rst

@@ -8,16 +8,16 @@ Variables specific to CPack Debian (DEB) generator
 
 The CPack DEB generator may be used to create DEB package using :module:`CPack`.
 The CPack DEB generator is a :module:`CPack` generator thus it uses the
-``CPACK_XXX`` variables used by :module:`CPack`.
+:variable:`!CPACK_XXX` variables used by :module:`CPack`.
 
 The CPack DEB generator should work on any Linux host but it will produce
 better deb package when Debian specific tools ``dpkg-xxx`` are usable on
 the build system.
 
 The CPack DEB generator has specific features which are controlled by the
-specifics ``CPACK_DEBIAN_XXX`` variables.
+specifics :variable:`!CPACK_DEBIAN_XXX` variables.
 
-``CPACK_DEBIAN_<COMPONENT>_XXXX`` variables may be used in order to have
+:variable:`!CPACK_DEBIAN_<COMPONENT>_XXXX` variables may be used in order to have
 **component** specific values.  Note however that ``<COMPONENT>`` refers to
 the **grouping name** written in upper case. It may be either a component name
 or a component GROUP name.
@@ -34,10 +34,10 @@ List of CPack DEB generator specific variables:
 
  Enable component packaging for CPackDEB
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   : OFF
+ :Default: ``OFF``
 
- If enabled (ON) multiple packages are generated. By default a single package
+ If enabled (``ON``) multiple packages are generated. By default a single package
  containing files of all components is generated.
 
 .. variable:: CPACK_DEBIAN_PACKAGE_NAME
@@ -46,16 +46,16 @@ List of CPack DEB generator specific variables:
  Set Package control field (variable is automatically transformed to lower
  case).
 
- * Mandatory : YES
+ :Mandatory: Yes
- * Default   :
+ :Default:
 
    - :variable:`CPACK_PACKAGE_NAME` for non-component based
      installations
-   - :variable:`CPACK_DEBIAN_PACKAGE_NAME` suffixed with -<COMPONENT>
+   - :variable:`CPACK_DEBIAN_PACKAGE_NAME` suffixed with ``-<COMPONENT>``
      for component-based installations.
 
  .. versionadded:: 3.5
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_NAME` variables.
 
  See https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-source
 
@@ -66,8 +66,8 @@ List of CPack DEB generator specific variables:
 
  Package file name.
 
- * Mandatory : YES
+ :Mandatory: Yes
- * Default   : ``<CPACK_PACKAGE_FILE_NAME>[-<component>].deb``
+ :Default: ``<CPACK_PACKAGE_FILE_NAME>[-<component>].deb``
 
  This may be set to ``DEB-DEFAULT`` to allow the CPack DEB generator to generate
  package file name by itself in deb format::
@@ -98,8 +98,8 @@ List of CPack DEB generator specific variables:
 
  The Debian package epoch
 
- * Mandatory : No
+ :Mandatory: No
- * Default   : -
+ :Default: None
 
  Optional number that should be incremented when changing versioning schemas
  or fixing mistakes in the version numbers of older packages.
@@ -108,8 +108,8 @@ List of CPack DEB generator specific variables:
 
  The Debian package version
 
- * Mandatory : YES
+ :Mandatory: Yes
- * Default   : :variable:`CPACK_PACKAGE_VERSION`
+ :Default: :variable:`CPACK_PACKAGE_VERSION`
 
  This variable may contain only alphanumerics (A-Za-z0-9) and the characters
  . + - ~ (full stop, plus, hyphen, tilde) and should start with a digit. If
@@ -130,8 +130,8 @@ List of CPack DEB generator specific variables:
 
  The Debian package release - Debian revision number.
 
- * Mandatory : No
+ :Mandatory: No
- * Default   : -
+ :Default: None
 
  This is the numbering of the DEB package itself, i.e. the version of the
  packaging and not the version of the content (see
@@ -144,20 +144,20 @@ List of CPack DEB generator specific variables:
 
  The Debian package architecture
 
- * Mandatory : YES
+ :Mandatory: Yes
- * Default   : Output of ``dpkg --print-architecture`` (or ``i386``
+ :Default: Output of ``dpkg --print-architecture`` (or ``i386``
    if ``dpkg`` is not found)
 
  .. versionadded:: 3.6
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_ARCHITECTURE` variables.
 
 .. variable:: CPACK_DEBIAN_PACKAGE_DEPENDS
               CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS
 
  Sets the Debian dependencies of this package.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   :
+ :Default:
 
    - An empty string for non-component based installations
    - :variable:`CPACK_DEBIAN_PACKAGE_DEPENDS` for component-based
@@ -165,7 +165,7 @@ List of CPack DEB generator specific variables:
 
 
  .. versionadded:: 3.3
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` variables.
 
  .. note::
 
@@ -178,7 +178,9 @@ List of CPack DEB generator specific variables:
    only the automatically discovered dependencies will be set for this
    component.
 
- Example::
+ Example:
+
+ .. code-block:: cmake
 
    set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.3.1-6), libc6 (< 2.4)")
 
@@ -189,23 +191,23 @@ List of CPack DEB generator specific variables:
  Sets inter-component dependencies if listed with
  :variable:`CPACK_COMPONENT_<compName>_DEPENDS` variables.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   : -
+ :Default: None
 
 .. variable:: CPACK_DEBIAN_PACKAGE_MAINTAINER
 
  The Debian package maintainer
 
- * Mandatory : YES
+ :Mandatory: Yes
- * Default   : ``CPACK_PACKAGE_CONTACT``
+ :Default: :variable:`!CPACK_PACKAGE_CONTACT`
 
 .. variable:: CPACK_DEBIAN_PACKAGE_DESCRIPTION
               CPACK_DEBIAN_<COMPONENT>_DESCRIPTION
 
  The Debian package description
 
- * Mandatory : YES
+ :Mandatory: Yes
- * Default   :
+ :Default:
 
    - :variable:`CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` (component
      based installers only) if set, or :variable:`CPACK_DEBIAN_PACKAGE_DESCRIPTION` if set, or
@@ -218,13 +220,13 @@ List of CPack DEB generator specific variables:
  line of description as defined in `Debian Policy Manual`_.
 
  .. versionadded:: 3.3
-  Per-component ``CPACK_COMPONENT_<compName>_DESCRIPTION`` variables.
+  Per-component :variable:`!CPACK_COMPONENT_<compName>_DESCRIPTION` variables.
 
  .. versionadded:: 3.16
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_DESCRIPTION`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_DESCRIPTION` variables.
 
  .. versionadded:: 3.16
-  The ``CPACK_PACKAGE_DESCRIPTION_FILE`` variable.
+  The :variable:`!CPACK_PACKAGE_DESCRIPTION_FILE` variable.
 
 .. _Debian Policy Manual: https://www.debian.org/doc/debian-policy/ch-controlfields.html#description
 
@@ -233,11 +235,11 @@ List of CPack DEB generator specific variables:
 
  Set Section control field e.g. admin, devel, doc, ...
 
- * Mandatory : YES
+ :Mandatory: Yes
- * Default   : "devel"
+ :Default: ``devel``
 
  .. versionadded:: 3.5
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_SECTION` variables.
 
  See https://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections
 
@@ -249,12 +251,10 @@ List of CPack DEB generator specific variables:
 
  The archive format used for creating the Debian package.
 
- * Mandatory : YES
+ :Mandatory: Yes
- * Default   : "gnutar"
+ :Default: ``gnutar``
 
- Possible value is:
+ Possible value is: ``gnutar``
-
- - gnutar
 
  .. note::
 
@@ -269,8 +269,8 @@ List of CPack DEB generator specific variables:
 
  The compression used for creating the Debian package.
 
- * Mandatory : YES
+ :Mandatory: Yes
- * Default   : "gzip"
+ :Default: ``gzip``
 
  Possible values are:
 
@@ -298,11 +298,11 @@ List of CPack DEB generator specific variables:
  Set Priority control field e.g. required, important, standard, optional,
  extra
 
- * Mandatory : YES
+ :Mandatory: Yes
- * Default   : "optional"
+ :Default: ``optional``
 
  .. versionadded:: 3.5
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_PRIORITY` variables.
 
  See https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities
 
@@ -312,11 +312,11 @@ List of CPack DEB generator specific variables:
  site from which the original source can be obtained and any additional
  upstream documentation or information may be found.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   : :variable:`CMAKE_PROJECT_HOMEPAGE_URL`
+ :Default: :variable:`CMAKE_PROJECT_HOMEPAGE_URL`
 
  .. versionadded:: 3.12
-  The ``CMAKE_PROJECT_HOMEPAGE_URL`` variable.
+  The :variable:`!CMAKE_PROJECT_HOMEPAGE_URL` variable.
 
  .. note::
 
@@ -329,11 +329,11 @@ List of CPack DEB generator specific variables:
  May be set to ON in order to use ``dpkg-shlibdeps`` to generate
  better package dependency list.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   :
+ :Default:
 
    - :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS` if set or
-   - OFF
+   - ``OFF``
 
  .. note::
 
@@ -350,7 +350,7 @@ List of CPack DEB generator specific variables:
    shared libraries that could not get resolved otherwise.
 
  .. versionadded:: 3.3
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS` variables.
 
  .. versionadded:: 3.6
   Correct handling of ``$ORIGIN`` in :variable:`CMAKE_INSTALL_RPATH`.
@@ -363,8 +363,8 @@ List of CPack DEB generator specific variables:
  via its ``-l`` option. These will be searched by ``dpkg-shlibdeps`` in order
  to find private shared library dependencies.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   :
+ :Default: None
 
  .. note::
 
@@ -377,8 +377,8 @@ List of CPack DEB generator specific variables:
  May be set when invoking cpack in order to trace debug information
  during the CPack DEB generator run.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   : -
+ :Default: None
 
 .. variable:: CPACK_DEBIAN_PACKAGE_PREDEPENDS
               CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS
@@ -389,58 +389,58 @@ List of CPack DEB generator specific variables:
  before even starting the installation of the package which declares the
  pre-dependency.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   :
+ :Default:
 
    - An empty string for non-component based installations
    - :variable:`CPACK_DEBIAN_PACKAGE_PREDEPENDS` for component-based
      installations.
 
  .. versionadded:: 3.4
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS` variables.
 
  See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 
 .. variable:: CPACK_DEBIAN_PACKAGE_ENHANCES
               CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES
 
- Sets the `Enhances` field of the Debian package.
+ Sets the ``Enhances`` field of the Debian package.
  Similar to :variable:`Suggests <CPACK_DEBIAN_PACKAGE_SUGGESTS>` but works
  in the opposite direction: declares that a package can enhance the
  functionality of another package.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   :
+ :Default:
 
    - An empty string for non-component based installations
    - :variable:`CPACK_DEBIAN_PACKAGE_ENHANCES` for component-based
      installations.
 
  .. versionadded:: 3.4
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES` variables.
 
  See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 
 .. variable:: CPACK_DEBIAN_PACKAGE_BREAKS
               CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS
 
- Sets the `Breaks` field of the Debian package.
+ Sets the ``Breaks`` field of the Debian package.
  When a binary package (P) declares that it breaks other packages (B),
- ``dpkg`` will not allow the package (P) which declares `Breaks` be
+ ``dpkg`` will not allow the package (P) which declares ``Breaks`` be
  **unpacked** unless the packages that will be broken (B) are deconfigured
  first.
  As long as the package (P) is configured, the previously deconfigured
  packages (B) cannot be reconfigured again.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   :
+ :Default:
 
    - An empty string for non-component based installations
    - :variable:`CPACK_DEBIAN_PACKAGE_BREAKS` for component-based
      installations.
 
  .. versionadded:: 3.4
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS` variables.
 
  See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-breaks
 
@@ -452,15 +452,15 @@ List of CPack DEB generator specific variables:
  field, ``dpkg`` will not allow them to be unpacked on the system at
  the same time.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   :
+ :Default:
 
    - An empty string for non-component based installations
    - :variable:`CPACK_DEBIAN_PACKAGE_CONFLICTS` for component-based
      installations.
 
  .. versionadded:: 3.4
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS` variables.
 
  See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts
 
@@ -479,15 +479,15 @@ List of CPack DEB generator specific variables:
  A virtual package is one which appears in the `Provides` control field of
  another package.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   :
+ :Default:
 
    - An empty string for non-component based installations
    - :variable:`CPACK_DEBIAN_PACKAGE_PROVIDES` for component-based
      installations.
 
  .. versionadded:: 3.4
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES` variables.
 
  See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-virtual
 
@@ -498,34 +498,34 @@ List of CPack DEB generator specific variables:
  Packages can declare in their control file that they should overwrite
  files in certain other packages, or completely replace other packages.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   :
+ :Default:
 
    - An empty string for non-component based installations
    - :variable:`CPACK_DEBIAN_PACKAGE_REPLACES` for component-based
      installations.
 
  .. versionadded:: 3.4
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES` variables.
 
  See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 
 .. variable:: CPACK_DEBIAN_PACKAGE_RECOMMENDS
               CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS
 
- Sets the `Recommends` field of the Debian package.
+ Sets the ``Recommends`` field of the Debian package.
  Allows packages to declare a strong, but not absolute, dependency on other
  packages.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   :
+ :Default:
 
    - An empty string for non-component based installations
    - :variable:`CPACK_DEBIAN_PACKAGE_RECOMMENDS` for component-based
      installations.
 
  .. versionadded:: 3.4
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS` variables.
 
  See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 
@@ -535,15 +535,15 @@ List of CPack DEB generator specific variables:
  Sets the `Suggests` field of the Debian package.
  Allows packages to declare a suggested package install grouping.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   :
+ :Default:
 
    - An empty string for non-component based installations
    - :variable:`CPACK_DEBIAN_PACKAGE_SUGGESTS` for component-based
      installations.
 
  .. versionadded:: 3.4
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS` variables.
 
  See https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 
@@ -551,8 +551,8 @@ List of CPack DEB generator specific variables:
 
  .. versionadded:: 3.6
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   : OFF
+ :Default: ``OFF``
 
  Allows to generate shlibs control file automatically. Compatibility is defined by
  :variable:`CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS_POLICY` variable value.
@@ -569,11 +569,11 @@ List of CPack DEB generator specific variables:
 
  Compatibility policy for auto-generated shlibs control file.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   : "="
+ :Default: ``=``
 
  Defines compatibility policy for auto-generated shlibs control file.
- Possible values: "=", ">="
+ Possible values: ``=``, ``>=``
 
  See https://www.debian.org/doc/debian-policy/ch-sharedlibs.html#s-sharedlibs-shlibdeps
 
@@ -584,16 +584,18 @@ List of CPack DEB generator specific variables:
  control.tar.gz.
  Typical usage is for conffiles, postinst, postrm, prerm.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   : -
+ :Default: None
 
- Usage::
+ Usage:
+
+ .. code-block:: cmake
 
   set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
       "${CMAKE_CURRENT_SOURCE_DIR}/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm")
 
  .. versionadded:: 3.4
-  Per-component ``CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA`` variables.
+  Per-component :variable:`!CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_EXTRA` variables.
 
 .. variable:: CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION
               CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONTROL_STRICT_PERMISSION
@@ -603,10 +605,12 @@ List of CPack DEB generator specific variables:
  This variable indicates if the Debian policy on control files should be
  strictly followed.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   : FALSE
+ :Default: ``FALSE``
 
- Usage::
+ Usage:
+
+ .. code-block:: cmake
 
   set(CPACK_DEBIAN_PACKAGE_CONTROL_STRICT_PERMISSION TRUE)
 
@@ -632,8 +636,8 @@ List of CPack DEB generator specific variables:
  source) the source from which the binary has been generated should be
  indicated with the field ``Source``.
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   :
+ :Default:
 
    - An empty string for non-component based installations
    - :variable:`CPACK_DEBIAN_PACKAGE_SOURCE` for component-based
@@ -660,8 +664,8 @@ Dbgsym packaging has its own set of variables:
 
  Enable generation of dbgsym .ddeb package(s).
 
- * Mandatory : NO
+ :Mandatory: No
- * Default   : OFF
+ :Default: ``OFF``
 
 .. note::
 
@@ -683,7 +687,7 @@ Building Debian packages on Windows
 .. versionadded:: 3.10
 
 To communicate UNIX file permissions from the install stage
-to the CPack DEB generator the "cmake_mode_t" NTFS
+to the CPack DEB generator the ``cmake_mode_t`` NTFS
 alternate data stream (ADT) is used.
 
 When a filesystem without ADT support is used only owner read/write
@@ -694,7 +698,7 @@ Reproducible packages
 
 .. versionadded:: 3.13
 
-The environment variable ``SOURCE_DATE_EPOCH`` may be set to a UNIX
+The environment variable :envvar:`!SOURCE_DATE_EPOCH` may be set to a UNIX
 timestamp, defined as the number of seconds, excluding leap seconds,
 since 01 Jan 1970 00:00:00 UTC.  If set, the CPack DEB generator will
 use its value for timestamps in the package.

Help/cpack_gen/dmg.rst

@@ -11,14 +11,19 @@ on macOS:
 
 .. variable:: CPACK_DMG_VOLUME_NAME
 
- The volume name of the generated disk image. Defaults to
+ The volume name of the generated disk image.
- CPACK_PACKAGE_FILE_NAME.
+
+ :Default: :variable:`CPACK_PACKAGE_FILE_NAME`
 
 .. variable:: CPACK_DMG_FORMAT
 
- The disk image format. Common values are ``UDRO`` (UDIF read-only), ``UDZO`` (UDIF
+ The disk image format.
+
+ :Default: ``UDZO``
+
+ Common values are ``UDRO`` (UDIF read-only), ``UDZO`` (UDIF
  zlib-compressed) or ``UDBZ`` (UDIF bzip2-compressed). Refer to ``hdiutil(1)`` for
- more information on other available formats. Defaults to ``UDZO``.
+ more information on other available formats.
 
 .. variable:: CPACK_DMG_DS_STORE
 
@@ -41,6 +46,8 @@ on macOS:
 
 .. variable:: CPACK_DMG_BACKGROUND_IMAGE
 
+ :Default:
+
  Path to an image file to be used as the background.  This file will be
  copied to ``.background``/``background.<ext>``, where ``<ext>`` is the original image file
  extension.  The background image is installed into the image before
@@ -58,13 +65,15 @@ on macOS:
 
  .. versionadded:: 3.23
 
+ :Default: ``OFF``
+
  Control whether :variable:`CPACK_RESOURCE_FILE_LICENSE`, if set to a
  non-default value, is used as the license agreement provided when
- mounting the DMG.  If ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`` is
+ mounting the DMG.  If :variable:`!CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` is
  not set, :manual:`cpack(1)` defaults to off.
 
  In a CMake project that uses the :module:`CPack` module to generate
- ``CPackConfig.cmake``, ``CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE``
+ ``CPackConfig.cmake``, :variable:`!CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE`
  must be explicitly enabled by the project to activate the SLA.
  See policy :policy:`CMP0133`.
 
@@ -82,8 +91,8 @@ on macOS:
   Directory where license and menu files for different languages are stored.
   Setting this causes CPack to look for a ``<language>.menu.txt`` and
   ``<language>.license.txt`` or ``<language>.license.rtf`` file for every
-  language defined in ``CPACK_DMG_SLA_LANGUAGES``.  If both this variable and
+  language defined in :variable:`CPACK_DMG_SLA_LANGUAGES`.  If both this variable and
-  ``CPACK_RESOURCE_FILE_LICENSE`` are set, CPack will only look for the menu
+  :variable:`CPACK_RESOURCE_FILE_LICENSE` are set, CPack will only look for the menu
   files and use the same license file for all languages.  If both
   ``<language>.license.txt`` and ``<language>.license.rtf`` exist, the ``.txt``
   file will be used.
@@ -120,17 +129,18 @@ on macOS:
  .. versionadded:: 3.17
 
  File name when packaging ``<component>`` as its own DMG
- (``CPACK_COMPONENTS_GROUPING`` set to IGNORE).
+ (:variable:`CPACK_COMPONENTS_GROUPING` set to ``IGNORE``).
 
- - Default: ``CPACK_PACKAGE_FILE_NAME-<component>``
+ :Default: ``CPACK_PACKAGE_FILE_NAME-<component>``
 
 .. variable:: CPACK_DMG_FILESYSTEM
 
  .. versionadded:: 3.21
 
+ :Default: ``HFS+``
+
  The filesystem format. Common values are ``APFS`` and ``HFS+``.
  See ``man hdiutil`` for a full list of supported formats.
- Defaults to ``HFS+``.
 
 .. variable:: CPACK_COMMAND_HDIUTIL