| CMake 4.5 Release Notes | |
| *********************** | |
| .. only:: html | |
| .. contents:: | |
| Changes made since CMake 4.4 include the following. | |
| New Features | |
| ============ | |
| Diagnostics | |
| ----------- | |
| * The :diagnostic:`CMD_NON_TARGET_DIRECTIVE` diagnostic category was added to | |
| diagnose commands that affect the directory scope when comparable | |
| target-specific commands exist. The use of such directives is discouraged. | |
| This diagnostic may be controlled with the | |
| :option:`-Wnon-target-directive <cmake -W>` command-line option, | |
| the ``nonTargetDirective`` field in a | |
| :manual:`CMake Presets <cmake-presets(7)>` | |
| :preset:`configurePresets.warnings` object, | |
| or the :command:`cmake_diagnostic` command. | |
| * The :diagnostic:`CMD_STRICT` diagnostic category was added to control | |
| diagnostics regarding allowed but discouraged usage as a group. | |
| This diagnostic may be controlled with the :option:`-Wstrict <cmake -W>` | |
| command-line option, the ``strict`` field in a | |
| :manual:`CMake Presets <cmake-presets(7)>` | |
| :preset:`configurePresets.warnings` object, | |
| or the :command:`cmake_diagnostic` command. | |
| Presets | |
| ------- | |
| * :manual:`cmake-presets(7)` files now support schema version 13. | |
| * :manual:`cmake-presets(7)` gained the ``${configurePresetName}`` macro to | |
| expand to the name of the configure preset associated with the preset being | |
| evaluated. It is available for configure, build, test, and package presets, | |
| but not for workflow presets. | |
| File-Based API | |
| -------------- | |
| * The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has | |
| been updated to 2.12. | |
| * The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained | |
| a new ``interfaceIncludes`` array field. | |
| Instrumentation | |
| --------------- | |
| * The :manual:`cmake-instrumentation(7)` data version has been updated to 1.2. | |
| * :manual:`cmake-instrumentation(7)` now records an overall ``cmakeBuild`` | |
| snippet even when a :option:`cmake --build` invocation is interrupted by the | |
| user (for example with Ctrl+C). The snippet includes a new | |
| ``interruptSignal`` field, recording the signal that interrupted the build, | |
| so that consumers can distinguish an interrupted build from one that ran | |
| to completion. | |
| * :manual:`cmake-instrumentation(7)` now records an overall ``cmakeInstall`` | |
| snippet, marked with the same ``interruptSignal`` field, when a | |
| :option:`cmake --install` invocation is interrupted by the user. | |
| * :manual:`cmake-instrumentation(7)` now records an overall ``ctest`` snippet, | |
| marked with the same ``interruptSignal`` field, when a :manual:`ctest(1)` | |
| invocation is interrupted by the user. On interrupt CTest stops scheduling | |
| further tests and preserves its checkpoint file so that a later | |
| :option:`ctest -F` can resume the interrupted test set. | |
| Generators | |
| ---------- | |
| * The :ref:`Ninja Generators`, :ref:`Makefile Generators`, and | |
| :generator:`FASTBuild` generator now provide ``install_prep/all`` and | |
| ``install_prep/<component>`` convenience build targets by default. The | |
| :variable:`CMAKE_SKIP_INSTALL_PREP_TARGETS` variable may be enabled to | |
| skip generating them. These targets build all known build dependencies for | |
| an installation that does not select a component, or for the named install | |
| component, respectively. This includes targets that produce installed C++ | |
| module BMIs, module export metadata, or generated files. See | |
| :ref:`Install Preparation Targets`. | |
| * The :generator:`FASTBuild` generator and the :ref:`Makefile Generators` | |
| now provide ``test_prep/<test-name>`` and ``test_prep/all`` convenience | |
| build targets by default. The :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` | |
| variable may be enabled to skip generating them. These targets build the | |
| dependencies of tests added by :command:`add_test`, including those listed | |
| with the ``BUILD_DEPENDS`` keyword. See :ref:`Test Preparation Targets`. | |
| * The :ref:`Ninja Generators` now provide ``test_prep/<test-name>`` and | |
| ``test_prep/all`` convenience build targets build targets by default. The | |
| :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` variable may be enabled to | |
| skip generating them. These targets were previously generated only if | |
| :variable:`CMAKE_TEST_BUILD_DEPENDS` was enabled. See | |
| :ref:`Test Preparation Targets`. | |
| * :ref:`Makefile Generators` and :ref:`Ninja Generators` gained support | |
| for adding a linker launcher with ``CUDA`` and ``HIP``. | |
| See the :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` variable | |
| and :prop_tgt:`<LANG>_LINKER_LAUNCHER` target property for details. | |
| Languages | |
| --------- | |
| * ``import std`` is now available for all C++ 20 and later code with | |
| :prop_tgt:`CXX_SCAN_FOR_MODULES` enabled. | |
| Compilers | |
| --------- | |
| * The `open-source DPC++ compiler`_, version 7.0 and newer, is now supported | |
| with :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``DPClang`` for | |
| languages ``C`` and ``CXX``. | |
| .. _`open-source DPC++ compiler`: https://github.com/intel/llvm | |
| Command-Line | |
| ------------ | |
| * The :option:`cmake -E capabilities <cmake-E capabilities>` output now includes | |
| an ``instrumentation`` object reporting the supported instrumentation API | |
| version and the latest supported data version. | |
| * The :option:`cmake --list-presets <cmake --list-presets>` option gained | |
| ``*-defined`` values that list all non-hidden presets of the corresponding | |
| type and explain why unavailable presets cannot be used. The ``defined`` | |
| value is an alias for ``configure-defined``, while ``all-defined`` selects | |
| every type. Build, test, and package presets whose configure preset is | |
| unavailable are now considered unavailable too. | |
| * The :option:`cmake --build --list-presets=defined | |
| <cmake--build --list-presets>`, | |
| :option:`ctest --list-presets=defined <ctest --list-presets>`, and | |
| :option:`cpack --list-presets=defined <cpack --list-presets>` options were | |
| added to list all defined build, test, and package presets, respectively. | |
| * The :option:`cmake --workflow --list-presets=defined | |
| <cmake--workflow --list-presets>` option was added to provide the same | |
| availability information for all defined workflow presets and their steps. | |
| Commands | |
| -------- | |
| * The :command:`add_custom_rule` command was added to allow the definition of | |
| pattern rules. | |
| * The :command:`add_dependencies` command now accepts :ref:`Alias Targets`. | |
| Dependencies are added to the target the alias references. | |
| * The :command:`discover_tests` command gained a ``BUILD_DEPENDS`` argument to | |
| support the :ctest-option:`--out-of-date` behavior of :manual:`ctest(1)`. | |
| * The :command:`cmake_language(PRINT_PROPERTIES)` command was added | |
| to print CMake entities' properties in human-readable form for | |
| debugging. | |
| * The :command:`cmake_language(PRINT_TARGETS)` command was added | |
| to print the targets that currently exist in human-readable form | |
| for debugging. | |
| * The :command:`cmake_language(PRINT_VARIABLES)` command was added | |
| to print variables and their values in human-readable form for | |
| debugging. | |
| * The :command:`file(ARCHIVE_CREATE)` command gained a ``PATTERNS_EXCLUDE`` | |
| option to omit files and directories matching the given patterns from the | |
| created archive. | |
| * The :command:`file(ARCHIVE_EXTRACT)` command gained a ``PATTERNS_EXCLUDE`` | |
| option to omit archive entries matching the given patterns from being | |
| extracted or listed. | |
| * The :command:`file(GET_RUNTIME_DEPENDENCIES)` command is now implemented | |
| on FreeBSD. | |
| * The :command:`find_package` command now supports importing |CPS|_ | |
| `executable` components. | |
| * The :command:`function` command now sets the ``ARGNC`` variable, which | |
| holds the number of arguments past the last expected argument. | |
| * The :command:`if` command gained a ``PATH_IS_PREFIX`` operator to test | |
| whether one path is a prefix of another without accessing the filesystem. | |
| See policy :policy:`CMP0222`. | |
| * The :command:`if` command gained a ``RULE`` operator to check if a rule | |
| exists. | |
| * The :command:`install` and :command:`export` commands now accept | |
| :ref:`Alias Targets`. The commands operate on the underlying | |
| aliased target. | |
| * The :command:`install(SBOM)` and :command:`export(SBOM)` commands were | |
| added to generate Software Bill of Materials (SBOM) files. | |
| * The :command:`install(TARGETS)` command no longer requires a | |
| ``LIBRARY DESTINATION`` for :ref:`Module Libraries`. When no destination is | |
| given, a module library is installed to the default ``RUNTIME`` | |
| destination on DLL platforms and to the default ``LIBRARY`` destination | |
| on other platforms. | |
| * The :command:`install(TARGETS)` command gained a | |
| ``RUNTIME_DEPENDENCY_TARGETS`` option to install runtime artifacts of | |
| non-imported shared libraries from the same build that the named targets | |
| link to. Unlike ``RUNTIME_DEPENDENCIES``, this uses CMake target graph | |
| information rather than :command:`file(GET_RUNTIME_DEPENDENCIES)`. | |
| The option cannot be used with ``EXPORT`` and may only install runtime | |
| artifacts. | |
| * The :command:`install` command's ``FILES``, ``PROGRAMS``, ``DIRECTORY``, | |
| ``SCRIPT``, and ``CODE`` signatures gained a ``BUILD_DEPENDS`` option to | |
| specify targets or files needed to prepare files or run installation | |
| code. See :ref:`Install Preparation Targets`. | |
| * The :command:`math` command gained new ``INCREMENT`` and ``DECREMENT`` modes. | |
| * The :command:`project` and :command:`enable_language` commands, when | |
| called in subdirectories, now propagate support for enabled languages | |
| to all ancestor scopes up to the top-level directory, including through | |
| enclosing :command:`block` and :command:`function` scopes. | |
| See policy :policy:`CMP0220`. | |
| * The :command:`set_property` and :command:`get_property` commands now | |
| support :ref:`RULE properties <Rule Properties>`. | |
| * The :command:`set_property` and :command:`set_target_properties` commands | |
| now accept :ref:`Alias Targets`. Properties are set on the target which | |
| the alias references. | |
| * The :command:`string(JSON)` command gained an ``ARRAY_SPLIT`` mode that | |
| splits a JSON array into a list of its elements with a single parse, | |
| enabling linear-time array iteration instead of re-parsing the whole | |
| JSON string for each element. | |
| * The :command:`target_compile_definitions`, :command:`target_compile_features`, | |
| :command:`target_compile_options`, :command:`target_include_directories`, | |
| :command:`target_link_directories`, :command:`target_link_libraries`, | |
| :command:`target_link_options`, :command:`target_precompile_headers`, | |
| and :command:`target_sources` commands now accept :ref:`Alias Targets`. | |
| The command operates on the target the alias references. | |
| File Sets | |
| --------- | |
| * |CPS|_ import by :command:`find_package`, and export by | |
| :command:`install(PACKAGE_INFO)` and :command:`export(PACKAGE_INFO)`, | |
| now support header file sets. | |
| * The :command:`source_group` command gained support for file sets. | |
| * The :prop_tgt:`FILE_SET_TYPES`, :prop_tgt:`FILE_SETS_<TYPE>`, and | |
| :prop_tgt:`INTERFACE_FILE_SETS_<TYPE>` target properties were added to get | |
| information about file sets attached to the target. | |
| * The :prop_fs:`LANGUAGE` file set property was added to select the compile | |
| language for members of a ``SOURCES`` file set without modifying their | |
| :prop_sf:`LANGUAGE` source file property. | |
| * The :prop_fs:`SOURCE_GROUP` file set property and :prop_sf:`SOURCE_GROUP` | |
| source file property were added to provide a fine grain control over the | |
| grouping of sources. | |
| Variables | |
| --------- | |
| * The :variable:`CMAKE_CXX_STDLIB_MODULES_JSON` variable was added to set | |
| the path to the ``import std`` metadata file for the standard library | |
| rather than using the compiler to discover its location. | |
| * The :variable:`CMAKE_INSTALL_SBOM_FORMATS` variable was added | |
| to enable Software Bill of Materials (SBOM) generation. | |
| * The :variable:`CMAKE_TEST_BUILD_DEPENDS` variable is no longer honored. | |
| Test preparation targets are now enabled by default. The | |
| :variable:`CMAKE_SKIP_TEST_PREP_TARGETS` variable may be enabled to skip | |
| generating them. | |
| Environment Variables | |
| --------------------- | |
| * The :envvar:`CMAKE_SYSTEM_ENVIRONMENT_ID` environment variable was added to | |
| hint to :manual:`cmake(1)` when :cmake-option:`--fresh` may be necessary, | |
| along with :envvar:`CMAKE_SYSTEM_ENVIRONMENT_ACTION` to control what happens | |
| when :envvar:`CMAKE_SYSTEM_ENVIRONMENT_ID` changes. | |
| Properties | |
| ---------- | |
| * The :prop_gbl:`CMAKE_COMPILE_WRAPPER_<NAME>` and | |
| :prop_gbl:`CMAKE_LINK_WRAPPER_<NAME>` global properties were added alongside | |
| the :prop_tgt:`COMPILE_WRAPPERS`, :prop_tgt:`LINK_WRAPPERS`, | |
| :prop_tgt:`INTERFACE_COMPILE_WRAPPERS`, and | |
| :prop_tgt:`INTERFACE_LINK_WRAPPERS` target properties. Together, for the | |
| :ref:`Makefile Generators` and :ref:`Ninja Generators`, they support | |
| wrapping compile and link commands for a given target or its consumers | |
| with arbitrary command lines. | |
| * The :prop_dir:`CMAKE_TEST_BUILD_DEPENDS` directory property was added to | |
| support directory-scoped build time dependencies for tests. | |
| * The :prop_tgt:`Fortran_BUILDING_INTRINSIC_MODULES` target property is now | |
| honored by the :ref:`Ninja Generators`. Previously it was only honored | |
| by the :ref:`Makefile Generators`. | |
| * The :prop_tgt:`Swift_MODULE_NAME` target property is now honored by the | |
| :generator:`Xcode` generator. See policy :policy:`CMP0226`. | |
| * The :prop_dir:`TEST_INCLUDE_FILES` and :prop_dir:`TEST_INCLUDE_FILE` | |
| directory properties now support :manual:`generator expressions | |
| <cmake-generator-expressions(7)>` in the include path. On multi-config | |
| generators a ``$<CONFIG>``-parameterized path can select a different script | |
| per configuration. | |
| * The :prop_tgt:`XCODE_EMBED_<type>` target property now supports | |
| :manual:`generator expressions <cmake-generator-expressions(7)>`. | |
| Because Xcode shares one copy-files build phase across all configurations, | |
| an expression whose result depends on the configuration is rejected with | |
| an error. | |
| Modules | |
| ------- | |
| * The :module:`ExternalProject` module's :command:`ExternalProject_Add` | |
| command now sets :variable:`CMAKE_INSTALL_PREFIX` to the external | |
| project's ``INSTALL_DIR`` in its default configure command, so a CMake | |
| external project installs into the prefix the module reserves for it | |
| rather than the built-in default (e.g. ``/usr/local``). | |
| A caller-supplied prefix still takes precedence. | |
| See policy :policy:`CMP0225`. | |
| * The :module:`FindCUDAToolkit` module now creates ``CUDAToolkit::`` | |
| namespace targets and changes the existing ``CUDA::`` namespace targets | |
| to be alias targets. | |
| * The :module:`FindDoxygen` module :command:`doxygen_add_docs` command | |
| gained a ``USES_TERMINAL`` option to give the Doxygen command direct | |
| access to the terminal during the build. | |
| * The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3` | |
| modules gained the possibility to override the | |
| :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable by respectively, the | |
| variables ``Python_CROSSCOMPILING_EMULATOR``, | |
| ``Python2_CROSSCOMPILING_EMULATOR``, and ``Python3_CROSSCOMPILING_EMULATOR``. | |
| * The :module:`FindPython3` and :module:`FindPython` modules gained, | |
| respectively, the variable ``Python3_SOSABI_PLATFORM`` and | |
| ``Python_SOSABI_PLATFORM`` which gives, on some platforms, for the Stable | |
| Application Binary Interface, the extension including the platform triplet. | |
| Generator Expressions | |
| --------------------- | |
| * The :genex:`$<ARGS>` generator expression was added to convert a | |
| :ref:`semicolon-separated list <CMake Language Lists>` into a comma-separated | |
| list. | |
| * The :genex:`$<DIRECTORY_PROPERTY>` generator expression was added to query | |
| directory properties. | |
| * The :genex:`$<GLOBAL_PROPERTY>` generator expression was added to query | |
| global properties. | |
| * The :genex:`LIST` generator expression's ``FILTER`` and ``TRANSFORM`` | |
| operations gained a ``PREDICATE`` keyword that selects items by evaluating an | |
| arbitrary generator expression once per item, with ``$<_0>`` referring to the | |
| current item. ``FILTER`` also gained an explicit ``REGEX`` keyword. | |
| * The :genex:`LIST` generator expression's ``SORT`` operation gained a | |
| ``COMPARATOR`` option that orders items using an arbitrary generator | |
| expression evaluated once per comparison, with ``$<_0>`` and ``$<_1>`` | |
| referring to the two items being compared. | |
| * The :genex:`LIST` generator expression's ``TRANSFORM`` operation gained an | |
| ``APPLY`` action that evaluates an arbitrary generator expression for each | |
| element, with ``$<_0>`` referring to the current element. | |
| * The :genex:`$<LINK_LIBRARY:NEEDED_LIBRARY,...>` generator expression feature | |
| is now supported on Linux with GNU-compatible linkers (GNU ld, gold, LLD, | |
| MOLD). | |
| * The :genex:`RULE_PROPERTY` generator expression was added to query | |
| properties of rules created by the :command:`add_custom_rule` command. | |
| Autogen | |
| ------- | |
| * :prop_tgt:`AUTOMOC` now processes C++ module interface and partition | |
| units that are members of a ``FILE_SET`` of type ``CXX_MODULES``. | |
| ``moc`` is run on such units and its generated output is compiled as a | |
| module implementation unit of the same module. This requires Qt 6.13 | |
| or newer, whose ``moc`` supports C++ module units. | |
| * :prop_tgt:`AUTOMOC` now has its generated ``mocs_compilation.cpp`` | |
| scanned for C++ module dependencies under the same conditions as the | |
| target's own sources. A header that imports a module may now be | |
| processed by ``moc``. | |
| CTest | |
| ----- | |
| * :manual:`ctest(1)` gained a :ctest-option:`--out-of-date` option to run | |
| only tests whose recorded build dependencies are newer than the last time | |
| the tests ran. | |
| * :manual:`ctest(1)` now supports :ref:`job server integration | |
| <ctest-job-server-integration>` on Windows. | |
| * The :manual:`ctest(1)` :ctest-option:`--show-only` option gained a | |
| ``json-v1-raw`` format in which the ``value`` for each test property | |
| is the original unparsed string value specified in CMake. | |
| * The :command:`ctest_test` and :command:`ctest_memcheck` commands gained the | |
| ability to accept more than one value for their ``INCLUDE_LABEL`` and | |
| ``EXCLUDE_LABEL`` options. When multiple regular expressions are given, a | |
| test is selected only if each expression matches at least one of the test's | |
| labels (i.e. the expressions form an ``AND`` relationship), matching the | |
| behavior of repeating the :option:`ctest --label-regex` and | |
| :option:`ctest --label-exclude` command-line options. | |
| * The :prop_test:`GENERATED_RESOURCE_SPEC_FILE` test property gained support | |
| for relative paths. | |
| * The :prop_test:`FIXTURE_REPEAT_MODE` test property was added to select how | |
| a test fixture behaves when :manual:`ctest(1)` repeats tests with its | |
| :ctest-option:`--repeat` option. See policy :policy:`CMP0224`. | |
| * The :prop_test:`RESOURCE_ERROR_ACTION` test property and | |
| :variable:`CTEST_RESOURCE_ERROR_ACTION` variable were added to | |
| configure the test behavior in case of insufficient resources. | |
| CPack | |
| ----- | |
| * The :cpack_gen:`CPack APK Generator` was added to package Android | |
| applications as APK files. It drives the Android SDK build tools | |
| directly and does not require Gradle. Maven dependencies, such as the | |
| AndroidX libraries, can be downloaded with | |
| :variable:`CPACK_APK_MAVEN_DEPENDENCIES`. | |
| Deprecated and Removed Features | |
| =============================== | |
| * The :generator:`Visual Studio 14 2015` generator has been removed. | |
| * The :module:`CMakePrintHelpers` module's :command:`cmake_print_properties` | |
| command is now deprecated in favor of | |
| :command:`cmake_language(PRINT_PROPERTIES)`. | |
| * The :module:`CMakePrintHelpers` module's :command:`cmake_print_variables` | |
| command is now deprecated in favor of | |
| :command:`cmake_language(PRINT_VARIABLES)`. | |
| * The :command:`install_files`, :command:`install_programs`, | |
| :command:`install_targets`, :command:`make_directory`, :command:`remove`, | |
| :command:`subdirs` and :command:`write_file` commands, which have been | |
| deprecated since CMake 3.0, now emit deprecation diagnostics when used. | |
| Other Changes | |
| ============= | |
| * The :option:`cmake --build` command now groups the output of each recipe in | |
| a parallel build so that concurrent jobs do not interleave, when CMake is | |
| the one passing the parallel flag to the build tool (via :option:`--parallel | |
| <cmake--build --parallel>` or :envvar:`CMAKE_BUILD_PARALLEL_LEVEL`) and that | |
| tool is GNU Make 4.0 or newer. Request parallelism natively, e.g. | |
| ``cmake --build . -- -j``, to opt out and stream output as it is produced. | |
| * The :option:`cmake --install` command now reports a non-zero exit code | |
| when an install script fails. Previously, a parallel install (enabled by | |
| the :prop_gbl:`INSTALL_PARALLEL` global property) always reported success, | |
| and a serial install could lose the failure of an earlier component that | |
| exited via :command:`cmake_language(EXIT) <cmake_language>` when a later | |
| component succeeded. | |
| * The :command:`cmake_host_system_information` command's ``DISTRIB_*`` queries | |
| now read the host os-release by default. See policy :policy:`CMP0221`. | |
| A new ``FROM_SYSROOT <bool>`` option explicitly enables or disables reading | |
| the target os-release from :variable:`CMAKE_SYSROOT`. | |
| * The :command:`cmake_path(IS_PREFIX)` command and the | |
| :genex:`$<PATH:IS_PREFIX>` generator expression no longer treat | |
| an empty path as a prefix of every path. The :command:`if` command's | |
| ``PATH_IS_PREFIX`` operator follows the same rule. | |
| See policy :policy:`CMP0223`. | |
| * When CTest build launchers are enabled (see the :module:`CTestUseLaunchers` | |
| module), a build rule that is terminated by a signal is now reported as a | |
| build failure. Previously such a rule was reported as success, so a crashed | |
| compiler, linker, or custom command could be recorded as a passing build on | |
| the dashboard. | |
| * The :prop_tgt:`ALIASED_TARGET` target property is now read-only. | |
| * The Qt Help (``.qch``) rendition of the documentation now carries its own | |
| color scheme. Previously it was rendered with layout rules only, because | |
| the ``qthelp`` builder does not generate the color scheme that the HTML | |
| documentation uses. A dark variant is shipped alongside it, which help | |
| viewers such as Qt Creator use when their own theme is dark. | |
| * The precompiled macOS binary provided on ``cmake.org`` now requires | |
| macOS 11 or newer for command-line tools. The :manual:`cmake-gui(1)` | |
| application still requires macOS 12. | |
| .. _CPS: https://cps-org.github.io/cps/ | |
| .. |CPS| replace:: Common Package Specification |