Help/release/3.21.rst

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.