Merge topic 'doc-3.21-relnotes'

f119fbeec5 Help: Update Sphinx versionadded directives for 3.21 release
45acb61432 Help: Organize and revise 3.21 release notes
046aee0441 Help: Consolidate 3.21 release notes

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6226

61 files changed, 294 insertions, 343 deletions

diff --git a/Help/release/3.21.rst b/Help/release/3.21.rst
new file mode 100644
index 0000000..04354db
--- /dev/null
+++ b/Help/release/3.21.rst
@@ -0,0 +1,291 @@
+CMake 3.21 Release Notes
+************************
+
+.. only:: html
+
+  .. contents::
+
+Changes made since CMake 3.20 include the following.
+
+New Features
+============
+
+Presets
+-------
+
+* :manual:`cmake-presets(7)` gained support for specifying the install prefix
+  in a configure preset.
+
+* :manual:`cmake-presets(7)` gained support for conditional enabling of presets.
+
+* :manual:`cmake-presets(7)` gained support for a ``${hostSystemName}`` macro.
+
+* :manual:`cmake-presets(7)` gained support for omitting the ``generator`` and
+  ``binaryDir`` fields.
+
+Generators
+----------
+
+* The :ref:`Makefile Generators` and the :generator:`Ninja` generator
+  learned to add linker launcher tools along with the linker for ``C``,
+  ``CXX``, ``OBJC``, and ``OBJCXX`` languages.
+  See the :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` variable
+  and :prop_tgt:`<LANG>_LINKER_LAUNCHER` target property for details.
+
+Languages
+---------
+
+* CMake learned to support ``HIP`` as a first-class language that can be
+  enabled via the :command:`project` and :command:`enable_language` commands.
+
+* :prop_tgt:`C_STANDARD`, :prop_tgt:`OBJC_STANDARD`, and the
+  :manual:`Compile Features <cmake-compile-features(7)>` functionality gained
+  support for C17 and C23.
+
+* Source file extensions ``.ixx`` and ``.cppm`` are now treated as C++.
+
+Command-Line
+------------
+
+* :manual:`cmake(1)` gained the ``--install-prefix <dir>``
+  command-line option to specify the location of the install prefix.
+
+* :manual:`cmake(1)` gained the ``--toolchain <path/to/file>``
+  command-line option to specify a toolchain file.
+
+* :manual:`cmake(1)` ``-E capabilities`` output now contains for each
+  generator a ``supportedPlatforms`` field listing platforms known to
+  be supported in :variable:`CMAKE_GENERATOR_PLATFORM`.
+
+* Messages printed to a terminal now may be colored by message type.
+
+Compilers
+---------
+
+* The Fujitsu compiler is now supported using compiler id ``Fujitsu``
+  in traditional (``Trad``) mode, and compiler id ``FujitsuClang``
+  in ``Clang`` mode.
+
+Platforms
+---------
+
+* CMake now supports the MSYS runtime environment, much like CYGWIN.
+
+File-Based API
+--------------
+
+* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field
+  has been updated to 2.3.
+
+* The :manual:`cmake-file-api(7)` "codemodel" version 2 gained a
+  new "directory" object containing directory-level information.
+  This includes a list of installers generated by the :command:`install`
+  command.
+
+Commands
+--------
+
+* The :command:`add_custom_command` command ``DEPFILE`` option:
+
+  * may now use
+    :manual:`generator expressions <cmake-generator-expressions(7)>`,
+
+  * is now supported by :ref:`Visual Studio Generators` for VS 2012
+    and above, and
+
+  * is now supported by the :generator:`Xcode` generator.
+
+* The :command:`add_custom_command(TARGET)` command
+  (for :ref:`Build Events <add_custom_command(TARGET)>`)
+  gained support for resolving target-dependent generator expressions.
+
+* The :command:`build_command` command gained a ``PARALLEL_LEVEL`` option.
+
+* The :command:`file(COPY_FILE)` command was added to copy a single file.
+
+* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command gained new
+  ``POST_INCLUDE_FILES`` and ``POST_EXCLUDE_FILES`` arguments.
+
+* The :command:`file(REAL_PATH)` command gained the option ``EXPAND_TILDE`` to
+  replace any leading tilde with the path to the user's home directory.
+
+* The :command:`file(RENAME)` command learned to optionally capture
+  failure in a result variable.  It also gained a ``NO_REPLACE``
+  option to fail if the destination exists.
+
+* The :command:`install` command gained a new ``IMPORTED_RUNTIME_ARTIFACTS``
+  mode, which can be used to install the runtime artifacts of imported targets.
+
+* The :command:`install` command gained a new ``RUNTIME_DEPENDENCY_SET`` mode,
+  which can be used to install runtime dependencies using
+  :command:`file(GET_RUNTIME_DEPENDENCIES)`.
+
+* The :command:`install(TARGETS)` command gained new ``RUNTIME_DEPENDENCIES``
+  and ``RUNTIME_DEPENDENCY_SET`` arguments, which can be used to install
+  runtime dependencies using :command:`file(GET_RUNTIME_DEPENDENCIES)`.
+
+* The :command:`install(SCRIPT|CODE)` command
+  supports a new option ``ALL_COMPONENTS`` which allows
+  the corresponding code to run for every component of
+  a per component installation.
+
+* The :command:`project` command now sets variables
+  :variable:`PROJECT_IS_TOP_LEVEL` and :variable:`<PROJECT-NAME>_IS_TOP_LEVEL`
+  to indicate whether it was called in a top-level ``CMakeLists.txt`` file.
+
+Variables
+---------
+
+* The :envvar:`CMAKE_TOOLCHAIN_FILE` environment variable was added to
+  provide a default value for the :variable:`CMAKE_TOOLCHAIN_FILE` variable.
+
+Properties
+----------
+
+* The :prop_dir:`IMPORTED_TARGETS` directory property was added to
+  get a list of :ref:`Imported Targets` created in the current
+  directory.
+
+* The :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS <XCODE_EMBED_<type>>` target property
+  was added to tell the :generator:`Xcode` generator to embed app extensions
+  such as iMessage sticker packs.
+  Aspects of the embedding can be customized with the
+  :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_PATH <XCODE_EMBED_<type>>`,
+  :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_CODE_SIGN_ON_COPY <XCODE_EMBED_<type>_CODE_SIGN_ON_COPY>` and
+  :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY <XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY>`
+  properties.
+
+Modules
+-------
+
+* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support
+  the serial ``Fujitsu_SSL2`` and parallel ``Fujitsu_SSL2BLAMP`` libraries.
+
+* The :module:`FindDevIL` module now provides imported targets.
+
+* The :module:`FindIconv` module now has version support.
+
+* The :module:`FindIntl` module now has version support.
+
+* The :module:`FindMPI` module learned to support ``Fujitsu`` and
+  ``FujitsuClang`` in both host and cross compiling modes.
+
+* The :module:`FindMsys` module was added to find MSYS installations.
+  Like :module:`FindCygwin`, it is used automatically by some other
+  find modules to locate UNIX-style tools on Windows.
+
+* The :module:`FindOpenMP` module learned to support ``Fujitsu`` and
+  ``FujitsuClang``.
+
+* The :module:`FindVulkan` module gained imported targets
+  ``Vulkan::Headers`` and ``Vulkan::glslangValidator``.
+
+* The :module:`UseJava` module command ``add_jar`` gained a ``RESOURCES``
+  option to allow explicit naming of resources with non-optional namespace.
+
+* The :module:`UseSWIG` module use now standard library naming conventions
+  for the ``CSharp`` language. See policy :policy:`CMP0122`.
+
+* The :module:`UseSWIG` module now supports using the ``swig`` tool to
+  generate implicit dependencies with the :generator:`Xcode` generator.
+
+Generator Expressions
+---------------------
+
+* A new :genex:`TARGET_RUNTIME_DLLS` generator expression was added.
+
+CTest
+-----
+
+* :manual:`ctest(1)` gained documentation for its ability to capture
+  :ref:`Additional Test Measurements`.
+
+* :manual:`ctest(1)` learned to recognize files attached to a test at run time.
+  Previously it was only possible to attach files to tests at configure time
+  by using the :prop_test:`ATTACHED_FILES` or
+  :prop_test:`ATTACHED_FILES_ON_FAIL` test properties.
+  See :ref:`Additional Test Measurements` for more information.
+
+* :manual:`ctest(1)` gained a ``--output-junit`` option to write test results
+  to a JUnit XML file.
+
+* The :command:`ctest_build` command gained a ``PARALLEL_LEVEL`` option.
+
+CPack
+-----
+
+* The :cpack_gen:`CPack DragNDrop Generator` gained option
+  :variable:`CPACK_DMG_FILESYSTEM` to control the ``.dmg`` filesystem.
+
+* The :cpack_gen:`CPack IFW Generator` now supports hyphens in names
+  given to :command:`cpack_ifw_configure_component` or
+  :command:`cpack_ifw_configure_component_group` as ``DEPENDS`` or
+  ``DEPENDENCIES`` arguments.  This requires QtIFW 3.1 or later.
+
+* The :cpack_gen:`CPack NSIS Generator` gained a new
+  :variable:`CPACK_NSIS_EXECUTABLE` variable to specify the ``makensis``
+  executable to use instead of the default one.
+
+* The :variable:`CPACK_CUSTOM_INSTALL_VARIABLES` variable was added to set
+  variables in ``cmake_install.cmake`` script invocations made by CPack.
+
+Deprecated and Removed Features
+===============================
+
+* Undocumented :variable:`CMAKE_SYSTEM_NAME` version-stripping behavior has
+  been removed entirely. If it is set by a ``-D`` flag or by a
+  :manual:`toolchain file <cmake-toolchains(7)>`, it is left unaltered,
+  even if it still contains a version number.
+  Similar :variable:`CMAKE_HOST_SYSTEM_NAME` version-stripping behavior,
+  also undocumented, has been moved earlier, before :command:`project` or
+  :command:`enable_language` is called.
+
+* ``ARMClang`` cpu/arch compile and link flags are no longer added
+  automatically based on the :variable:`CMAKE_SYSTEM_PROCESSOR`
+  variable or the undocumented ``CMAKE_SYSTEM_ARCH`` variable.
+  They must be specified explicitly.  See policy :policy:`CMP0123`.
+
+Other Changes
+=============
+
+* The :command:`find_file`, :command:`find_path`, :command:`find_program`,
+  and :command:`find_library` commands handle cache variables in the same way
+  regardless how they are defined. See policy :policy:`CMP0125` for details.
+
+* The :command:`find_file`, :command:`find_path`, :command:`find_program`,
+  and :command:`find_library` commands gained the option ``NO_CACHE`` to store
+  find result in normal variable.
+
+* The :command:`foreach` command now isolates loop variables in the loop scope.
+  See policy :policy:`CMP0124` for details.
+
+* The :command:`list` command's ``GET``, ``INSERT``, ``SUBLIST``, and
+  ``REMOVE_AT`` subcommands now error with invalid (i.e., non-integer) values
+  are given as any of their index arguments based on the setting of policy
+  :policy:`CMP0121`.
+
+* The :command:`set(CACHE)` command no longer removes a normal variable
+  of the same name, if any. See policy :policy:`CMP0126`.
+
+* :command:`target_link_libraries` calls referencing object libraries
+  via the :genex:`TARGET_OBJECTS` generator expression now place the
+  object files before all libraries on the link line, regardless of
+  their specified order.  See documentation on
+  :ref:`Linking Object Libraries via \$\<TARGET_OBJECTS\>` for details.
+
+* The :ref:`Ninja Generators` now pass source files and include directories
+  to the compiler using absolute paths.  This makes diagnostic messages and
+  debug symbols more consistent, and matches the :ref:`Makefile Generators`.
+
+* The :generator:`NMake Makefiles` generator now encodes the generated
+  makefiles as UTF-8 with a BOM when using ``nmake`` from VS 9 or above.
+
+* The :ref:`Visual Studio Generators` for VS 2010 and above now place
+  per-source preprocessor definitions after target-wide preprocssor
+  definitions.  This makes VS consistent with the :ref:`Ninja Generators`
+  and the :ref:`Makefile Generators`.
+
+* The precompiled binaries provided on
+  `cmake.org <https://cmake.org/download/>`_ now support
+  ``liblzma`` multi-threading.  See the :variable:`CPACK_THREADS` and
+  :variable:`CPACK_ARCHIVE_THREADS` variables.
diff --git a/Help/release/dev/ARMClang-cpu-arch-flags.rst b/Help/release/dev/ARMClang-cpu-arch-flags.rst
deleted file mode 100644
index 5e885fe..0000000
--- a/Help/release/dev/ARMClang-cpu-arch-flags.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-ARMClang-cpu-arch-flags
------------------------
-
-* ``ARMClang`` cpu/arch compile and link flags are no longer added
-  automatically based on the :variable:`CMAKE_SYSTEM_PROCESSOR`
-  variable or the undocumented ``CMAKE_SYSTEM_ARCH`` variable.
-  They must be specified explicitly.  See policy :policy:`CMP0123`.
diff --git a/Help/release/dev/FindDevIL-imported-targets.rst b/Help/release/dev/FindDevIL-imported-targets.rst
deleted file mode 100644
index aa0929e..0000000
--- a/Help/release/dev/FindDevIL-imported-targets.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-FindDevIL
----------
-
-* The :module:`FindDevIL` module now provides imported targets.
diff --git a/Help/release/dev/FindIconv-version.rst b/Help/release/dev/FindIconv-version.rst
deleted file mode 100644
index 3546d86..0000000
--- a/Help/release/dev/FindIconv-version.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-FindIconv-version
------------------
-
-* The :module:`FindIconv` module now has version support.
diff --git a/Help/release/dev/FindIntl-version.rst b/Help/release/dev/FindIntl-version.rst
deleted file mode 100644
index 5365cf1..0000000
--- a/Help/release/dev/FindIntl-version.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-FindIntl-version
-----------------
-
-* The :module:`FindIntl` module now has version support.
diff --git a/Help/release/dev/FindMsys.rst b/Help/release/dev/FindMsys.rst
deleted file mode 100644
index d237c4e..0000000
--- a/Help/release/dev/FindMsys.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-FindMsys
---------
-
-* The :module:`FindMsys` module was added to find MSYS installations.
-  Like :module:`FindCygwin`, it is used automatically by some other
-  find modules to locate UNIX-style tools on Windows.
diff --git a/Help/release/dev/FindVulkan-add-Headers-glslangValidator-targets.rst b/Help/release/dev/FindVulkan-add-Headers-glslangValidator-targets.rst
deleted file mode 100644
index 4f224cc..0000000
--- a/Help/release/dev/FindVulkan-add-Headers-glslangValidator-targets.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-FindVulkan-add-Headers-glslangValidator-targets
------------------------------------------------
-
-* The :module:`FindVulkan` module gained imported targets
-  ``Vulkan::Headers`` and ``Vulkan::glslangValidator``.
diff --git a/Help/release/dev/UseJava-RESOURCES-NAMESPACE.rst b/Help/release/dev/UseJava-RESOURCES-NAMESPACE.rst
deleted file mode 100644
index caa07e7..0000000
--- a/Help/release/dev/UseJava-RESOURCES-NAMESPACE.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-UseJava-RESOURCES-NAMESPACE
----------------------------
-
-* The :module:`UseJava` module command ``add_jar`` gained option RESOURCES
-  allow explicit naming of resources with non-optional namespace.
diff --git a/Help/release/dev/UseSWIG-csharp.rst b/Help/release/dev/UseSWIG-csharp.rst
deleted file mode 100644
index dbbeaf1..0000000
--- a/Help/release/dev/UseSWIG-csharp.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-UseSWIG-csharp
---------------
-
-* The :module:`UseSWIG` module use now standard library name conventions for
-  ``CSharp`` language. See policy :policy:`CMP0122`.
diff --git a/Help/release/dev/UseSWIG-dependencies.rst b/Help/release/dev/UseSWIG-dependencies.rst
deleted file mode 100644
index b5a38c3..0000000
--- a/Help/release/dev/UseSWIG-dependencies.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-UseSWIG-dependencies
---------------------
-
-* :module:`UseSWIG` module gained the capability, for
-  :generator:`Xcode` generator, to use `swig` tool to generate implicit
-  dependencies.
diff --git a/Help/release/dev/add_custom_command-DEPFILE-genex.rst b/Help/release/dev/add_custom_command-DEPFILE-genex.rst
deleted file mode 100644
index 52e5e9f..0000000
--- a/Help/release/dev/add_custom_command-DEPFILE-genex.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-add_custom_command-DEPFILE-genex
---------------------------------
-
-* The :command:`add_custom_command` command ``DEPFILE`` option learned to
-  support :manual:`generator expressions <cmake-generator-expressions(7)>`.
diff --git a/Help/release/dev/add_custom_command-DEPFILE.rst b/Help/release/dev/add_custom_command-DEPFILE.rst
deleted file mode 100644
index 893c374..0000000
--- a/Help/release/dev/add_custom_command-DEPFILE.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-add_custom_command-DEPFILE
---------------------------
-
-* The :command:`add_custom_command` command gained ``DEPFILE`` support on
-  the :generator:`Xcode` generator, and on :ref:`Visual Studio Generators`
-  for VS 2012 and above.
diff --git a/Help/release/dev/add_custom_command-TARGET-genex.rst b/Help/release/dev/add_custom_command-TARGET-genex.rst
deleted file mode 100644
index 86f8b36..0000000
--- a/Help/release/dev/add_custom_command-TARGET-genex.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-add_custom_command-TARGET-genex
--------------------------------
-
-* The :ref:`add_custom_command(TARGET) <add_custom_command(TARGET)>` command
-  gained support for resolving target-dependent generator expressions.
diff --git a/Help/release/dev/c-std.rst b/Help/release/dev/c-std.rst
deleted file mode 100644
index 44daa85..0000000
--- a/Help/release/dev/c-std.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-c-std
------
-
-* :prop_tgt:`C_STANDARD` and the
-  :manual:`Compile Features <cmake-compile-features(7)>` functionality gained
-  support for C17 and C23.
diff --git a/Help/release/dev/capabilties-generator-platforms.rst b/Help/release/dev/capabilties-generator-platforms.rst
deleted file mode 100644
index 5de2b67..0000000
--- a/Help/release/dev/capabilties-generator-platforms.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-capabilties-generator-platforms
--------------------------------
-
-* The :manual:`cmake(1)` ``-E capabilities`` output now contains for each
-  generator a ``supportedPlatforms`` field listing platform known to
-  be supported in :variable:`CMAKE_GENERATOR_PLATFORM`.
diff --git a/Help/release/dev/cmake-install-prefix-command.rst b/Help/release/dev/cmake-install-prefix-command.rst
deleted file mode 100644
index 2de5d91..0000000
--- a/Help/release/dev/cmake-install-prefix-command.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-cmake-install-prefix-command
-----------------------------
-
-* The :manual:`cmake(1)` command gained the ``--install-prefix <dir>``
-  command line option to specify the location of the install prefix.
-
-* :manual:`cmake-presets(7)` configure preset gained support for specifying
-  the install prefix.
diff --git a/Help/release/dev/cmake-presets-condition.rst b/Help/release/dev/cmake-presets-condition.rst
deleted file mode 100644
index aa01bc1..0000000
--- a/Help/release/dev/cmake-presets-condition.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-cmake-presets-condition
------------------------
-
-* :manual:`cmake-presets(7)` now support conditional enabling of presets.
diff --git a/Help/release/dev/cmake-presets-host-system-name.rst b/Help/release/dev/cmake-presets-host-system-name.rst
deleted file mode 100644
index 8036939..0000000
--- a/Help/release/dev/cmake-presets-host-system-name.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-cmake-presets-host-system-name
-------------------------------
-
-* :manual:`cmake-presets(7)` gained support for a new ``${hostSystemName}``
-  macro.
diff --git a/Help/release/dev/cmake-presets-optional-generator-and-binarydir.rst b/Help/release/dev/cmake-presets-optional-generator-and-binarydir.rst
deleted file mode 100644
index 7973489..0000000
--- a/Help/release/dev/cmake-presets-optional-generator-and-binarydir.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-cmake-presets-optional-generator-and-binarydir
-----------------------------------------------
-
-* :manual:`cmake-presets(7)` now support omitting the ``generator`` and
-  ``binaryDir`` fields.
diff --git a/Help/release/dev/cmake-system-name-version.rst b/Help/release/dev/cmake-system-name-version.rst
deleted file mode 100644
index 9cfe401..0000000
--- a/Help/release/dev/cmake-system-name-version.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-cmake-system-name-version
--------------------------
-
-* :variable:`CMAKE_HOST_SYSTEM_NAME`'s undocumented version-stripping behavior
-  has been moved earlier, before :command:`project` or
-  :command:`enable_language` is called.
-* :variable:`CMAKE_SYSTEM_NAME`'s undocumented version-stripping behavior has
-  been removed entirely. If it is set by a ``-D`` flag or by a
-  :manual:`toolchain file <cmake-toolchains(7)>`, it is left unaltered, even if
-  it still contains a version number.
diff --git a/Help/release/dev/cmake-toolchain-command.rst b/Help/release/dev/cmake-toolchain-command.rst
deleted file mode 100644
index 111ca49..0000000
--- a/Help/release/dev/cmake-toolchain-command.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-cmake-toolchain-command
-----------------------------
-
-* The :manual:`cmake(1)` command gained the ``--toolchain <path/to/file>``
-  command line option to specify a toolchain file.
diff --git a/Help/release/dev/compile-options-order.rst b/Help/release/dev/compile-options-order.rst
deleted file mode 100644
index 2e182cd..0000000
--- a/Help/release/dev/compile-options-order.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-compile-options-order
----------------------
-
-* The :ref:`Visual Studio Generators` for VS 2010 and above now place
-  per-source preprocessor definitions after target-wide preprocssor
-  definitions.  This makes VS consistent with the :ref:`Ninja Generators`
-  and the :ref:`Makefile Generators`.
diff --git a/Help/release/dev/cpack-dmg-filesystem.rst b/Help/release/dev/cpack-dmg-filesystem.rst
deleted file mode 100644
index e2a4742..0000000
--- a/Help/release/dev/cpack-dmg-filesystem.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-cpack-dmg-filesystem
---------------------
-
-* The :cpack_gen:`CPack DragNDrop Generator` gained option
-  :variable:`CPACK_DMG_FILESYSTEM` to control the ``.dmg`` filesystem.
diff --git a/Help/release/dev/cpack-install-opts.rst b/Help/release/dev/cpack-install-opts.rst
deleted file mode 100644
index 970f9a9..0000000
--- a/Help/release/dev/cpack-install-opts.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-cpack-install-opts
-------------------
-
-* The new :variable:`CPACK_CUSTOM_INSTALL_VARIABLES`
-  can be used to set variables in CPack ``cmake_install.cmake``
-  invocations.
diff --git a/Help/release/dev/cpack-nsis-executable-name.rst b/Help/release/dev/cpack-nsis-executable-name.rst
deleted file mode 100644
index a3818db..0000000
--- a/Help/release/dev/cpack-nsis-executable-name.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-cpack-nsis-executable-name
---------------------------
-
-* The :cpack_gen:`CPack NSIS Generator` gained a new variable
-  :variable:`CPACK_NSIS_EXECUTABLE` to specify the makensis
-  executable to use instead of the default one.
diff --git a/Help/release/dev/ctest-measurements-docs.rst b/Help/release/dev/ctest-measurements-docs.rst
deleted file mode 100644
index e47582e..0000000
--- a/Help/release/dev/ctest-measurements-docs.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-ctest-measurements-docs
------------------------
-
-* :manual:`ctest(1)` gained documentation for its ability to capture
-  :ref:`Additional Test Measurements`.
diff --git a/Help/release/dev/ctest-output-junit.rst b/Help/release/dev/ctest-output-junit.rst
deleted file mode 100644
index 66df19d..0000000
--- a/Help/release/dev/ctest-output-junit.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-ctest-output-junit
-------------------
-
-* :manual:`ctest(1)` gained a ``--output-junit`` option to write test results
-  to a JUnit XML file.
diff --git a/Help/release/dev/ctest-runtime-files.rst b/Help/release/dev/ctest-runtime-files.rst
deleted file mode 100644
index f13baa4..0000000
--- a/Help/release/dev/ctest-runtime-files.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-ctest-runtime-files
--------------------
-
-* :manual:`ctest(1)` learned to recognize files attached to a test at run time.
-  Previously it was only possible to attach files to tests at configure time
-  by using the :prop_test:`ATTACHED_FILES` or
-  :prop_test:`ATTACHED_FILES_ON_FAIL` test properties.
-  See :ref:`Additional Test Measurements` for more information.
diff --git a/Help/release/dev/cxx-module-extensions.rst b/Help/release/dev/cxx-module-extensions.rst
deleted file mode 100644
index b9d0a8a..0000000
--- a/Help/release/dev/cxx-module-extensions.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-cxx-module-extensions
----------------------
-
-* Source file extensions ``.ixx`` and ``.cppm`` are now treated as C++.
diff --git a/Help/release/dev/dir-IMPORTED_TARGETS.rst b/Help/release/dev/dir-IMPORTED_TARGETS.rst
deleted file mode 100644
index a2797ec..0000000
--- a/Help/release/dev/dir-IMPORTED_TARGETS.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-dir-IMPORTED_TARGETS
---------------------
-
-* The :prop_dir:`IMPORTED_TARGETS` directory property was added to
-  get a list of :ref:`Imported Targets` created in the current
-  directory.
diff --git a/Help/release/dev/env-toolchain-file.rst b/Help/release/dev/env-toolchain-file.rst
deleted file mode 100644
index 0bcd493..0000000
--- a/Help/release/dev/env-toolchain-file.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-env-toolchain-file
-------------------
-
-* The :envvar:`CMAKE_TOOLCHAIN_FILE` environment variable was added to
-  provide a default value for the :variable:`CMAKE_TOOLCHAIN_FILE` variable.
diff --git a/Help/release/dev/file-COPY_FILE.rst b/Help/release/dev/file-COPY_FILE.rst
deleted file mode 100644
index 2f0cdf0..0000000
--- a/Help/release/dev/file-COPY_FILE.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-file-COPY_ONLY
---------------
-
-* The :command:`file(COPY_FILE)` command was added to copy a file to another.
diff --git a/Help/release/dev/file-REAL_PATH-EXPAND_TILDE.rst b/Help/release/dev/file-REAL_PATH-EXPAND_TILDE.rst
deleted file mode 100644
index cdf1efa..0000000
--- a/Help/release/dev/file-REAL_PATH-EXPAND_TILDE.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-file-REAL_PATH-EXPAND_TILDE
----------------------------
-
-* The :command:`file(REAL_PATH)` command gained the option ``EXPAND_TILDE`` to
-  replace any leading tilde with the path to the user's home directory.
diff --git a/Help/release/dev/file-RENAME.rst b/Help/release/dev/file-RENAME.rst
deleted file mode 100644
index 6c1314d..0000000
--- a/Help/release/dev/file-RENAME.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-file-RENAME
------------
-
-* The :command:`file(RENAME)` command learned to optionally capture
-  failure in a result variable.  It also gained a ``NO_REPLACE``
-  option to fail if the destination exists.
diff --git a/Help/release/dev/fileapi-codemodel-directory.rst b/Help/release/dev/fileapi-codemodel-directory.rst
deleted file mode 100644
index f6515fd..0000000
--- a/Help/release/dev/fileapi-codemodel-directory.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-fileapi-codemodel-directory
----------------------------
-
-* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
-  component been updated to 2.3.
-
-* The :manual:`cmake-file-api(7)` "codemodel" version 2 gained a
-  new "directory" object containing directory-level information.
-  This includes a list of installers generated by the :command:`install`
-  command.
diff --git a/Help/release/dev/find_item-NO_CACHE.rst b/Help/release/dev/find_item-NO_CACHE.rst
deleted file mode 100644
index be5258c..0000000
--- a/Help/release/dev/find_item-NO_CACHE.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-find_item-NO_CACHE
-------------------
-
-* The :command:`find_file`, :command:`find_path`, :command:`find_program`,
-  and :command:`find_library` commands gained the option ``NO_CACHE`` to store
-  find result in normal variable.
diff --git a/Help/release/dev/find_item-consistent-behavior.rst b/Help/release/dev/find_item-consistent-behavior.rst
deleted file mode 100644
index 43905e7..0000000
--- a/Help/release/dev/find_item-consistent-behavior.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-find_item-consistent-behavior
------------------------------
-
-* The :command:`find_file`, :command:`find_path`, :command:`find_program`,
-  and :command:`find_library` commands handle cache variables in the same way
-  regardless how they are defined. See policy :policy:`CMP0125` for details.
diff --git a/Help/release/dev/foreach-variable-scope.rst b/Help/release/dev/foreach-variable-scope.rst
deleted file mode 100644
index 29a57bb..0000000
--- a/Help/release/dev/foreach-variable-scope.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-foreach-variable-scope
-----------------------
-
-* The :command:`foreach` command restrict loop variables to the loop scope.
-  See policy :policy:`CMP0124` for details.
diff --git a/Help/release/dev/fujitsu-compiler-support.rst b/Help/release/dev/fujitsu-compiler-support.rst
deleted file mode 100644
index c6f8cfb..0000000
--- a/Help/release/dev/fujitsu-compiler-support.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-fujitsu-compiler-support
-------------------------
-
-* Addition of the ``Fujitsu`` compiler ID operating in traditional ``Trad``
-  mode and ``FujitsuClang`` operating in ``Clang`` mode.
-* The :module:`FindOpenMP` module learned to support ``Fujitsu`` and
-  ``FujitsuClang``.
-* The :module:`FindMPI` module learned to support ``Fujitsu`` and
-  ``FujitsuClang`` in both host and cross compiling modes.
-* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support
-  the serial ``Fujitsu SSL2`` and parallel ``Fujitsu SSL2BLAMP`` libraries.
diff --git a/Help/release/dev/generate-cmake-build-command-parallel.rst b/Help/release/dev/generate-cmake-build-command-parallel.rst
deleted file mode 100644
index 1b8dd40..0000000
--- a/Help/release/dev/generate-cmake-build-command-parallel.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-generate-cmake-build-command-parallel
--------------------------------------
-
-* The :command:`build_command` command gained a ``PARALLEL_LEVEL`` option.
-
-* The :command:`ctest_build` command gained a ``PARALLEL_LEVEL`` option.
diff --git a/Help/release/dev/get-runtime-dependencies-file-filter.rst b/Help/release/dev/get-runtime-dependencies-file-filter.rst
deleted file mode 100644
index 3fc17ac..0000000
--- a/Help/release/dev/get-runtime-dependencies-file-filter.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-get-runtime-dependencies-file-filter
-------------------------------------
-
-* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command gained new
-  ``POST_INCLUDE_FILES`` and ``POST_EXCLUDE_FILES`` arguments.
diff --git a/Help/release/dev/hip.rst b/Help/release/dev/hip.rst
deleted file mode 100644
index abf9a35..0000000
--- a/Help/release/dev/hip.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-hip
----
-
-* CMake learned to support ``HIP`` as a first-class language that can be
-  enabled via the :command:`project` and :command:`enable_language` commands.
diff --git a/Help/release/dev/ifw-default-version-operator.rst b/Help/release/dev/ifw-default-version-operator.rst
deleted file mode 100644
index 4aeace2..0000000
--- a/Help/release/dev/ifw-default-version-operator.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-ifw-default-version-operator
-----------------------------
-
-* Names given as ``DEPENDS`` or ``DEPENDENCIES`` arguments to
-  :command:`cpack_ifw_configure_component` or
-  :command:`cpack_ifw_configure_component_group` may now contain hyphens.
-  This requires QtIFW 3.1 or later.
diff --git a/Help/release/dev/install-imported-runtime-artifacts.rst b/Help/release/dev/install-imported-runtime-artifacts.rst
deleted file mode 100644
index e2821c1..0000000
--- a/Help/release/dev/install-imported-runtime-artifacts.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-install-imported-runtime-artifacts
-----------------------------------
-
-* The :command:`install` command gained a new ``IMPORTED_RUNTIME_ARTIFACTS``
-  mode, which can be used to install the runtime artifacts of imported targets.
diff --git a/Help/release/dev/install-runtime-dependencies.rst b/Help/release/dev/install-runtime-dependencies.rst
deleted file mode 100644
index 58c92e6..0000000
--- a/Help/release/dev/install-runtime-dependencies.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-install-runtime-dependencies
-----------------------------
-
-* The :command:`install(TARGETS)` command gained new ``RUNTIME_DEPENDENCIES``
-  and ``RUNTIME_DEPENDENCY_SET`` arguments, which can be used to install
-  runtime dependencies using :command:`file(GET_RUNTIME_DEPENDENCIES)`.
-* The :command:`install` command gained a new ``RUNTIME_DEPENDENCY_SET`` mode,
-  which can be used to install runtime dependencies using
-  :command:`file(GET_RUNTIME_DEPENDENCIES)`.
diff --git a/Help/release/dev/install-script-all-components.rst b/Help/release/dev/install-script-all-components.rst
deleted file mode 100644
index e421d3d..0000000
--- a/Help/release/dev/install-script-all-components.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-install-script-all-components
------------------------------
-
-* The :command:`install(SCRIPT|CODE)` command
-  supports a new option ``ALL_COMPONENTS`` which allows
-  the corresponding code to run for every component of
-  a per component installation.
diff --git a/Help/release/dev/link-objects-first.rst b/Help/release/dev/link-objects-first.rst
deleted file mode 100644
index 0c622e7..0000000
--- a/Help/release/dev/link-objects-first.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-link-objects-first
-------------------
-
-* :command:`target_link_libraries` calls referencing object libraries
-  via the :genex:`TARGET_OBJECTS` generator expression now place the
-  object files before all libraries on the link line, regardless of
-  their specified order.  See documentation on
-  :ref:`Linking Object Libraries via \$\<TARGET_OBJECTS\>` for details.
diff --git a/Help/release/dev/linker-launcher.rst b/Help/release/dev/linker-launcher.rst
deleted file mode 100644
index 6563347..0000000
--- a/Help/release/dev/linker-launcher.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-linker-launcher
----------------
-
-* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned to
-  add linker launcher tools along with the linker for ``C``, ``CXX``, ``OBJC``, and
-  ``OBJCXX`` languages. See the :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` variable
-  and :prop_tgt:`<LANG>_LINKER_LAUNCHER` target property for details.
diff --git a/Help/release/dev/list-index-arg-parsing.rst b/Help/release/dev/list-index-arg-parsing.rst
deleted file mode 100644
index 2ea525b..0000000
--- a/Help/release/dev/list-index-arg-parsing.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-list-index-arg-parsing
-----------------------
-
-* The :command:`list` command's ``GET``, ``INSERT``, ``SUBLIST``, and
-  ``REMOVE_AT`` subcommands now error with invalid (i.e., non-integer) values
-  are given as any of their index arguments based on the setting of policy
-  :policy:`CMP0121`.
diff --git a/Help/release/dev/lzma-threads.rst b/Help/release/dev/lzma-threads.rst
deleted file mode 100644
index a481cfa..0000000
--- a/Help/release/dev/lzma-threads.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-lzma-threads
-------------
-
-* The precompiled binaries provided on
-  `cmake.org <https://cmake.org/download/>`_ now support
-  ``liblzma`` multi-threading.  See the :variable:`CPACK_THREADS` and
-  :variable:`CPACK_ARCHIVE_THREADS` variables.
diff --git a/Help/release/dev/message-color.rst b/Help/release/dev/message-color.rst
deleted file mode 100644
index 4acf15e..0000000
--- a/Help/release/dev/message-color.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-message-color
--------------
-
-* Messages printed to a terminal now may be colored by message type.
diff --git a/Help/release/dev/msys.rst b/Help/release/dev/msys.rst
deleted file mode 100644
index ece5de7..0000000
--- a/Help/release/dev/msys.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-msys
-----
-
-* CMake now supports the MSYS runtime environment, much like CYGWIN.
diff --git a/Help/release/dev/ninja-absolute-paths.rst b/Help/release/dev/ninja-absolute-paths.rst
deleted file mode 100644
index 2dfc1b7..0000000
--- a/Help/release/dev/ninja-absolute-paths.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-ninja-absolute-paths
---------------------
-
-* The :ref:`Ninja Generators` now pass source files and include directories
-  to the compiler using absolute paths.  This makes diagnostic messages and
-  debug symbols more consistent, and matches the :ref:`Makefile Generators`.
diff --git a/Help/release/dev/nmake-utf8.rst b/Help/release/dev/nmake-utf8.rst
deleted file mode 100644
index ebbb45b..0000000
--- a/Help/release/dev/nmake-utf8.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-nmake-utf8
-----------
-
-* The :generator:`NMake Makefiles` generator now encodes the generated
-  makefiles as UTF-8 with a BOM when using ``nmake`` from VS 9 or above.
diff --git a/Help/release/dev/objc-std-17-23.rst b/Help/release/dev/objc-std-17-23.rst
deleted file mode 100644
index 5aba395..0000000
--- a/Help/release/dev/objc-std-17-23.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-objc-std-17-23
---------------
-
-* :prop_tgt:`OBJC_STANDARD` gained support for C17 and C23.
diff --git a/Help/release/dev/project-is-top-level.rst b/Help/release/dev/project-is-top-level.rst
deleted file mode 100644
index 568afe0..0000000
--- a/Help/release/dev/project-is-top-level.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-project-is-top-level
---------------------
-
-* :command:`project` now sets variables :variable:`PROJECT_IS_TOP_LEVEL` and
-  :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` to indicate whether it was called
-  in a top level ``CMakeLists.txt`` file.
diff --git a/Help/release/dev/runtime-dll-deps.rst b/Help/release/dev/runtime-dll-deps.rst
deleted file mode 100644
index 831410f..0000000
--- a/Help/release/dev/runtime-dll-deps.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-runtime-dll-deps
-----------------
-
-* A new :genex:`TARGET_RUNTIME_DLLS` generator expression was added.
diff --git a/Help/release/dev/set-cache-variable.rst b/Help/release/dev/set-cache-variable.rst
deleted file mode 100644
index a96242c..0000000
--- a/Help/release/dev/set-cache-variable.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-set-cache-variable
-------------------
-
-* The :command:`set(CACHE)` command no longer removes a normal variable of the
-  same name, if any. See policy :policy:`CMP0126`.
diff --git a/Help/release/dev/xcode_app_extensions.rst b/Help/release/dev/xcode_app_extensions.rst
deleted file mode 100644
index 7be7d82..0000000
--- a/Help/release/dev/xcode_app_extensions.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-xcode_app_extensions
---------------------
-
-* The :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS <XCODE_EMBED_<type>>` target property
-  was added to tell the :generator:`Xcode` generator to embed app extensions
-  such as iMessage sticker packs.
-  Aspects of the embedding can be customized with the
-  :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_PATH <XCODE_EMBED_<type>>`,
-  :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_CODE_SIGN_ON_COPY <XCODE_EMBED_<type>_CODE_SIGN_ON_COPY>` and
-  :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY <XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY>`
-  properties.
diff --git a/Help/release/index.rst b/Help/release/index.rst
index 5dfca05..5938878 100644
--- a/Help/release/index.rst
+++ b/Help/release/index.rst
@@ -15,6 +15,7 @@ Releases
 .. toctree::
    :maxdepth: 1
 
+   3.21 <3.21>
    3.20 <3.20>
    3.19 <3.19>
    3.18 <3.18>
diff --git a/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst
index 534e2ad..1c070b8 100644
--- a/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst
+++ b/Help/variable/CPACK_CUSTOM_INSTALL_VARIABLES.rst
@@ -1,6 +1,8 @@
 CPACK_CUSTOM_INSTALL_VARIABLES
 ------------------------------
 
+.. versionadded:: 3.21
+
 CPack variables (set via e.g. ``cpack -D``, ``CPackConfig.cmake`` or
 :variable:`CPACK_PROJECT_CONFIG_FILE` scripts) are not directly visible in
 installation scripts.  Instead, one can pass a list of ``varName=value``