Help/release/3.23.rst

   1 CMake 3.23 Release Notes
   2 ************************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 3.22 include the following.
   9
  10 New Features
  11 ============
  12
  13 Presets
  14 -------
  15
  16 * :manual:`cmake-presets(7)` files now support schema version ``4``.
  17
  18 * :manual:`cmake-presets(7)` files now have an optional ``include`` field,
  19   which allows the files to include other files.
  20
  21 * :manual:`cmake-presets(7)` files now support a ``${fileDir}`` macro, which
  22   contains the directory containing the preset file.
  23
  24 * :manual:`cmake-presets(7)` gained support for specifying the
  25   ``resolvePackageReferences`` command line option in a build preset to control
  26   restoration behavior of package references from external package managers.
  27   Currently this is only supported by the Visual Studio generator to support
  28   restoring packages from NuGet. Other generators ignore this option.
  29
  30 Generators
  31 ----------
  32
  33 * The :ref:`Visual Studio Generators` for VS 2019 and above learned to
  34   support .NET SDK-style project files (``.csproj``) for C# projects.
  35   See the :prop_tgt:`DOTNET_SDK` target property and corresponding
  36   :variable:`CMAKE_DOTNET_SDK` variable.  :command:`add_custom_command`
  37   is not yet supported in .NET SDK-style projects.
  38
  39 * The :ref:`Visual Studio Generators` for VS 2017 and above learned to
  40   use portable instances of Visual Studio not known to the VS installer.
  41   See the :variable:`CMAKE_GENERATOR_INSTANCE` variable.
  42
  43 Command-Line
  44 ------------
  45
  46 * The :manual:`cmake(1)` ``--build`` command, when used with
  47   :ref:`Visual Studio Generators` on projects that set the
  48   :prop_tgt:`VS_PACKAGE_REFERENCES` target property, now automatically
  49   restores package references from NuGet.  The cache variable
  50   :variable:`CMAKE_VS_NUGET_PACKAGE_RESTORE` may be set to toggle this behavior
  51   in a build tree.  Use the ``--resolve-package-references=<on|off|only>``
  52   command-line option to control the behavior on one invocation.
  53
  54 * The :manual:`cmake(1)` command line tool gained a ``--debug-find-pkg=``
  55   option to enable debug messages under specific :command:`find_package`
  56   calls.
  57
  58 * The :manual:`cmake(1)` command line tool gained a ``--debug-find-var=``
  59   option to enable debug messages for ``find_*`` calls that use specific
  60   result variables.
  61
  62 Compilers
  63 ---------
  64
  65 * The IBM Open XL C/C++ compiler, based on LLVM, is now supported with
  66   compiler id ``IBMClang``.
  67
  68 * The MCST LCC compiler is now supported with compiler id ``LCC``.
  69   See policy :policy:`CMP0129`.
  70
  71 File-Based API
  72 --------------
  73
  74 * The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field
  75   has been updated to ``2.4``.
  76
  77 * The :manual:`cmake-file-api(7)` "codemodel" version 2 ``directory``
  78   object ``installers`` field gained a new ``fileSet`` installer type.
  79
  80 Commands
  81 --------
  82
  83 * The :command:`define_property` command gained a new
  84   ``INITIALIZE_FROM_VARIABLE`` option to cause a target property to be
  85   initialized from a variable when a target is created.
  86
  87 * The :command:`install(TARGETS)` command gained a new ``FILE_SET`` argument,
  88   which can be used to install header file sets associated with a target.
  89
  90 * The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` commands now
  91   support the ``%f`` specifier for microseconds.
  92
  93 * The :command:`target_sources` command gained a new ``FILE_SET`` mode, which
  94   can be used to add headers as header-only source files of a target.
  95
  96 Variables
  97 ---------
  98
  99 * The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated
 100   :prop_tgt:`CUDA_ARCHITECTURES` target property now support the
 101   ``all``, and ``all-major`` values for CUDA toolkit 7.0+.
 102
 103 * The :variable:`CMAKE_IGNORE_PREFIX_PATH` and
 104   :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables were added
 105   to tell the :command:`find_package`, :command:`find_program`,
 106   :command:`find_library`, :command:`find_path`, and :command:`find_file`
 107   commands to ignore specified prefixes.
 108
 109 * The :variable:`CMAKE_LINK_LIBRARIES_ONLY_TARGETS` variable and
 110   corresponding :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` target
 111   property were added to optionally require that all link items
 112   that can be target names are actually names of existing targets.
 113
 114 Properties
 115 ----------
 116
 117 * The :prop_tgt:`HEADER_SETS` and :prop_tgt:`INTERFACE_HEADER_SETS` read-only
 118   target properties were added to list header sets associated with a target.
 119
 120 * The :prop_tgt:`HEADER_SET` and :prop_tgt:`HEADER_SET_<NAME>` target
 121   properties were added to list files in the default header set
 122   and named header sets, respectively.
 123
 124 * The :prop_tgt:`HEADER_DIRS` and :prop_tgt:`HEADER_DIRS_<NAME>` target
 125   properties were added to specify the base directories of the default
 126   header set and named header sets, respectively.
 127
 128 * The :prop_tgt:`IMPORTED_NO_SYSTEM` target property was added to
 129   specify that an :ref:`Imported Target <Imported Targets>` should
 130   not be treated as a system library (i.e. its include directories
 131   are not automatically ``SYSTEM``).
 132
 133 * The :prop_tgt:`XCODE_EMBED_PLUGINS <XCODE_EMBED_<type>>` target property
 134   was added to tell the :generator:`Xcode` generator what targets to put in
 135   the ``Embed PlugIns`` build phase.
 136
 137 * The :prop_tgt:`XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE` target property
 138   and supporting :variable:`CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE`
 139   variable were added to tell the :generator:`Xcode` generator to enable
 140   specifying the Xcode scheme option property ``GPU Frame Capture``.
 141
 142 Modules
 143 -------
 144
 145 * The :module:`CheckPIESupported` module now supports the ``OBJC``,
 146   ``OBJCXX``, ``CUDA``, and ``HIP`` languages.  It also now honors
 147   :variable:`CMAKE_SYSROOT` and :variable:`CMAKE_OSX_SYSROOT`.
 148
 149 * The :module:`ExternalProject` module's :command:`ExternalProject_Add`
 150   command gained support for a ``USES_TERMINAL_PATCH`` option to give
 151   the patch step exclusive terminal access.
 152
 153 * The :module:`FindCUDAToolkit` module now provides a target for
 154   ``libcufft_static_nocallback``, if found.
 155
 156 * The :module:`FindGLUT` module now provides the ``GLUT_INCLUDE_DIRS``
 157   result variable to conform with naming conventions documented in the
 158   :manual:`cmake-developer(7)` manual.  This supersedes the legacy
 159   ``GLUT_INCLUDE_DIR`` variable.
 160
 161 * The :module:`FindGTest` module now provides a target for GMock, if found.
 162
 163 * The :module:`FindVulkan` module now provides a ``Vulkan_VERSION`` result
 164   variable reporting the version number.
 165
 166 CTest
 167 -----
 168
 169 * :manual:`ctest(1)` gained a new :variable:`CTEST_SUBMIT_INACTIVITY_TIMEOUT`
 170   variable, which can be used to specify a timeout for submission inactivity.
 171
 172 CPack
 173 -----
 174
 175 * The :cpack_gen:`CPack productbuild Generator` gained the new
 176   :variable:`CPACK_PRODUCTBUILD_DOMAINS`,
 177   :variable:`CPACK_PRODUCTBUILD_DOMAINS_ANYWHERE`,
 178   :variable:`CPACK_PRODUCTBUILD_DOMAINS_USER`, and
 179   :variable:`CPACK_PRODUCTBUILD_DOMAINS_ROOT` variables for
 180   adding the domains element to the Distribution XML. With these variables,
 181   it is now possible to install products to the user's home directory
 182   without requiring administrative privileges.
 183
 184 * The :cpack_gen:`CPack productbuild Generator` gained a new variable,
 185   :variable:`CPACK_PRODUCTBUILD_IDENTIFIER`, used to customize the unique
 186   product identifier associated with the product.
 187
 188 * The ``CPack.distribution.dist.in`` template used by the
 189   :cpack_gen:`CPack productbuild Generator` and
 190   :cpack_gen:`CPack PackageMaker Generator` was updated to use a new
 191   ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable for its main content.
 192   This replaced the previously undocumented and now deprecated
 193   ``CPACK_PACKAGEMAKER_CHOICES`` variable.
 194
 195 * The :cpack_gen:`CPack IFW Generator` gained the new
 196   :variable:`CPACK_IFW_ARCHIVE_FORMAT` and
 197   :variable:`CPACK_IFW_ARCHIVE_COMPRESSION` variables for setting the
 198   format used when packaging new component data archives, and choosing
 199   the compression level used.
 200   These features are available for QtIFW 4.2 and newer.
 201
 202 * The :cpack_gen:`CPack IFW Generator` gained new
 203   :variable:`CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE` variable to
 204   prevent the user from passing any consumer command to the installer, like
 205   ``install``, ``update``, and ``remove``.
 206   This feature is available for QtIFW 4.0 and newer.
 207
 208 * The :cpack_gen:`CPack IFW Generator` gained the new
 209   :variable:`CPACK_IFW_PACKAGE_PRODUCT_IMAGES` variable for adding a
 210   list of images to be shown on the ``PerformInstallationPage``.
 211   This feature is available for QtIFW 4.0 and newer.
 212
 213 * The :cpack_gen:`CPack IFW Generator` gained the new
 214   :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM`,
 215   :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM_ARGUMENTS`, and
 216   :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM_DESCRIPTION` variables for
 217   executing a command after the installer is done if the user accepts
 218   the action.  This feature is available for QtIFW 4.0 and newer.
 219
 220 * The :cpack_gen:`CPack IFW Generator` gained the new
 221   :variable:`CPACK_IFW_PACKAGE_SIGNING_IDENTITY` variable for specifying a
 222   code signing identity to be used for signing the generated app bundle.
 223   This feature is available on macOS only, and for QtIFW 3.0 and newer.
 224
 225 * The :cpack_gen:`CPack WIX Generator` gained a new variable,
 226   :variable:`CPACK_WIX_SKIP_WIX_UI_EXTENSION`, to skip the inclusion
 227   of WixUIExtensions.
 228
 229 Deprecated and Removed Features
 230 ===============================
 231
 232 * :manual:`cmake(1)` now warns when multiple source paths are specified,
 233   as in ``cmake -S src1 src2``.  This has never been officially documented
 234   or supported, but older versions accidentally accepted multiple source
 235   paths and used the last path specified.  Update scripts to avoid
 236   passing multiple source path arguments.
 237
 238 * The :manual:`cpack(1)` undocumented ``OSXX11`` generator has been removed.
 239
 240 * The previously undocumented ``CPACK_PACKAGEMAKER_CHOICES`` variable used in
 241   the ``CPack.distribution.dist.in`` template has been replaced by a new
 242   ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable. This only affects projects
 243   that were providing their own custom ``CPack.distribution.dist.in`` template
 244   file, but still relied on ``CPACK_PACKAGEMAKER_CHOICES`` being set. Those
 245   custom template files should be updated to use
 246   ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` instead, or to fully define all the
 247   template file's contents without relying on substitution of either variable.
 248
 249 Other Changes
 250 =============
 251
 252 * The :cpack_gen:`CPack DragNDrop Generator` no longer attaches
 253   :variable:`CPACK_RESOURCE_FILE_LICENSE` as the license agreement in
 254   the generated ``.dmg`` unless explicitly activated by a
 255   :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` option.
 256   In CMake projects, the :module:`CPack` module enables the option
 257   by default for compatibility.
 258
 259 * ``CUDA`` targets may now enable both :prop_tgt:`CUDA_SEPARABLE_COMPILATION`
 260   and :prop_tgt:`CUDA_PTX_COMPILATION`.
 261
 262 * ``CUDA`` compiler detection now:
 263
 264   * issues an error in all cases when it's unable to compute the default
 265     architecture(s) if required (see :policy:`CMP0104`),
 266
 267   * handles ``OFF`` for :variable:`CMAKE_CUDA_ARCHITECTURES` on Clang,
 268
 269   * supports the theoretical case of multiple default architectures, and
 270
 271   * tries to detect invalid architectures and issue an error.
 272
 273 * ``CUDA`` with Clang now implements policy :policy:`CMP0105` and
 274   the ``$<DEVICE_LINK:...>`` and ``$<HOST_LINK:...>``
 275   :manual:`generator expressions <cmake-generator-expressions(7)>`.
 276
 277 * The :command:`define_property` command's ``BRIEF_DOCS`` and ``FULL_DOCS``
 278   arguments are now optional.
 279
 280 * :manual:`ccmake(1)` may now be enabled on Windows when building
 281   CMake from source.  This is experimental, and so is not included
 282   in official distributions.
 283
 284 Updates
 285 =======
 286
 287 Changes made since CMake 3.23.0 include the following.
 288
 289 3.23.1
 290 ------
 291
 292 * The :command:`target_sources` ``FILE_SET`` feature added in CMake 3.23.0
 293   does not yet place header files properly in Apple :prop_tgt:`FRAMEWORK`
 294   targets.  Pending further work in a future version of CMake, it is now
 295   an error to add a ``FILE_SET`` of type ``HEADERS`` to such targets on
 296   Apple platforms.
 297
 298 * The :prop_tgt:`HEADER_SETS` and :prop_tgt:`INTERFACE_HEADER_SETS` target
 299   properties added in CMake 3.23.0 are now read-only records of the header
 300   sets created by the :command:`target_sources` command.
 301
 302 3.23.2
 303 ------
 304
 305 * The ``CPACK_PACKAGEMAKER_CHOICES`` variable used in the
 306   ``CPack.distribution.dist.in`` template file was replaced by a new
 307   ``CPACK_APPLE_PKG_INSTALLER_CONTENT`` variable in CMake 3.23.0.
 308   This broke projects that provided their own template file but still
 309   expected the ``CPACK_PACKAGEMAKER_CHOICES`` variable to be defined.
 310   The old ``CPACK_PACKAGEMAKER_CHOICES`` variable is now also set to the
 311   same content as it was before, but it is formally deprecated.