diff --git a/Help/release/3.25.rst b/Help/release/3.25.rst index 6bce41391b..2250dd413a 100644 --- a/Help/release/3.25.rst +++ b/Help/release/3.25.rst @@ -7,174 +7,111 @@ CMake 3.25 Release Notes Changes made since CMake 3.24 include the following. - * Support for the `Tasking compiler toolsets`_ (SmartCode, TriCore, - Standalone: ARM, MCS, 8051) was added with compiler id ``Tasking``. - See the :variable:`CMAKE_TASKING_TOOLSET` variable. +New Features +============ + +Presets +------- + +* The :manual:`cmake-presets(7)` schema version has been bumped to ``6``. + +* The :manual:`cmake-presets(7)` format now supports a + ``packagePresets`` field to specify presets for :option:`cpack --preset`. + +* The :manual:`cmake-presets(7)` format now supports a + ``workflowPresets`` field to specify presets for :option:`cmake --workflow`. + +Languages +--------- + +* The :manual:`Compile Features ` functionality + is now aware of C++26, and defines a ``cxx_std_26`` meta-feature. + C++26 compiler modes may also be specified via the :prop_tgt:`CXX_STANDARD`, + :prop_tgt:`CUDA_STANDARD`, :prop_tgt:`HIP_STANDARD`, + or :prop_tgt:`OBJCXX_STANDARD` target properties. + +* ``CUDA`` language support now includes device link-time optimization when + using ``nvcc``. The :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable + and the associated :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property + will activate device LTO. + +Command-Line +------------ + +* A :ref:`cmake --workflow --preset ` mode was added + to drive sequences of configure, build, test, and package operations + through a single command. + +* The :option:`cmake -E capabilities ` command + gained a new ``tls`` field that tells whether or not TLS is enabled. + +* The :option:`cmake -E env ` command-line tool gained + a ``--modify`` flag to support :prop_test:`ENVIRONMENT_MODIFICATION` + operations. + +* The :option:`cmake --debug-trycompile` option now prints log messages + reporting the directory in which each try-compile check is done. + +Compilers +--------- + +* Support for the `Tasking compiler toolsets`_ (SmartCode, TriCore, + Standalone: ARM, MCS, 8051) was added with compiler id ``Tasking``. + See the :variable:`CMAKE_TASKING_TOOLSET` variable. .. _`Tasking compiler toolsets`: https://tasking.com -* CMake language gains the commands :command:`block` and :command:`endblock` to - manage specific scopes (policy or variable) for group of commands. +Commands +-------- -* The :variable:`BSD` variable is set to a string value when the target system is BSD. - This value can be one of the following: DragonFlyBSD, FreeBSD, OpenBSD, or NetBSD. +* The :command:`add_subdirectory` command gained a ``SYSTEM`` option + to enable the :prop_dir:`SYSTEM` directory property in the subdirectory. -* The :variable:`CMAKE_HOST_BSD` variable is set to a string value when the host system is BSD. - This value can be one of the following: DragonFlyBSD, FreeBSD, OpenBSD, or NetBSD. - -* If :prop_tgt:`_CLANG_TIDY` includes a ``-p`` argument, the - full compiler command line is no longer appended after ``--``. - -* A new ``--modify`` flag was added to :option:`cmake -E env ` to - support :prop_test:`ENVIRONMENT_MODIFICATION` operations. +* The :command:`block` and :command:`endblock` commands were added to manage + specific scopes (policy or variable) for a contained block of commands. * The :command:`cmake_language` command gained a new ``GET_MESSAGE_LOG_LEVEL`` sub-command. It can be used to query the current message logging level. -* The :manual:`cmake-presets(7)` schema version has been bumped to ``6``. -* The :manual:`cmake-presets(7)` format now supports a ``packagePresets`` field. - -* The :manual:`cmake-presets(7)` format now supports a ``workflowPresets`` field. - -* The :prop_tgt:`_COMPILER_LAUNCHER` target property now supports - :manual:`generator expressions `. - -* The :cpack_gen:`CPack Archive Generator` gained a new - :variable:`CPACK_ARCHIVE_FILE_EXTENSION` variable to control - the package file name extension. - -* The :cpack_gen:`CPack NSIS Generator` gained two new variables - :variable:`CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS` and - :variable:`CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS` - to provide arguments to the nsis executable invocation. - -* The :module:`CPack` module gained the :variable:`CPACK_READELF_EXECUTABLE`, - :variable:`CPACK_OBJCOPY_EXECUTABLE`, and - :variable:`CPACK_OBJDUMP_EXECUTABLE` variables to control the locations - of binutils used by :manual:`cpack(1)`. - -* ``CUDA`` language now supports device link time optimization when using - ``nvcc``. The :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable and - the associated :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property will - activate device LTO. - -* C++26 compiler modes may now be specified via the :prop_tgt:`CXX_STANDARD`, - :prop_tgt:`CUDA_STANDARD`, :prop_tgt:`HIP_STANDARD`, or - :prop_tgt:`OBJCXX_STANDARD` target properties, - or via the :manual:`Compile Features ` - functionality's ``cxx_std_26`` meta-feature. - -* On Windows, when targeting the MSVC ABI, the :command:`find_library` command - now accepts ``.a`` file names after first considering ``.lib``. This is - symmetric with existing behavior when targeting the GNU ABI, in which the - command accepts ``.lib`` file names after first considering ``.a``. - -* The :manual:`cmake -E capabilities ` command gained a new ``tls`` - field that tells whether or not TLS is enabled. - -* The :envvar:`SSL_CERT_FILE` and :envvar:`SSL_CERT_DIR` environment - variables are now used to find certificate authorities for TLS/SSL - operations. - -* The :module:`FindCUDAToolkit` module now provides a target for - :ref:`nvtx3 ` for CUDA 10.0+, which supersedes - :ref:`nvToolsExt `. A deprecation warning is emitted - when using ``nvToolsExt`` if the project requires CMake 3.25 and CUDA 10.0+ - is used. - -* The :module:`FindDoxygen` module now evaluates as many candidate - Doxygen installs as are necessary to satisfy version constraints, - with the package considered to be not found if none are available. - -* The :module:`FindDoxygen` module now handles version ranges. - -* The :module:`FindDoxygen` module now ignores non-semantic portions - of the output from Doxygen's `--version` option. - -* :command:`find_file`, :command:`find_path`, :command:`find_library`, and - :command:`find_program` commands gain the capability to specify a function - which will be called for each found item to validate it. - -* The :module:`FindOpenAL` module now provides an imported target. - -* The :module:`FindOpenSP` module was added to find the OpenSP library. +* The :command:`find_file`, :command:`find_path`, :command:`find_library`, and + :command:`find_program` commands gained a ``VALIDATOR`` option to specify a + function to be called for each candidate item to validate it. * The :command:`find_package` command now considers paths of the form ``/*/(cmake|CMake)/*/`` when searching for package configuration files. -* The :module:`FindVulkan` module gained support for a DirectX Shader Compiler - component, ``dxc``. - -* The :module:`FindVulkan` module now includes a ``volk`` component - for the Volk open source vulkan meta-loader. - -The :genex:`$` generator expression gains the capability, for the -``FRAMEWORK`` features, to handle the suffix of the framework library name. - -* The :variable:`LINUX` variable is set to true when the target system is Linux. - -* The :variable:`CMAKE_HOST_LINUX` variable is set to true when the host system is Linux. - -* The :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` variable and - :prop_tgt:`MSVC_DEBUG_INFORMATION_FORMAT` target property were introduced - to select the debug information format for compilers targeting the MSVC ABI. - See policy :policy:`CMP0141`. - -* C++ module scanning now supports the latest revision, `P1689R5`_. - -.. _`P1689r5`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html - -* The :generator:`Visual Studio 10 2010` generator has been removed. - -* The :command:`return` command gains the capability to propagate variables to - the include directory of function caller scope. See policy :policy:`CMP0140`. - -* The :prop_tgt:`SYSTEM` target property was added to specify - that a target should be treated as a system library (i.e. - its include directories are automatically ``SYSTEM`` when - compiling consumers). - -* The :prop_dir:`SYSTEM` directory property was added to initialize the - :prop_tgt:`SYSTEM` target property for targets created in that directory. - -* The :command:`add_subdirectory` command gained a ``SYSTEM`` option - to enable the :prop_dir:`SYSTEM` directory property in the subdirectory. - -* The :module:`FetchContent` module :command:`FetchContent_Declare` - command gained a ``SYSTEM`` option to enable the :prop_dir:`SYSTEM` - directory property in the subdirectory. - -* The :prop_tgt:`EXPORT_NO_SYSTEM` target property was added to - specify that :command:`install(EXPORT)` and :command:`export` - commands will generate a imported target with - :prop_tgt:`SYSTEM` property `OFF`. - -* The :prop_tgt:`IMPORTED_NO_SYSTEM` target property was deprecated - in favor of :prop_tgt:`SYSTEM` and :prop_tgt:`EXPORT_NO_SYSTEM`. - -* The :command:`try_compile` and :command:`try_run` commands gained the option - ``NO_CACHE`` to store results in normal variables. +* The :command:`return` command gained a ``PROPAGATE`` option to propagate + variables to the scope to which control returns. + See policy :policy:`CMP0140`. * The :command:`try_compile` and :command:`try_run` commands gained new signatures that more consistently use keyword dispatch and do not require a binary directory to be specified. Additionally, these signatures use a unique directory for each invocation, which allows multiple outputs to be - preserved when using :option:`--debug-trycompile `. + preserved when using :option:`cmake --debug-trycompile`. -* The :option:`cmake --debug-trycompile` option now prints log messages - reporting the directory in which each try-compile check is done. +* The :command:`try_compile` and :command:`try_run` commands gained the + option ``NO_CACHE`` to store results in normal variables. * The :command:`try_run` command gained ``RUN_OUTPUT_STDOUT_VARIABLE`` and ``RUN_OUTPUT_STDERR_VARIABLE`` options to capture stdout and stderr separately from the output of the compiled program. -* The :module:`UseSWIG` module gained knowledge about generated Perl module - files (extension ``.pm``). +Variables +--------- -* The :generator:`Visual Studio 11 2012` generator is now deprecated - and will be removed in a future version of CMake. +* The :variable:`BSD` and :variable:`CMAKE_HOST_BSD` variables are now set + to a string value when the target or host system is BSD, respectively. + +* The :variable:`LINUX` and :variable:`CMAKE_HOST_LINUX` variables are + now set to true when the target or host system is Linux, respectively. + +* The :variable:`CMAKE_MSVC_DEBUG_INFORMATION_FORMAT` variable and + :prop_tgt:`MSVC_DEBUG_INFORMATION_FORMAT` target property were introduced + to select the debug information format for compilers targeting the MSVC ABI. + See policy :policy:`CMP0141`. * The :variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_API_VALIDATION` variable and corresponding :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_API_VALIDATION` target @@ -196,6 +133,105 @@ The :genex:`$` generator expression gains the capability, for the property were added to tell the :generator:`Xcode` generator what configuration to put in the scheme's Launch action. +Properties +---------- + +* The :prop_tgt:`_COMPILER_LAUNCHER` target property now supports + :manual:`generator expressions `. + +* The :prop_tgt:`EXPORT_NO_SYSTEM` target property was added to + specify that :command:`install(EXPORT)` and :command:`export` + commands will generate na imported target with + :prop_tgt:`SYSTEM` property ``OFF``. + +* The :prop_tgt:`SYSTEM` target property was added to specify + whether a target should be treated as a system library (i.e. + its include directories are automatically ``SYSTEM`` when + compiling consumers). If not set, the default is the previous + behavior: on for imported targets and off for other targets. + +* The :prop_dir:`SYSTEM` directory property was added to initialize the + :prop_tgt:`SYSTEM` target property for targets created in that directory. + +Modules +------- + +* The :module:`FetchContent` module :command:`FetchContent_Declare` + command gained a ``SYSTEM`` option to enable the :prop_dir:`SYSTEM` + directory property in the subdirectory. + +* The :module:`FindCUDAToolkit` module now provides a target for + :ref:`nvtx3 ` for CUDA 10.0+, which supersedes + :ref:`nvToolsExt `. A deprecation warning + is emitted when using ``nvToolsExt`` if the project requires CMake + 3.25 and CUDA 10.0+ is used. + +* The :module:`FindDoxygen` module's version handling has been improved: + + * Multiple candidate installations will now be considered, if needed, + to satisfy version constraints. Previously, only the first one + encountered would be considered. + + * Version ranges are supported. + + * Variations in the version format reported by Doxygen are now + tolerated (e.g. a trailing git commit hash). + +* The :module:`FindOpenAL` module now provides an imported target. + +* The :module:`FindOpenSP` module was added to find the OpenSP library. + +* The :module:`FindVulkan` module gained support for new components: + + ``dxc`` + DirectX Shader Compiler. + + ``volk`` + Volk open-source vulkan meta-loader. + +CPack +----- + +* The :cpack_gen:`CPack Archive Generator` gained a new + :variable:`CPACK_ARCHIVE_FILE_EXTENSION` variable to control + the package file name extension. + +* The :cpack_gen:`CPack NSIS Generator` gained two new variables + :variable:`CPACK_NSIS_EXECUTABLE_PRE_ARGUMENTS` and + :variable:`CPACK_NSIS_EXECUTABLE_POST_ARGUMENTS` + to provide arguments to the nsis executable invocation. + +* The :module:`CPack` module gained the :variable:`CPACK_READELF_EXECUTABLE`, + :variable:`CPACK_OBJCOPY_EXECUTABLE`, and + :variable:`CPACK_OBJDUMP_EXECUTABLE` variables to control the locations + of binutils used by :manual:`cpack(1)`. + +Deprecated and Removed Features +=============================== + +* The :prop_tgt:`IMPORTED_NO_SYSTEM` target property has been deprecated + in favor of :prop_tgt:`SYSTEM` and :prop_tgt:`EXPORT_NO_SYSTEM`. + +* The :generator:`Visual Studio 10 2010` generator has been removed. + +* The :generator:`Visual Studio 11 2012` generator is now deprecated + and will be removed in a future version of CMake. + +Other Changes +============= + +* On Windows, when targeting the MSVC ABI, the :command:`find_library` command + now accepts ``.a`` file names after first considering ``.lib``. This is + symmetric with existing behavior when targeting the GNU ABI, in which the + command accepts ``.lib`` file names after first considering ``.a``. + +* The :envvar:`SSL_CERT_FILE` and :envvar:`SSL_CERT_DIR` environment + variables can now be used to override where to find certificate + authorities for TLS/SSL operations. + +* If :prop_tgt:`_CLANG_TIDY` includes a ``-p`` argument, the + full compiler command line is no longer appended after ``--``. + * The :generator:`Xcode` generator no longer adds the per-config suffix ``$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME)`` to library search paths. See policy :policy:`CMP0142`.