CMake 3.21 Release Notes | |
************************ | |
.. only:: html | |
.. contents:: | |
Changes made since CMake 3.20 include the following. | |
New Features | |
============ | |
Presets | |
------- | |
* :manual:`cmake-presets(7)` gained support for specifying the install prefix | |
in a configure preset. | |
* :manual:`cmake-presets(7)` gained support for conditional enabling of presets. | |
* :manual:`cmake-presets(7)` gained support for a ``${hostSystemName}`` macro. | |
* :manual:`cmake-presets(7)` gained support for omitting the ``generator`` and | |
``binaryDir`` fields. | |
Generators | |
---------- | |
* The :generator:`Visual Studio 17 2022` generator was added. | |
* The :ref:`Makefile Generators` and the :generator:`Ninja` generator | |
learned to add linker launcher tools along with the linker for ``C``, | |
``CXX``, ``OBJC``, and ``OBJCXX`` languages. | |
See the :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` variable | |
and :prop_tgt:`<LANG>_LINKER_LAUNCHER` target property for details. | |
Languages | |
--------- | |
* CMake learned to support ``HIP`` as a first-class language that can be | |
enabled via the :command:`project` and :command:`enable_language` commands. | |
* :prop_tgt:`C_STANDARD`, :prop_tgt:`OBJC_STANDARD`, and the | |
:manual:`Compile Features <cmake-compile-features(7)>` functionality gained | |
support for C17 and C23. | |
* Source file extensions ``.ixx`` and ``.cppm`` are now treated as C++. | |
Command-Line | |
------------ | |
* :manual:`cmake(1)` gained the ``--install-prefix <dir>`` | |
command-line option to specify the location of the install prefix. | |
* :manual:`cmake(1)` gained the ``--toolchain <path/to/file>`` | |
command-line option to specify a toolchain file. | |
* :manual:`cmake(1)` ``-E capabilities`` output, for some generators, | |
may now contain a ``supportedPlatforms`` field listing platforms | |
known to be supported in :variable:`CMAKE_GENERATOR_PLATFORM`. | |
* Messages printed to a terminal now may be colored by message type. | |
Compilers | |
--------- | |
* The Fujitsu compiler is now supported using compiler id ``Fujitsu`` | |
in traditional (``Trad``) mode, and compiler id ``FujitsuClang`` | |
in ``Clang`` mode. | |
Platforms | |
--------- | |
* CMake now supports the MSYS runtime environment, much like CYGWIN. | |
File-Based API | |
-------------- | |
* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field | |
has been updated to 2.3. | |
* The :manual:`cmake-file-api(7)` "codemodel" version 2 gained a | |
new "directory" object containing directory-level information. | |
This includes a list of installers generated by the :command:`install` | |
command. | |
Commands | |
-------- | |
* The :command:`add_custom_command` command ``DEPFILE`` option: | |
* may now use | |
:manual:`generator expressions <cmake-generator-expressions(7)>`, | |
* is now supported by :ref:`Visual Studio Generators` for VS 2012 | |
and above, and | |
* is now supported by the :generator:`Xcode` generator. | |
* The :command:`add_custom_command(TARGET)` command | |
(for :ref:`Build Events <add_custom_command(TARGET)>`) | |
gained support for resolving target-dependent generator expressions. | |
* The :command:`build_command` command gained a ``PARALLEL_LEVEL`` option. | |
* The :command:`file(COPY_FILE)` command was added to copy a single file. | |
* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command gained new | |
``POST_INCLUDE_FILES`` and ``POST_EXCLUDE_FILES`` arguments. | |
* The :command:`file(REAL_PATH)` command gained the option ``EXPAND_TILDE`` to | |
replace any leading tilde with the path to the user's home directory. | |
* The :command:`file(RENAME)` command learned to optionally capture | |
failure in a result variable. It also gained a ``NO_REPLACE`` | |
option to fail if the destination exists. | |
* The :command:`install` command gained a new ``IMPORTED_RUNTIME_ARTIFACTS`` | |
mode, which can be used to install the runtime artifacts of imported targets. | |
* The :command:`install` command gained a new ``RUNTIME_DEPENDENCY_SET`` mode, | |
which can be used to install runtime dependencies using | |
:command:`file(GET_RUNTIME_DEPENDENCIES)`. | |
* The :command:`install(TARGETS)` command gained new ``RUNTIME_DEPENDENCIES`` | |
and ``RUNTIME_DEPENDENCY_SET`` arguments, which can be used to install | |
runtime dependencies using :command:`file(GET_RUNTIME_DEPENDENCIES)`. | |
* The :command:`install(SCRIPT|CODE)` command | |
supports a new option ``ALL_COMPONENTS`` which allows | |
the corresponding code to run for every component of | |
a per component installation. | |
* The :command:`project` command now sets variables | |
:variable:`PROJECT_IS_TOP_LEVEL` and :variable:`<PROJECT-NAME>_IS_TOP_LEVEL` | |
to indicate whether it was called in a top-level ``CMakeLists.txt`` file. | |
Variables | |
--------- | |
* The :envvar:`CMAKE_TOOLCHAIN_FILE` environment variable was added to | |
provide a default value for the :variable:`CMAKE_TOOLCHAIN_FILE` variable. | |
Properties | |
---------- | |
* The :prop_dir:`IMPORTED_TARGETS` directory property was added to | |
get a list of :ref:`Imported Targets` created in the current | |
directory. | |
* The :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS <XCODE_EMBED_<type>>` target property | |
was added to tell the :generator:`Xcode` generator to embed app extensions | |
such as iMessage sticker packs. | |
Aspects of the embedding can be customized with the | |
:prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_PATH <XCODE_EMBED_<type>>`, | |
:prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_CODE_SIGN_ON_COPY <XCODE_EMBED_<type>_CODE_SIGN_ON_COPY>` and | |
:prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY <XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY>` | |
properties. | |
Modules | |
------- | |
* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support | |
the serial ``Fujitsu_SSL2`` and parallel ``Fujitsu_SSL2BLAMP`` libraries. | |
* The :module:`FindDevIL` module now provides imported targets. | |
* The :module:`FindIconv` module now has version support. | |
* The :module:`FindIntl` module now has version support. | |
* The :module:`FindMPI` module learned to support ``Fujitsu`` and | |
``FujitsuClang`` in both host and cross compiling modes. | |
* The :module:`FindMsys` module was added to find MSYS installations. | |
Like :module:`FindCygwin`, it is used automatically by some other | |
find modules to locate UNIX-style tools on Windows. | |
* The :module:`FindOpenMP` module learned to support ``Fujitsu`` and | |
``FujitsuClang``. | |
* The :module:`FindVulkan` module gained imported targets | |
``Vulkan::Headers`` and ``Vulkan::glslangValidator``. | |
* The :module:`UseJava` module command ``add_jar`` gained a ``RESOURCES`` | |
option to allow explicit naming of resources with non-optional namespace. | |
* The :module:`UseSWIG` module use now standard library naming conventions | |
for the ``CSharp`` language. See policy :policy:`CMP0122`. | |
* The :module:`UseSWIG` module now supports using the ``swig`` tool to | |
generate implicit dependencies with the :generator:`Xcode` generator. | |
Generator Expressions | |
--------------------- | |
* A new :genex:`TARGET_RUNTIME_DLLS` generator expression was added. | |
CTest | |
----- | |
* :manual:`ctest(1)` gained documentation for its ability to capture | |
:ref:`Additional Test Measurements`. | |
* :manual:`ctest(1)` learned to recognize files attached to a test at run time. | |
Previously it was only possible to attach files to tests at configure time | |
by using the :prop_test:`ATTACHED_FILES` or | |
:prop_test:`ATTACHED_FILES_ON_FAIL` test properties. | |
See :ref:`Additional Test Measurements` for more information. | |
* :manual:`ctest(1)` gained a ``--output-junit`` option to write test results | |
to a JUnit XML file. | |
* The :command:`ctest_build` command gained a ``PARALLEL_LEVEL`` option. | |
CPack | |
----- | |
* The :cpack_gen:`CPack DragNDrop Generator` gained option | |
:variable:`CPACK_DMG_FILESYSTEM` to control the ``.dmg`` filesystem. | |
* The :cpack_gen:`CPack IFW Generator` now supports hyphens in names | |
given to :command:`cpack_ifw_configure_component` or | |
:command:`cpack_ifw_configure_component_group` as ``DEPENDS`` or | |
``DEPENDENCIES`` arguments. This requires QtIFW 3.1 or later. | |
* The :cpack_gen:`CPack NSIS Generator` gained a new | |
:variable:`CPACK_NSIS_EXECUTABLE` variable to specify the ``makensis`` | |
executable to use instead of the default one. | |
* The :variable:`CPACK_CUSTOM_INSTALL_VARIABLES` variable was added to set | |
variables in ``cmake_install.cmake`` script invocations made by CPack. | |
Deprecated and Removed Features | |
=============================== | |
* Undocumented :variable:`CMAKE_SYSTEM_NAME` version-stripping behavior has | |
been removed entirely. If it is set by a ``-D`` flag or by a | |
:manual:`toolchain file <cmake-toolchains(7)>`, it is left unaltered, | |
even if it still contains a version number. | |
Similar :variable:`CMAKE_HOST_SYSTEM_NAME` version-stripping behavior, | |
also undocumented, has been moved earlier, before :command:`project` or | |
:command:`enable_language` is called. | |
* ``ARMClang`` cpu/arch compile and link flags are no longer added | |
automatically based on the :variable:`CMAKE_SYSTEM_PROCESSOR` | |
variable or the undocumented ``CMAKE_SYSTEM_ARCH`` variable. | |
They must be specified explicitly. See policy :policy:`CMP0123`. | |
Other Changes | |
============= | |
* The :command:`find_file`, :command:`find_path`, :command:`find_program`, | |
and :command:`find_library` commands handle cache variables in the same way | |
regardless how they are defined. See policy :policy:`CMP0125` for details. | |
* The :command:`find_file`, :command:`find_path`, :command:`find_program`, | |
and :command:`find_library` commands gained the option ``NO_CACHE`` to store | |
find result in normal variable. | |
* The :command:`foreach` command now isolates loop variables in the loop scope. | |
See policy :policy:`CMP0124` for details. | |
* The :command:`list` command's ``GET``, ``INSERT``, ``SUBLIST``, and | |
``REMOVE_AT`` subcommands now error with invalid (i.e., non-integer) values | |
are given as any of their index arguments based on the setting of policy | |
:policy:`CMP0121`. | |
* The :command:`set(CACHE)` command no longer removes a normal variable | |
of the same name, if any. See policy :policy:`CMP0126`. | |
* :command:`target_link_libraries` calls referencing object libraries | |
via the :genex:`TARGET_OBJECTS` generator expression now place the | |
object files before all libraries on the link line, regardless of | |
their specified order. See documentation on | |
:ref:`Linking Object Libraries via \$\<TARGET_OBJECTS\>` for details. | |
* The :ref:`Ninja Generators` now pass source files and include directories | |
to the compiler using absolute paths. This makes diagnostic messages and | |
debug symbols more consistent, and matches the :ref:`Makefile Generators`. | |
* The :generator:`NMake Makefiles` generator now encodes the generated | |
makefiles as UTF-8 with a BOM when using ``nmake`` from VS 9 or above. | |
* The :ref:`Visual Studio Generators` for VS 2010 and above now place | |
per-source preprocessor definitions after target-wide preprocssor | |
definitions. This makes VS consistent with the :ref:`Ninja Generators` | |
and the :ref:`Makefile Generators`. | |
* The precompiled binaries provided on | |
`cmake.org <https://cmake.org/download/>`_ now support | |
``liblzma`` multi-threading. See the :variable:`CPACK_THREADS` and | |
:variable:`CPACK_ARCHIVE_THREADS` variables. | |
Updates | |
======= | |
Changes made since CMake 3.21.0 include the following. | |
3.21.1 | |
------ | |
* The :generator:`Visual Studio 17 2022` generator is now based on | |
"Visual Studio 2022 Preview 2". Previously it was based on "Preview 1.1". | |
3.21.2 | |
------ | |
* ``CUDA`` targets with :prop_tgt:`CUDA_SEPARABLE_COMPILATION` enabled are now | |
correctly generated in non-root directories. | |
* The :generator:`Visual Studio 17 2022` generator is now based on | |
"Visual Studio 2022 Preview 3.1". Previously it was based on "Preview 2". | |
3.21.3 | |
------ | |
* The :generator:`Visual Studio 17 2022` generator is now based on | |
"Visual Studio 2022 Preview 4". Previously it was based on "Preview 3.1". | |
* The AMD ROCm Platform ``hipcc`` compiler was identifed by CMake 3.21.0 | |
through 3.21.2 as a distinct compiler with id ``ROCMClang``. This has | |
been removed because it caused regressions. Instead: | |
* ``hipcc`` may no longer be used as a ``HIP`` compiler because it | |
interferes with flags CMake needs to pass to Clang. Use Clang directly. | |
* ``hipcc`` may once again be used as a ``CXX`` compiler, and is treated as | |
whatever compiler it selects underneath, as CMake 3.20 and below did. | |
3.21.4 | |
------ | |
* The :generator:`Visual Studio 17 2022` generator is now based on the | |
"Visual Studio 2022" release candidates. Previously it was based on | |
preview versions. | |
3.21.5, 3.21.6 | |
-------------- | |
These versions made no changes to documented features or interfaces. | |
Some implementation updates were made to support ecosystem changes | |
and/or fix regressions. |