Merge topic 'doc-3.17-relnotes'

730a53ef1d Help: Organize and revise 3.17 release notes
ad33da76b1 Help: Consolidate 3.17 release notes

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

62 files changed, 317 insertions, 394 deletions

diff --git a/Help/release/3.17.rst b/Help/release/3.17.rst
new file mode 100644
index 0000000..30e6cc3
--- /dev/null
+++ b/Help/release/3.17.rst
@@ -0,0 +1,316 @@
+CMake 3.17 Release Notes
+************************
+
+.. only:: html
+
+  .. contents::
+
+Changes made since CMake 3.16 include the following.
+
+New Features
+============
+
+Generators
+----------
+
+* :manual:`cmake(1)` gained a :generator:`Ninja Multi-Config` generator,
+  which is similar to the :generator:`Ninja` generator but can be used to build
+  multiple configurations at once.
+
+* :ref:`Visual Studio Generators` learned to support per-config sources.
+  Previously only :ref:`Command-Line Build Tool Generators` supported them.
+
+* :ref:`Visual Studio Generators` for VS 2010 and above now support
+  specifying the ``VCTargetsPath`` value for project files in
+  :variable:`CMAKE_GENERATOR_TOOLSET` setting.
+
+* :ref:`Visual Studio Generators` for VS 2010 and above learned to
+  support .NET Standard and .NET Core.  See the
+  :prop_tgt:`DOTNET_TARGET_FRAMEWORK` target property and
+  associated :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK` variable.
+
+Languages
+---------
+
+* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
+  now offers meta-features for the CUDA language standard levels
+  (e.g. ``cuda_std_03``, ``cuda_std_14``).  See
+  :prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES`.
+
+Compilers
+---------
+
+* The IBM XL Fortran compiler is now supported by the :generator:`Ninja`
+  generator.
+
+Command-Line
+------------
+
+* :manual:`cmake(1)` gained a ``--debug-find`` command-line option to
+  enable additional human-readable output on where find commands search.
+
+* :manual:`cmake(1)` gained a ``--trace-format`` command-line option that
+  can be used to set the ``--trace`` output format. Currently, the old
+  human readable and the new JSON format are supported. The new JSON format
+  is easier to parse automatically, than the existing format.
+
+* :manual:`cmake(1)` gained a ``-E rm`` command-line tool that can be
+  used to remove directories and files.  This supersedes the existing
+  ``-E remove`` and ``-E remove_directory`` tools and has better semantics.
+
+Commands
+--------
+
+* The :command:`add_custom_command` command learned to interpret paths in
+  ``DEPENDS`` arguments that are specified relative to the current
+  binary directory.
+
+* The :command:`foreach` learned a new option ``ZIP_LISTS`` to iterate
+  over multiple lists simultaneously.
+
+* The :command:`load_cache(READ_WITH_PREFIX)` command mode is now allowed
+  when using ``cmake -P`` to :ref:`Run a Script <Script Processing Mode>`.
+
+* The :command:`message` command learned to output context provided in
+  the :variable:`CMAKE_MESSAGE_CONTEXT` variable for log levels
+  ``NOTICE`` and below.  Enable this output with the new ``--log-context``
+  command-line option or :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable.
+
+* The :command:`message` command gained new keywords ``CHECK_START``,
+  ``CHECK_PASS`` and ``CHECK_FAIL``.
+
+* :command:`target_compile_options` command now honors the ``BEFORE``
+  keyword more consistently.  See policy :policy:`CMP0101`.
+
+Variables
+---------
+
+* A :variable:`CMAKE_CTEST_ARGUMENTS` variable was added to specify a list
+  of command-line arguments passed to CTest when running through the
+  ``test`` (or ``RUN_TESTS``) target of the generated build system.
+
+* The following variables are now defined inside a :command:`function`:
+
+  - :variable:`CMAKE_CURRENT_FUNCTION`
+  - :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`
+  - :variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`
+  - :variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`
+
+* The :variable:`CMAKE_CUDA_RUNTIME_LIBRARY` variable and
+  :prop_tgt:`CUDA_RUNTIME_LIBRARY` target property were introduced to
+  select the CUDA runtime library used when linking targets that
+  use CUDA.
+
+* The :variable:`CMAKE_FIND_DEBUG_MODE` variable was introduced to
+  print extra find call information during the cmake run to standard
+  error. Output is designed for human consumption and not for parsing.
+
+* The :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable now takes its
+  initial value from the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment
+  variable if no explicit configuration is given.
+
+* The :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable, if not set
+  explicitly, now takes its initial value from the
+  :envvar:`CMAKE_<LANG>_COMPILER_LAUNCHER` environment variable.
+
+* The :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can now be used
+  to persist a log level between CMake runs, unlike the ``--log-level``
+  command line option which only applies to that particular run.
+
+* The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable and
+  :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property were added to
+  tell the :generator:`Xcode` generator to set the value of the
+  ``Custom Working Directory`` schema option.
+
+Properties
+----------
+
+* The :prop_tgt:`AIX_EXPORT_ALL_SYMBOLS` target property and associated
+  :variable:`CMAKE_AIX_EXPORT_ALL_SYMBOLS` variable were created to
+  optionally explicitly disbale automatic export of symbols from shared
+  libraries on AIX.
+
+* The :prop_tgt:`DEPRECATION` target property was added to mark
+  a target as deprecated.  If a linked target is marked as
+  deprecated, a warning with the deprecation message is issued
+  at generate time.
+
+* The :prop_tgt:`INSTALL_NAME_DIR` target property now supports
+  :manual:`generator expressions <cmake-generator-expressions(7)>`.
+  In particular, the ``$<INSTALL_PREFIX>`` generator expression can
+  be used to set the directory relative to the install-time prefix.
+
+* Target properties :prop_tgt:`OSX_COMPATIBILITY_VERSION` and
+  :prop_tgt:`OSX_CURRENT_VERSION` were added to set the
+  ``compatibility_version`` and ``curent_version`` respectively
+  on macOS. For backwards compatibility, if these properties
+  are not set, :prop_tgt:`SOVERSION` and :prop_tgt:`VERSION`
+  are used respectively as fallbacks.
+
+* The :prop_tgt:`VS_DOTNET_DOCUMENTATION_FILE` target property was added
+  to tell :ref:`Visual Studio Generators` to generate a ``DocumentationFile``
+  reference in ``.csproj`` files.
+
+Modules
+-------
+
+* The :module:`ExternalProject` module :command:`ExternalProject_Add`
+  command gained a ``GIT_SUBMODULES_RECURSE`` option to specify whether
+  Git submodules should be updated recursively.  The default is on to
+  preserve existing behavior.
+
+* The :module:`FindCUDAToolkit` module was added to find the
+  CUDA Toolkit without enabling CUDA as a language.
+
+* The :module:`FindCURL` module learned to find CURL using
+  the ``CURLConfig.cmake`` package configuration file generated by
+  CURL's cmake buildsystem.  It also gained a new ``CURL_NO_CURL_CMAKE``
+  option to disable this behavior.
+
+* The :module:`FindFLEX` module's ``FLEX_TARGET`` command now runs ``flex``
+  with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory.
+  See policy :policy:`CMP0098`.
+
+* The :module:`FindLibArchive` module now provides an imported target
+  for libarchive.
+
+* The :module:`FindPython` module has learned to find Python components
+  in active virtual environments managed by ``conda``.
+
+* The :module:`FindPython3` and :module:`FindPython` modules gained,
+  respectively, variable ``Python3_SOABI`` and ``Python_SOABI`` giving
+  the standard extension suffix for modules.
+
+* The :module:`FindLibXml2` module now provides an imported target for the
+  ``xmllint`` executable
+
+Autogen
+-------
+
+* :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` learned to process headers
+  with a ``.hh`` extension.  See policy :policy:`CMP0100`.
+
+CTest
+-----
+
+* The :variable:`CTEST_CONFIGURATION_TYPE` variable is now set from the
+  command line when :manual:`ctest(1)` is invoked with ``-C <cfg>``.
+
+* The :manual:`ctest(1)` gained support for Dr. Memory to run
+  memcheck runs.
+
+* The :manual:`ctest(1)` tool gained a ``--no-tests=<[error|ignore]>`` option
+  to explicitly set and unify the behavior between direct invocation and
+  script mode if no tests were found.
+
+* The :manual:`ctest(1)` tool gained a ``--repeat <mode>:<n>`` option
+  to specify conditions in which to repeat tests.  This generalizes
+  the existing ``--repeat-until-fail <n>`` option to add modes for
+  ``until-pass`` and ``after-timeout``.
+
+* The :command:`ctest_test` command gained a ``REPEAT <mode>:<n>`` option
+  to specify conditions in which to repeat tests.
+
+CPack
+-----
+
+* The :cpack_gen:`CPack DragNDrop Generator` learned to use
+  the :variable:`CPACK_DMG_<component>_FILE_NAME` variable
+  to set a custom filename when packaging components into
+  their own DMGs.
+
+* The :cpack_gen:`CPack DragNDrop Generator` learned to handle
+  RTF formatted license files.  When :variable:`CPACK_DMG_SLA_DIR`
+  variable is set, ``<language>.license.rtf`` is considered, but
+  only as a fallback when the plaintext (``.txt``) file is not found
+  in order to maintain backwards compatibility.
+
+* The :cpack_gen:`CPack NSIS Generator` gained a new variable
+  :variable:`CPACK_NSIS_MUI_HEADERIMAGE` to set the header image.
+  To not break existing setups, it still defaults to
+  :variable:`CPACK_PACKAGE_ICON` if the new variable is not set.
+
+* The :cpack_gen:`CPack NSIS Generator` now supports
+  :variable:`CPACK_NSIS_UNINSTALL_NAME`.
+  This can be used to specify the name of the Uninstall program.
+
+* The :cpack_gen:`CPack NSIS Generator` now supports
+  :variable:`CPACK_NSIS_WELCOME_TITLE` and
+  :variable:`CPACK_NSIS_WELCOME_TITLE_3LINES`.
+  These can be used to specify the welcome page title and display it in 3 lines.
+
+* The :cpack_gen:`CPack NSIS Generator` now supports
+  :variable:`CPACK_NSIS_FINISH_TITLE` and
+  :variable:`CPACK_NSIS_FINISH_TITLE_3LINES`.
+  These can be used to specify the finish page title and display it in 3 lines.
+
+* The :cpack_gen:`CPack productbuild Generator` gained option
+  :variable:`CPACK_PRODUCTBUILD_BACKGROUND` to specify a background image
+  for the macOS installer.
+
+Other
+-----
+
+* :manual:`ccmake(1)` now displays cache values using colors
+  based on the entry type if the terminal supports color.
+
+* :manual:`ccmake(1)` now displays messages and a progress bar during
+  configure and generate.  It will keep the output displayed if any
+  errors or warnings occurred.
+
+Deprecated and Removed Features
+===============================
+
+* An explicit deprecation diagnostic was added for policy ``CMP0068``
+  and policy ``CMP0069`` (``CMP0067`` and below were already deprecated).
+  The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
+  of all policies are deprecated and that projects should port to the
+  NEW behaviors.
+
+* The :cpack_gen:`CPack PackageMaker Generator` generator has been
+  deprecated because Xcode no longer distributes the PackageMaker tools.
+  The undocumented ``OSXX11`` generator has also been deprecated.
+
+* The :manual:`cmake(1)` command-line ``-E remove`` and ``-E remove_directory``
+  tools are deprecated in favor of the new ``-E rm`` tool.  The older tools
+  always returned 0 if a named path did not exist even without the force
+  option and cannot be fixed without breaking compatibility, and so have
+  been superseded.
+
+Other Changes
+=============
+
+* The :manual:`file API <cmake-file-api(7)>` index file now emits a
+  ``multiConfig`` flag specifying whether or not the generator supports
+  multiple output configurations.
+
+* Target link properties :prop_tgt:`INTERFACE_LINK_OPTIONS`,
+  :prop_tgt:`INTERFACE_LINK_DIRECTORIES` and
+  :prop_tgt:`INTERFACE_LINK_DEPENDS` are now transitive over private
+  dependencies on static libraries.
+  See policy :policy:`CMP0099`.
+
+* When using MinGW tools, the :command:`find_library` command no longer
+  finds ``.dll`` files by default.  Instead it expects ``.dll.a`` import
+  libraries to be available.
+
+* The :generator:`MinGW Makefiles` generator no longer issues an error if
+  ``sh.exe`` is present in the environment's ``PATH``.
+
+* The :generator:`Ninja` generator now prefers the first ninja build
+  tool to appear in the ``PATH`` no matter whether it is called
+  ``ninja-build``, ``ninja``, or ``samu``.  Previously the first
+  of those names to appear anywhere in the ``PATH`` would be preferred.
+
+* With SDCC the ``sdar`` tool is now preferred over ``sdcclib`` as librarian.
+  The latter was deprecated by SDCC 3.2.0 and removed in SDCC 3.8.6.
+
+* With SDCC the default flags no longer include any target-specific flags.
+  Previously the default flags were hard-coded for 8051.
+
+* The :variable:`CMAKE_VS_GLOBALS` variable value now applies during
+  compiler identification and in targets created by the
+  :command:`add_custom_target` command.
+
+* The :generator:`Xcode` generator no longer hard-codes ``-Wmost``,
+  ``-Wno-four-char-constants``, and ``-Wno-unknown-pragmas`` warning flags.
diff --git a/Help/release/dev/CMAKE_CURRENT_FUNCTION.rst b/Help/release/dev/CMAKE_CURRENT_FUNCTION.rst
deleted file mode 100644
index a15e63d..0000000
--- a/Help/release/dev/CMAKE_CURRENT_FUNCTION.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-CMAKE_CURRENT_FUNCTION
-----------------------
-
-* Define the following variables inside a function:
-
-    - :variable:`CMAKE_CURRENT_FUNCTION`
-    - :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`
-    - :variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`
-    - :variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`
diff --git a/Help/release/dev/ExternalProject-git-no-recurse.rst b/Help/release/dev/ExternalProject-git-no-recurse.rst
deleted file mode 100644
index b9e09d3..0000000
--- a/Help/release/dev/ExternalProject-git-no-recurse.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-ExternalProject-git-no-recurse
-------------------------------
-
-* The :module:`ExternalProject` module :command:`ExternalProject_Add`
-  command gained a ``GIT_SUBMODULES_RECURSE`` option to specify whether
-  Git submodules should be updated recursively.  The default is on to
-  preserve existing behavior.
diff --git a/Help/release/dev/FindCUDAToolkit-module.rst b/Help/release/dev/FindCUDAToolkit-module.rst
deleted file mode 100644
index 53a69c6..0000000
--- a/Help/release/dev/FindCUDAToolkit-module.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-FindCUDAToolkit-module
-----------------------
-
-* The :module:`FindCUDAToolkit` module was added to find the CUDA Toolkit without enabling CUDA as a language.
diff --git a/Help/release/dev/FindCURL-cmake-package.rst b/Help/release/dev/FindCURL-cmake-package.rst
deleted file mode 100644
index 67c5bbc..0000000
--- a/Help/release/dev/FindCURL-cmake-package.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-FindCURL-cmake-package
-----------------------
-
-* The :module:`FindCURL` module learned to find CURL using
-  the ``CURLConfig.cmake`` package configuration file generated by
-  CURL's cmake buildsystem.  It also gained a new ``CURL_NO_CURL_CMAKE``
-  option to disable this behavior.
diff --git a/Help/release/dev/FindFLEX-work-dir.rst b/Help/release/dev/FindFLEX-work-dir.rst
deleted file mode 100644
index 3569185..0000000
--- a/Help/release/dev/FindFLEX-work-dir.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-FindFLEX-work-dir
------------------
-
-* The :module:`FindFLEX` module's ``FLEX_TARGET`` command now runs ``flex``
-  with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory.
-  See policy :policy:`CMP0098`.
diff --git a/Help/release/dev/FindLibArchive-target.rst b/Help/release/dev/FindLibArchive-target.rst
deleted file mode 100644
index 8998dae..0000000
--- a/Help/release/dev/FindLibArchive-target.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-FindLibArchive-target
----------------------
-
-* The :module:`FindLibArchive` module now returns an ``IMPORTED`` target
-  for libarchive.
diff --git a/Help/release/dev/FindPython-SOABI.rst b/Help/release/dev/FindPython-SOABI.rst
deleted file mode 100644
index 29f7292..0000000
--- a/Help/release/dev/FindPython-SOABI.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-FindPython-SOABI
-----------------
-
-* The :module:`FindPython3` and :module:`FindPython` modules gained,
-  respectively, variable ``Python3_SOABI`` and ``Python_SOABI`` giving
-  the standard extension suffix for modules.
diff --git a/Help/release/dev/FindPythonConda-module.rst b/Help/release/dev/FindPythonConda-module.rst
deleted file mode 100644
index d762fbf..0000000
--- a/Help/release/dev/FindPythonConda-module.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-FindPythonConda-module
-----------------------
-
-* The :module:`FindPython` module has learned to find Python components in active
-  virtual environments managed by ``conda``.
diff --git a/Help/release/dev/Link-properties-transitive.rst b/Help/release/dev/Link-properties-transitive.rst
deleted file mode 100644
index 535b40c..0000000
--- a/Help/release/dev/Link-properties-transitive.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-Link-properties-transitive
---------------------------
-
-* Target link properties :prop_tgt:`INTERFACE_LINK_OPTIONS`,
-  :prop_tgt:`INTERFACE_LINK_DIRECTORIES` and
-  :prop_tgt:`INTERFACE_LINK_DEPENDS` are now transitive over private
-  dependency on static libraries.
-  See policy :policy:`CMP0099`.
diff --git a/Help/release/dev/add_custom_command-depends-path.rst b/Help/release/dev/add_custom_command-depends-path.rst
deleted file mode 100644
index 69a805b..0000000
--- a/Help/release/dev/add_custom_command-depends-path.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-add_custom_command-depends-path
--------------------------------
-
-* The :command:`add_custom_command` command learned to detect paths in
-  ``DEPENDS`` arguments and convert them to paths relative to the current
-  binary directory. This only applies to paths which contain a ``/`` or ``\\``
-  in them because names like ``filename.txt`` could also be target names and
-  cannot be coverted into absolute paths blindly.
diff --git a/Help/release/dev/add_target_deprecation.rst b/Help/release/dev/add_target_deprecation.rst
deleted file mode 100644
index b91eca9..0000000
--- a/Help/release/dev/add_target_deprecation.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-add_target_deprecation
-----------------------
-
-* A :prop_tgt:`DEPRECATION` target property was added to mark
-  a target as deprecated. If a linked target is marked as
-  deprecated, a warning with the deprecation message is issued
-  at generate time.
diff --git a/Help/release/dev/aix-no-export-all.rst b/Help/release/dev/aix-no-export-all.rst
deleted file mode 100644
index fa9ed8d..0000000
--- a/Help/release/dev/aix-no-export-all.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-aix-no-export-all
------------------
-
-* The :prop_tgt:`AIX_EXPORT_ALL_SYMBOLS` target property and associated
-  :variable:`CMAKE_AIX_EXPORT_ALL_SYMBOLS` variable were created to
-  optionally explicitly disbale automatic export of symbols from shared
-  libraries on AIX.
diff --git a/Help/release/dev/autogen_hh_headers.rst b/Help/release/dev/autogen_hh_headers.rst
deleted file mode 100644
index 35ccd61..0000000
--- a/Help/release/dev/autogen_hh_headers.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-autogen_hh_headers
-------------------
-
-* :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` learned to process headers with
-  a ``.hh`` extension.  The new behavior is enabled by policy
-  :policy:`CMP0100`.
diff --git a/Help/release/dev/ccmake-colored-values.rst b/Help/release/dev/ccmake-colored-values.rst
deleted file mode 100644
index b00885d..0000000
--- a/Help/release/dev/ccmake-colored-values.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-ccmake-colored-values
----------------------
-
-* :manual:`ccmake(1)` now displays cache values using colors
-  based on the entry type if the terminal supports color.
diff --git a/Help/release/dev/ccmake_progress_bar_and_log_display.rst b/Help/release/dev/ccmake_progress_bar_and_log_display.rst
deleted file mode 100644
index 5c67c7d..0000000
--- a/Help/release/dev/ccmake_progress_bar_and_log_display.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-ccmake_progress_bar_and_log_display
------------------------------------
-
-* :manual:`ccmake(1)` now displays messages and a progress bar during
-  configure and generate.  It will keep the output displayed if any
-  errors or warnings occurred.
diff --git a/Help/release/dev/cmake-ctest-arguments.rst b/Help/release/dev/cmake-ctest-arguments.rst
deleted file mode 100644
index 72a264a..0000000
--- a/Help/release/dev/cmake-ctest-arguments.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-cmake-ctest-arguments
----------------------
-
-* A :variable:`CMAKE_CTEST_ARGUMENTS` variable was added to specify a list
-  of command-line arguments passed to CTest when running through the
-  ``test`` (or ``RUN_TESTS``) target of the generated build system.
diff --git a/Help/release/dev/command_debug_find.rst b/Help/release/dev/command_debug_find.rst
deleted file mode 100644
index 673852c..0000000
--- a/Help/release/dev/command_debug_find.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-cmake-debug-find
-----------------
-
-* :manual:`cmake(1)` gained a ``--debug-find`` command line
-  option that can be used to provide information on where find
-  commands searched.
-
-* Variable :variable:`CMAKE_FIND_DEBUG_MODE` was introduced to
-  print extra find call information during the cmake run to standard
-  error. Output is designed for human consumption and not for parsing.
diff --git a/Help/release/dev/command_rm.rst b/Help/release/dev/command_rm.rst
deleted file mode 100644
index a58362e..0000000
--- a/Help/release/dev/command_rm.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-Command-Line
---------------------
-
-* :manual:`cmake(1)` gained a ``rm`` command line
-  option that can be used to remove directories (with ``-r`` or ``-R`` flag)
-  and files.
-  If the ``-f`` flag is not specified, attempting to remove a file that
-  doesn't exist returns an non-zero error code.
-  This command deprecates ``remove`` and ``remove_directory``.
-  The ``remove`` implementation was buggy and always returned 0 when ``force``
-  flag was not present and a file didn't exist. It cannot be fixed without
-  breaking backwards compatibility so we introduced ``rm``.
diff --git a/Help/release/dev/compiler-launcher-env.rst b/Help/release/dev/compiler-launcher-env.rst
deleted file mode 100644
index 58519d9..0000000
--- a/Help/release/dev/compiler-launcher-env.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-compiler-launcher-env
----------------------
-
-* The :envvar:`CMAKE_<LANG>_COMPILER_LAUNCHER` environment variable may now be
-  used to initialize the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable.
diff --git a/Help/release/dev/cpack-deprecate-old-macos-generators.rst b/Help/release/dev/cpack-deprecate-old-macos-generators.rst
deleted file mode 100644
index 15d121a..0000000
--- a/Help/release/dev/cpack-deprecate-old-macos-generators.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-cpack-deprecate-old-macos-generators
-------------------------------------
-
-* The :cpack_gen:`CPack PackageMaker Generator` generator has been
-  deprecated because Xcode no longer distributes the PackageMaker tools.
-  The undocumented ``OSXX11`` generator has also been deprecated.
diff --git a/Help/release/dev/cpack-dmg-rtf-for-sla.rst b/Help/release/dev/cpack-dmg-rtf-for-sla.rst
deleted file mode 100644
index 5941796..0000000
--- a/Help/release/dev/cpack-dmg-rtf-for-sla.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-cpack-dmg-rtf-for-sla
----------------------
-
-* The :cpack_gen:`CPack DragNDrop Generator` learned to handle
-  RTF formatted license files.  When :variable:`CPACK_DMG_SLA_DIR`
-  variable is set, <language>.license.rtf is considered, but
-  only as a fallback when the plaintext (.txt) file is not found
-  in order to maintain backwards compatibility.
diff --git a/Help/release/dev/cpack-nsis-headerimage_var.rst b/Help/release/dev/cpack-nsis-headerimage_var.rst
deleted file mode 100644
index d44686b..0000000
--- a/Help/release/dev/cpack-nsis-headerimage_var.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-cpack-nsis-headerimage_var
---------------------------
-
-* The :cpack_gen:`CPack NSIS Generator` gained a new variable
-  :variable:`CPACK_NSIS_MUI_HEADERIMAGE` to set the header image.
-  To not break existing setups, it still defaults to
-  :variable:`CPACK_PACKAGE_ICON` if the new variable is not set.
diff --git a/Help/release/dev/cpack-nsis-uninstaller-name.rst b/Help/release/dev/cpack-nsis-uninstaller-name.rst
deleted file mode 100644
index b7ceb4c..0000000
--- a/Help/release/dev/cpack-nsis-uninstaller-name.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-cpack-nsis-uninstaller-name
----------------------------
-
-* The :cpack_gen:`CPack NSIS Generator` now supports
-  :variable:`CPACK_NSIS_UNINSTALL_NAME`.
-  This can be used to specify the name of the Uninstall program.
diff --git a/Help/release/dev/cpack-nsis-welcome-finish-page-title.rst b/Help/release/dev/cpack-nsis-welcome-finish-page-title.rst
deleted file mode 100644
index 8091d31..0000000
--- a/Help/release/dev/cpack-nsis-welcome-finish-page-title.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-cpack-nsis-welcome-finish-page-title
-------------------------------------
-
-* The :cpack_gen:`CPack NSIS Generator` now supports
-  :variable:`CPACK_NSIS_WELCOME_TITLE` and :variable:`CPACK_NSIS_WELCOME_TITLE_3LINES`.
-  These can be used to specify the welcome page title and display it in 3 lines.
-
-* The :cpack_gen:`CPack NSIS Generator` now supports
-  :variable:`CPACK_NSIS_FINISH_TITLE` and :variable:`CPACK_NSIS_FINISH_TITLE_3LINES`.
-  These can be used to specify the finish page title and display it in 3 lines.
diff --git a/Help/release/dev/cpack-pkg-background.rst b/Help/release/dev/cpack-pkg-background.rst
deleted file mode 100644
index 796f5d6..0000000
--- a/Help/release/dev/cpack-pkg-background.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-cpack-pkg-background
---------------------
-
-* The :cpack_gen:`CPack productbuild Generator` and
-  :cpack_gen:`CPack PackageMaker Generator` gained options
-  :variable:`CPACK_PRODUCTBUILD_BACKGROUND` and
-  :variable:`CPACK_PACKAGEMAKER_BACKGROUND`, respectively,
-  to specify a background image for the macOS installer.
diff --git a/Help/release/dev/ctest-configuration-type.rst b/Help/release/dev/ctest-configuration-type.rst
deleted file mode 100644
index 89e36c4..0000000
--- a/Help/release/dev/ctest-configuration-type.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-ctest-configuration-type
-------------------------
-
-* The :variable:`CTEST_CONFIGURATION_TYPE` variable is now set from the command
-  line when :manual:`ctest(1)` is invoked with ``-C <cfg>``.
diff --git a/Help/release/dev/ctest-drmemory-support.rst b/Help/release/dev/ctest-drmemory-support.rst
deleted file mode 100644
index b329995..0000000
--- a/Help/release/dev/ctest-drmemory-support.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-ctest-drmemory-support
-----------------------
-
-* The :manual:`ctest(1)` gained support for Dr. Memory to run
-  memcheck runs.
diff --git a/Help/release/dev/ctest-no-tests.rst b/Help/release/dev/ctest-no-tests.rst
deleted file mode 100644
index be0f28b..0000000
--- a/Help/release/dev/ctest-no-tests.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-ctest-no-tests
---------------
-
-* The :manual:`ctest(1)` tool gained a ``--no-tests=<[error|ignore]>`` option
-  to explicitly set and unify the behavior between direct invocation and
-  script mode if no tests were found.
diff --git a/Help/release/dev/ctest-repeat.rst b/Help/release/dev/ctest-repeat.rst
deleted file mode 100644
index b1ff59b..0000000
--- a/Help/release/dev/ctest-repeat.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-ctest-repeat
-------------
-
-* The :manual:`ctest(1)` tool gained a ``--repeat <mode>:<n>`` option
-  to specify conditions in which to repeat tests.  This generalizes
-  the existing ``--repeat-until-fail <n>`` option to add modes for
-  ``until-pass`` and ``after-timeout``.
-
-* The :command:`ctest_test` command gained a ``REPEAT <mode>:<n>`` option
-  to specify conditions in which to repeat tests.
diff --git a/Help/release/dev/cuda-gains-meta-features.rst b/Help/release/dev/cuda-gains-meta-features.rst
deleted file mode 100644
index e5e1022..0000000
--- a/Help/release/dev/cuda-gains-meta-features.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-cuda-gains-meta-features
-------------------------
-
-* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
-  now offers meta-features for the CUDA language standard levels
-  (e.g. ``cuda_std_03``, ``cuda_std_14``).  See
-  :prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES`.
diff --git a/Help/release/dev/cuda-runtime-library.rst b/Help/release/dev/cuda-runtime-library.rst
deleted file mode 100644
index 0d5b1f6..0000000
--- a/Help/release/dev/cuda-runtime-library.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-cuda-runtime-library
---------------------
-
-* The :variable:`CMAKE_CUDA_RUNTIME_LIBRARY` variable and
-  :prop_tgt:`CUDA_RUNTIME_LIBRARY` target property were introduced to
-  select the CUDA runtime library used when linking targets that
-  use CUDA.
diff --git a/Help/release/dev/custom-dmg-names.rst b/Help/release/dev/custom-dmg-names.rst
deleted file mode 100644
index 73a70a1..0000000
--- a/Help/release/dev/custom-dmg-names.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-custom-dmg-names
-----------------
-
-* The :cpack_gen:`CPack DragNDrop Generator` learned to use
-  the :variable:`CPACK_DMG_<component>_FILE_NAME` variable
-  to set a custom filename when packaging components into
-  their own DMGs.
diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst
deleted file mode 100644
index 401f4b2..0000000
--- a/Help/release/dev/deprecate-policy-old.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-deprecate-policy-old
---------------------
-
-* An explicit deprecation diagnostic was added for policy ``CMP0068``
-  and policy ``CMP0069`` (``CMP0067`` and below were already deprecated).
-  The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
-  of all policies are deprecated and that projects should port to the
-  NEW behaviors.
diff --git a/Help/release/dev/export-compile-commands-environment-variable.rst b/Help/release/dev/export-compile-commands-environment-variable.rst
deleted file mode 100644
index da9d66b..0000000
--- a/Help/release/dev/export-compile-commands-environment-variable.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-export-compile-commands-environment-variable
---------------------------------------------
-
-* The :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable now takes its
-  initial value from the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment
-  variable if no explicit configuration is given.
diff --git a/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT.rst b/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT.rst
deleted file mode 100644
index a6a5c71..0000000
--- a/Help/release/dev/feature-CMAKE_MESSAGE_CONTEXT.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-feature-CMAKE_MESSAGE_CONTEXT
------------------------------
-
-* The :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can now be used
-  to persist a log level between CMake runs, unlike the ``--log-level``
-  command line option which only applies to that particular run.
-
-* The :command:`message` command learned to output context provided in
-  the :variable:`CMAKE_MESSAGE_CONTEXT` variable for log levels
-  ``NOTICE`` and below.  Enable this output with the new ``--log-context``
-  command-line option or :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable.
diff --git a/Help/release/dev/fileapi-multi-config.rst b/Help/release/dev/fileapi-multi-config.rst
deleted file mode 100644
index e0e2e16..0000000
--- a/Help/release/dev/fileapi-multi-config.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-fileapi-multi-config
---------------------
-
-* The :manual:`file API <cmake-file-api(7)>` index file now emits a
-  ``multiConfig`` flag specifying whether or not the generator supports
-  multiple output configurations.
diff --git a/Help/release/dev/foreach-ZIP_LISTS.rst b/Help/release/dev/foreach-ZIP_LISTS.rst
deleted file mode 100644
index d45d9b9..0000000
--- a/Help/release/dev/foreach-ZIP_LISTS.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-foreach-ZIP_LISTS
------------------
-
-* The :command:`foreach` learned a new option ``ZIP_LISTS`` to iterate
-  over multiple lists simultaneously.
diff --git a/Help/release/dev/fphsa-detect-name-mismatch.rst b/Help/release/dev/fphsa-detect-name-mismatch.rst
deleted file mode 100644
index be51a43..0000000
--- a/Help/release/dev/fphsa-detect-name-mismatch.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-fphsa-name-mismatch
--------------------
-
-* The :module:`FindPackageHandleStandardArgs` module learned to check the
-  package name passed in for typo mistakes.
diff --git a/Help/release/dev/install-name-dir-genex.rst b/Help/release/dev/install-name-dir-genex.rst
deleted file mode 100644
index 0cb41f0..0000000
--- a/Help/release/dev/install-name-dir-genex.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-install-name-dir-genex
-----------------------
-
-* The :prop_tgt:`INSTALL_NAME_DIR` target property now supports
-  :manual:`generator expressions <cmake-generator-expressions(7)>`.
-  In particular, the ``$<INSTALL_PREFIX>`` generator expression can
-  be used to set the directory relative to the install-time prefix.
diff --git a/Help/release/dev/json_trace.rst b/Help/release/dev/json_trace.rst
deleted file mode 100644
index 69a1fb7..0000000
--- a/Help/release/dev/json_trace.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-json-trace
-----------
-
-* :manual:`cmake(1)` gained a ``--trace-format`` command line option that
-  can be used to set the ``--trace`` output format. Currently, the old
-  human readable and the new JSON format are supported. The new JSON format
-  is easier to parse automatically, than the existing format.
diff --git a/Help/release/dev/load_cache-script-mode.rst b/Help/release/dev/load_cache-script-mode.rst
deleted file mode 100644
index d84b08a..0000000
--- a/Help/release/dev/load_cache-script-mode.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-load_cache-script-mode
-----------------------
-
-* The :command:`load_cache(READ_WITH_PREFIX)` command mode is now allowed
-  when using ``cmake -P`` to :ref:`Run a Script <Script Processing Mode>`.
diff --git a/Help/release/dev/mingw-find-no-dll.rst b/Help/release/dev/mingw-find-no-dll.rst
deleted file mode 100644
index 84e7431..0000000
--- a/Help/release/dev/mingw-find-no-dll.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-mingw-find-no-dll
------------------
-
-* When using MinGW tools, the :command:`find_library` command no longer
-  finds ``.dll`` files by default.  Instead it expects ``.dll.a`` import
-  libraries to be available.
diff --git a/Help/release/dev/mingw_no_sh.rst b/Help/release/dev/mingw_no_sh.rst
deleted file mode 100644
index 7008865..0000000
--- a/Help/release/dev/mingw_no_sh.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-mingw-no-sh
------------
-
-* The :generator:`MinGW Makefiles` generator no longer issues an error if
-  ``sh.exe`` is present in the environment's ``PATH``.
diff --git a/Help/release/dev/multi-configuration-ninja.rst b/Help/release/dev/multi-configuration-ninja.rst
deleted file mode 100644
index d9f72cb..0000000
--- a/Help/release/dev/multi-configuration-ninja.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-multi-configuration-ninja
--------------------------
-
-* :manual:`cmake(1)` gained a :generator:`Ninja Multi-Config` generator,
-  which is similar to the :generator:`Ninja` generator but can be used to build
-  multiple configurations at once.
diff --git a/Help/release/dev/new-message-types.rst b/Help/release/dev/new-message-types.rst
deleted file mode 100644
index 8f164b9..0000000
--- a/Help/release/dev/new-message-types.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-new-message-types
------------------
-
-* The :command:`message` command gained new keywords ``CHECK_START``,
-  ``CHECK_PASS`` and ``CHECK_FAIL``.
diff --git a/Help/release/dev/ninja-postgen-commands.rst b/Help/release/dev/ninja-postgen-commands.rst
deleted file mode 100644
index 85b60dc..0000000
--- a/Help/release/dev/ninja-postgen-commands.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-ninja-postgen-commands
-----------------------
-
-* The :generator:`Ninja` generator learned to perform some post-processing on
-  the generated files for more consistent builds.
diff --git a/Help/release/dev/ninja-tool.rst b/Help/release/dev/ninja-tool.rst
deleted file mode 100644
index aa0292e..0000000
--- a/Help/release/dev/ninja-tool.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-ninja-tool
-----------
-
-* The :generator:`Ninja` generator now prefers the first ninja build
-  tool to appear in the ``PATH`` no matter whether it is called
-  ``ninja-build``, ``ninja``, or ``samu``.  Previously the first
-  of those names to appear anywhere in the ``PATH`` would be preferred.
diff --git a/Help/release/dev/osx-version-flags.rst b/Help/release/dev/osx-version-flags.rst
deleted file mode 100644
index 329aca3..0000000
--- a/Help/release/dev/osx-version-flags.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-add_osx_compatiblity_property
------------------------------
-
-* Target properties :prop_tgt:`OSX_COMPATIBILITY_VERSION` and
-  :prop_tgt:`OSX_CURRENT_VERSION` were added to set the
-  ``compatibility_version`` and ``curent_version`` respectively
-  on macOS. For backwards compatibility, if these properties
-  are not set, :prop_tgt:`SOVERSION` and :prop_tgt:`VERSION`
-  are used respectively as fallbacks.
diff --git a/Help/release/dev/sdcc-new-librarian.rst b/Help/release/dev/sdcc-new-librarian.rst
deleted file mode 100644
index 93961ce..0000000
--- a/Help/release/dev/sdcc-new-librarian.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-sdcc-new-librarian
-------------------
-
-* Since sdcc 3.2.0, sdcclib has been deprecated in favor of sdar as librarian.
-  Since sdcc 3.8.6, it has been removed from the distribution.
-  Use sdar if found, else use sdcclib to keep older compatibility.
diff --git a/Help/release/dev/sdcc-no-default-target.rst b/Help/release/dev/sdcc-no-default-target.rst
deleted file mode 100644
index f707dce..0000000
--- a/Help/release/dev/sdcc-no-default-target.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-sdcc-no-default-target
-----------------------
-
-* The default flags used for SDCC no longer include any target-specific flags.
-  Previously the default flags were hard-coded for 8051.
diff --git a/Help/release/dev/target_compile_options-BEFORE-keyword.rst b/Help/release/dev/target_compile_options-BEFORE-keyword.rst
deleted file mode 100644
index 8dafddd..0000000
--- a/Help/release/dev/target_compile_options-BEFORE-keyword.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-target_compile_options-BEFORE-keyword
--------------------------------------
-
-* :command:`target_compile_options` command learns to honor ``BEFORE`` keyword
-  in all scopes. See policy :policy:`CMP0101`.
diff --git a/Help/release/dev/vs-dotnet-standard-core.rst b/Help/release/dev/vs-dotnet-standard-core.rst
deleted file mode 100644
index 9bb292e..0000000
--- a/Help/release/dev/vs-dotnet-standard-core.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-vs-dotnet-standard-core
------------------------
-
-* :ref:`Visual Studio Generators` for VS 2010 and above learned to
-  support .NET Standard and .NET Core.  See the
-  :prop_tgt:`DOTNET_TARGET_FRAMEWORK` target property and
-  associated :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK` variable.
diff --git a/Help/release/dev/vs-per-config-sources.rst b/Help/release/dev/vs-per-config-sources.rst
deleted file mode 100644
index bf7572b..0000000
--- a/Help/release/dev/vs-per-config-sources.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-vs-per-config-sources
----------------------
-
-* :ref:`Visual Studio Generators` learned to support per-config sources.
-  Previously only :ref:`Command-Line Build Tool Generators` supported them.
diff --git a/Help/release/dev/vs-vctargetspath.rst b/Help/release/dev/vs-vctargetspath.rst
deleted file mode 100644
index d40af34..0000000
--- a/Help/release/dev/vs-vctargetspath.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-vs-vctargetspath
-----------------
-
-* With :ref:`Visual Studio Generators` for VS 2010 and above,
-  the :variable:`CMAKE_GENERATOR_TOOLSET` setting gained an option
-  to specify the ``VCTargetsPath`` value for project files.
-
-* The :variable:`CMAKE_VS_GLOBALS` variable value now applies during
-  compiler identification and in targets created by the
-  :command:`add_custom_target` command.
diff --git a/Help/release/dev/vs_dotnet_documentation_file.rst b/Help/release/dev/vs_dotnet_documentation_file.rst
deleted file mode 100644
index fdffb1c..0000000
--- a/Help/release/dev/vs_dotnet_documentation_file.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-vs_dotnet_documentation_file
-----------------------------
-
-* The :prop_tgt:`VS_DOTNET_DOCUMENTATION_FILE` target property was added
-  to tell :ref:`Visual Studio Generators` to generate a ``DocumentationFile``
-  reference in ``.csproj`` files.
diff --git a/Help/release/dev/xcode-default-warnings.rst b/Help/release/dev/xcode-default-warnings.rst
deleted file mode 100644
index a9a2e49..0000000
--- a/Help/release/dev/xcode-default-warnings.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-xcode-default-warnings
-----------------------
-
-* The :generator:`Xcode` generator no longer hard-codes ``-Wmost``,
-  ``-Wno-four-char-constants``, and ``-Wno-unknown-pragmas`` warning flags.
diff --git a/Help/release/dev/xcode-scheme-env.rst b/Help/release/dev/xcode-scheme-env.rst
deleted file mode 100644
index 238cb61..0000000
--- a/Help/release/dev/xcode-scheme-env.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-xcode-scheme-env
-----------------
-
-* The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable was added
-  to initialize the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property.
diff --git a/Help/release/dev/xcode-scheme-workdir.rst b/Help/release/dev/xcode-scheme-workdir.rst
deleted file mode 100644
index 8eb5ed8..0000000
--- a/Help/release/dev/xcode-scheme-workdir.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-xcode-scheme-workdir
---------------------
-
-* The Xcode generator learnt to set the value of the
-  ``Custom Working Directory`` schema
-  option with the :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY`
-  target property.
diff --git a/Help/release/dev/xlf-ninja.rst b/Help/release/dev/xlf-ninja.rst
deleted file mode 100644
index 916e713..0000000
--- a/Help/release/dev/xlf-ninja.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-xlf-ninja
----------
-
-* The IBM XL Fortran compiler is now supported by the :generator:`Ninja`
-  generator.
diff --git a/Help/release/dev/xmllint-target.rst b/Help/release/dev/xmllint-target.rst
deleted file mode 100644
index 19c69bf..0000000
--- a/Help/release/dev/xmllint-target.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-xmllint-target
---------------
-
-* The :module:`FindLibXml2` module now provides an imported target for the xmllint executable
diff --git a/Help/release/index.rst b/Help/release/index.rst
index a4585a5..22b1a09 100644
--- a/Help/release/index.rst
+++ b/Help/release/index.rst
@@ -15,6 +15,7 @@ Releases
 .. toctree::
    :maxdepth: 1
 
+   3.17 <3.17>
    3.16 <3.16>
    3.15 <3.15>
    3.14 <3.14>