From 78d2c9fef0745ffd67929a76497bf88d1b04e590 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 5 Jun 2023 11:44:09 -0400 Subject: [PATCH] Help: Organize and revise 3.27 release notes Add section headers similar to the 3.26 release notes and move each individual bullet into an appropriate section. Revise a few bullets. --- Help/release/3.27.rst | 337 ++++++++++++++++++++++++------------------ 1 file changed, 191 insertions(+), 146 deletions(-) diff --git a/Help/release/3.27.rst b/Help/release/3.27.rst index a5187b5939..db087fe153 100644 --- a/Help/release/3.27.rst +++ b/Help/release/3.27.rst @@ -7,43 +7,100 @@ CMake 3.27 Release Notes Changes made since CMake 3.26 include the following. -* Support for text-based stubs (i.e. ``.tbd`` files) was added on macOS - platform. This capability is managed through the :prop_tgt:`ENABLE_EXPORTS` - property. +New Features +============ -* The :variable:`CMAKE_AUTOMOC_EXECUTABLE`, - :variable:`CMAKE_AUTORCC_EXECUTABLE`, and - :variable:`CMAKE_AUTOUIC_EXECUTABLE` variables were added to initialize the - corresponding target properties as targets are created. - -* The :prop_tgt:`AUTOGEN_USE_SYSTEM_INCLUDE` target property and - corresponding :variable:`CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE` were - added to explicitly control whether autogen headers are - considered system headers. - -* The :prop_tgt:`INTERFACE_AUTOMOC_MACRO_NAMES` target property was added to - specify macro names for ``moc`` as a transitive usage requirement. +Debugger +-------- * :manual:`cmake(1)` now supports interactive debugging of the CMake language. See the :option:`--debugger ` option. -* ``cmake --build $dir --verbose`` will now print the working directory and - command line used to perform the build. +Presets +------- -* The :cpack_gen:`CPack Inno Setup Generator` was added to package using - Inno Setup. +* :manual:`cmake-presets(7)` files now support schema version ``7``. - The new generator adds: +* :manual:`cmake-presets(7)` now supports ``$penv{}`` macro expansion + in ``include`` fields. - * A lot of options to customize the Inno Setup installer (e.g. custom - installation rules) - * Start menu and desktop shortcuts - * Components (and also downloaded components) +Generators +---------- -* The :prop_test:`TIMEOUT_SIGNAL_NAME` and - :prop_test:`TIMEOUT_SIGNAL_GRACE_PERIOD` test properties were added - to specify a POSIX signal to send to a test process when its timeout - is reached. +* The :ref:`Makefile ` and :ref:`Ninja ` + generators now support using the ``--dependency-file`` linker flag, + added by GNU Binutils 2.35 and LLVM's LLD 12.0.0, so that files read by the + linker will cause a relink if they change (typically modified timestamps). + See the :variable:`CMAKE_LINK_DEPENDS_USE_LINKER` variable. + +* The :ref:`Visual Studio Generators` for VS 2015 and above learned to + select the Windows SDK version explicitly using a ``version=`` field + in the :variable:`CMAKE_GENERATOR_PLATFORM` variable. + See :ref:`Visual Studio Platform Selection`. + +Languages +--------- + +* The ``CXX`` language now treats source file extensions + ``.ccm``, ``.cxxm``, and ``.c++m`` as C++. + +File-Based API +-------------- + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has + been updated to 2.6. + +* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained + a new "frameworks" field in the "compileGroups" objects. + +Platforms +--------- + +* Apple text-based stubs (i.e. ``.tbd`` files) may now be created for shared + libraries on macOS. See the :prop_tgt:`ENABLE_EXPORTS` property. + +Commands +-------- + +* The :command:`add_custom_command` command gained a new + ``DEPENDS_EXPLICIT_ONLY`` option to tell the :ref:`Ninja Generators` + not to add any dependencies implied by the target to which it is + attached. The :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` + variable was added to enable ``DEPENDS_EXPLICIT_ONLY`` on all calls to + :command:`add_custom_command` command. + +* The :command:`cmake_file_api` command was added for projects to add + :manual:`CMake file API ` queries for the current + CMake run. + +* The :command:`find_package` command now searches prefixes specified by + upper-case :variable:`_ROOT` CMake variables and upper-case + :envvar:`_ROOT` environment variables. + See policy :policy:`CMP0144`. + +* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands + now support the :genex:`$` generator expression. + +Variables +--------- + +* The :variable:`CMAKE_DLL_NAME_WITH_SOVERSION` variable and associated + :prop_tgt:`DLL_NAME_WITH_SOVERSION` target property were added to + optionally append the :prop_tgt:`SOVERSION` to the filename of the + ``.dll`` part of a shared library on Windows. + +* Variables :variable:`CMAKE_VS_DEBUGGER_COMMAND`, + :variable:`CMAKE_VS_DEBUGGER_COMMAND_ARGUMENTS`, + :variable:`CMAKE_VS_DEBUGGER_ENVIRONMENT`, and + :variable:`CMAKE_VS_DEBUGGER_WORKING_DIRECTORY` were added to initialize + corresponding target properties. + +* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION` variable + was added to initialize the :prop_tgt:`VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION` + target property on all targets when they are created. + +Properties +---------- * A :prop_tgt:`CUDA_CUBIN_COMPILATION` target property was added to :ref:`Object Libraries` to support compiling to ``.cubin`` files @@ -57,146 +114,134 @@ Changes made since CMake 3.26 include the following. :ref:`Object Libraries` to support compiling to ``.optixir`` files instead of host object files. Currently only supported with NVIDIA. -* Source file extensions ``.ccm``, ``.cxxm``, or ``.c++m`` are now - treated as C++. +* The :prop_tgt:`_CLANG_TIDY`, :prop_tgt:`_CPPCHECK`, + :prop_tgt:`_CPPLINT`, and :prop_tgt:`_INCLUDE_WHAT_YOU_USE`, + target properties now support + :manual:`generator expressions `. -* The :ref:`Extra Generators` have been deprecated. IDEs may use the - :manual:`cmake-file-api(7)` to view CMake-generated project build trees. +* The :prop_tgt:`_LINKER_LAUNCHER` target property now supports + :manual:`generator expressions `. + +* The :prop_sf:`SKIP_LINTING` source file property was added to suppress + target-wide code checks on specific sources. + +Modules +------- + +* The :module:`FindCUDAToolkit` module now provides an imported target for + ``cudla``, if found. + +* The :module:`FindDoxygen` module's :command:`doxygen_add_docs` command gained + a ``CONFIG_FILE`` option to specify a custom doxygen configuration file. + +* The :module:`FindOpenGL` module gained support for components + ``GLES2`` and ``GLES3``. + +* The :module:`FindwxWidgets` module now provides an imported target. + +Generator Expressions +--------------------- + +* The :genex:`COMPILE_ONLY` generator expression was added to specify + compilation usage requirements without any linking requirements. + +* ``$`` generator expressions were added for + :ref:`query `, + :ref:`transformation `, and + :ref:`ordering ` operations on + :ref:`lists `. + +* ``$`` generator expressions for + :ref:`decomposition ` and + :ref:`transformation ` operations learned + to process :ref:`lists ` of paths element-wise. + +Autogen +------- + +* The :variable:`CMAKE_AUTOMOC_EXECUTABLE`, + :variable:`CMAKE_AUTORCC_EXECUTABLE`, and + :variable:`CMAKE_AUTOUIC_EXECUTABLE` variables were added to initialize the + corresponding target properties as targets are created. + +* The :prop_tgt:`AUTOGEN_USE_SYSTEM_INCLUDE` target property and + corresponding :variable:`CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE` variable were + added to explicitly control whether autogen headers are + considered system headers. + +* The :prop_tgt:`INTERFACE_AUTOMOC_MACRO_NAMES` target property was added to + specify macro names for ``moc`` as a transitive usage requirement. + +CTest +----- + +* The :prop_test:`TIMEOUT_SIGNAL_NAME` and + :prop_test:`TIMEOUT_SIGNAL_GRACE_PERIOD` test properties were added + to specify a POSIX signal to send to a test process when its timeout + is reached. + +CPack +----- + +* The :cpack_gen:`CPack Inno Setup Generator` was added to package using + Inno Setup. + +Deprecated and Removed Features +=============================== * Compatibility with versions of CMake older than 3.5 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 :variable:`CMAKE_DLL_NAME_WITH_SOVERSION` variable and associated - :prop_tgt:`DLL_NAME_WITH_SOVERSION` target property were added to - optionally append the :prop_tgt:`SOVERSION` to the filename of the - ``.dll`` part of a shared library on Windows. +* The :ref:`Extra Generators` have been deprecated. IDEs may use the + :manual:`cmake-file-api(7)` to view CMake-generated project build trees. -* The ``update`` and ``patch`` steps of an :module:`ExternalProject` will now - always re-execute if any of their details change, even if - ``UPDATE_DISCONNECTED`` was set to true in the call to - :command:`ExternalProject_Add`. If using the GIT download method and the - ``GIT_TAG`` is changed and the new ``GIT_TAG`` isn't already known locally, - this is now a fatal error instead of silently using the previous ``GIT_TAG``. +* The :module:`FindCUDA` module, which has been deprecated since CMake 3.10, + has been removed by policy :policy:`CMP0146`. Port projects to CMake's + first-class ``CUDA`` language support. -* When ``UPDATE_DISCONNECTED`` is set to true in a call to - :command:`ExternalProject_Add`, the ``configure`` step will no longer - re-run on every build. It will only re-run if details of the ``download``, - ``update`` or ``patch`` step change. +* The :module:`FindPythonInterp` and :module:`FindPythonLibs` modules, + which have been deprecated since CMake 3.12, have been removed by + policy :policy:`CMP0148`. Port projects to :module:`FindPython3`, + :module:`FindPython2`, or :module:`FindPython`. + +* The :module:`Dart` and :module:`FindDart` modules have been deprecated via + policy :policy:`CMP0145`. Port projects to the :module:`CTest` module. + +* The :generator:`Visual Studio 9 2008` generator is now deprecated + and will be removed in a future version of CMake. + +Other Changes +============= + +* ``cmake --build $dir --verbose`` will now print the working directory and + command line used to perform the build. * The :module:`ExternalProject` and :module:`FetchContent` modules - now resolve relative `GIT_REPOSITORY` paths as relative to the + now resolve relative ``GIT_REPOSITORY`` paths as relative to the parent project's remote, not as a relative local file system path. See :policy:`CMP0150`. -* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has - been updated to 2.6. -* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained - a new "frameworks" field in the "compileGroups" objects. +* The :module:`ExternalProject` ``configure`` step no longer re-runs on + every build when the ``UPDATE_DISCONNECTED`` option is enabled. + It will only re-run if details of the ``download``, ``update``, + or ``patch`` step change. -* The :command:`cmake_file_api` command was added, enabling projects to - add :manual:`CMake file API ` queries for the current - CMake run. +* The :module:`ExternalProject` ``update`` and ``patch`` steps now always + re-run if any of their details change, even if the ``UPDATE_DISCONNECTED`` + option is enabled. If using the ``GIT`` download method, and the ``GIT_TAG`` + is changed to a commit that is not already known locally, an error is now + issued instead of silently using the previous ``GIT_TAG``. +* The :module:`FindPython`, :module:`FindPython2` and :module:`FindPython3` + modules now support the Windows ARM64 platform. * The :command:`file(GET_RUNTIME_DEPENDENCIES)` command now case-preserves DLL names reported on Windows. They are still converted to lowercase for filter matching. -* The :module:`FindCUDA` module has been fully deprecated via policy - :policy:`CMP0146`. Port projects to CMake's first-class ``CUDA`` - language support. - -* The :module:`FindCUDAToolkit` module now provides an imported target for ``cudla``, if found. - -* The :module:`FindDoxygen` module's ``doxygen_add_docs`` command gained - a ``CONFIG_FILE`` option to specify a custom doxygen configuration file. - -* The :module:`FindOpenGL` module gained support for components - ``GLES2`` and ``GLES3``. - -* The :command:`find_package` command now searches prefixes specified by - upper-case :variable:`_ROOT` CMake variables and upper-case - :envvar:`_ROOT` environment variables. - See policy :policy:`CMP0144`. - -* :module:`FindPython`, :module:`FindPython2` and :module:`FindPython3` modules - learn to manage ``Windows/ARM`` platform. - -* The :module:`FindwxWidgets` module now provides an imported target. - -* The :genex:`COMPILE_ONLY` generator expression has been added which provides - compilation usage requirements without any linking requirements. - -* The :genex:`LIST` generator expression was added to manage lists. - -* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands - now support the :genex:`$` generator expression. - -* The :prop_tgt:`_LINKER_LAUNCHER` target property now supports - :manual:`generator expressions `. - -* The :prop_tgt:`_CLANG_TIDY`, :prop_tgt:`_CPPCHECK`, - :prop_tgt:`_CPPLINT`, and :prop_tgt:`_INCLUDE_WHAT_YOU_USE`, - target properties now support - :manual:`generator expressions `. - -* The :command:`add_custom_command` command gained a new - ``DEPENDS_EXPLICIT_ONLY`` option to tell the :ref:`Ninja Generators` - not to add any dependencies implied by the target to which it is - attached. - -* The :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` variable can - be set to enable ``DEPENDS_EXPLICIT_ONLY`` in all uses of - :command:`add_custom_command` command. - -* The :genex:`$` generator expression learned to process list of paths - for decomposition and transformation operations. - -* :manual:`cmake-presets(7)` files now support schema version ``7``. - -* :manual:`cmake-presets(7)` now supports ``$penv{}`` macro expansion - in ``include`` fields. - -* The :module:`Dart` and :module:`FindDart` modules have been deprecated via - policy :policy:`CMP0145`. Port projects to the :module:`CTest` module. - -* The :module:`FindPythonInterp` and :module:`FindPythonLibs` modules have - been fully deprecated via policy :policy:`CMP0148`. Port projects to - :module:`FindPython3`, :module:`FindPython2`, or :module:`FindPython`. - -* The :prop_sf:`SKIP_LINTING` source file property was added to suppress - target-wide code checks on specific sources. - * The :prop_tgt:`SYSTEM` target property is now honored for Apple Frameworks. -* GNU (and GNU-compatible) linkers gained support for a ``--dependency-file`` - flag in GNU Binutils 2.35 and LLVM's LLD 12.0.0. The - :ref:`Makefile ` and :ref:`Ninja ` - generators will now add these flags so that files read by the linker will - cause a relink if they change (typically modified timestamps). - - This feature can be controlled by the variable - :variable:`CMAKE_LINK_DEPENDS_USE_LINKER`. - -* The :generator:`Visual Studio 9 2008` generator is now deprecated - and will be removed in a future version of CMake. - * :ref:`Visual Studio Generators`, for VS 15.8 (2017) and newer, now build custom commands in parallel. See policy :policy:`CMP0147`. - -* Variables :variable:`CMAKE_VS_DEBUGGER_COMMAND`, - :variable:`CMAKE_VS_DEBUGGER_COMMAND_ARGUMENTS`, - :variable:`CMAKE_VS_DEBUGGER_ENVIRONMENT`, and - :variable:`CMAKE_VS_DEBUGGER_WORKING_DIRECTORY` were added to initialize - corresponding target properties. - -* The :ref:`Visual Studio Generators` for VS 2015 and above learned to - select the Windows SDK version explicitly using a ``version=`` field - in the :variable:`CMAKE_GENERATOR_PLATFORM` variable. - See :ref:`Visual Studio Platform Selection`. - -* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION` variable - was added to initialize the :prop_tgt:`VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION` - target property on all targets when they are created.