Help/release/4.3.rst

CMake 4.3 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 4.2 include the following.

New Features
============

Common Package Specification
----------------------------

* Support for importing and exporting packages described using the |CPS|_
  (CPS) was added.  This improves build system interoperability by allowing
  expressive, feature-rich package descriptions to be exchanged in a format
  other than CMake Language.

  * The :command:`find_package` now searches for and can import CPS packages.

  * The :command:`install` and :command:`export` commands gained a new
    ``PACKAGE_INFO`` sub-command to generate CPS package descriptions.

  * The :command:`project` command gained new ``COMPAT_VERSION`` and
    ``SPDX_LICENSE`` options.  These values may be inherited when creating a
    CPS package description.  See the :command:`install(PACKAGE_INFO)`
    documentation for details.

.. _CPS: https://cps-org.github.io/cps/
.. |CPS| replace:: Common Package Specification

Instrumentation
---------------

* :manual:`cmake-instrumentation(7)` was added to enable collection of
  timing data, target information, and system diagnostic information during
  the configure, generate, build, test, and install steps of a CMake project:

  * Instrumentation data are :ref:`indexed <cmake-instrumentation Indexing>`
    and provided to :ref:`callbacks <cmake-instrumentation Callbacks>` for
    custom processing.

  * Instrumentation data are included in submissions to CDash.

  * Optionally,
    :ref:`Google Trace Event Format <cmake-instrumentation Google Trace File>`
    files may be generated to visualize instrumentation data.

Presets
-------

* :manual:`cmake-presets(7)` files now support schema version ``11``.
  The ``jobs`` field under test presets now supports an empty string, to
  match the behavior of :option:`ctest --parallel` with the value omitted.
* The ``jobs`` field under both build and test presets no longer accept
  negative integer values, regardless of the schema version.

File-Based API
--------------

* The :manual:`cmake-file-api(7)` "codemodel" version 2 version field
  has been updated to 2.10.

* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object
  gained a new ``interfaceSources`` array field, and the ``sourceGroups``
  array items gained a new ``interfaceSourceIndexes`` array field.

Platforms
---------

* ``HIP`` language code may now be compiled for SPIR-V targets,
  e.g., via chipStar.  See the :variable:`CMAKE_HIP_PLATFORM` variable.

Command-Line
------------

* :option:`cmake --version` now supports a ``=json-v1`` value to print
  detailed version information in a JSON format.

* :option:`cmake --build` now supports specifying a build directory and
  preset together.  The build preset will be used with the explicit
  build directory substituted.

* The :option:`cmake -E` commands
  :option:`md5sum <cmake-E md5sum>`,
  :option:`sha1sum <cmake-E sha1sum>`,
  :option:`sha224sum <cmake-E sha224sum>`,
  :option:`sha256sum <cmake-E sha256sum>`,
  :option:`sha384sum <cmake-E sha384sum>`, and
  :option:`sha512sum <cmake-E sha512sum>`
  now support reading from standard input by passing ``-``.

* The :option:`cmake -E bin2c <cmake-E bin2c>` command-line tool was added.

* The :option:`cmake -E tar <cmake-E tar>` command-line tool:

  * Gained a ``--cmake-tar-compression-level`` flag to specify the
    compression level.
  * Gained a ``--cmake-tar-compression-method`` flag to specify the
    compression method.
  * Gained a ``--cmake-tar-threads`` flag to enable multithreaded operations.
  * Now supports specifying compression method and level for ``7zip`` and
    ``zip`` formats.
  * Gained a ``--format=raw`` flag to disable compression.
  * Gained a ``--lzma`` flag to specify ``LZMA`` compression.

Commands
--------

* The :command:`cmake_instrumentation` command was added to make
  project-level instrumentation queries.

* The :command:`file(ARCHIVE_CREATE)` command:

  * Gained a ``THREADS`` option to enable multithreaded operations.
  * Now supports ``COMPRESSION`` method ``Deflate`` as an alias for ``GZip``.
  * Now supports ``COMPRESSION`` method ``LZMA``.
  * Now supports ``COMPRESSION`` method ``LZMA2`` as an alias for ``XZ``.
  * Now supports ``COMPRESSION`` method ``PPMd`` for format ``7zip``.
  * Now supports ``COMPRESSION`` and ``COMPRESSION_LEVEL`` options
    for formats ``7zip`` and ``zip``.

* The :command:`get_property` and :command:`set_property` commands
  now support a ``FILE_SET`` scope for file set properties of a target.

* The :command:`string(JSON)` command gained new ``GET_RAW`` and
  ``STRING_ENCODE`` modes.

* The :command:`source_group` command now supports
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

* The :command:`cmake_host_system_information` command gained a
  ``LOCALE_CHARSET`` query for the expected :manual:`cmake-language(7)`
  script encoding.

Variables
---------

* The :variable:`CMAKE_<LANG>_LINK_FLAGS` and
  :variable:`CMAKE_<LANG>_LINK_FLAGS_<CONFIG>` variables were added
  to support per-language link flags for all target types.
  See policy :policy:`CMP0210`.

* The :variable:`CMAKE_VERIFY_PRIVATE_HEADER_SETS` variable and corresponding
  :prop_tgt:`VERIFY_PRIVATE_HEADER_SETS` target property were added to
  enable build rules that verify all headers in private file sets can be used
  on their own.

Properties
----------

* A :prop_tgt:`<LANG>_PVS_STUDIO` target property and supporting
  :variable:`CMAKE_<LANG>_PVS_STUDIO` variable were introduced to tell
  :ref:`Makefile Generators` and :ref:`Ninja Generators` to run
  ``pvs-studio-analyzer`` with the compiler for ``C`` and ``CXX`` languages.

* When :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` is set to true on an executable
  target, that target's interface file sets are verified regardless of its
  :prop_tgt:`ENABLE_EXPORTS` property. See policy :policy:`CMP0209`.

* The :prop_tgt:`PRIVATE_HEADER_SETS_TO_VERIFY` target property was added to
  customize which private file sets to verify when the target's
  :prop_tgt:`VERIFY_PRIVATE_HEADER_SETS` property is true.

Modules
-------

* The :module:`FindCUDAToolkit` module now creates a ``CUDA::bin2c``
  imported target for the :ref:`bin2c <FindCUDAToolkit_bin2c>` utility.

* The :module:`FindLibXml2` module gained a ``LibXml2_USE_STATIC_LIBS`` hint
  to select static libraries.

* The :module:`FindRuby` module now provides imported targets.

* The :module:`FindSQLite3` module now provides imported
  targets with the ``SQLite3::`` prefix.

* The :module:`UseJava` module's :command:`add_jar` command now accepts a new
  ``INCLUDE_MODULES`` option that adds its arguments to the ``--module-path``
  argument to the Java compiler. This allows building JAR files that use JPMS
  modules in their build.

Generator Expressions
---------------------

* :ref:`String Comparison <String Comparisons Generator Expressions>`
  generator expressions were added.

* :genex:`$<STRING:...>` generator expressions were added for
  :ref:`query <String Queries Generator Expressions>`,
  :ref:`generation <String Generating Generator Expressions>`, and
  :ref:`transformation <String Transforming Generator Expressions>`
  operations on strings.

* The :genex:`$<FILE_SET_EXISTS>` and :genex:`$<FILE_SET_PROPERTY>` generator
  expressions were added to query file set existence and properties.

* The :genex:`$<SOURCE_EXISTS>` and :genex:`$<SOURCE_PROPERTY>` generator
  expressions were added to query source file existence and properties.

CTest
-----

* The :module:`CTestCoverageCollectGCOV` module:

  * Now supports ``TARBALL_COMPRESSION`` method ``LZMA``.

  * Now supports ``TARBALL_COMPRESSION`` method ``LZMA2``
    as an alias for ``XZ``.

  * Now supports ``FROM_EXT`` with file extensions corresponding to
    ``LZMA`` and ``ZSTD`` compression.

CPack
-----

* :module:`CPack` gained the :variable:`CPACK_COMPRESSION_LEVEL`
  variable to control the compression level used when creating
  packages.

* The :cpack_gen:`CPack Archive Generator`:

  * Now supports compression method specification for formats
    ``7zip`` and ``zip``.

  * Gained a :variable:`CPACK_ARCHIVE_COMPRESSION_LEVEL` option to
    control the compression level used when creating archive packages.

  * Gained :variable:`CPACK_ARCHIVE_UID` and :variable:`CPACK_ARCHIVE_GID`
    options to specify the UID and GID of archive entries, respectively.
    The defaults are UID ``0`` and GID ``0``.  See policy :policy:`CMP0206`.

* The :cpack_gen:`CPack DEB Generator` gained a new
  :variable:`CPACK_DEBIAN_COMPRESSION_LEVEL` variable to control the
  compression level used when creating Debian packages.

* The :cpack_gen:`CPack WIX Generator` now supports per-user installers
  by setting :variable:`CPACK_WIX_INSTALL_SCOPE` to ``perUser``.

Deprecated and Removed Features
===============================

* The :variable:`CMAKE_ENABLE_EXPORTS` variable is deprecated in favor of
  the :variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` and
  :variable:`CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS` variables.

* The :command:`export(EXPORT)` command no longer allows certain
  arguments to be missing or empty.  See policy :policy:`CMP0208`.

Other Changes
=============

* The :option:`cmake -E tar <cmake-E tar>` command-line tool
  and the :command:`file(ARCHIVE_EXTRACT)` command now reject archive
  entries whose paths are absolute or contain ``..`` path traversal
  components.

* The family of :option:`cmake --trace` and related commands now print "end"
  commands for control structures: :command:`endblock`, :command:`endforeach`,
  :command:`endfunction`, :command:`endif`, :command:`endmacro`, and
  :command:`endwhile`.

* The :command:`file(CREATE_LINK)` command's ``COPY_ON_ERROR`` option,
  when used with a directory, now copies directory content.
  See policy :policy:`CMP0205`.

* The :command:`file(GET_RUNTIME_DEPENDENCIES)`
  and :command:`install(RUNTIME_DEPENDENCY_SET)` commands now normalize
  paths before matching filters.  See policy :policy:`CMP0207`.

* The precompiled Linux ``aarch64`` binaries provided on
  `cmake.org <https://cmake.org/download/>`_ now require GLIBC 2.28 or higher.

* The precompiled macOS binary provided on ``cmake.org`` for macOS 10.13+
  now requires macOS 12 or newer for the :manual:`cmake-gui(1)` application.
  The command-line tools still run on macOS 10.13.

* The precompiled Windows binaries provided on
  `cmake.org <https://cmake.org/download/>`_ now require Windows 10 or higher.

Updates
=======

Changes made since CMake 4.3.0 include the following.

4.3.1, 4.3.2
------------

* These versions made no changes to documented features or interfaces.
  Some implementation updates were made to support ecosystem changes
  and/or fix regressions.

4.3.3
-----

* The :command:`export(PACKAGE_INFO)` command now writes to the
  ``cps/<package-name>`` subdirectory of the current build directory,
  rather than directly to the current build directory.

4.3.4
-----

* :manual:`cmake-instrumentation(7)`, introduced in 4.3.0, has been *changed*
  to generate :ref:`index files <cmake-instrumentation v1 Index File>` and
  :ref:`snippet files <cmake-instrumentation v1 Snippet File>` with a new
  ``version`` field format.  It is now an object with major and minor version
  components, ``{ "major": 1, "minor": 0 }``.  Previously it was an integer
  with only the major version, ``1``.

4.3.5
-----

* This version made no changes to documented features or interfaces.
  Some implementation updates were made to support ecosystem changes
  and/or fix regressions.