Help: Organize and revise 3.31 release notes
Add section headers similar to the 3.30 release notes and move each
individual bullet into an appropriate section. Revise a few bullets.
diff --git a/Help/release/3.31.rst b/Help/release/3.31.rst
index 7c516fc..b738c3d 100644
--- a/Help/release/3.31.rst
+++ b/Help/release/3.31.rst
@@ -7,37 +7,170 @@
Changes made since CMake 3.30 include the following.
-* On AIX, shared libraries may now be created as shared library archives.
- See the :variable:`CMAKE_AIX_SHARED_LIBRARY_ARCHIVE` variable
- and :prop_tgt:`AIX_SHARED_LIBRARY_ARCHIVE` target property.
+New Features
+============
-* The :prop_tgt:`MACOSX_FRAMEWORK_BUNDLE_NAME <MACOSX_FRAMEWORK_INFO_PLIST>`
- target property was added to set the ``CFBundleName`` key in an Apple
- :prop_tgt:`FRAMEWORK`'s ``Info.plist`` file.
+Presets
+-------
-* The :variable:`CMAKE_HOST_EXECUTABLE_SUFFIX` variable was added to
- provide suffix for executable names on the host platform.
+* :manual:`cmake-presets(7)` files may now include comments using the key
+ ``$comment`` at any level within the JSON object to provide documentation.
+
+* :manual:`cmake-presets(7)` files may now request graphviz output using
+ the ``graphviz`` key in a configure preset.
+
+Generators
+----------
+
+* The :ref:`Ninja Generators` and :ref:`Makefile Generators` now produce
+ a ``codegen`` build target. See policy :policy:`CMP0171`. It drives a
+ subset of the build graph sufficient to run custom commands created with
+ :command:`add_custom_command`'s new ``CODEGEN`` option.
+
+Command-Line
+------------
+
+* The :option:`cmake --workflow` mode now accepts a preset name as the first
+ argument, allowing the simpler command line
+ :option:`cmake --workflow \<preset\> <cmake--workflow --preset>`.
* The :option:`cmake -LR[A][H]` option was added to list cache entries
whose names match a regular expression.
+Compilers
+---------
+
+* The LFortran compiler is now supported with
+ :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``LFortran``.
+
+Commands
+--------
+
+* The :command:`add_custom_command` command gained a ``CODEGEN`` option
+ to mark a custom command's outputs as dependencies of a ``codegen`` target.
+ See policy :policy:`CMP0171`.
+
* The :command:`cmake_pkg_config` command was added as an endpoint for using
CMake's native pkg-config format parser. The only supported option in this
release is ``EXTRACT``, which provides low-level access to the values
produced by parsing a pkg-config file. For most users, this is not yet a
suitable replacement for the :module:`FindPkgConfig` module.
-* When executing a CMake workflow preset, the ``--preset`` option can now be
- omitted, allowing the simpler command line
- :option:`cmake --workflow \<preset\> <cmake--workflow --preset>`.
+* The :command:`file(ARCHIVE_CREATE)` command gained a ``WORKING_DIRECTORY``
+ option to specify a working directory for the archiving process.
-* The :ref:`Ninja Generators` and :ref:`Makefile Generators` now produce
- a ``codegen`` build target. See policy :policy:`CMP0171`. It drives a
- subset of the build graph sufficient to run custom commands created with
- :command:`add_custom_command`'s new ``CODEGEN`` option.
+* The :command:`install(FILES)` and :command:`install(DIRECTORY)` commands'
+ ``TYPE`` argument gained support for a ``LIBEXEC`` type.
-* The :command:`add_custom_command` command gained a ``CODEGEN`` option
- to mark a custom commands outputs as dependencies of a ``codegen`` target.
+Variables
+---------
+
+* The :variable:`CMAKE_AIX_SHARED_LIBRARY_ARCHIVE` variable and corresponding
+ :prop_tgt:`AIX_SHARED_LIBRARY_ARCHIVE` target property were added to
+ create shared libraries on AIX as shared library archives.
+
+* The :variable:`CMAKE_EXPORT_BUILD_DATABASE` variable, a corresponding
+ :envvar:`CMAKE_EXPORT_BUILD_DATABASE` environment variable, and an
+ :prop_tgt:`EXPORT_BUILD_DATABASE` target property, were added to
+ enable exporting C++ module compile commands.
+ This is only supported with :ref:`Ninja Generators`.
+
+* The :variable:`CMAKE_HOST_EXECUTABLE_SUFFIX` variable was added to
+ provide the suffix for executable names on the host platform.
+
+* The :variable:`CMAKE_<LANG>_HOST_COMPILER_ID` and
+ :variable:`CMAKE_<LANG>_HOST_COMPILER_VERSION` variables were added,
+ where ``<LANG>`` is either ``CUDA`` or ``HIP``. They are populated
+ when :variable:`CMAKE_<LANG>_COMPILER_ID` is ``NVIDIA`` to identify
+ NVCC's host compiler.
+
+* The :variable:`CMAKE_<LANG>_STANDARD_LINK_DIRECTORIES` variable was added.
+ Toolchain files can set this variable to control which link library directory
+ paths are always passed to the compiler for the specified language.
+
+* The :variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable and
+ corresponding :prop_tgt:`LINK_LIBRARIES_STRATEGY` target
+ property were added to optionally specify the strategy
+ CMake uses to generate link lines.
+
+Properties
+----------
+
+* The :prop_tgt:`MACOSX_FRAMEWORK_BUNDLE_NAME <MACOSX_FRAMEWORK_INFO_PLIST>`
+ target property was added to set the ``CFBundleName`` key in an Apple
+ :prop_tgt:`FRAMEWORK`'s ``Info.plist`` file.
+
+* The :prop_tgt:`UNITY_BUILD` target property now supports the
+ ``CUDA`` language.
+
+* The :prop_tgt:`VS_FRAMEWORK_REFERENCES` target property was added
+ to tell :ref:`Visual Studio Generators` to add framework references.
+
+Modules
+-------
+
+* Check modules now support a ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
+ The following modules gained this support:
+
+ * :module:`CMakePushCheckState`
+ * :module:`CheckCCompilerFlag`
+ * :module:`CheckCSourceCompiles`
+ * :module:`CheckCSourceRuns`
+ * :module:`CheckCXXCompilerFlag`
+ * :module:`CheckCXXSourceCompiles`
+ * :module:`CheckCXXSourceRuns`
+ * :module:`CheckCXXSymbolExists`
+ * :module:`CheckCompilerFlag`
+ * :module:`CheckFortranCompilerFlag`
+ * :module:`CheckFortranFunctionExists`
+ * :module:`CheckFortranSourceCompiles`
+ * :module:`CheckFortranSourceRuns`
+ * :module:`CheckFunctionExists`
+ * :module:`CheckIncludeFile`
+ * :module:`CheckIncludeFileCXX`
+ * :module:`CheckIncludeFiles`
+ * :module:`CheckOBJCCompilerFlag`
+ * :module:`CheckLibraryExists`
+ * :module:`CheckOBJCCompilerFlag`
+ * :module:`CheckOBJCSourceCompiles`
+ * :module:`CheckOBJCSourceRuns`
+ * :module:`CheckOBJCXXCompilerFlag`
+ * :module:`CheckOBJCXXSourceCompiles`
+ * :module:`CheckOBJCXXSourceRuns`
+ * :module:`CheckPrototypeDefinition`
+ * :module:`CheckSourceCompiles`
+ * :module:`CheckSourceRuns`
+ * :module:`CheckStructHasMember`
+ * :module:`CheckSymbolExists`
+ * :module:`CheckTypeSize`
+ * :module:`CheckVariableExists`
+
+* The :module:`CMakePackageConfigHelpers` module's
+ :command:`generate_apple_platform_selection_file` function
+ gained support for iOS Mac Catalyst.
+
+* The :module:`GoogleTest` module :command:`gtest_discover_tests` command
+ gained a new ``DISCOVERY_EXTRA_ARGS`` keyword. It allows extra arguments
+ to be appended to the command line when querying for the list of tests.
+
+* The :module:`FindCUDAToolkit` module now provides a ``CUDA::nvml_static``
+ target.
+
+* The :module:`FindOpenMP` module gained support for the ``CUDA`` language.
+
+CTest
+-----
+
+* The :command:`ctest_submit` command and :option:`ctest -T Submit <ctest -T>`
+ step now verify TLS server certificates for connections to ``https://`` URLs
+ by default. See the :variable:`CTEST_TLS_VERIFY` variable for details.
+
+* The :command:`ctest_submit` command and :option:`ctest -T Submit <ctest -T>`
+ step now require TLS 1.2 or higher for connections to ``https://`` URLs by
+ default. See the :variable:`CTEST_TLS_VERSION` variable for details.
+
+CPack
+-----
* The :cpack_gen:`CPack DEB Generator` gained a
:variable:`CPACK_DEBIAN_PACKAGE_MULTIARCH` option
@@ -56,14 +189,42 @@
in the :cpack_gen:`CPack WIX Generator`. See policy :policy:`CMP0172`
and the :variable:`CPACK_WIX_INSTALL_SCOPE` variable.
-* The :variable:`CMAKE_<LANG>_HOST_COMPILER_ID` and
- :variable:`CMAKE_<LANG>_HOST_COMPILER_VERSION` variables were added,
- where ``<LANG>`` is either ``CUDA`` or ``HIP``. They are populated
- when :variable:`CMAKE_<LANG>_COMPILER_ID` is ``NVIDIA`` to identify
- NVCC's host compiler.
+Deprecated and Removed Features
+===============================
-* The :module:`FindCUDAToolkit` module now provides a ``CUDA::nvml_static``
- target.
+* Compatibility with versions of CMake older than 3.10 is now deprecated
+ and will be removed from a future version. Calls to
+ :command:`cmake_minimum_required` or :command:`cmake_policy` that set
+ the policy version to an older value now issue a deprecation diagnostic.
+
+* The :module:`CMakeFindFrameworks` module has been deprecated via
+ :policy:`CMP0173`. Projects should use :command:`find_library` instead.
+
+* The :generator:`Visual Studio 12 2013` generator has been removed.
+
+Other Changes
+=============
+
+* When static libraries on link lines are de-duplicated (by policy
+ :policy:`CMP0156`), the first occurrence is now kept on all platforms.
+ See policy :policy:`CMP0179`.
+
+* Empty list elements in the :prop_tgt:`TEST_LAUNCHER` and
+ :prop_tgt:`CROSSCOMPILING_EMULATOR` target properties are now preserved by:
+
+ * The :command:`add_test` command.
+ * The :command:`ExternalData_Add_Test` command from the
+ :module:`ExternalData` module.
+ * The :command:`gtest_add_tests` and :command:`gtest_discover_tests`
+ commands from the :module:`GoogleTest` module.
+ Empty list elements after the ``EXTRA_ARGS`` keyword of these
+ two commands are also now preserved.
+
+ See policy :policy:`CMP0178`.
+
+* The :command:`execute_process` command's ``ENCODING`` option,
+ meaningful on Windows, now defaults to ``UTF-8``.
+ See policy :policy:`CMP0176`.
* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands now
verify TLS server certificates for connections to ``https://`` URLs by
@@ -73,204 +234,19 @@
Users may set the :envvar:`CMAKE_TLS_VERIFY` environment
variable to ``0`` to restore the old default.
-* The :command:`ctest_submit` command and :option:`ctest -T Submit <ctest -T>`
- step now verify TLS server certificates for connections to ``https://`` URLs
- by default. See the :variable:`CTEST_TLS_VERIFY` variable for details.
-
* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands now
require TLS 1.2 or higher for connections to ``https://`` URLs by default.
See the :variable:`CMAKE_TLS_VERSION` variable for details.
-* The :command:`ctest_submit` command and :option:`ctest -T Submit <ctest -T>`
- step now require TLS 1.2 or higher for connections to ``https://`` URLs by
- default. See the :variable:`CTEST_TLS_VERSION` variable for details.
-
-* The :module:`CMakeFindFrameworks` module has been deprecated via
- :policy:`CMP0173`. Projects should use :command:`find_library` instead.
-
-* Compatibility with versions of CMake older than 3.10 is now deprecated
- and will be removed from a future version. Calls to
- :command:`cmake_minimum_required` or :command:`cmake_policy` that set
- the policy version to an older value now issue a deprecation diagnostic.
-
* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command was updated
to more closely match the dynamic loader's behavior on Linux.
-* The :command:`execute_process` command's ``ENCODING`` option,
- meaningful on Windows, now defaults to ``UTF-8``.
- See policy :policy:`CMP0176`.
-
-* The :command:`file(ARCHIVE_CREATE)` command gained a ``WORKING_DIRECTORY``
- option to specify a working directory for the archiving process.
-
-* The :module:`FindOpenMP` module gained support for the ``CUDA`` language.
-
-* The :command:`gtest_discover_tests` command gained a new
- ``DISCOVERY_EXTRA_ARGS`` keyword. It allows extra arguments to be
- appended to the command line when querying for the list of tests.
-
-* The :command:`install(FILES)` and :command:`install(DIRECTORY)` commands'
- ``TYPE`` argument gained support for a ``LIBEXEC`` type.
-
-* The :module:`CMakePackageConfigHelpers` module's
- :command:`generate_apple_platform_selection_file` function
- gained support iOS Mac Catalyst.
-
-* The LFortran compiler is now supported with
- :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``LFortran``.
-
-* The :variable:`CMAKE_LINK_LIBRARIES_STRATEGY` variable and
- corresponding :prop_tgt:`LINK_LIBRARIES_STRATEGY` target
- property were added to optionally specify the strategy
- CMake uses to generate link lines.
-
-* The :module:`CMakePushCheckState` module ``cmake_push_check_state``,
- ``cmake_pop_check_state`` and ``cmake_reset_check_state`` macros
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckCCompilerFlag` module ``check_c_compiler_flag`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckCSourceCompiles` module ``check_c_source_compiles`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckCSourceRuns` module ``check_c_source_runs`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckCXXCompilerFlag` module ``check_cxx_compiler_flag`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckCXXSourceCompiles` module ``check_cxx_source_compiles`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckCXXSourceRuns` module ``check_cxx_source_runs`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckCXXSymbolExists` module ``check_cxx_symbol_exists`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckCompilerFlag` module ``check_compiler_flag`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckFortranCompilerFlag` module ``check_fortran_compiler_flag`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckFortranFunctionExists` module ``check_fortran_function_exists`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckFortranSourceCompiles` module ``check_fortran_source_compiles`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckFortranSourceRuns` module ``check_fortran_source_runs`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckFunctionExists` module ``check_function_exists`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckIncludeFile` module ``check_include_file`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckIncludeFileCXX` module ``check_include_file_cxx`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckIncludeFiles` module ``check_include_files`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckOBJCCompilerFlag` module ``check_objc_compiler_flag`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckLibraryExists` module ``check_library_exists`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckOBJCCompilerFlag` module ``check_objc_compiler_flag`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckOBJCSourceCompiles` module ``check_objc_source_compiles`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckOBJCSourceRuns` module ``check_objc_source_runs`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckOBJCXXCompilerFlag` module ``check_objcxx_compiler_flag`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckOBJCXXSourceCompiles` module ``check_objcxx_source_compiles`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckOBJCXXSourceRuns` module ``check_objcxx_source_runs`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckPrototypeDefinition` module ``check_prototype_definition`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckSourceCompiles` module ``check_source_compiles`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckSourceRuns` module ``check_source_runs`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckStructHasMember` module ``check_struct_has_member`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckSymbolExists` module ``check_symbol_exists`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckTypeSize` module ``check_type_size`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* The :module:`CheckVariableExists` module ``check_variable_exists`` macro
- learned to honor the ``CMAKE_REQUIRED_LINK_DIRECTORIES`` variable.
-
-* Targets with C++ modules may now export their module compile commands using
- the :prop_tgt:`EXPORT_BUILD_DATABASE` target property. This is initialized
- with the :variable:`CMAKE_EXPORT_BUILD_DATABASE` variable which is itself
- initialized using the :envvar:`CMAKE_EXPORT_BUILD_DATABASE` environment
- variable. Only supported with the :ref:`Ninja Generators`.
-
-* All ``DESTINATION`` arguments in :command:`install` commands
- are now :ref:`normalized <Normalization>`, with the exception
- of ``INCLUDES DESTINATION`` arguments in the ``TARGETS`` form.
-
-* Empty list elements in the :prop_tgt:`TEST_LAUNCHER` and
- :prop_tgt:`CROSSCOMPILING_EMULATOR` target properties are now preserved
- when the executable for a command given to :command:`add_test` is a CMake
- target. See policy :policy:`CMP0178`.
-
-* Empty list elements in the :prop_tgt:`TEST_LAUNCHER` and
- :prop_tgt:`CROSSCOMPILING_EMULATOR` target properties are now preserved
- for the test created by :command:`ExternalData_Add_Test` from the
- :module:`ExternalData` module. See policy :policy:`CMP0178`.
-
-* Empty list elements in the :prop_tgt:`TEST_LAUNCHER` and
- :prop_tgt:`CROSSCOMPILING_EMULATOR` target properties are now preserved
- for tests created by :command:`gtest_add_tests` and
- :command:`gtest_discover_tests` from the :module:`GoogleTest` module.
- Empty list elements after the ``EXTRA_ARGS`` keyword of these two commands
- are also now preserved. See policy :policy:`CMP0178`.
-
-* Preset files may now include comments using the key ``$comment``
- at any level within the JSON object to provide documentation.
-
-* Preset files may now request graphviz output using the ``graphviz`` key
- in a configure preset.
+* The :command:`install` command's ``DESTINATION`` arguments are
+ now :ref:`normalized <Normalization>`, with the exception
+ of ``INCLUDES DESTINATION`` arguments in :command:`install(TARGETS)`.
+ See policy :policy:`CMP0177`.
* The :command:`project` command now always sets
:variable:`<PROJECT-NAME>_SOURCE_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR`,
and :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` as both normal variables and
cache entries. See policy :policy:`CMP0180`.
-
-* The :generator:`Visual Studio 12 2013` generator has been removed.
-
-* The :variable:`CMAKE_<LANG>_STANDARD_LINK_DIRECTORIES` variable was added.
- Toolchain files can set this variable to control which link library directory
- paths are always passed to the compiler for the specified language.
-
-* When static libraries on link lines are de-duplicated (by policy
- :policy:`CMP0156`), the first occurrence is now kept on all platforms.
- See policy :policy:`CMP0179`.
-
-* The :prop_tgt:`UNITY_BUILD` target property now supports the
- CUDA (``CUDA``) language.
-
-* The :prop_tgt:`VS_FRAMEWORK_REFERENCES` target property was added
- to tell :ref:`Visual Studio Generators` to add framework references.
