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)` gained support for specifying the
  ``resolvePackageReferences`` command line option in a build preset.

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)` ``--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 ``--resolve-package-references=<on|off|only>``
  command-line option to control the behavior on one invocation.

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

* The :manual:`cmake(1)` command line tool gained a ``--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` 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:`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:`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.

* 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_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
===============================

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

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 ``$<DEVICE_LINK:...>`` and ``$<HOST_LINK:...>``
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

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