Help: Consolidate 3.24 release notes

Run the `Utilities/Release/consolidate-relnotes.bash` script to move
notes from `Help/release/dev/*` into `Help/release/3.24.rst`.

1 files changed, 306 insertions, 0 deletions

diff --git a/Help/release/3.24.rst b/Help/release/3.24.rst
new file mode 100644
index 0000000..803d7dc
--- /dev/null
+++ b/Help/release/3.24.rst
@@ -0,0 +1,306 @@
+CMake 3.24 Release Notes
+************************
+
+.. only:: html
+
+  .. contents::
+
+Changes made since CMake 3.23 include the following.
+
+* The ADSP compiler (SHARC and Blackfin) now supports
+  both CCES and VDSP++ installations,
+  with required configuration now done in the compiler module itself
+  rather than the Generic-ADSP platform module.
+
+* A dedicated ``ADSP`` platform has been added
+  to replace the existing ``Generic-ADSP`` implementation.
+  This features automatic detection of the latest CCES/VDSP++ install
+  and compiler selection (``cc21k`` vs. ``ccblkfn``)
+  based off of the :variable:`CMAKE_SYSTEM_PROCESSOR` variable.
+
+* The :genex:`LINK_LIBRARY` generator expression gained the ability to link
+  frameworks in various ways when targeting ``Apple`` platforms. The following
+  new features were added:
+
+  * ``FRAMEWORK``
+  * ``NEEDED_FRAMEWORK``
+  * ``REEXPORT_FRAMEWORK``
+  * ``WEAK_FRAMEWORK``
+
+* The :genex:`LINK_LIBRARY` generator expression gained the ability to link
+  libraries in various ways when targeting ``Apple`` platforms. The following
+  new features were added:
+
+  * ``NEEDED_LIBRARY``
+  * ``REEXPORT_LIBRARY``
+  * ``WEAK_LIBRARY``
+
+* :command:`cmake_host_system_information` command gains the capability, on
+  ``Windows`` platform, to  query the registry.
+
+* The :manual:`cmake(1)` ``-E tar`` command gained the ``--touch`` option
+  to keep the current local timestamp instead of extracting file timestamps
+  from the archive.
+
+* :manual:`cmake(1)` gained the ``--fresh`` command-line option to remove
+  any existing ``CMakeCache.txt`` when configuring a build tree.
+
+* The :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable was added to allow
+  injecting custom code at the site of the first :command:`project` call,
+  after the host and target platform details have been determined.
+
+* The :manual:`cmake(1)` ``-E`` commands ``cat`` and ``env`` learned to respect
+  a double dash (``--``) argument that acts as a delimiter indicating the end of
+  options. Any following arguments are treated as operands/positional arguments,
+  even if they begin with a dash ``-`` character.
+
+* The :variable:`CMAKE_COLOR_DIAGNOSTICS` variable was added to control
+  color diagnostics generated by compilers.  This variable also controls
+  color buildsystem messages with :ref:`Makefile Generators`, replacing
+  :variable:`CMAKE_COLOR_MAKEFILE`.
+
+  The :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment was added to set
+  a default value for :variable:`CMAKE_COLOR_DIAGNOSTICS`.
+
+* The :module:`CPack` module no longer enables the SLA by default in the
+  :cpack_gen:`CPack DragNDrop Generator`.  See policy :policy:`CMP0133`
+  and the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` variable.
+
+* The :cpack_gen:`CPack WIX Generator` gained a new variable,
+  :variable:`CPACK_WIX_ARCHITECTURE`, to specify the installer architecture
+  in order to support computers running Windows for ARM.
+
+* CPack now supports the :variable:`CPACK_THREADS` option for ``zstd``
+  compression when compiled with libarchive 3.6 or higher.  It is
+  supported by official CMake binaries available on ``cmake.org``.
+
+* :manual:`ctest(1)` gained a ``--test-output-truncation`` option (and
+  corresponding :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable) to
+  specify the truncation mode once the maximum test output size has been
+  reached. Possible values are ``tail`` (default), ``middle`` or ``head``.
+* :manual:`cmake-presets(7)` files now support schema version ``5``.
+* :manual:`cmake-presets(7)` files gained support for specifying a
+  ``testOutputTruncation`` field in test presets, which specifies the truncation
+  mode once the maximum test output size has been reached.
+
+* The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated
+  :prop_tgt:`CUDA_ARCHITECTURES` target property now support the
+  special ``native`` value to compile for the architectures(s)
+  of the host's GPU(s).
+
+* The :command:`cmake_language` command gained a new
+  ``SET_DEPENDENCY_PROVIDER`` sub-command.  When a dependency provider is set,
+  calls to :command:`find_package` and :command:`FetchContent_MakeAvailable`
+  can be redirected through a custom command, which can choose to fulfill the
+  request directly, modify how the request is processed, or leave it to be
+  fulfilled by the built-in implementation.  See :ref:`dependency_providers`.
+
+* The :command:`ExternalProject_Add` command gained a new
+  ``DOWNLOAD_EXTRACT_TIMESTAMP`` option for controlling whether the timestamps
+  of extracted contents are set to match those in the archive when the ``URL``
+  download method is used. A new policy :policy:`CMP0135` was added to control
+  the default behavior when the new option is not used.
+
+* Integration has been added between the :module:`FetchContent` module and the
+  :command:`find_package` command, enabling the following new capabilities:
+
+  * :command:`FetchContent_MakeAvailable` can now try to satisfy a dependency
+    by calling :command:`find_package` first.  A new
+    :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable controls whether
+    this is done by default for all dependencies, is opt-in per dependency,
+    or is disabled entirely.
+
+  * :command:`find_package` can be re-routed to call
+    :command:`FetchContent_MakeAvailable` instead.  A new read-only
+    :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable points to a
+    directory where config package files can be located to facilitate these
+    re-routed calls.
+
+* Add the fields ``RANGE_START`` and ``RANGE_END`` to ``file(DOWNLOAD)``.
+  Those fields provide a convenient way to specify the range, passed to the
+  libcurl, which can be useful for downloading parts of big binary files.
+
+* The :command:`find_file`, :command:`find_library`, :command:`find_path`,
+  :command:`find_package`, and :command:`find_program` commands have gained
+  the `NO_CMAKE_INSTALL_PREFIX` option to control searching
+  `CMAKE_INSTALL_PREFIX`.
+
+* Adds support for :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to toggle
+  behavior of the :command:`find_file`, :command:`find_library`, :command:`find_path`,
+  :command:`find_package`, and :command:`find_program` commands new
+  `NO_CMAKE_INSTALL_PREFIX` option.
+
+* The :module:`FindGLUT` module no longer provides the undocumented
+  result variables ``GLUT_LIBRARY`` and ``GLUT_INCLUDE_PATH``.
+
+* :command:`find_file`, :command:`find_path`, :command:`find_library`,
+  :command:`find_program`, and :command:`find_package` commands gain the
+  capability to specify which registry views must be queried.
+
+* The :module:`FindJNI` module now provides imported targets.
+
+* The :module:`FindMatlab` module :command:`matlab_add_mex` function
+  gained a ``NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES`` option to disable
+  automatic linking of MATLAB libraries.
+
+* The :command:`find_package` command gained a `GLOBAL` option that
+  allows for the promotion of imported targets to global scope fur the
+  duration of the :command:`find_package` call.
+
+* Adds support for :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` to
+  toggle behavior of the :command:`find_package` command's new GLOBAL option
+
+* The :module:`FindZLIB` learned a new ``ZLIB_USE_STATIC_LIBS`` variable to
+  search only for static libraries.
+
+* The :genex:`LINK_GROUP` generator expression was added to manage the grouping
+  of libraries during the link step. The variables
+  :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` and
+  :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` are used to define features
+  usable by the :genex:`LINK_GROUP` generator expression.
+
+* The :genex:`LINK_LIBRARY` generator expression was added to manage how
+  libraries are specified during the link step. The variables
+  :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
+  :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` are used to define features
+  usable by the :genex:`LINK_LIBRARY` generator expression. Moreover, the
+  :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
+  :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties are available
+  to resolve incompatible features.
+
+* The :genex:`PATH_EQUAL` generator expression was added to manage path
+  comparisons.
+
+* The :genex:`PATH` generator expression was added to manage paths.
+
+* A new predefined target `RERUN_CMAKE` is added for
+  :generator:`Green Hills MULTI` generator to easily rerun
+  CMake if any CMake files were updated.
+
+* The :command:`if` command gains the capability to compare paths by using the
+  ``PATH_EQUAL`` operator. See policy :policy:`CMP0139`.
+
+* The :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
+  :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties
+  were added to express usage requirements affecting a consumer's
+  direct link dependencies.
+
+* The :prop_tgt:`LINK_LIBRARIES` target property now supports
+  the :genex:`$<LINK_ONLY:...>` generator expression.
+  See policy :policy:`CMP0131`.
+
+* The :genex:`LINK_LIBRARY` generator expression gained the feature
+  ``WHOLE_ARCHIVE`` to force load of all members in a static library. This
+  feature is supported on the following target platforms:
+
+  * all ``Apple`` variants
+  * ``Linux``
+  * all ``BSD`` variants
+  * ``SunOS``
+  * ``Windows``
+  * ``CYGWIN``
+  * ``MSYS``
+
+* LLVM's `flang`_ Fortran compiler is now supported, with compiler id ``LLVMFlang``.
+
+.. _`flang`: https://github.com/llvm/llvm-project/tree/main/flang
+
+* The :generator:`MSYS Makefiles` and :generator:`MinGW Makefiles`
+  generators, when a compiler is not explicitly specified, now select
+  the first compiler (of any name) found in directories listed by the
+  ``PATH`` environment variable.
+
+* With MSVC compilers, debug configurations now use ``-ZI`` by default
+  instead of ``/Zi``.  See policy :policy:`CMP0138`.
+
+* The :module:`FindPkgConfig` module learned to find static libraries
+  in addition to the default search for shared libraries.
+  :command:`pkg_check_modules` gained a ``STATIC_TARGET`` option
+  to make the imported target reference static libraries.
+
+* :manual:`cmake-presets(7)` files now support a ``${pathListSep}`` macro,
+  which expands to ``:`` or ``;`` based on the platform.
+
+* The precompiled macOS binaries provided on
+  `cmake.org <https://cmake.org/download/>`_ no longer attach a SLA
+  to the ``.dmg`` packages.  This was removed because macOS 12 deprecated
+  the tools used to attach ``.dmg`` resources.
+
+* The deprecated ``PackageMaker`` :manual:`cpack(1)` generator has
+  been removed.
+
+* The :genex:`LINK_GROUP` generator expression gained the ability to manage, on
+  ``Linux`` and ``BSD`` systems, circular references between static libraries
+  by using ``RESCAN`` feature.
+
+* CMake no longer sets environment variables like :envvar:`CC`, :envvar:`CXX`,
+  etc. when enabling the corresponding language during the first CMake run in
+  a build directory. See policy :policy:`CMP0132`.
+
+* Added the new :genex:`TARGET_BUNDLE_DIR_NAME` generator expression
+  which evaluates to the name of the bundle directory for a given bundle
+  target.
+
+* Add the field ``global_frame`` to the json-v1 trace format. This
+  frame tracks the depth of the call stack globally across all
+  ``CMakeLists.txt`` files involved in the trace, and will let tools
+  reconstruct stack traces that span from the top-level ``CMakeLists.txt``
+  file of the project.
+
+* Add the field ``line_end`` to the json-v1 trace format. This
+  field tells you the line in file ``file`` at which the function
+  call ends. Tools can use this new field, together with ``line``
+  and ``file``, to map traces to lines of CMake source code.
+
+* The :command:`try_compile` command
+  :ref:`whole-project <Try Compiling Whole Projects>` signature
+  now propagates platform variables.  See policy :policy:`CMP0137`.
+
+* The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable
+  was added to tell the :command:`try_compile` command not to
+  pass any platform variables to the test project.
+
+* A new :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` target property was added,
+  which can be used to verify that all headers in header sets can be used on
+  their own.
+* A new :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable was added,
+  which is used to initialize the :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS`
+  target property.
+* A new :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY` target property was added,
+  which can be used to specify which header sets should be verified by
+  :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS`.
+
+* The :prop_tgt:`VS_NO_COMPILE_BATCHING` target property was added to
+  tell :ref:`Visual Studio Generators` whether to disable compiler parallelism
+  and call the compiler with one c/cpp file at a time.
+
+* The :prop_tgt:`VS_DOTNET_STARTUP_OBJECT` target property was added to
+  tell :ref:`Visual Studio Generators` which startup class shall be used
+  when the program or project is executed. This is necessary when more
+  than one ``static void Main(string[])`` function signature is available
+  in a managed .NET project.
+
+* :ref:`Visual Studio Generators` now support ``SYSTEM`` headers.
+
+* The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` variable and
+  :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property were introduced to
+  select the runtime library used by compilers targeting the Watcom ABI.
+  See policy :policy:`CMP0136`.
+
+* Added the Target Property :prop_tgt:`COMPILE_WARNING_AS_ERROR` and the
+  Variable :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` which initializes the
+  Target Property. If :prop_tgt:`COMPILE_WARNING_AS_ERROR` is true, it expands
+  to a different flag depending on the compiler such that any warnings at
+  compile will be treated as errors.
+
+* :manual:`cmake(1)` gained the command-line option
+  ``--compile-no-warning-as-error`` which causes the values of
+  the :prop_tgt:`COMPILE_WARNING_AS_ERROR` target property and
+  :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable to be ignored.
+
+* The :command:`while` command now diagnoses errors during condition
+  evaluation.  See policy :policy:`CMP0130`.
+
+* The Xcode generator learned to handle global and target specific
+  ``xcconfig`` files with the :variable:`CMAKE_XCODE_XCCONFIG`
+  variable and :prop_tgt:`XCODE_XCCONFIG` target property.