code:
CMake 3.2 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.1 include the following.

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

Syntax
------

* CMake learned to support unicode characters
  :ref:`encoded as UTF-8 <CMake Language Encoding>`
  on Windows.  This was already supported on platforms whose
  system APIs accept UTF-8 encoded strings.
  Unicode characters may now be used in CMake code, paths to
  source files, configured files such as ``.h.in`` files, and
  other files read and written by CMake.  Note that because CMake
  interoperates with many other tools, there may still be some
  limitations when using certain unicode characters.

Commands
--------

* The :command:`add_custom_command` and :command:`add_custom_target`
  commands learned a new ``BYPRODUCTS`` option to specify files
  produced as side effects of the custom commands.  These are not
  outputs because they do not always have to be newer than inputs.

* The :command:`add_custom_command` and :command:`add_custom_target`
  commands learned a new ``USES_TERMINAL`` option to request that
  the command be given direct access to the terminal if possible.
  The :generator:`Ninja` generator will places such commands in the
  ``console`` :prop_gbl:`pool <JOB_POOLS>`.  Build targets provided by CMake
  that are meant for individual interactive use, such as ``install``, are now
  placed in this pool.

* A new :command:`continue` command was added that can be called inside loop
  contexts to end the current iteration and start the next one at the top of
  the loop block.

* The :command:`file(LOCK)` subcommand was created to allow CMake
  processes to synchronize through file and directory locks.

* The :command:`file(STRINGS)` now supports UTF-16LE, UTF-16BE,
  UTF-32LE, UTF-32BE as ``ENCODING`` options.

* The :command:`install(EXPORT)` command now works with an absolute
  ``DESTINATION`` even if targets in the export set are installed
  with a destination or :ref:`usage requirements <Target Usage Requirements>`
  specified relative to the install prefix.  The value of the
  :variable:`CMAKE_INSTALL_PREFIX` variable is hard-coded into the installed
  export file as the base for relative references.

* The :command:`try_compile` command source file signature now honors
  link flags (e.g. :variable:`CMAKE_EXE_LINKER_FLAGS`) in the generated
  test project.  See policy :policy:`CMP0056`.

* The :command:`try_run` command learned to honor the ``LINK_LIBRARIES``
  option just as :command:`try_compile` already does.

* The :command:`file(GENERATE)` command now generates the output file with
  the same permissions as the input file if set.

* The :command:`file(GENERATE)` command can now generate files which are
  used as source files for buildsystem targets.  Generated files
  automatically get their :prop_sf:`GENERATED` property set to ``TRUE``.

Variables
---------

* The :variable:`CMAKE_MATCH_COUNT` variable was introduced to record the
  number of matches made in the last regular expression matched in an
  :command:`if` command or a :command:`string` command.

Properties
----------

* An :prop_tgt:`ANDROID_API_MIN` target property was introduced to
  specify the minimum version to be targeted by the toolchain.

* A :prop_sf:`VS_SHADER_FLAGS` source file property was added to specify
  additional shader flags to ``.hlsl`` files, for the Visual Studio
  generators.

Modules
-------

* The :module:`ExternalData` module learned to support
  :ref:`Custom Fetch Scripts <ExternalData Custom Fetch Scripts>`.
  This allows projects to specify custom ``.cmake`` scripts for
  fetching data objects during the build.

* The :module:`ExternalProject` module learned options to create
  independent external project step targets that do not depend
  on the builtin steps.

* The :module:`ExternalProject` module :command:`ExternalProject_Add`
  command learned a new ``CMAKE_CACHE_DEFAULT_ARGS`` option to
  initialize cache values in the external project without setting
  them on future builds.

* The :module:`ExternalProject` module :command:`ExternalProject_Add`
  command learned a new ``TEST_EXCLUDE_FROM_MAIN`` option to exclude
  tests from the main build.

* The :module:`ExternalProject` module :command:`ExternalProject_Add`
  command learned a new ``UPDATE_DISCONNECTED`` option to avoid
  automatically updating the source tree checkout from version control.

* The :module:`FindCUDA` module learned about the ``cusolver``
  library in CUDA 7.0.

* The :module:`FindGit` module learned to find the ``git`` command-line tool
  that comes with GitHub for Windows installed in user home directories.

* A :module:`FindGSL` module was introduced to find the
  GNU Scientific Library.

* A :module:`FindIntl` module was introduced to find the
  Gettext ``libintl`` library.

* The :module:`FindLATEX` module learned to support components.

* The :module:`FindMPI` module learned to find MS-MPI on Windows.

* The :module:`FindOpenSSL` module now reports ``crypto`` and ``ssl``
  libraries separately in ``OPENSSL_CRYPTO_LIBRARY`` and
  ``OPENSSL_SSL_LIBRARY``, respectively, to allow applications to
  link to one without the other.

* The :module:`WriteCompilerDetectionHeader` module learned to
  create a define for portability of the ``cxx_thread_local`` feature.
  The define expands to either the C++11 ``thread_local`` keyword, or a
  pre-standardization compiler-specific equivalent, as appropriate.

* The :module:`WriteCompilerDetectionHeader` module learned to create
  multiple output files per compiler and per language, instead of creating
  one large file.

CTest
-----

* The :command:`ctest_coverage` command learned to support Delphi coverage.

* The :command:`ctest_coverage` command learned to support Javascript coverage.

* The :module:`CTestCoverageCollectGCOV` module was introduced as an
  alternative to the :command:`ctest_coverage` command for collecting
  ``gcov`` results for submission to CDash.

CPack
-----

* The :cpack_gen:`CPack RPM Generator` learned options to set per-component
  descriptions and summaries.  See the
  :variable:`CPACK_RPM_<component>_PACKAGE_DESCRIPTION` and
  :variable:`CPACK_RPM_<component>_PACKAGE_SUMMARY` variables.

* The :cpack_gen:`CPack RPM Generator` learned options to specify
  requirements for pre- and post-install scripts.  See the
  :variable:`CPACK_RPM_PACKAGE_REQUIRES_PRE` and
  :variable:`CPACK_RPM_PACKAGE_REQUIRES_POST` variables.

* The :cpack_gen:`CPack RPM Generator` learned options to specify
  requirements for pre- and post-uninstall scripts.  See the
  :variable:`CPACK_RPM_PACKAGE_REQUIRES_PREUN` and
  :variable:`CPACK_RPM_PACKAGE_REQUIRES_POSTUN` variables.

* The :cpack_gen:`CPack RPM Generator` learned a new
  :variable:`CPACK_RPM_<COMPONENT>_PACKAGE_PREFIX` variable to
  specify a component-specific value to use instead of
  :variable:`CPACK_PACKAGING_INSTALL_PREFIX`.

* The :cpack_gen:`CPack RPM Generator` learned a new
  :variable:`CPACK_RPM_RELOCATION_PATHS` variable to
  specify multiple relocation prefixes for a single rpm package.

Other
-----

* The :manual:`cmake(1)` ``-E tar`` command now supports creating
  ``.xz``-compressed archives with the ``J`` flag.

* The :manual:`cmake(1)` ``-E tar`` command learned a new
  ``--files-from=<file>`` option to specify file names using
  lines in a file to overcome command-line length limits.

* The :manual:`cmake(1)` ``-E tar`` command learned a new
  ``--mtime=<date>`` option to specify the modification time
  recorded in tarball entries.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of features supported by more compilers, including:

  * Apple Clang (``AppleClang``) for Xcode versions 4.4 though 6.1.
  * GNU compiler versions 4.4 through 5.0 on UNIX and Apple (``GNU``).
  * Microsoft Visual Studio (``MSVC``) for versions 2010 through 2015.
  * Oracle SolarisStudio (``SunPro``) version 12.4.

* The :ref:`Qt AUTORCC` feature now tracks files listed in ``.qrc`` files
  as dependencies. If an input file to the ``rcc`` tool is changed, the tool
  is automatically re-run.

New Diagnostics
===============

* The :command:`break` command now rejects calls outside of a loop
  context or that pass arguments to the command.
  See policy :policy:`CMP0055`.

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

* Files written in the :manual:`cmake-language(7)`, such as
  ``CMakeLists.txt`` or ``*.cmake`` files, are now expected to be
  encoded as UTF-8.  If files are already ASCII, they will be
  compatible.  If files were in a different encoding, including
  Latin 1, they will need to be converted.

* The :module:`FindOpenGL` module no longer explicitly searches
  for any dependency on X11 libraries with the :module:`FindX11`
  module.  Such dependencies should not need to be explicit.
  Applications using X11 APIs themselves should find and link
  to X11 libraries explicitly.

* The implementation of CMake now relies on some C++ compiler features which
  are not supported by some older compilers.  As a result, those old compilers
  can no longer be used to build CMake itself.  CMake continues to be able to
  generate Makefiles and project files for users of those old compilers
  however.  Compilers known to no longer be capable of building CMake are:

  * Visual Studio 6 and 7.0 -- superseded by VisualStudio 7.1 and newer.
  * GCC 2.95 -- superseded by GCC 3 and newer compilers.
  * Borland compilers -- superseded by other Windows compilers.
  * Compaq compilers -- superseded by other compilers.
  * SGI compilers -- IRIX was dropped as a host platform.

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

* On Windows and OS X, commands supporting network communication
  via ``https``, such as :command:`file(DOWNLOAD)`,
  :command:`file(UPLOAD)`, and :command:`ctest_submit`, now support
  SSL/TLS even when CMake is not built against OpenSSL.
  The Windows or OS X native SSL/TLS implementation is used by default.
  OS-configured certificate authorities will be trusted automatically.

  On other platforms, when CMake is built with OpenSSL, these
  commands now search for OS-configured certificate authorities
  in a few ``/etc`` paths to be trusted automatically.

* On OS X with Makefile and Ninja generators, when a compiler is found
  in ``/usr/bin`` it is now mapped to the corresponding compiler inside
  the Xcode application folder, if any.  This allows such build
  trees to continue to work with their original compiler even when
  ``xcode-select`` switches to a different Xcode installation.

* The Visual Studio generators now write solution and project
  files in UTF-8 instead of Windows-1252.  Windows-1252 supported
  Latin 1 languages such as those found in North and South America
  and Western Europe.  With UTF-8, additional languages are now
  supported.

* The :generator:`Xcode` generator no longer requires a value for
  the :variable:`CMAKE_MAKE_PROGRAM` variable to be located up front.
  It now locates ``xcodebuild`` when needed at build time.

* When building CMake itself using SolarisStudio 12, the default ``libCStd``
  standard library is not sufficient to build CMake.  The SolarisStudio
  distribution supports compiler options to use ``STLPort4`` or ``libstdc++``.
  An appropriate option to select the standard library is now added
  automatically when building CMake with SolarisStudio compilers.


code:
CMake 3.20 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.19 include the following.

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

Presets
-------

* :manual:`cmake-presets(7)` gained support for build and test presets.

Generators
----------

* :ref:`Makefile Generators`, for some toolchains, now use the compiler
  to extract implicit dependencies while compiling source files.

Languages
---------

* C++23 compiler modes may now be specified via the :prop_tgt:`CXX_STANDARD`,
  :prop_tgt:`CUDA_STANDARD`, or :prop_tgt:`OBJCXX_STANDARD` target properties,
  or via the :manual:`Compile Features <cmake-compile-features(7)>`
  functionality's ``cxx_std_23`` meta-feature.

* ``CUDA`` language support now works when ``nvcc`` is a symbolic link,
  for example due to a ``ccache`` or ``colornvcc`` wrapper script.

* The :envvar:`CUDAARCHS` environment variable was added for initializing
  :variable:`CMAKE_CUDA_ARCHITECTURES`. Useful in cases where the compiler
  default is unsuitable for the machine's GPU.

Compilers
---------

* The NVIDIA HPC SDK compilers are now supported with compiler id ``NVHPC``.

* The Intel oneAPI NextGen LLVM compilers are now supported with
  compiler id ``IntelLLVM``:

  * The ``icx``/``icpx`` C/C++ compilers on Linux, and the ``icx``
    C/C++ compiler on Windows, are fully supported as of oneAPI 2021.1.

  * The ``ifx`` Fortran compiler on Linux is supported as of oneAPI 2021.1.

  * The ``ifx`` Fortran compiler on Windows is not yet supported.

  The Intel oneAPI Classic compilers (``icc``, ``icpc``, and ``ifort``)
  continue to be supported with compiler id ``Intel``.

* Support was added for the IAR STM8 compiler.

Platforms
---------

* CMake's support for :ref:`Cross Compiling for Android`
  is now merged with the Android NDK's toolchain file.
  They now have similar behavior, though some variable names differ.
  User-facing changes include:

  - ``find_*`` functions will search NDK ABI / API specific paths by default.

  - The default :variable:`CMAKE_BUILD_TYPE` for Android is
    now ``RelWithDebInfo``.

  - The :variable:`CMAKE_ANDROID_NDK_VERSION` variable was added to
    report the version of the NDK.

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

* The :manual:`cmake-file-api(7)` gained a new "toolchains" object
  kind that describes the compiler used for each enabled language.

Commands
--------

* :command:`add_custom_command` and :command:`add_custom_target` now
  support :manual:`generator expressions <cmake-generator-expressions(7)>`
  in their ``OUTPUT`` and ``BYPRODUCTS`` options.

  Their ``COMMAND``, ``WORKING_DIRECTORY``, and ``DEPENDS`` options gained
  support for new generator expressions :genex:`$<COMMAND_CONFIG:...>` and
  :genex:`$<OUTPUT_CONFIG:...>` that control cross-config handling when using
  the :generator:`Ninja Multi-Config` generator.

* The :command:`add_custom_command` command gained ``DEPFILE`` support on
  :ref:`Makefile Generators`.

* The :command:`add_library` command previously prohibited imported object
  libraries when using potentially multi-architecture configurations.
  This mostly affected the :generator:`Xcode` generator, e.g. when targeting
  iOS or one of the other device platforms.  This restriction has now been
  removed.

* The :command:`cmake_path` command was added for operations on
  filesystem paths.

* The :command:`configure_file` command gained ``USE_SOURCE_PERMISSIONS``
  and ``FILE_PERMISSIONS`` options to support copying of permissions of the
  source file and using specified permissions respectively.

* The :command:`file(GENERATE)` command gained a ``NEWLINE_STYLE`` option to
  specify how newlines are handled for the generated file.

* The :command:`file(GENERATE)` command gained ``NO_SOURCE_PERMISSIONS``,
  ``USE_SOURCE_PERMISSIONS``, and ``FILE_PERMISSIONS`` options for controlling
  the permissions of the generated file.

* The :command:`install(FILES)` command ``RENAME`` option learned to
  support :manual:`generator expressions <cmake-generator-expressions(7)>`.

* The :command:`target_include_directories` command gained a new option
  ``AFTER``.

* The :command:`target_sources` command now supports targets created
  by the :command:`add_custom_target` command.

* The :command:`try_run` command gained a ``WORKING_DIRECTORY`` option to
  set the working directory in which to run the compiled check executable.

Variables
---------

* The :variable:`CMAKE_<LANG>_BYTE_ORDER` variable was added to provide the
  target architecture byte order detected from the toolchain.

* The :variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY`,
  :variable:`CMAKE_LIBRARY_OUTPUT_DIRECTORY`, and
  :variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY` variables now support
  target-dependent generator expressions.

Properties
----------

* The :prop_tgt:`<LANG>_CLANG_TIDY` target property and the associated
  :variable:`CMAKE_<LANG>_CLANG_TIDY` variable learned to support
  the ``OBJC`` and ``OBJCXX`` languages.

* The :prop_tgt:`EXPORT_COMPILE_COMMANDS` target property was added
  for the associated :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable
  to allow for configuration of exporting compile commands per target.

* The :prop_sf:`GENERATED` source-file property is now visible
  from any directory scope, regardless of the scope in which it is set.
  See policy :policy:`CMP0118`.

* The :prop_tgt:`UNITY_BUILD_UNIQUE_ID` target property
  was added to support generation of an identifier that is
  unique per source file in unity builds.  It can help to
  resolve duplicate symbol problems with anonymous namespaces.

* The :prop_tgt:`WIN32_EXECUTABLE` target property now works with Clang
  on Windows.

* The :prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` target property
  was added to tell the :generator:`Xcode` generator to embed frameworks.
  Aspects of the embedding can be customized with the
  :prop_tgt:`XCODE_EMBED_FRAMEWORKS_PATH <XCODE_EMBED_<type>>`,
  :prop_tgt:`XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY`, and
  :prop_tgt:`XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY` target properties.

Modules
-------

* The :module:`ExternalData` module :command:`ExternalData_Add_Target`
  function gained a ``SHOW_PROGRESS <bool>`` option for controlling whether
  or not to show progress output during the build.

* The :module:`ExternalProject` module :command:`ExternalProject_Add` function
  gained a ``CONFIGURE_HANDLED_BY_BUILD`` option.  This can be used to make
  subsequent runs of the configure step be triggered by the build step when
  an external project dependency rebuilds instead of always re-running the
  configure step in such cases.

* The :module:`FindBoost` module gained a ``Boost_NO_WARN_NEW_VERSIONS``
  option to silence the warning about unknown dependencies for new
  Boost versions.

* The :module:`FindCUDAToolkit` module gained support for finding CUDA
  toolkits when ``nvcc`` is a symbolic link,
  for example due to a ``ccache`` or ``colornvcc`` wrapper script.

* The :module:`FindGDAL` module has been improved to document and mark as
  advanced its cache variables. There is a new ``FindGDAL_SKIP_GDAL_CONFIG``
  variable which may be used to skip over the ``gdal-config``-based search.
  Users may also set ``GDAL_ADDITIONAL_LIBRARY_VERSIONS`` to add additional
  versions to the library name search strategy.

* The :module:`FindIntl` module now provides an imported target.

* The :module:`FindOpenSSL` module learned to support a version range.

* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
  modules gained options controlling how unversioned interpreter names are
  searched.

* The :module:`UseJava` module ``add_jar()`` command's
  ``GENERATE_NATIVE_HEADERS`` feature gained options to export the
  generated target.

* The :module:`UseSWIG` module gained the capability, for
  :ref:`Makefile <Makefile Generators>` and :ref:`Ninja <Ninja Generators>`
  generators, to use the ``swig`` tool to generate implicit dependencies.

Autogen
-------

* The :ref:`Qt AUTOMOC` feature now works with per-config sources.

CTest
-----

* :manual:`ctest(1)` gained a :option:`--test-dir <ctest --test-dir>`
  option to specify the directory in which to look for tests.

CPack
-----

* :module:`CPack` gained the :variable:`CPACK_THREADS` variable to
  control the number of threads used for parallelized operations,
  such as compressing the installer package.

* The :cpack_gen:`CPack DEB Generator` learned a new
  :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS`
  variable to specify additional search directories for
  resolving private library dependencies when using
  ``dpkg-shlibdeps``.

* The :cpack_gen:`CPack IFW Generator` gained a new
  :variable:`CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST` variable to
  control visibility of the widget listing installer pages on the left side
  of the wizard. This feature available only since QtIFW 4.0.

* The :cpack_gen:`CPack NSIS Generator` gained new
  :variable:`CPACK_NSIS_BRANDING_TEXT` and
  :variable:`CPACK_NSIS_BRANDING_TEXT_TRIM_POSITION` variables to change
  the text at the bottom of the install window and change its trim position

* The :cpack_gen:`CPack NSIS Generator` now correctly handles Unicode
  characters.  If you want to have a :variable:`CPACK_RESOURCE_FILE_LICENSE`
  with UTF-8 characters, it needs to be encoded in UTF-8 BOM.

* The :cpack_gen:`CPack NuGet Generator` gained options:

  - :variable:`CPACK_NUGET_PACKAGE_ICON` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_ICON`
    allow package icons to be specified by local files.
  - :variable:`CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION` add
    support for specifying licenses recognized by the
    `Software Package Data Exchange`_ (SPDX).
  - :variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME` allow
    licenses to be specified by local files.
  - :variable:`CPACK_NUGET_PACKAGE_LANGUAGE` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LANGUAGE` allow the locale
    for a package to be specified, for example ``en_CA``.

.. _Software Package Data Exchange: https://spdx.dev/

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

* The :manual:`cmake-server(7)` mode has been removed.
  Clients should use the :manual:`cmake-file-api(7)` instead.

* The :module:`WriteCompilerDetectionHeader` module has been deprecated
  via policy :policy:`CMP0120`.  Projects should be ported away from it.

* The :module:`TestBigEndian` module has been deprecated in favor
  of the :variable:`CMAKE_<LANG>_BYTE_ORDER` variable.

* The :module:`AddFileDependencies` module is deprecated.
  Port projects to use :command:`set_property` directly.

* The :cpack_gen:`CPack NuGet Generator` deprecated some variables to reflect
  changes in the NuGet specification:

  - :variable:`CPACK_NUGET_PACKAGE_ICONURL` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_ICONURL` have been deprecated;
    replace with a reference to a local icon file.
  - :variable:`CPACK_NUGET_PACKAGE_LICENSEURL` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSEURL` have been deprecated;
    replace with a reference to the project's license file or SPDX
    license expression.

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

* When running :manual:`cmake(1)` to :ref:`Generate a Project Buildsystem`,
  unknown command-line arguments starting with a hyphen (``-``) are now
  rejected with an error.  Previously they were silently ignored.

* Source file extensions must now be explicit.
  See policy :policy:`CMP0115` for details.

* The :prop_sf:`LANGUAGE` source file property now forces compilation
  as the specified language.  See policy :policy:`CMP0119`.

* On AIX, installation of XCOFF executables and shared libraries
  no longer requires relinking to change the runtime search path
  from the build-tree RPATH to the install-tree RPATH.  CMake now
  edits the XCOFF binaries directly during installation, as has
  long been done on ELF platforms.

* With MSVC-like compilers the value of
  :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` no longer contains
  the ``/GR`` flag for runtime type information by default.
  See policy :policy:`CMP0117`.

* Ninja generators now transform the ``DEPFILE`` generated by an
  :command:`add_custom_command`. See policy :policy:`CMP0116` for details.

* The precompiled Linux binaries provided on
  `cmake.org <https://cmake.org/download/>`_ have changed their naming pattern
  to ``cmake-$ver-linux-$arch``, where ``$arch`` is either ``x86_64`` or
  ``aarch64``.

* The precompiled Windows binaries provided on
  `cmake.org <https://cmake.org/download/>`_ have changed their naming pattern
  to ``cmake-$ver-windows-$arch``, where ``$arch`` is either ``x86_64`` or
  ``i386``.

Updates
=======

Changes made since CMake 3.20.0 include the following.

3.20.1
------

* The :module:`FindIntl` module in CMake 3.20.0 added checks
  ``Intl_HAVE_GETTEXT_BUILTIN``, ``Intl_HAVE_DCGETTEXT_BUILTIN``,
  and ``Intl_IS_BUILTIN``, but they were not implemented correctly.
  These have been removed and replaced with a single ``Intl_IS_BUILT_IN``
  check, whose name is consistent with the :module:`FindIconv` module.

* The ``-rpath`` linker flag is now specified as supported on all Apple
  platforms, not just macOS.  The ``install_name_dir`` used for
  iOS, tvOS and watchOS should now default to ``@rpath`` instead of using
  a full absolute path and failing at runtime when the library or framework
  is embedded in an application bundle (see :prop_tgt:`XCODE_EMBED_<type>`).

3.20.2
------

* The Intel Classic 2021 compiler version numbers are now detected correctly
  as having major version 2021.  CMake 3.20.1 and below were not aware of a
  change to the identification macro version scheme made by Intel starting
  in version 2021, and detected the version as 20.2.

* The Intel oneAPI Fortran compiler is now identified as ``IntelLLVM``.
  The oneAPI 2021.1 Fortran compiler is missing an identification macro,
  so CMake 3.20.1 and below identified it as ``Intel``.  CMake now has
  a special case to recognize oneAPI 2021.1 Fortran as ``IntelLLVM``.
  The oneAPI 2021.2 Fortran compiler defines the proper identification
  macro and so is identified as ``IntelLLVM`` by all CMake 3.20 versions.

3.20.3, 3.20.4, 3.20.5, 3.20.6
------------------------------

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

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
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 :option:`--install-prefix <cmake --install-prefix>`
  command-line option to specify the location of the install prefix.

* :manual:`cmake(1)` gained the :option:`--toolchain <cmake --toolchain>`
  command-line option to specify a toolchain file.

* :manual:`cmake(1)` :option:`-E capabilities <cmake-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 :option:`--output-junit <ctest --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 identified 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, 3.21.7
----------------------

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


code:
CMake 3.22 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.21 include the following.

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

Commands
--------

* The :command:`cmake_host_system_information` command can now query
  `OS identification variables`_ from the :file:`/etc/os-release` file.

* The :command:`string(TIMESTAMP)` command now supports the ``%V``
  specifier for ISO 8601 week numbers.

.. _`OS identification variables`: https://www.freedesktop.org/software/systemd/man/latest/os-release.html

Variables
---------

* The :envvar:`CMAKE_BUILD_TYPE` environment variable was added to
  provide a default value for the :variable:`CMAKE_BUILD_TYPE` variable.

* The :envvar:`CMAKE_CONFIGURATION_TYPES` environment variable was added to
  provide a default value for the :variable:`CMAKE_CONFIGURATION_TYPES`
  variable.

* The :envvar:`CMAKE_INSTALL_MODE` environment variable was added to
  tell :command:`install` rules (implemented by :command:`file(INSTALL)`)
  to install symbolic links instead of copying of files.

* The :variable:`CMAKE_<LANG>_LINK_WHAT_YOU_USE_FLAG` and
  :variable:`CMAKE_LINK_WHAT_YOU_USE_CHECK` variables were added to
  control the linker flag and check used by the
  :prop_tgt:`LINK_WHAT_YOU_USE` target property.

* The :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable
  was added to turn a non-REQUIRED :command:`find_package` call into
  a REQUIRED one.

Properties
----------

* The :prop_tgt:`<LANG>_EXTENSIONS` target property is now initialized to
  :variable:`CMAKE_<LANG>_EXTENSIONS_DEFAULT`, detected from the compiler.
  See :policy:`CMP0128`.

* The :prop_sf:`VS_SETTINGS` source file property is now supported for
  all source file types.  Previously it worked only for non-built sources.

Modules
-------

* The :module:`CMakeDependentOption` module :command:`cmake_dependent_option`
  macro now supports full :ref:`Condition Syntax`.
  See policy :policy:`CMP0127`.

* The :module:`FetchContent` module now passes through the
  :variable:`CMAKE_TLS_VERIFY`, :variable:`CMAKE_TLS_CAINFO`,
  :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables (when
  defined) to the underlying :module:`ExternalProject` sub-build.
  Previously, those variables were silently ignored by :module:`FetchContent`.

* The :module:`FindBLAS` and :module:`FindLAPACK` modules gained
  a ``BLA_SIZEOF_INTEGER`` option to find a BLAS/LAPACK whose ABI
  uses a specific integer size.

* The :module:`FindJasper` module now provides an imported target.

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

* The :module:`FindPkgConfig` module gained a :variable:`PKG_CONFIG_ARGN`
  variable to specify arguments to ``pkg-config`` calls.

* The :module:`GoogleTest` module :command:`gtest_discover_tests`
  function gained a ``TEST_FILTER`` option to filter tests using
  ``--gtest_filter`` during test discovery.

* The :module:`UseSWIG` module, for :ref:`Visual Studio Generators`,
  can now use the ``swig`` tool to generate implicit dependencies.

CTest
-----

* :manual:`ctest(1)` learned to recognize labels attached to a test at run time.
  Previously it was only possible to attach labels to tests at configure time
  by using the :prop_test:`LABELS` test property.
  See :ref:`Additional Test Measurements` for more information.

* :manual:`ctest(1)` learned to be able to modify the environment for a test
  through the :prop_test:`ENVIRONMENT_MODIFICATION` property. This is allows
  for updates to environment variables based on the environment present at
  test time.

* The :command:`ctest_memcheck` command now also generates a
  :file:`DynamicAnalysis-Test.xml` file which may be used to submit test
  results to CDash.

CPack
-----

* The :cpack_gen:`CPack DEB Generator` gained the
  option to set :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` to ``zstd``,
  which enables Zstandard compression for deb packages.

* The :cpack_gen:`CPack NSIS Generator` gained a new
  :variable:`CPACK_NSIS_IGNORE_LICENSE_PAGE` variable to suppress
  the license page in the installer.

* The :cpack_gen:`CPack RPM Generator` gained the
  :variable:`CPACK_RPM_REQUIRES_EXCLUDE_FROM` option to avoid scanning
  specific paths for dependencies.

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

* The :generator:`Visual Studio 10 2010` generator is now deprecated
  and will be removed in a future version of CMake.

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

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality now
  correctly disables or enables compiler extensions when no standard level is
  specified and avoids unnecessarily adding language standard flags if the
  requested settings match the compiler's defaults. See :policy:`CMP0128`.

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  now ignores features for languages that are not enabled.

* The :ref:`Ninja Generators` now implement the ``edit_cache`` target
  using :manual:`ccmake(1)` if available.

* The :generator:`Ninja` and :generator:`NMake Makefiles` generators
  now use the MSVC ``-external:I`` flag for system includes.
  This became available as of VS 16.10 (toolchain version 14.29.30037).

* The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.03 or later.

Updates
=======

Changes made since CMake 3.22.0 include the following.

3.22.1
------

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

3.22.2
------

* The ``OLD`` behavior of :policy:`CMP0128` was fixed to add flags even when
  the specified standard matches the compiler default.

3.22.3
------

* The :command:`while` command again ignores errors in condition evaluation
  as CMake 3.21 and below did.  This bug was fixed in 3.22.0, but exposed
  errors in existing projects.  The fix has been reverted to restore
  compatibility.  The fix may be restored in a future version of CMake
  via a policy.

3.22.4, 3.22.5, 3.22.6
----------------------

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


code:
CMake 3.23 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.22 include the following.

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

Presets
-------

* :manual:`cmake-presets(7)` files now support schema version ``4``.

* :manual:`cmake-presets(7)` files now have an optional ``include`` field,
  which allows the files to include other files.

* :manual:`cmake-presets(7)` files now support a ``${fileDir}`` macro, which
  contains the directory containing the preset file.

* :manual:`cmake-presets(7)` gained support for specifying the
  ``resolvePackageReferences`` command line option in a build preset to control
  restoration behavior of package references from external package managers.
  Currently this is only supported by the Visual Studio generator to support
  restoring packages from NuGet. Other generators ignore this option.

Generators
----------

* The :ref:`Visual Studio Generators` for VS 2019 and above learned to
  support .NET SDK-style project files (``.csproj``) for C# projects.
  See the :prop_tgt:`DOTNET_SDK` target property and corresponding
  :variable:`CMAKE_DOTNET_SDK` variable.  :command:`add_custom_command`
  is not yet supported in .NET SDK-style projects.

* The :ref:`Visual Studio Generators` for VS 2017 and above learned to
  use portable instances of Visual Studio not known to the VS installer.
  See the :variable:`CMAKE_GENERATOR_INSTANCE` variable.

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

* The :manual:`cmake(1)` :option:`--build <cmake --build>` command, when used with
  :ref:`Visual Studio Generators` on projects that set the
  :prop_tgt:`VS_PACKAGE_REFERENCES` target property, now automatically
  restores package references from NuGet.  The cache variable
  :variable:`CMAKE_VS_NUGET_PACKAGE_RESTORE` may be set to toggle this behavior
  in a build tree.  Use the
  :option:`--resolve-package-references <cmake--build --resolve-package-references>`
  command-line option to control the behavior on one invocation.

* The :manual:`cmake(1)` command line tool gained a
  :option:`--debug-find-pkg <cmake --debug-find-pkg>`
  option to enable debug messages under specific :command:`find_package`
  calls.

* The :manual:`cmake(1)` command line tool gained a
  :option:`--debug-find-var <cmake --debug-find-var>`
  option to enable debug messages for ``find_*`` calls that use specific
  result variables.

Compilers
---------

* The IBM Open XL C/C++ compiler, based on LLVM, is now supported with
  compiler id ``IBMClang``.

* The MCST LCC compiler is now supported with compiler id ``LCC``.
  See policy :policy:`CMP0129`.

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

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

* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``directory``
  object ``installers`` field gained a new ``fileSet`` installer type.

Commands
--------

* The :command:`define_property` command gained a new
  ``INITIALIZE_FROM_VARIABLE`` option to cause a target property to be
  initialized from a variable when a target is created.

* The :command:`install(TARGETS)` command gained a new ``FILE_SET`` argument,
  which can be used to install header file sets associated with a target.

* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` commands now
  support the ``%f`` specifier for microseconds.

* The :command:`target_sources` command gained a new ``FILE_SET`` mode, which
  can be used to add headers as header-only source files of a target.

Variables
---------

* The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated
  :prop_tgt:`CUDA_ARCHITECTURES` target property now support the
  ``all``, and ``all-major`` values for CUDA toolkit 7.0+.

* The :variable:`CMAKE_IGNORE_PREFIX_PATH` and
  :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables were added
  to tell the :command:`find_package`, :command:`find_program`,
  :command:`find_library`, :command:`find_path`, and :command:`find_file`
  commands to ignore specified prefixes.

* The :variable:`CMAKE_LINK_LIBRARIES_ONLY_TARGETS` variable and
  corresponding :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` target
  property were added to optionally require that all link items
  that can be target names are actually names of existing targets.

Properties
----------

* The :prop_tgt:`HEADER_SETS` and :prop_tgt:`INTERFACE_HEADER_SETS` read-only
  target properties were added to list header sets associated with a target.

* The :prop_tgt:`HEADER_SET` and :prop_tgt:`HEADER_SET_<NAME>` target
  properties were added to list files in the default header set
  and named header sets, respectively.

* The :prop_tgt:`HEADER_DIRS` and :prop_tgt:`HEADER_DIRS_<NAME>` target
  properties were added to specify the base directories of the default
  header set and named header sets, respectively.

* The :prop_tgt:`IMPORTED_NO_SYSTEM` target property was added to
  specify that an :ref:`Imported Target <Imported Targets>` should
  not be treated as a system library (i.e. its include directories
  are not automatically ``SYSTEM``).

* The :prop_tgt:`XCODE_EMBED_PLUGINS <XCODE_EMBED_<type>>` target property
  was added to tell the :generator:`Xcode` generator what targets to put in
  the ``Embed PlugIns`` build phase.

* The :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` target property
  and supporting :variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE`
  variable were added to tell the :generator:`Xcode` generator to enable
  specifying the Xcode scheme option property ``GPU Frame Capture``.

Modules
-------

* The :module:`CheckPIESupported` module now supports the ``OBJC``,
  ``OBJCXX``, ``CUDA``, and ``HIP`` languages.  It also now honors
  :variable:`CMAKE_SYSROOT` and :variable:`CMAKE_OSX_SYSROOT`.

* The :module:`ExternalProject` module's :command:`ExternalProject_Add`
  command gained support for a ``USES_TERMINAL_PATCH`` option to give
  the patch step exclusive terminal access.

* The :module:`FindCUDAToolkit` module now provides a target for
  ``libcufft_static_nocallback``, if found.

* The :module:`FindGLUT` module now provides the ``GLUT_INCLUDE_DIRS``
  result variable to conform with naming conventions documented in the
  :manual:`cmake-developer(7)` manual.  This supersedes the legacy
  ``GLUT_INCLUDE_DIR`` variable.

* The :module:`FindGTest` module now provides a target for GMock, if found.

* The :module:`FindVulkan` module now provides a ``Vulkan_VERSION`` result
  variable reporting the version number.

CTest
-----

* :manual:`ctest(1)` gained a new :variable:`CTEST_SUBMIT_INACTIVITY_TIMEOUT`
  variable, which can be used to specify a timeout for submission inactivity.

CPack
-----

* The :cpack_gen:`CPack productbuild Generator` gained the new
  :variable:`CPACK_PRODUCTBUILD_DOMAINS`,
  :variable:`CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE`,
  :variable:`CPACK_PRODUCTBUILD_DOMAINS_USER`, and
  :variable:`CPACK_PRODUCTBUILD_DOMAINS_ROOT` variables for
  adding the domains element to the Distribution XML. With these variables,
  it is now possible to install products to the user's home directory
  without requiring administrative privileges.

* The :cpack_gen:`CPack productbuild Generator` gained a new variable,
  :variable:`CPACK_PRODUCTBUILD_IDENTIFIER`, used to customize the unique
  product identifier associated with the product.

* The ``CPack.distribution.dist.in`` template used by the
  :cpack_gen:`CPack productbuild Generator` and
  CPack ``PackageMaker`` generator was updated to use a new
  ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable for its main content.
  This replaced the previously undocumented and now deprecated
  ``CPACK_PACKAGEMAKER_CHOICES`` variable.

* The :cpack_gen:`CPack IFW Generator` gained the new
  :variable:`CPACK_IFW_ARCHIVE_FORMAT` and
  :variable:`CPACK_IFW_ARCHIVE_COMPRESSION` variables for setting the
  format used when packaging new component data archives, and choosing
  the compression level used.
  These features are available for QtIFW 4.2 and newer.

* The :cpack_gen:`CPack IFW Generator` gained new
  :variable:`CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE` variable to
  prevent the user from passing any consumer command to the installer, like
  ``install``, ``update``, and ``remove``.
  This feature is available for QtIFW 4.0 and newer.

* The :cpack_gen:`CPack IFW Generator` gained the new
  :variable:`CPACK_IFW_PACKAGE_PRODUCT_IMAGES` variable for adding a
  list of images to be shown on the ``PerformInstallationPage``.
  This feature is available for QtIFW 4.0 and newer.

* The :cpack_gen:`CPack IFW Generator` gained the new
  :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM`,
  :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM_ARGUMENTS`, and
  :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM_DESCRIPTION` variables for
  executing a command after the installer is done if the user accepts
  the action.  This feature is available for QtIFW 4.0 and newer.

* The :cpack_gen:`CPack IFW Generator` gained the new
  :variable:`CPACK_IFW_PACKAGE_SIGNING_IDENTITY` variable for specifying a
  code signing identity to be used for signing the generated app bundle.
  This feature is available on macOS only, and for QtIFW 3.0 and newer.

* The :cpack_gen:`CPack WIX Generator` gained a new variable,
  :variable:`CPACK_WIX_SKIP_WIX_UI_EXTENSION`, to skip the inclusion
  of WixUIExtensions.

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

* :manual:`cmake(1)` now warns when multiple source paths are specified,
  as in ``cmake -S src1 src2``.  This has never been officially documented
  or supported, but older versions accidentally accepted multiple source
  paths and used the last path specified.  Update scripts to avoid
  passing multiple source path arguments.

* The :manual:`cpack(1)` undocumented ``OSXX11`` generator has been removed.

* The previously undocumented ``CPACK_PACKAGEMAKER_CHOICES`` variable used in
  the ``CPack.distribution.dist.in`` template has been replaced by a new
  ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable. This only affects projects
  that were providing their own custom ``CPack.distribution.dist.in`` template
  file, but still relied on ``CPACK_PACKAGEMAKER_CHOICES`` being set. Those
  custom template files should be updated to use
  ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` instead, or to fully define all the
  template file's contents without relying on substitution of either variable.

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

* The :cpack_gen:`CPack DragNDrop Generator` no longer attaches
  :variable:`CPACK_RESOURCE_FILE_LICENSE` as the license agreement in
  the generated ``.dmg`` unless explicitly activated by a
  :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option.
  In CMake projects, the :module:`CPack` module enables the option
  by default for compatibility.

* ``CUDA`` targets may now enable both :prop_tgt:`CUDA_SEPARABLE_COMPILATION`
  and :prop_tgt:`CUDA_PTX_COMPILATION`.

* ``CUDA`` compiler detection now:

  * issues an error in all cases when it's unable to compute the default
    architecture(s) if required (see :policy:`CMP0104`),

  * handles ``OFF`` for :variable:`CMAKE_CUDA_ARCHITECTURES` on Clang,

  * supports the theoretical case of multiple default architectures, and

  * tries to detect invalid architectures and issue an error.

* ``CUDA`` with Clang now implements policy :policy:`CMP0105` and
  the :genex:`$<DEVICE_LINK:...>` and :genex:`$<HOST_LINK:...>`
  generator expressions.

* The :command:`define_property` command's ``BRIEF_DOCS`` and ``FULL_DOCS``
  arguments are now optional.

* :manual:`ccmake(1)` may now be enabled on Windows when building
  CMake from source.  This is experimental, and so is not included
  in official distributions.

Updates
=======

Changes made since CMake 3.23.0 include the following.

3.23.1
------

* The :command:`target_sources` ``FILE_SET`` feature added in CMake 3.23.0
  does not yet place header files properly in Apple :prop_tgt:`FRAMEWORK`
  targets.  Pending further work in a future version of CMake, it is now
  an error to add a ``FILE_SET`` of type ``HEADERS`` to such targets on
  Apple platforms.

* The :prop_tgt:`HEADER_SETS` and :prop_tgt:`INTERFACE_HEADER_SETS` target
  properties added in CMake 3.23.0 are now read-only records of the header
  sets created by the :command:`target_sources` command.

3.23.2
------

* The ``CPACK_PACKAGEMAKER_CHOICES`` variable used in the
  ``CPack.distribution.dist.in`` template file was replaced by a new
  ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable in CMake 3.23.0.
  This broke projects that provided their own template file but still
  expected the ``CPACK_PACKAGEMAKER_CHOICES`` variable to be defined.
  The old ``CPACK_PACKAGEMAKER_CHOICES`` variable is now also set to the
  same content as it was before, but it is formally deprecated.

3.23.3, 3.23.4, 3.23.5
----------------------

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


code:
CMake 3.24 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.23 include the following.

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

Presets
-------

* :manual:`cmake-presets(7)` files now support schema version ``5``.

* :manual:`cmake-presets(7)` files now support a ``${pathListSep}`` macro,
  which expands to ``:`` or ``;`` based on the platform.

* :manual:`cmake-presets(7)` files gained support for specifying a
  ``testOutputTruncation`` field in test presets, which specifies the
  truncation mode once the maximum test output size has been reached.

Generators
----------

* The :generator:`Green Hills MULTI` generator now generates build
  rules to re-run CMake if any CMake files are updated.

* The :ref:`Visual Studio Generators` now support ``SYSTEM`` headers
  when using VS 2019 Update 11 or later.

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

* :manual:`cmake(1)` gained the :option:`--fresh <cmake --fresh>` command-line
  option to remove any existing ``CMakeCache.txt`` file and associated ``CMakeFiles/``
  directory, when configuring a build tree, thus starting a new configuration
  as if the build tree were freshly created.

* :manual:`cmake(1)` gained the
  :option:`--compile-no-warning-as-error <cmake --compile-no-warning-as-error>`
  command-line option which causes the effects of the
  :prop_tgt:`COMPILE_WARNING_AS_ERROR` target property and
  :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable to be ignored.

* The :manual:`cmake(1)` :option:`--trace=json-v1 <cmake --trace>` trace
  format gained fields ``global_frame`` and ``line_end``.

* The :manual:`cmake(1)` :option:`-E <cmake -E>` commands :option:`cat <cmake-E cat>`
  and :option:`env <cmake-E env>` learned to respect a double dash
  (:option:`-- <cmake-E_env -->`) argument that acts as a delimiter indicating
  the end of options. Any following arguments are treated as operands/positional
  arguments, even if they begin with a dash ``-`` character.

* The :manual:`cmake(1)` :option:`-E tar <cmake-E tar>` command gained the
  :option:`--touch <cmake-E_tar --touch>` option
  to keep the current local timestamp instead of extracting file timestamps
  from the archive.

Compilers
---------

* LLVM's `flang`_ Fortran compiler is now supported on some platforms,
  with compiler id ``LLVMFlang``.

.. _`flang`: https://github.com/llvm/llvm-project/tree/main/flang

* ADSP compiler support (SHARC and Blackfin) now covers both CCES and
  VDSP++ installations, with required configuration now done in the
  compiler module itself rather than the ``Generic-ADSP`` platform module.

Platforms
---------

* A dedicated ``ADSP`` platform has been added
  to replace the existing ``Generic-ADSP`` implementation.
  This features automatic detection of the latest CCES/VDSP++ install
  and compiler selection (``cc21k`` vs. ``ccblkfn``)
  based off of the :variable:`CMAKE_SYSTEM_PROCESSOR` variable.

Commands
--------

* The :command:`cmake_host_system_information` command, on Windows,
  gained a ``QUERY WINDOWS_REGISTRY`` mode.
  See its :ref:`Query Windows registry` section.

* The :command:`cmake_language` command gained a new
  ``SET_DEPENDENCY_PROVIDER`` sub-command.  When a dependency provider is set,
  calls to :command:`find_package` and :command:`FetchContent_MakeAvailable`
  can be redirected through a custom command, which can choose to fulfill the
  request directly, modify how the request is processed, or leave it to be
  fulfilled by the built-in implementation.  See :ref:`dependency_providers`.

* The :command:`file(DOWNLOAD)` command gained options ``RANGE_START`` and
  ``RANGE_END`` to specify a range of bytes to download.  This can be
  useful for downloading parts of big binary files.

* The :command:`find_file`, :command:`find_path`, :command:`find_library`,
  :command:`find_program`, and :command:`find_package` commands gained the
  ``NO_CMAKE_INSTALL_PREFIX`` option to control searching
  :variable:`CMAKE_INSTALL_PREFIX`.

* The :command:`find_file`, :command:`find_path`, :command:`find_library`,
  :command:`find_program`, and :command:`find_package` commands gained the
  ability to specify which Windows Registry views must be queried.

* The :command:`find_package` command gained a ``GLOBAL`` option that
  allows for the promotion of imported targets to global scope for the
  duration of the :command:`find_package` call.

* The :command:`if` command gained the capability to compare paths by
  using the ``PATH_EQUAL`` operator.  See policy :policy:`CMP0139`.

Variables
---------

* The :variable:`CMAKE_COLOR_DIAGNOSTICS` variable was added to control
  color diagnostics generated by compilers.  This variable also controls
  color build system messages with :ref:`Makefile Generators`, replacing
  :variable:`CMAKE_COLOR_MAKEFILE`.

  The :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment variable was added to set
  a default value for :variable:`CMAKE_COLOR_DIAGNOSTICS`.

* The :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable and corresponding
  :prop_tgt:`COMPILE_WARNING_AS_ERROR` target property were added to enable
  compilation with a compiler-specific flag to treat warnings as errors,
  such as ``-Werror``.

* The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated
  :prop_tgt:`CUDA_ARCHITECTURES` target property now support the
  special ``native`` value to compile for the architectures(s)
  of the host's GPU(s).

* The :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` variable was added to
  toggle behavior of the :command:`find_package` command's new ``GLOBAL``
  option.

* The :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` variable was added to toggle
  behavior of the :command:`find_file`, :command:`find_library`,
  :command:`find_path`, :command:`find_package`, and :command:`find_program`
  commands' new ``NO_CMAKE_INSTALL_PREFIX`` option.

* The :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable was added to allow
  injecting custom code at the site of the first :command:`project` call,
  after the host and target platform details have been determined.

* The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable
  was added to tell the :command:`try_compile` command not to
  pass any platform variables to the test project.

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

* The :variable:`CMAKE_VS_NO_COMPILE_BATCHING` variable and corresponding
  :prop_tgt:`VS_NO_COMPILE_BATCHING` target property were added to
  tell :ref:`Visual Studio Generators` whether to disable compiler
  parallelism and call the compiler with one source file at a time.

* The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` variable and
  :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property were introduced to
  select the runtime library used by compilers targeting the Watcom ABI.
  See policy :policy:`CMP0136`.

* The :variable:`CMAKE_XCODE_XCCONFIG` variable and corresponding
  :prop_tgt:`XCODE_XCCONFIG` target property were added to tell
  the :generator:`Xcode` generator to handle ``xcconfig`` files.

Properties
----------

* The :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
  :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties
  were added to express usage requirements affecting a consumer's
  direct link dependencies.

* The :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY` target property was
  added to specify which header sets should be verified by
  :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS`.

* The :prop_tgt:`LINK_LIBRARIES` target property now supports
  the :genex:`$<LINK_ONLY:...>` generator expression.
  See policy :policy:`CMP0131`.

* The :prop_tgt:`VS_DOTNET_STARTUP_OBJECT` target property was added to
  tell :ref:`Visual Studio Generators` which startup class shall be used
  when the program or project is executed. This is necessary when more
  than one ``static void Main(string[])`` function signature is available
  in a managed .NET project.

Modules
-------

* The :module:`ExternalProject` module :command:`ExternalProject_Add`
  command gained a new ``DOWNLOAD_EXTRACT_TIMESTAMP`` option for
  controlling whether the timestamps of extracted contents are set to
  match those in the archive when the ``URL`` download method is used.
  Policy :policy:`CMP0135` was added to enable the option by default.

* The :module:`FetchContent` module and the :command:`find_package` command
  now support integration capabilities:

  * :command:`FetchContent_MakeAvailable` can now try to satisfy a dependency
    by calling :command:`find_package` first.  A new
    :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable controls whether
    this is done by default for all dependencies, is opt-in per dependency,
    or is disabled entirely.

  * :command:`find_package` can be re-routed to call
    :command:`FetchContent_MakeAvailable` instead.  A new read-only
    :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable points to a
    directory where config package files can be located to facilitate these
    re-routed calls.

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

* The :module:`FindMatlab` module :command:`matlab_add_mex` function
  gained a ``NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES`` option to disable
  automatic linking of MATLAB libraries.

* The :module:`FindVulkan` module now supports components to select which
  VulkanSDK tool and libraries to find in addition to the Vulkan SDK headers
  and library.

* The :module:`FindZLIB` gained a new ``ZLIB_USE_STATIC_LIBS`` variable to
  search only for static libraries.

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

* The :genex:`LINK_LIBRARY` generator expression was added to manage how
  libraries are specified during the link step.
  The :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
  :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables are used to define
  features usable by the :genex:`LINK_LIBRARY` generator expression.
  Moreover, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
  :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties are
  available to resolve incompatible features.

  The :genex:`LINK_LIBRARY` generator expression can link frameworks in
  various ways when targeting ``Apple`` platforms.
  The following features were added:

  * ``FRAMEWORK``
  * ``NEEDED_FRAMEWORK``
  * ``REEXPORT_FRAMEWORK``
  * ``WEAK_FRAMEWORK``

  The :genex:`LINK_LIBRARY` generator expression can link libraries in
  various ways when targeting ``Apple`` platforms.
  The following features were added:

  * ``NEEDED_LIBRARY``
  * ``REEXPORT_LIBRARY``
  * ``WEAK_LIBRARY``

  The :genex:`LINK_LIBRARY` generator expression gained the feature
  ``WHOLE_ARCHIVE`` to force load of all members in a static library.
  This feature is supported on the following target platforms:

  * all ``Apple`` variants
  * ``Linux``
  * all ``BSD`` variants
  * ``SunOS``
  * ``Windows``
  * ``CYGWIN``
  * ``MSYS``

* The :genex:`LINK_GROUP` generator expression was added to manage the
  grouping of libraries during the link step.  The
  :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` and
  :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variables are used to define
  features usable with the :genex:`LINK_GROUP` generator expression.
  This release defines the ``RESCAN`` feature, which can be used to handle
  circular references among static libraries when using toolchains for
  Linux, BSD, SunOS and GNU toolchains for Windows.

* The :genex:`PATH` generator expression was added to manage paths.

* The :genex:`PATH_EQUAL` generator expression was added to manage path
  comparisons.

* The :genex:`TARGET_BUNDLE_DIR_NAME` generator expression
  was added to evaluate to the name of the bundle directory
  for a given bundle target.

CTest
-----

* :manual:`ctest(1)` gained a
  :option:`--test-output-truncation <ctest --test-output-truncation>` option
  (and corresponding :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable)
  to specify the truncation mode once the maximum test output size has been
  reached. Possible values are ``tail`` (default), ``middle`` or ``head``.

CPack
-----

* The :cpack_gen:`CPack WIX Generator` gained a new variable,
  :variable:`CPACK_WIX_ARCHITECTURE`, to specify the installer architecture
  in order to support computers running Windows for ARM.

* CPack now supports the :variable:`CPACK_THREADS` option for ``zstd``
  compression when compiled with libarchive 3.6 or higher.  It is
  supported by official CMake binaries available on `cmake.org`_.

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

* The :module:`CPack` module no longer enables the SLA by default in the
  :cpack_gen:`CPack DragNDrop Generator`.  See policy :policy:`CMP0133`
  and the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` variable.

* The deprecated :cpack_gen:`CPack PackageMaker Generator` has been removed.

* The :module:`FindGLUT` module no longer provides the undocumented
  ``GLUT_LIBRARY`` and ``GLUT_INCLUDE_PATH`` result variables.

* The :module:`FindVulkan` module no longer silently ignores unknown
  components requested by a ``find_package(Vulkan REQUIRED ...)`` call.
  With the addition of support for components, requests for unknown
  components now produce an error.

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

* CMake no longer sets environment variables like :envvar:`CC`, :envvar:`CXX`,
  etc. when enabling the corresponding language during the first CMake run in
  a build directory.  See policy :policy:`CMP0132`.

* The :module:`CheckIPOSupported` module :command:`check_ipo_supported`
  command now uses the caller's :variable:`CMAKE_<LANG>_FLAGS`
  and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values.
  See policy :policy:`CMP0138`.

* The :generator:`MSYS Makefiles` and :generator:`MinGW Makefiles`
  generators, when a compiler is not explicitly specified, now select
  the first compiler (of any name) found in directories listed by the
  ``PATH`` environment variable.

* The :command:`try_compile` command
  :ref:`whole-project <Try Compiling Whole Projects>` signature
  now propagates platform variables.  See policy :policy:`CMP0137`.

* The :command:`while` command now diagnoses errors during condition
  evaluation.  See policy :policy:`CMP0130`.

* The precompiled macOS binaries provided on `cmake.org`_ no longer attach a
  SLA to the ``.dmg`` packages.  This was removed because macOS 12 deprecated
  the tools used to attach ``.dmg`` resources.

* A precompiled Windows ``arm64`` binary is now provided on `cmake.org`_.

.. _`cmake.org`: https://cmake.org/download/

Updates
=======

Changes made since CMake 3.24.0 include the following.

3.24.1, 3.24.2
--------------

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

3.24.3
------

* The ``LLVMFlang`` Fortran compiler support added in 3.24.0 has been extended:

  * It now supports mixed-language linking between Fortran and C or CXX.
  * It now supports the GNU ABI (MinGW) on Windows, but not yet the MSVC ABI.

* Some implementation updates were made to support ecosystem changes
  and/or fix regressions.

3.24.4
------

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


code:
CMake 3.25 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.24 include the following.

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`.

* The :manual:`cmake-presets(7)` format now supports an
  ``outputJUnitFile`` field to specify JUnit output in test presets.

Languages
---------

* The :manual:`Compile Features <cmake-compile-features(7)>` 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 :option:`cmake --workflow --preset <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 <cmake-E capabilities>` command
  gained a new ``tls`` field that tells whether or not TLS is enabled.

* The :option:`cmake -E env <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://www.tasking.com

Commands
--------

* The :command:`add_subdirectory` command gained a ``SYSTEM`` option
  to enable the :prop_dir:`SYSTEM` directory property in the subdirectory.

* 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 :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 ``<prefix>/<name>*/(cmake|CMake)/<name>*/`` when
  searching for package configuration files.

* 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:`cmake --debug-trycompile`.

* 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.

Variables
---------

* 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
  property were added to tell the :generator:`Xcode` generator what to put
  in the scheme's ``Metal: API Validation`` setting.

* The :variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION` variable and
  corresponding :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_SHADER_VALIDATION` target
  property were added to tell the :generator:`Xcode` generator what to put
  in the scheme's ``Metal: Shader Validation`` setting.

* The :variable:`CMAKE_XCODE_SCHEME_LAUNCH_MODE` variable and corresponding
  :prop_tgt:`XCODE_SCHEME_LAUNCH_MODE` target property were added to tell
  the :generator:`Xcode` generator what to put in the scheme's "Launch"
  mode setting.

* The :variable:`CMAKE_XCODE_SCHEME_LAUNCH_CONFIGURATION` variable and
  corresponding :prop_tgt:`XCODE_SCHEME_LAUNCH_CONFIGURATION` target
  property were added to tell the :generator:`Xcode` generator what
  configuration to put in the scheme's Launch action.

Properties
----------

* The :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property now supports
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

* 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's :command:`FetchContent_Declare`
  command gained a ``SYSTEM`` option which sets the :prop_dir:`SYSTEM`
  directory property on subdirectories created by
  :command:`FetchContent_MakeAvailable`.

* The :module:`FindCUDAToolkit` module now provides a target for
  :ref:`nvtx3 <cuda_toolkit_nvtx3>` for CUDA 10.0+, which supersedes
  :ref:`nvToolsExt <cuda_toolkit_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
=============

* 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:`<LANG>_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`.

Updates
=======

Changes made since CMake 3.25.0 include the following.

3.25.1
------

* On Windows, when targeting the MSVC ABI, the :command:`find_library`
  command no longer accepts ``.a`` file names.  This behavior was added
  in CMake 3.25.0, but has been reverted due finding GNU-ABI libraries
  in cases we did not previously.

3.25.2
------

* CUDA language level 20 (corresponding to C++20) is now supported with
  NVCC 12.0 and above.

* On Windows, the ``icpx`` compiler now provided by Intel oneAPI 2023.0
  and above is no longer selected because its GNU-like command-line is
  not yet supported by CMake.

3.25.3
------

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


code:
CMake 3.26 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.25 include the following.

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

Languages
---------

* The ``ASM_MARMASM`` language was added to support the
  Microsoft ARM assembler language.

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

* The :option:`cmake -E copy <cmake-E copy>` command-line tool now
  supports a ``-t`` argument.

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

Configure Log
-------------

* CMake now writes a YAML log of configure-time checks to
  ``CMakeFiles/CMakeConfigureLog.yaml`` under the top of the build tree.
  See the :manual:`cmake-configure-log(7)` manual.

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

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

* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object
  gained a new ``fileSets`` field and associated ``fileSetIndex``
  field to ``sources`` objects.

* The :manual:`cmake-file-api(7)` gained a new "configureLog" object kind
  that enables stable access to the :manual:`cmake-configure-log(7)`.

Commands
--------

* The :command:`add_custom_command` and :command:`add_custom_target` commands
  now support :manual:`generator expressions <cmake-generator-expressions(7)>`
  in their ``COMMENT`` option.

* The :command:`message` command gained a ``CONFIGURE_LOG`` mode to
  record an entry in the :manual:`cmake-configure-log(7)`.

* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` commands
  now support the ``%z`` and ``%Z`` specifiers for the time zone.

* The :command:`try_compile` and :command:`try_run` commands gained
  a ``LOG_DESCRIPTION`` option specifying text to be recorded in the
  :manual:`cmake-configure-log(7)`.

* The :command:`try_compile` and :command:`try_run` commands gained a
  ``NO_LOG`` option to skip recording a :manual:`cmake-configure-log(7)`
  entry.

Variables
---------

* The :variable:`CMAKE_<LANG>_COMPILER_FRONTEND_VARIANT` variable is now
  set for ``GNU``, ``MSVC``, and ``AppleClang`` compilers that have only
  one frontend variant.

* A :variable:`CMAKE_VS_VERSION_BUILD_NUMBER` variable is now set by
  :ref:`Visual Studio Generators` for VS 2017 and above to report the
  four-component Visual Studio version number.

Properties
----------

* The :prop_tgt:`<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR` target property was
  added to allow the ``clang-tidy`` tool to export its suggested fixes to a
  set of ``.yaml`` files. A new
  :variable:`CMAKE_<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR` variable was created to
  initialize this property.

* The :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS <XCODE_EMBED_<type>>`
  target property was added to tell the :generator:`Xcode` generator to embed
  ExtensionKit-based extensions such as extensions using the Background
  Assets framework.  Aspects of the embedding can be customized with:

  * :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS_PATH <XCODE_EMBED_<type>>`
  * :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS_CODE_SIGN_ON_COPY <XCODE_EMBED_<type>_CODE_SIGN_ON_COPY>`
  * :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS_REMOVE_HEADERS_ON_COPY <XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY>`

Modules
-------

* The :module:`ExternalProject` module's :command:`ExternalProject_Add` command
  gained an ``INSTALL_BYPRODUCTS`` option to specify files generated by the
  ``install`` step.

* The :module:`FindCUDAToolkit` module:

  * gained support for the ``sbsa-linux`` cross compilation target, and

  * now provides an imported target for ``nvrtc_static``, if found.

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

* The :module:`FindPython3` and :module:`FindPython` modules gained
  support for the `Stable Application Binary Interface`_.

* The :module:`UseSWIG` module gained support for the ``perl5`` language.

.. _`Stable Application Binary Interface`: https://docs.python.org/3/c-api/stable.html

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

* The :genex:`$<BUILD_LOCAL_INTERFACE:...>` generator expression was added to
  prevent usage requirements from being exported to dependent projects.

CTest
-----

* The :envvar:`CTEST_NO_TESTS_ACTION` environment variable was added to
  provide a default value for the
  :option:`--no-tests=\<action\> <ctest --no-tests>` command line
  argument of :manual:`ctest(1)`.

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

* The ``CMakeFiles/CMakeOutput.log`` and ``CMakeFiles/CMakeError.log``
  files are no longer populated by CMake's built-in modules.
  :manual:`cmake(1)` no longer suggests looking at them after a
  ``CMake Error`` occurs.  Information previously logged to those
  files is instead logged to the :manual:`cmake-configure-log(7)`.

* On CYGWIN, the undocumented ``CMAKE_LEGACY_CYGWIN_WIN32`` mode for
  compatibility with CMake versions older than 2.8.4 has been removed.

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

* :ref:`Language Standard Flags`, such as ``-std=c++11``, when generated due
  to :command:`target_compile_features` or :variable:`CMAKE_<LANG>_STANDARD`,
  are now placed before flags added by :command:`target_compile_options`,
  rather than after them.

* For all ``COMPILE_DEFINITIONS`` properties, any leading ``-D`` on an item
  is removed whether or not it was specified by a generator expression.

* The ``compile_commands.json`` database enabled by
  :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` now provides the ``output``
  field in the compile commands objects.  This allows multi-config
  generators, such as the :generator:`Ninja Multi-Config` generator,
  to provide the compile commands for all configurations.

* The :prop_gbl:`USE_FOLDERS` global property is treated as ``ON`` by default.
  See policy :policy:`CMP0143`.

* The top-level :command:`project` call will now emit an author warning if the
  documented command order in relation to :command:`cmake_minimum_required` is
  not respected.

* The :option:`cmake --trace` option now follows :command:`try_compile` and
  :command:`try_run` invocations.

Updates
=======

Changes made since CMake 3.26.0 include the following.

3.26.1, 3.26.2, 3.26.3, 3.26.4, 3.26.5
--------------------------------------

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

3.26.6
------

* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object
  ``fileSets`` field was introduced by CMake 3.26.0 with entries of its
  ``baseDirectories`` member incorrectly expressed as absolute paths
  even if they are inside the top-level source directory.  This has
  been fixed.  Clients must be updated to expect relative paths under
  the top-level source directory.