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.

repo_name: lazytadpole/codenamesilverfish

license: mit


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.


code:
CMake 3.27 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.26 include the following.

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

Debugger
--------

* :manual:`cmake(1)` now supports interactive debugging of the CMake language.
  See the :option:`--debugger <cmake --debugger>` option.

Presets
-------

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

* :manual:`cmake-presets(7)` now supports ``$penv{}`` macro expansion
  in ``include`` fields.

Generators
----------

* The :ref:`Makefile <Makefile Generators>` and :ref:`Ninja <Ninja Generators>`
  generators now support using the ``--dependency-file`` linker flag,
  added by GNU Binutils 2.35 and LLVM's LLD 12.0.0, so that files read by the
  linker will cause a relink if they change (typically modified timestamps).
  See the :variable:`CMAKE_LINK_DEPENDS_USE_LINKER` variable.

* The :ref:`Visual Studio Generators` for VS 14 (2015) and above learned to
  select the Windows SDK version explicitly using a ``version=`` field
  in the :variable:`CMAKE_GENERATOR_PLATFORM` variable.
  See :ref:`Visual Studio Platform Selection`.

Languages
---------

* The ``CXX`` language now treats source file extensions
  ``.ccm``, ``.cxxm``, and ``.c++m`` as C++.

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

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

* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained
  a new "frameworks" field in the "compileGroups" objects.

Platforms
---------

* Apple text-based stubs (i.e. ``.tbd`` files) may now be created for shared
  libraries on macOS.  See the :prop_tgt:`ENABLE_EXPORTS` property.

Commands
--------

* The :command:`add_custom_command` command gained a new
  ``DEPENDS_EXPLICIT_ONLY`` option to tell the :ref:`Ninja Generators`
  not to add any dependencies implied by the target to which it is
  attached.  The :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY`
  variable was added to enable ``DEPENDS_EXPLICIT_ONLY`` on all calls to
  :command:`add_custom_command` command.

* The :command:`cmake_file_api` command was added for projects to add
  :manual:`CMake file API <cmake-file-api(7)>` queries for the current
  CMake run.

* The :command:`find_package` command now searches prefixes specified by
  upper-case :variable:`<PACKAGENAME>_ROOT` CMake variables and upper-case
  :envvar:`<PACKAGENAME>_ROOT` environment variables.
  See policy :policy:`CMP0144`.

* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands
  now support the :genex:`$<INSTALL_PREFIX>` generator expression.

Variables
---------

* The :variable:`CMAKE_DLL_NAME_WITH_SOVERSION` variable and associated
  :prop_tgt:`DLL_NAME_WITH_SOVERSION` target property were added to
  optionally append the :prop_tgt:`SOVERSION` to the filename of the
  ``.dll`` part of a shared library on Windows.

* Variables :variable:`CMAKE_VS_DEBUGGER_COMMAND`,
  :variable:`CMAKE_VS_DEBUGGER_COMMAND_ARGUMENTS`,
  :variable:`CMAKE_VS_DEBUGGER_ENVIRONMENT`, and
  :variable:`CMAKE_VS_DEBUGGER_WORKING_DIRECTORY` were added to initialize
  corresponding target properties.

* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION` variable
  was added to initialize the :prop_tgt:`VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION`
  target property on all targets when they are created.

Properties
----------

* A :prop_tgt:`CUDA_CUBIN_COMPILATION` target property was added to
  :ref:`Object Libraries` to support compiling to ``.cubin`` files
  instead of host object files. Currently only supported with NVIDIA.

* A :prop_tgt:`CUDA_FATBIN_COMPILATION` target property was added to
  :ref:`Object Libraries` to support compiling to ``.fatbin`` files
  instead of host object files. Currently only supported with NVIDIA.

* A :prop_tgt:`CUDA_OPTIX_COMPILATION` target property was added to
  :ref:`Object Libraries` to support compiling to ``.optixir`` files
  instead of host object files. Currently only supported with NVIDIA.

* The :prop_tgt:`<LANG>_CLANG_TIDY`, :prop_tgt:`<LANG>_CPPCHECK`,
  :prop_tgt:`<LANG>_CPPLINT`, and :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE`,
  target properties now support
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

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

* The :prop_sf:`SKIP_LINTING` source file property was added to suppress
  target-wide code checks on specific sources.

Modules
-------

* The :module:`FindCUDAToolkit` module now provides an imported target for
  ``cudla``, and imported targets for CUPTI's ``nvperf`` and ``pcsampling``
  components.

* The :module:`FindDoxygen` module's :command:`doxygen_add_docs` command gained
  a ``CONFIG_FILE`` option to specify a custom doxygen configuration file.

* The :module:`FindOpenGL` module gained support for components
  ``GLES2`` and ``GLES3``.

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

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

* The :genex:`COMPILE_ONLY` generator expression was added to specify
  compilation usage requirements without any linking requirements.

* ``$<LIST:...>`` generator expressions were added for
  :ref:`query <GenEx List Queries>`,
  :ref:`transformation <GenEx List Transformations>`, and
  :ref:`ordering <GenEx List Ordering>` operations on
  :ref:`lists <CMake Language Lists>`.

* ``$<PATH:...>`` generator expressions for
  :ref:`decomposition <GenEx Path Decomposition>` and
  :ref:`transformation <GenEx Path Transformations>` operations learned
  to process :ref:`lists <CMake Language Lists>` of paths element-wise.

* The :genex:`TARGET_IMPORT_FILE`, :genex:`TARGET_IMPORT_FILE_BASE_NAME`,
  :genex:`TARGET_IMPORT_FILE_PREFIX`, :genex:`TARGET_IMPORT_FILE_SUFFIX`,
  :genex:`TARGET_IMPORT_FILE_NAME`, and :genex:`TARGET_IMPORT_FILE_DIR`
  generator expressions were added.  These expand to details about the
  linker import file for a target.

* The :genex:`TARGET_RUNTIME_DLL_DIRS` generator expression was added.
  It expands to a list of the directories containing DLLs in
  :genex:`TARGET_RUNTIME_DLLS`.

Autogen
-------

* The :variable:`CMAKE_AUTOMOC_EXECUTABLE`,
  :variable:`CMAKE_AUTORCC_EXECUTABLE`, and
  :variable:`CMAKE_AUTOUIC_EXECUTABLE` variables were added to initialize the
  corresponding target properties as targets are created.

* The :prop_tgt:`AUTOGEN_USE_SYSTEM_INCLUDE` target property and
  corresponding :variable:`CMAKE_AUTOGEN_USE_SYSTEM_INCLUDE` variable were
  added to explicitly control whether autogen headers are
  considered system headers.

* The :prop_tgt:`INTERFACE_AUTOMOC_MACRO_NAMES` target property was added to
  specify macro names for ``moc`` as a transitive usage requirement.

CTest
-----

* The :prop_test:`TIMEOUT_SIGNAL_NAME` and
  :prop_test:`TIMEOUT_SIGNAL_GRACE_PERIOD` test properties were added
  to specify a POSIX signal to send to a test process when its timeout
  is reached.

CPack
-----

* The :cpack_gen:`CPack Inno Setup Generator` was added to package using
  Inno Setup.

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

* Compatibility with versions of CMake older than 3.5 is now deprecated
  and will be removed from a future version.  Calls to
  :command:`cmake_minimum_required` or :command:`cmake_policy` that set
  the policy version to an older value now issue a deprecation diagnostic.

* The :ref:`Extra Generators` have been deprecated.  IDEs may use the
  :manual:`cmake-file-api(7)` to view CMake-generated project build trees.

* The :module:`FindCUDA` module, which has been deprecated since CMake 3.10,
  has been removed by policy :policy:`CMP0146`.  Port projects to CMake's
  first-class ``CUDA`` language support.

* The :module:`FindPythonInterp` and :module:`FindPythonLibs` modules,
  which have been deprecated since CMake 3.12, have been removed by
  policy :policy:`CMP0148`.  Port projects to :module:`FindPython3`,
  :module:`FindPython2`, or :module:`FindPython`.

* The :module:`Dart` and :module:`FindDart` modules have been deprecated via
  policy :policy:`CMP0145`.  Port projects to the :module:`CTest` module.

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

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

* ``cmake --build $dir --verbose`` will now print the working directory and
  command line used to perform the build.

* The :module:`ExternalProject` and :module:`FetchContent` modules
  now resolve relative ``GIT_REPOSITORY`` paths as relative to the
  parent project's remote, not as a relative local file system path.
  See :policy:`CMP0150`.

* The :module:`ExternalProject` ``configure`` step no longer re-runs on
  every build when the ``UPDATE_DISCONNECTED`` option is enabled.
  It will only re-run if details of the ``download``, ``update``,
  or ``patch`` step change.

* The :module:`ExternalProject` ``update`` and ``patch`` steps now always
  re-run if any of their details change, even if the ``UPDATE_DISCONNECTED``
  option is enabled.  If using the ``GIT`` download method, and the ``GIT_TAG``
  is changed to a commit that is not already known locally, an error is now
  issued instead of silently using the previous ``GIT_TAG``.

* The :module:`FindPython`, :module:`FindPython2` and :module:`FindPython3`
  modules now support the Windows ARM64 platform.

* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command now case-preserves
  DLL names reported on Windows.  They are still converted to lowercase
  for filter matching.

* The :prop_tgt:`SYSTEM` target property is now honored for Apple Frameworks.

* :ref:`Visual Studio Generators`, for VS 15.8 (2017) and newer, now
  build custom commands in parallel.  See policy :policy:`CMP0147`.

* :ref:`Visual Studio Generators` for VS 14 (2015) and above now prefer
  to select the latest Windows SDK version.  See policy :policy:`CMP0149`.

Updates
=======

Changes made since CMake 3.27.0 include the following.

3.27.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.27.2
------

* :ref:`Visual Studio Generators` for VS 14 (2015) and above now prefer to
  select the latest Windows SDK, as documented by policy :policy:`CMP0149`,
  when targeting any version of Windows.  In CMake 3.27.[0-1] the
  preference was limited to targeting Windows 10 and above.

* :ref:`Visual Studio Generators` for VS 14 (2015) and above now support
  using ``version=8.1`` in the :variable:`CMAKE_GENERATOR_PLATFORM` variable
  to select the Windows 8.1 SDK.  In CMake 3.27.[0-1] the ``version=`` field
  was limited to selecting Windows 10 SDKs.

3.27.3, 3.27.4, 3.27.5, 3.27.6, 3.27.7, 3.27.8
----------------------------------------------

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

3.27.9
------

* 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 was
  fixed in CMake 3.26.6 and has now been fixed in 3.27.9.  Clients must
  be updated to expect relative paths under the top-level source directory.

* Fortran module dependency scanning in :ref:`Ninja Generators` was updated
  by CMake 3.27.0 to use exact collation dependencies.  This was supposed
  to fix subtle rebuild failures when moving module sources among targets.
  Since then, several cases have been found in which exact collation
  dependencies were incorrectly computed when using :ref:`Object Libraries`.
  Some of these cases were incrementally fixed through the 3.27.x patch
  series, but additional more subtle cases have since been found.  In order
  to avoid further churn in the 3.27 release series, the original change has
  been reverted and deferred to a future version of CMake.


code:
CMake 3.28 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.27 include the following.

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

Languages
---------

* C++ 20 named modules are now supported by :ref:`Ninja Generators`
  and :ref:`Visual Studio Generators` for VS 2022 and newer, in combination
  with the MSVC 14.34 toolset (provided with VS 17.4) and newer, LLVM/Clang
  16.0 and newer, and GCC 14 (after the 2023-09-20 daily bump) and newer.
  See :manual:`cmake-cxxmodules(7)` for details.

* ``HIP`` language code may now be compiled for NVIDIA GPUs
  using the NVIDIA CUDA Compiler (NVCC).
  See the :variable:`CMAKE_HIP_PLATFORM` variable.

Platforms
---------

* On Apple platforms, ``.xcframework`` folders are now supported:

  * The :command:`find_library` command now finds ``.xcframework`` folders.

  * The :command:`target_link_libraries` command now supports
    linking against a ``.xcframework`` folder.

  * The :prop_tgt:`IMPORTED_LOCATION` target property of an imported
    library target may now be the path to a ``.xcframework`` folder.

* Apple visionOS and its ``xros`` and ``xrsimulator`` SDKs are now supported.
  Compiling for Apple visionOS can be requested by setting
  :variable:`CMAKE_SYSTEM_NAME` to ``visionOS``.
  See :ref:`Cross Compiling for iOS, tvOS, visionOS, or watchOS`
  for more information.

Presets
-------

* :manual:`cmake-presets(7)` files now support schema version ``8``.
  It adds support for a ``$schema`` field.

Compilers
---------

* Cray Clang-based compilers are now supported with
  :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``CrayClang``.

* The OrangeC compiler is now supported with
  :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``OrangeC``.

Commands
--------

* The :command:`add_custom_command` and :command:`add_custom_target`
  commands gained a ``JOB_SERVER_AWARE`` option.

* The :command:`cmake_host_system_information` command gained a
  ``MSYSTEM_PREFIX`` query for the installation prefix of a MSYS
  or MinGW development environment on Windows hosts.

* The :command:`set_property` command ``TEST`` mode gained a ``DIRECTORY``
  option to set properties on tests in other directories.

* The :command:`set_tests_properties` command gained a ``DIRECTORY``
  option to set properties on tests in other directories.

* The :command:`get_property` command ``TEST`` mode gained a ``DIRECTORY``
  option to get properties on tests in other directories.

* The :command:`get_test_property` command gained a ``DIRECTORY``
  option to get properties on tests in other directories.

Variables
---------

* The :envvar:`CMAKE_CROSSCOMPILING_EMULATOR` environment variable
  was added to initialize the :variable:`CMAKE_CROSSCOMPILING_EMULATOR`
  cache variable.

* The :variable:`CMAKE_HIP_PLATFORM` variable was added to specify
  the GPU platform for which HIP language sources are to be compiled
  (``amd`` or ``nvidia``).

Properties
----------

* On imported shared libraries, the :prop_tgt:`IMPORTED_IMPLIB` target
  property may now be used without :prop_tgt:`IMPORTED_LOCATION`.
  This can be used to represent a stub library whose location should not
  be added as a runtime search path to dependents that link it.

* The :prop_tgt:`IMPORTED_LOCATION` property of a macOS framework
  may now be a path to the ``.framework`` folder itself.

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

Modules
-------

* The :module:`ExternalProject` module now includes the
  ``BUILD_JOB_SERVER_AWARE`` option for the
  :command:`ExternalProject_Add` command. This option enables
  the integration of the GNU Make job server when using an
  explicit ``BUILD_COMMAND`` with certain :ref:`Makefile Generators`.
  Additionally, the :command:`ExternalProject_Add_Step` command
  has been updated to support the new ``JOB_SERVER_AWARE`` option.

* The :module:`FetchContent` module's :command:`FetchContent_Declare` command
  gained an ``EXCLUDE_FROM_ALL`` option, which propagates through to the
  :command:`add_subdirectory` call made by
  :command:`FetchContent_MakeAvailable` for the dependency.

* The :module:`FindCURL` module gained a ``CURL_USE_STATIC_LIBS`` hint
  to select static libraries.

* The :module:`FindEXPAT` module gained an ``EXPAT_USE_STATIC_LIBS`` hint
  to select static libraries.

* The :module:`FindPkgConfig` module :command:`pkg_get_variable` command
  gained a ``DEFINE_VARIABLES`` option to pass variables to ``pkg-config``.

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

* The :manual:`generator expressions <cmake-generator-expressions(7)>`
  :genex:`$<IF:...>`, :genex:`$<AND:...>`, and :genex:`$<OR:...>`
  short-circuit to avoid unnecessary evaluation of parameters.

CTest
-----

* CTest may now take a :ref:`dynamically-generated resource spec file
  <ctest-resource-dynamically-generated-spec-file>`, which can be specified by the
  :prop_test:`GENERATED_RESOURCE_SPEC_FILE` test property.

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

* The :command:`exec_program` command, which has been deprecated
  since CMake 3.0, has been removed by policy :policy:`CMP0153`.
  Use the :command:`execute_process` command instead.

* The :generator:`Visual Studio 11 2012` generator has been removed.

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

* The :prop_tgt:`IOS_INSTALL_COMBINED` target property and corresponding
  :variable:`CMAKE_IOS_INSTALL_COMBINED` variable have been deprecated.
  Their functionality does not make sense on Apple Silicon hosts.

* The :generator:`Xcode` generator will now issue a fatal error if
  the Legacy Build System has been selected for Xcode 14 and
  newer. Those Xcode versions dropped support for the Legacy Build
  System and expect the project to be set-up for their current
  Build System.

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

* Generated files, in targets using :ref:`file sets`, are now considered
  private by default.  Generated public headers must be specified using
  file sets.  This allows :ref:`Ninja Generators` to produce more
  efficient build graphs.  See policy :policy:`CMP0154`.

* The :command:`find_library`, :command:`find_path`, and :command:`find_file`
  commands no longer search in installation prefixes derived from the ``PATH``
  environment variable.  This behavior was added in CMake 3.3 to support
  MSYS and MinGW (``MSYSTEM``) development environments on Windows, but
  it can search undesired prefixes that happen to be in the ``PATH`` for
  unrelated reasons.  Users who keep some ``<prefix>/bin`` directories in
  the ``PATH`` just for their tools do not necessarily want any corresponding
  ``<prefix>/lib`` or ``<prefix>/include`` directories searched.
  The behavior was reverted for non-Windows platforms by CMake 3.6.
  Now it has been reverted on Windows platforms too.

  One may set the ``CMAKE_PREFIX_PATH`` environment variable with a
  :ref:`semicolon-separated list <CMake Language Lists>` of prefixes
  that are to be searched.

* When using MinGW tools in a ``MSYSTEM`` environment on Windows,
  the ``$MSYSTEM_PREFIX/local`` and ``$MSYSTEM_PREFIX`` prefixes are
  now added to :variable:`CMAKE_SYSTEM_PREFIX_PATH`.

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

Updates
=======

Changes made since CMake 3.28.0 include the following.

3.28.1, 3.28.2, 3.28.3
----------------------

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

.. 3.28.4 (unreleased)

  * Apple visionOS support has been updated for the official Xcode 15.2
    release of the  ``xros`` and ``xrsimulator`` SDKs.


code:
CMake 3.29 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.28 include the following.

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

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

* :manual:`cmake(1)` :option:`-E cat <cmake-E cat>` can now print the standard
  input by passing the ``-`` argument.

Generators
----------

* :ref:`Visual Studio Generators` now support selecting between the
  Intel oneAPI Fortran compiler (``ifx``) and the Intel classic Fortran
  compiler (``ifort``) using a ``fortran=`` field in
  :variable:`CMAKE_GENERATOR_TOOLSET`.

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

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

* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained
  a new "launchers" field.

Compilers
---------

* The LLVM/Clang GNU-like frontend on Windows (``clang++``) may now be used
  to compile ``CUDA`` language sources.

* Compilers targeting the GNU ABI on Windows (MinGW) may now be used to
  compile Objective C (``OBJC``) and Objective C++ (``OBJCXX``).  These
  include GNU compilers (``gcc`` and ``g++``) and the LLVM/Clang GNU-like
  frontends (``clang`` and ``clang++``).

* TI Clang-based compilers are now supported with
  :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``TIClang``.

Commands
--------

* The :ref:`add_custom_command(TARGET) <add_custom_command(TARGET)>`
  signature now supports adding build events through :ref:`Alias Targets`.

* The :command:`cmake_language(EXIT)` sub-command was added to terminate
  :option:`cmake -P` scripts with a specified exit code.

* The :command:`export(SETUP)` sub-command was added to configure export sets.
  Its ``PACKAGE_DEPENDENCY`` option configures how :command:`find_dependency`
  calls are exported.  Its ``TARGET`` option's ``XCFRAMEWORK_LOCATION``
  setting specifies the location of a ``.xcframework`` that can be
  substituted for an installed target.

* The :command:`if` command gained new tests ``IS_READABLE``, ``IS_WRITABLE``
  and ``IS_EXECUTABLE`` to check file or directory permissions.

* :command:`install(EXPORT)` and :command:`export(EXPORT)` learned a new
  ``EXPORT_PACKAGE_DEPENDENCIES`` argument, which can be used to generate
  :command:`find_dependency` calls based on what targets the exported targets
  depend on.

Variables
---------

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

* The :variable:`CMAKE_LINKER_TYPE` variable and corresponding
  :prop_tgt:`LINKER_TYPE` target property were added to specify
  what linker to use with some toolchains.

* The :variable:`CMAKE_<LANG>_COMPILER_LINKER`,
  :variable:`CMAKE_<LANG>_COMPILER_LINKER_ID`,
  :variable:`CMAKE_<LANG>_COMPILER_LINKER_VERSION` and
  :variable:`CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT` variables
  were added to describe the linker used by the language's link step.

* The :variable:`CMAKE_PROJECT_INCLUDE`,
  :variable:`CMAKE_PROJECT_INCLUDE_BEFORE`,
  :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, and
  :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables learned
  to support a :ref:`semicolon-separated list <CMake Language Lists>` of
  CMake language files to be included sequentially. These variables can also
  reference module names to be found in :variable:`CMAKE_MODULE_PATH` or
  builtin to CMake.

* The :variable:`CMAKE_SKIP_TEST_ALL_DEPENDENCY` variable was added
  to control whether the ``test`` (or ``RUN_TESTS``) buildsystem
  target depends on the ``all`` (or ``ALL_BUILD``) target.

* A :variable:`CMAKE_TEST_LAUNCHER` variable and corresponding
  :prop_tgt:`TEST_LAUNCHER` target property were added to specify
  a launcher to be used by executable targets when invoked by
  tests added by the :command:`add_test` command.

Properties
----------

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

* The :prop_tgt:`EXPORT_FIND_PACKAGE_NAME` target property was added to
  allow targets to specify what package name to pass when exporting
  :command:`find_dependency` calls. This property is initialized with a new
  :variable:`CMAKE_EXPORT_FIND_PACKAGE_NAME` variable.

* The :prop_tgt:`UNITY_BUILD` target property now supports the
  Objective C (``OBJC``) and Objective C++ (``OBJCXX``) languages.

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

Modules
-------

* The :module:`CMakePackageConfigHelpers` module gained new
  :command:`generate_apple_platform_selection_file` and
  :command:`generate_apple_architecture_selection_file` functions, which can
  be used to generate a file that includes another Apple-platform-specific
  file or the includes an architecture-specific implementation of a package
  for an Apple platform, respectively.

* The :module:`FindOpenGL` module learned to find a GLU include
  directory different than the GL include directory.  A new
  ``OPENGL_INCLUDE_DIRS`` result variable provides all include
  directories.

CTest
-----

* :manual:`ctest(1)` gained a :option:`--http-header <ctest --http-header>`
  option to add custom headers on submission to CDash.

* :manual:`ctest(1)` gained the :option:`--tests-from-file <ctest
  --tests-from-file>` and :option:`--exclude-from-file <ctest
  --exclude-from-file>` options to run or exclude tests named in a file.

* :manual:`ctest(1)` now supports :ref:`job server integration
  <ctest-job-server-integration>` on POSIX systems.

* The :command:`ctest_test` command gained options
  ``INCLUDE_FROM_FILE`` and ``EXCLUDE_FROM_FILE`` to run or exclude
  tests named in a file.

CPack
-----

* The :cpack_gen:`CPack DEB Generator` :variable:`CPACK_DEBIAN_FILE_NAME`
  variable may now be set without any suffix, and the ``.deb`` suffix
  will be added automatically.

* The :cpack_gen:`CPack RPM Generator` :variable:`CPACK_RPM_FILE_NAME`
  variable may now be set without any suffix, and the ``.rpm`` suffix
  will be added automatically.

* The :cpack_gen:`CPack WIX Generator` gained a new variable,
  :variable:`CPACK_WIX_INSTALL_SCOPE`, to control the
  ``InstallScope`` property of WiX MSI installers.

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

* CMake learned to de-duplicate libraries on link lines based on linker
  capabilities.  See policy :policy:`CMP0156`.

* The :command:`add_test` command now honors
  :variable:`CMAKE_CROSSCOMPILING_EMULATOR` only when cross-compiling.
  See policy :policy:`CMP0158`.

* :command:`FetchContent_MakeAvailable` now sets the
  :variable:`CMAKE_EXPORT_FIND_PACKAGE_NAME` variable for CMake projects.

* On Windows, when targeting the MSVC ABI, the :command:`find_library` command
  now accepts ``.a`` file names after first considering ``.lib``.  This is
  symmetric with existing behavior when targeting the GNU ABI, in which the
  command accepts ``.lib`` file names after first considering ``.a``.

* On Windows, when targeting the MSVC ABI, the :command:`find_library` command
  now considers ``.dll.lib`` file names before ``.lib``.  This is the default
  suffix for DLL import libraries created by Rust toolchains for the MSVC ABI.

* The :generator:`Ninja` and :generator:`NMake Makefiles` generators now use
  the ``-external:I`` flag for system includes when using IntelLLVM as of
  version 2021.4. The ``-external:W0`` flag is also used as of version 2022.2.

* The :command:`create_test_sourcelist` command now provides a full path to
  the generated driver source file.

* The :variable:`CPACK_PRODUCTBUILD_DOMAINS` variable now defaults to true.
  See policy :policy:`CMP0161`.

* The :cpack_gen:`CPack WIX Generator` now produces WiX MSI installers
  that create start menu and uninstall entries for all users by default,
  as documented by the :variable:`CPACK_WIX_INSTALL_SCOPE` variable
  ``perMachine`` value.  Previously, without a custom WiX template,
  it produced installers that would only create start menu and uninstall
  entries for the current user, even though they install for all users.


code:
CMake 3.3 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.2 include the following.

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

Generators
----------

* The :ref:`Makefile Generators` now add ``.DELETE_ON_ERROR`` to the
  makefiles that contain the actual build rules for files on disk.
  This tells GNU make to remove rule outputs when their recipe
  modifies an output but fails.

* The :ref:`Visual Studio Generators` learned to support ``.xaml``
  source files and automatically associate them with corresponding
  ``.h`` and ``.cpp`` sources.

* A new experimental :generator:`Green Hills MULTI` generator was
  added on Windows.  `Green Hills MULTI`_ is an IDE for embedded
  real-time systems.

.. _`Green Hills MULTI`: https://www.ghs.com/products/MULTI_IDE.html

Commands
--------

* The :command:`add_dependencies` command learned to allow dependencies
  to be added to :ref:`interface libraries <Interface Libraries>`.
  Dependencies added to an interface library are followed transitively
  in its place since the target itself does not build.

* The :command:`execute_process` command learned to support specifying
  the same file for ``OUTPUT_FILE`` and ``ERROR_FILE``.

* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands
  learned a new ``LIST_DIRECTORIES <bool>`` option to specify whether
  the glob result should include directories.

* The :command:`find_library`, :command:`find_path`, and :command:`find_file`
  commands now search in installation prefixes derived from the ``PATH``
  environment variable.

* The :command:`if` command learned a new ``IN_LIST`` operator that
  evaluates to true if a given element is contained in a named list.

* The :command:`install(EXPORT)` and :command:`export()` commands
  learned to export targets that populate the :prop_tgt:`INTERFACE_SOURCES`
  target property.

* The :command:`install(TARGETS)` command learned to support
  generator expressions in the ``DESTINATION`` value.

Variables
---------

* The version of some Fortran compilers is now detected and stored in the
  :variable:`CMAKE_Fortran_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>`
  variable.

* The :ref:`Visual Studio Generators` learned a new
  :variable:`CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD` option
  to put the ``INSTALL`` target in the default build of a
  solution (``.sln``) file.

Properties
----------

* A :prop_tgt:`CROSSCOMPILING_EMULATOR` target property and supporting
  :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable were introduced
  to allow target platform binaries to run on the host during cross
  compiling.

* A :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` target property and supporting
  :variable:`CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE` variable were introduced
  to tell the :ref:`Makefile Generators` and the :generator:`Ninja` generator
  to run ``include-what-you-use`` along with the compiler for ``C`` and
  ``CXX`` languages.

* The :prop_tgt:`<LANG>_VISIBILITY_PRESET` and
  :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties now
  affect compilation in sources of all target types.  See
  policy :policy:`CMP0063`.

* The :prop_tgt:`XCODE_ATTRIBUTE_<an-attribute>` target property learned
  to support generator expressions.

Modules
-------

* The :module:`CheckFortranCompilerFlag` module was introduced
  to check ``Fortran`` compiler flags, much like the
  :module:`CheckCCompilerFlag` module already does for ``C``.

* The :module:`ExternalData` module learned a new
  :variable:`ExternalData_NO_SYMLINKS` option to disable use of
  symbolic links to populate the real data files and use copies
  instead.

* The :module:`ExternalData` module learned a new ``RECURSE:``
  option in ``DATA{}`` references specifying directories.
  This allows an entire directory tree of associated files
  to be matched.

* The :module:`ExternalData` module learned a new URL template
  placeholder ``%(algo:<key>)`` to allow custom mapping from
  algorithm name to URL component through configuration of new
  :variable:`ExternalData_URL_ALGO_<algo>_<key>` variables.
  This allows more flexibility in remote URLs.

* The :module:`ExternalProject` module learned to replace tokens
  like ``<BINARY_DIR>`` in the ``BYPRODUCTS`` of each step.

* The :module:`ExternalProject` module APIs learned to support
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  when using ``LOG_*`` options and in CMake initial cache options.

* The :module:`FindBoost` module now tracks the directories containing
  libraries separately for RELEASE and DEBUG configurations.

* The :module:`FindCUDA` module now defaults to using the static
  CUDA runtime library if it is available.  A new
  ``CUDA_USE_STATIC_CUDA_RUNTIME`` option is offered to control
  this behavior.

* The :module:`FindMatlab` module was completely rewritten.  It learned
  about versions and components and to find Matlab in a more precise and
  multiplatform way.  The module now offers APIs to create mex extensions,
  documentation, and unit tests.

* The :module:`FindPackageHandleStandardArgs` module
  ``FIND_PACKAGE_HANDLE_STANDARD_ARGS`` function now
  always populates both the ``<PackageName>_FOUND``
  and ``<UPPERCASE_NAME>_FOUND`` variables (the latter
  for backwards compatibility).  The ``FOUND_VAR``
  option is now ignored except to enforce its allowed
  values.

* The :module:`InstallRequiredSystemLibraries` module learned a new
  ``CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT`` option to specify the
  installation component.

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

* A new ``COMPILE_LANGUAGE`` generator expression was introduced to
  allow specification of compile options for target files based on the
  :prop_sf:`LANGUAGE` of each source file.  Due to limitations of the
  underlying native build tools, this feature has varying support across
  generators.  See the :manual:`cmake-generator-expressions(7)` manual
  for details.

CTest
-----

* The :manual:`ctest(1)` tool learned a new ``--repeat-until-fail <n>``
  option to help find sporadic test failures.

* The :module:`CTestCoverageCollectGCOV` module learned to support
  the same ``CTEST_CUSTOM_COVERAGE_EXCLUDE`` option as the
  :command:`ctest_coverage` command.

CPack
-----

* The :cpack_gen:`CPack IFW Generator` learned to support
  Qt Framework Installer 2.0 tools.

* The :cpack_gen:`CPack DEB Generator` learned a new
  :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS`
  variable to specify per-component use of ``dpkg-shlibdeps``.

* The :cpack_gen:`CPack DEB Generator` learned a new
  :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS`
  option to specify per-component dependencies.

* The :cpack_gen:`CPack RPM Generator` learned to package symbolic links
  more cleanly and now supports directory symlinks with recent
  ``rpmbuild`` versions.

* The :cpack_gen:`CPack RPM Generator` learned a new
  :variable:`CPACK_RPM_ADDITIONAL_MAN_DIRS` variable to specify
  directories containing man pages for the brp-compress RPM macro.

* The :cpack_gen:`CPack RPM Generator` learned a new
  :variable:`CPACK_RPM_<component>_PACKAGE_ARCHITECTURE` variable
  to specify a component-specific package architecture.

* The CPack WIX generator learned the new
  :prop_inst:`CPACK_START_MENU_SHORTCUTS`,
  :prop_inst:`CPACK_DESKTOP_SHORTCUTS` and
  :prop_inst:`CPACK_STARTUP_SHORTCUTS` installed file properties which can
  be used to install shortcuts in the Start Menu, on the Desktop and
  in the Startup Folder respectively.

Other
-----

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of features supported by GNU compilers on Windows, versions
  4.4 through 5.0.

* The :manual:`cmake(1)` ``-E tar`` command learned a new
  ``--format<format>`` option to specify the archive format to
  be written.

* On OS X, CMake learned to create XCTest bundles to test Frameworks
  and App Bundles within Xcode.  The :module:`FindXCTest` module
  provides convenience functions to handle :prop_tgt:`XCTEST` bundles.

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

* On OS X the :manual:`cmake-gui(1)` no longer has the
  ``Install For Command Line Use`` menu item.  Instead there
  is a ``How to Install For Command Line Use`` menu item
  that shows an informational dialog box explaining how to
  make the command line tools available.  For example::

    /Applications/CMake.app/Contents/bin/cmake-gui --install

* The :command:`ctest_build` and :command:`build_command` commands
  no longer tell ``make`` tools to ignore errors with the ``-i`` option.
  Previously this was done for :ref:`Makefile Generators` but not others.
  See policy :policy:`CMP0061`.

* The :generator:`Visual Studio 10 2010` generator no longer checks
  for running VS IDEs with the project open or asks them to reload.
  This was originally done for VS 10 because it had been done for
  VS 7 through 9 to avoid prompting for every project in a solution.
  Since VS >= 10 allow the whole solution to reload at once they
  do not need CMake to help them.

* The :generator:`Visual Studio 7` generator (.NET 2002) is now
  deprecated and will be removed in a future version of CMake.

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

* The :command:`find_package` command no longer considers project
  build trees recently configured in a :manual:`cmake-gui(1)`.
  This was previously done only on Windows and is now never done.
  The ``NO_CMAKE_BUILDS_PATH`` option is now ignored if given
  and effectively always on.
  Projects may populate the :ref:`User Package Registry` to aid
  users building multiple dependent projects one after another.

* The :command:`add_definitions()` command no longer causes a
  :prop_dir:`DEFINITIONS` directory property to be populated. See policy
  :policy:`CMP0059`.

* With Visual Studio 7, 8, and 9 generators the value of the ``$(OutDir)``
  placeholder no longer evaluates to the configuration name.  Projects
  should use ``$(ConfigurationName)`` for that instead.

* Using the output of :command:`export()` with the :command:`install(FILES)`
  command is no longer allowed.  See policy :policy:`CMP0062` for details.

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

* The :generator:`Ninja` generator now requires that calls to the
  :command:`add_custom_command` and :command:`add_custom_target`
  commands use the ``BYPRODUCTS`` option to explicitly specify any
  files generated by the custom commands that are not listed as
  outputs (perhaps because their timestamps are allowed to be older
  than the inputs).  See policy :policy:`CMP0058`.

* Build-time progress output of :ref:`Makefile Generators` has been improved.
  It no longer mixes progress and build rule messages during parallel builds.
  The link rule messages now have progress and are displayed as bold green
  instead of bold red (since red is often associated with an error message).

* The :variable:`CMAKE_CFG_INTDIR` variable value for Visual Studio
  7, 8, and 9 is now ``$(ConfigurationName)`` instead of ``$(OutDir)``.
  This should have no effect on the intended use cases of the variable.

* Linking to library files by a full path in an implicit linker search
  directory (e.g. ``/usr/lib/libfoo.a``) no longer asks the linker to
  search for the library (e.g. ``-lfoo``) and now links by full path.
  See policy :policy:`CMP0060`.


code:
CMake 3.4 Release Notes
***********************

.. only:: html

  .. contents::

Changes made since CMake 3.3 include the following.

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

Generators
----------

* The :generator:`Visual Studio 14 2015` generator learned to select
  a Windows 10 SDK based on the value of the :variable:`CMAKE_SYSTEM_VERSION`
  variable and the SDKs available on the host.

* CMake learned rudimentary support for the Apple Swift language.  When using
  the :generator:`Xcode` generator with Xcode 6.1 or higher, one may enable
  the ``Swift`` language with the :command:`enable_language` command or the
  :command:`project` command (this is an error with other generators or when
  Xcode is too old).  Then one may list ``.swift`` source files in targets
  for compilation.

Commands
--------

* The :command:`find_program` command learned a ``NAMES_PER_DIR``
  option to consider all given ``NAMES`` in each directory before
  moving on to the next directory.

* The :command:`get_filename_component` command learned a new ``BASE_DIR``
  subcommand.  This is used to specify a base directory when calculating an
  absolute path from a relative path.

* The :command:`if` command learned a new ``TEST`` operator that evaluates
  to true if a given test name has been defined by the :command:`add_test`
  command.  See policy :policy:`CMP0064`.

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

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

* The :command:`string` command learned a new ``APPEND`` subcommand.

Variables
---------

* The :ref:`Makefile Generators` and the :generator:`Ninja` generator
  learned to add compiler launcher tools like distcc and ccache along
  with the compiler for ``C`` and ``CXX`` languages.  See the
  :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and
  :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details.

* New :variable:`CMAKE_LINK_SEARCH_START_STATIC` and
  :variable:`CMAKE_LINK_SEARCH_END_STATIC` variables were
  introduced to initialize the
  :prop_tgt:`LINK_SEARCH_START_STATIC` and
  :prop_tgt:`LINK_SEARCH_END_STATIC` target properties,
  respectively.

Properties
----------

* :ref:`Visual Studio Generators` learned to support additional
  target properties to customize projects for NVIDIA Nsight
  Tegra Visual Studio Edition:

  * :prop_tgt:`ANDROID_ANT_ADDITIONAL_OPTIONS`
  * :prop_tgt:`ANDROID_ARCH`
  * :prop_tgt:`ANDROID_ASSETS_DIRECTORIES`
  * :prop_tgt:`ANDROID_JAR_DEPENDENCIES`
  * :prop_tgt:`ANDROID_JAR_DIRECTORIES`
  * :prop_tgt:`ANDROID_JAVA_SOURCE_DIR`
  * :prop_tgt:`ANDROID_NATIVE_LIB_DEPENDENCIES`
  * :prop_tgt:`ANDROID_NATIVE_LIB_DIRECTORIES`
  * :prop_tgt:`ANDROID_PROCESS_MAX`
  * :prop_tgt:`ANDROID_PROGUARD`
  * :prop_tgt:`ANDROID_PROGUARD_CONFIG_PATH`
  * :prop_tgt:`ANDROID_SECURE_PROPS_PATH`
  * :prop_tgt:`ANDROID_SKIP_ANT_STEP`
  * :prop_tgt:`ANDROID_STL_TYPE`

* The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`,
  :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and
  :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties learned to
  support :manual:`generator expressions <cmake-generator-expressions(7)>`.

* The :prop_tgt:`SOURCE_DIR` and :prop_tgt:`BINARY_DIR` target properties
  were introduced to allow project code to query where a target is defined.

* The :prop_tgt:`OUTPUT_NAME` target property and its variants learned to
  support :manual:`generator expressions <cmake-generator-expressions(7)>`.

* A :prop_gbl:`TARGET_MESSAGES` global property was added to tell the
  :ref:`Makefile Generators` whether to generate commands to print output
  after each target is completed.

* On Windows with MS-compatible tools, CMake learned to optionally
  generate a module definition (``.def``) file for ``SHARED`` libraries.
  See the :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property.

Modules
-------

* The :module:`ExternalProject` module :command:`ExternalProject_Add`
  function ``GIT_SUBMODULES`` option now also limits the set of
  submodules that are initialized in addition to the prior behavior
  of limiting the set of submodules that are updated.

* The :module:`ExternalProject` module learned new ``USES_TERMINAL``
  arguments for giving steps exclusive terminal access.  This is
  useful with the :generator:`Ninja` generator to monitor CMake
  superbuild progress and prevent CPU oversubscription.

* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a
  new ``DEFINES_FILE`` option to specify a custom output header
  to be generated.

* The :module:`FindHDF5` module learend a new ``HDF5_PREFER_PARALLEL``
  option allowing users to specify that a parallel HDF5 tool is
  preferred if both are available.

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

* The :module:`FindJava` module learned to optionally find
  the ``idlj`` and ``jarsigner`` tools.

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

* The :module:`FindOpenSSL` module learned a new ``OPENSSL_USE_STATIC_LIBS``
  option to search only for static libraries.

* The :module:`FindPkgConfig` learned a new :command:`pkg_get_variable`
  command which may be used to query for arbitrary variables from a package
  (such as for related tools or data and plugin install paths).

* The :module:`FindProtobuf` module gained a new
  :command:`protobuf_generate_python` function to generate python
  sources from ``.proto`` files.

* The :module:`FindTIFF` module learned to search separately for
  debug and release variants.

* The :module:`FindwxWidgets` module learned to support version requests.

* The :module:`FindXercesC` module learned to search separately for
  debug and release variants.

* The :module:`FindZLIB` module learned to search separately for
  debug and release variants.

* The :module:`GNUInstallDirs` module learned special default values
  for certain installation prefixes according to the `GNU Coding
  Standards`_ and the `Filesystem Hierarchy Standard`_.

* The :module:`UseJava` module ``add_jar`` function learned
  to support response files (e.g. ``@srcs.txt``) for source
  specification.

* The :module:`UseJava` module ``install_jar`` function learned
  new ``DESTINATION`` and ``COMPONENT`` options to specify
  the corresponding :command:`install` command options.

* The :module:`UseJava` module gained a new ``create_javah``
  function to create C headers from Java classes.

.. _`GNU Coding Standards`: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html
.. _`Filesystem Hierarchy Standard`: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html

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

* A new ``$<SHELL_PATH:...>``
  :manual:`generator expression <cmake-generator-expressions(7)>`
  has been added.

CTest
-----

* CTest learned to optionally measure the CPU load during parallel
  testing and avoid starting tests that may cause the load to exceed
  a given threshold.  See the :manual:`ctest(1)` command ``--test-load``
  option, the ``TestLoad`` setting of the :ref:`CTest Test Step`,
  the :variable:`CTEST_TEST_LOAD` variable, and the ``TEST_LOAD``
  option of the :command:`ctest_test` command.

* :manual:`ctest(1)` learned options
  ``--test-output-size-passed`` and ``--test-output-size-failed``
  to customize the limit on test output size submitted when
  running as a :ref:`Dashboard Client`.

CPack
-----

* The :cpack_gen:`CPack DEB Generator` learned to set package dependencies
  per component.  See variables:

  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_BREAKS`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_CONFLICTS`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_ENHANCES`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PREDEPENDS`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_PROVIDES`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_RECOMMENDS`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_REPLACES`
  * :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SUGGESTS`

* The :module:`CPack` module learned to package empty directories.

* The :module:`CPack` module gained a new setting, ``CPACK_VERBATIM_VARIABLES``,
  which can be used to ensure the cpack program receives the settings' values
  exactly as they were set, even if they contain CMake-special characters.
  For compatibility, it's off by default.

Other
-----

* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
  is now aware of features supported by GNU C compilers on Windows.

* CMake learned to honor ``*.manifest`` source files with MSVC tools.
  Manifest files named as sources of ``.exe`` and ``.dll`` targets
  will be merged with linker-generated manifests and embedded in the
  binary.

* The Concurrent Fortran 77 compiler is now supported.
  Its :variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` is ``CCur``.

* :manual:`cmake(1)` gained a new ``--trace-expand`` command line option
  that is like ``--trace`` but expands variable references in the output.

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

* The :module:`CMakeExpandImportedTargets` module is now documented
  as deprecated.  See module documentation for an explanation.

* The :variable:`CMAKE_USE_RELATIVE_PATHS` variable no longer has any
  effect.  Previously it was partially implemented and unreliable.

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

* The :module:`CheckFunctionExists`, :module:`CheckLibraryExists`,
  :module:`CheckSymbolExists`, and :module:`FindThreads` modules learned to
  work in environments where only CXX is enabled.

* The :cpack_gen:`CPack DEB Generator` now correctly excludes symlinks
  during package checksum calculation.

* The :cpack_gen:`CPack DEB Generator` no longer uses fakeroot and
  system tar program for packaging.

* The :module:`CPack` module no longer mangles settings with CMake-special
  characters when they're used as defaults for other settings. The macro
  ``cpack_set_if_not_set``, which was responsible for this, is now deprecated.

* CMake no longer links executables with flags to export symbols
  unless the :prop_tgt:`ENABLE_EXPORTS` target property is set.
  See policy :policy:`CMP0065`.

* The ``SONAME`` field is no longer set for ``MODULE`` libraries
  created with the :command:`add_library` command.  ``MODULE``
  libraries are meant for explicit dynamic loading at runtime.
  They cannot be linked so ``SONAME`` is not useful.

* The internal :variable:`CMAKE_<LANG>_COMPILE_OBJECT` rule variable now
  substitutes compiler include flags in a separate ``<INCLUDES>`` placeholder
  instead of the main ``<FLAGS>`` placeholder.