Help/release/3.24.rst

   1 CMake 3.24 Release Notes
   2 ************************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 3.23 include the following.
   9
  10 New Features
  11 ============
  12
  13 Presets
  14 -------
  15
  16 * :manual:`cmake-presets(7)` files now support schema version ``5``.
  17
  18 * :manual:`cmake-presets(7)` files now support a ``${pathListSep}`` macro,
  19   which expands to ``:`` or ``;`` based on the platform.
  20
  21 * :manual:`cmake-presets(7)` files gained support for specifying a
  22   ``testOutputTruncation`` field in test presets, which specifies the
  23   truncation mode once the maximum test output size has been reached.
  24
  25 Generators
  26 ----------
  27
  28 * The :generator:`Green Hills MULTI` generator now generates build
  29   rules to re-run CMake if any CMake files are updated.
  30
  31 * The :ref:`Visual Studio Generators` now support ``SYSTEM`` headers
  32   when using VS 2019 Update 11 or later.
  33
  34 Command-Line
  35 ------------
  36
  37 * :manual:`cmake(1)` gained the :option:`--fresh <cmake --fresh>` command-line
  38   option to remove any existing ``CMakeCache.txt`` file and associated ``CMakeFiles/``
  39   directory, when configuring a build tree, thus starting a new configuration
  40   as if the build tree were freshly created.
  41
  42 * :manual:`cmake(1)` gained the
  43   :option:`--compile-no-warning-as-error <cmake --compile-no-warning-as-error>`
  44   command-line option which causes the effects of the
  45   :prop_tgt:`COMPILE_WARNING_AS_ERROR` target property and
  46   :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable to be ignored.
  47
  48 * The :manual:`cmake(1)` :option:`--trace=json-v1 <cmake --trace>` trace
  49   format gained fields ``global_frame`` and ``line_end``.
  50
  51 * The :manual:`cmake(1)` :option:`-E <cmake -E>` commands :option:`cat <cmake-E cat>`
  52   and :option:`env <cmake-E env>` learned to respect a double dash
  53   (:option:`-- <cmake-E_env -->`) argument that acts as a delimiter indicating
  54   the end of options. Any following arguments are treated as operands/positional
  55   arguments, even if they begin with a dash ``-`` character.
  56
  57 * The :manual:`cmake(1)` :option:`-E tar <cmake-E tar>` command gained the
  58   :option:`--touch <cmake-E_tar --touch>` option
  59   to keep the current local timestamp instead of extracting file timestamps
  60   from the archive.
  61
  62 Compilers
  63 ---------
  64
  65 * LLVM's `flang`_ Fortran compiler is now supported on some platforms,
  66   with compiler id ``LLVMFlang``.
  67
  68 .. _`flang`: https://github.com/llvm/llvm-project/tree/main/flang
  69
  70 * ADSP compiler support (SHARC and Blackfin) now covers both CCES and
  71   VDSP++ installations, with required configuration now done in the
  72   compiler module itself rather than the ``Generic-ADSP`` platform module.
  73
  74 Platforms
  75 ---------
  76
  77 * A dedicated ``ADSP`` platform has been added
  78   to replace the existing ``Generic-ADSP`` implementation.
  79   This features automatic detection of the latest CCES/VDSP++ install
  80   and compiler selection (``cc21k`` vs. ``ccblkfn``)
  81   based off of the :variable:`CMAKE_SYSTEM_PROCESSOR` variable.
  82
  83 Commands
  84 --------
  85
  86 * The :command:`cmake_host_system_information` command, on Windows,
  87   gained a ``QUERY WINDOWS_REGISTRY`` mode.
  88   See its :ref:`Query Windows registry` section.
  89
  90 * The :command:`cmake_language` command gained a new
  91   ``SET_DEPENDENCY_PROVIDER`` sub-command.  When a dependency provider is set,
  92   calls to :command:`find_package` and :command:`FetchContent_MakeAvailable`
  93   can be redirected through a custom command, which can choose to fulfill the
  94   request directly, modify how the request is processed, or leave it to be
  95   fulfilled by the built-in implementation.  See :ref:`dependency_providers`.
  96
  97 * The :command:`file(DOWNLOAD)` command gained options ``RANGE_START`` and
  98   ``RANGE_END`` to specify a range of bytes to download.  This can be
  99   useful for downloading parts of big binary files.
 100
 101 * The :command:`find_file`, :command:`find_path`, :command:`find_library`,
 102   :command:`find_program`, and :command:`find_package` commands gained the
 103   ``NO_CMAKE_INSTALL_PREFIX`` option to control searching
 104   :variable:`CMAKE_INSTALL_PREFIX`.
 105
 106 * The :command:`find_file`, :command:`find_path`, :command:`find_library`,
 107   :command:`find_program`, and :command:`find_package` commands gained the
 108   ability to specify which Windows Registry views must be queried.
 109
 110 * The :command:`find_package` command gained a ``GLOBAL`` option that
 111   allows for the promotion of imported targets to global scope for the
 112   duration of the :command:`find_package` call.
 113
 114 * The :command:`if` command gained the capability to compare paths by
 115   using the ``PATH_EQUAL`` operator.  See policy :policy:`CMP0139`.
 116
 117 Variables
 118 ---------
 119
 120 * The :variable:`CMAKE_COLOR_DIAGNOSTICS` variable was added to control
 121   color diagnostics generated by compilers.  This variable also controls
 122   color build system messages with :ref:`Makefile Generators`, replacing
 123   :variable:`CMAKE_COLOR_MAKEFILE`.
 124
 125   The :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment variable was added to set
 126   a default value for :variable:`CMAKE_COLOR_DIAGNOSTICS`.
 127
 128 * The :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable and corresponding
 129   :prop_tgt:`COMPILE_WARNING_AS_ERROR` target property were added to enable
 130   compilation with a compiler-specific flag to treat warnings as errors,
 131   such as ``-Werror``.
 132
 133 * The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated
 134   :prop_tgt:`CUDA_ARCHITECTURES` target property now support the
 135   special ``native`` value to compile for the architectures(s)
 136   of the host's GPU(s).
 137
 138 * The :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` variable was added to
 139   toggle behavior of the :command:`find_package` command's new ``GLOBAL``
 140   option.
 141
 142 * The :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` variable was added to toggle
 143   behavior of the :command:`find_file`, :command:`find_library`,
 144   :command:`find_path`, :command:`find_package`, and :command:`find_program`
 145   commands' new ``NO_CMAKE_INSTALL_PREFIX`` option.
 146
 147 * The :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable was added to allow
 148   injecting custom code at the site of the first :command:`project` call,
 149   after the host and target platform details have been determined.
 150
 151 * The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable
 152   was added to tell the :command:`try_compile` command not to
 153   pass any platform variables to the test project.
 154
 155 * The :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable and
 156   corresponding :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` target property
 157   were added to enable build rules that verify all headers in header sets
 158   can be used on their own.
 159
 160 * The :variable:`CMAKE_VS_NO_COMPILE_BATCHING` variable and corresponding
 161   :prop_tgt:`VS_NO_COMPILE_BATCHING` target property were added to
 162   tell :ref:`Visual Studio Generators` whether to disable compiler
 163   parallelism and call the compiler with one source file at a time.
 164
 165 * The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` variable and
 166   :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property were introduced to
 167   select the runtime library used by compilers targeting the Watcom ABI.
 168   See policy :policy:`CMP0136`.
 169
 170 * The :variable:`CMAKE_XCODE_XCCONFIG` variable and corresponding
 171   :prop_tgt:`XCODE_XCCONFIG` target property were added to tell
 172   the :generator:`Xcode` generator to handle ``xcconfig`` files.
 173
 174 Properties
 175 ----------
 176
 177 * The :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and
 178   :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties
 179   were added to express usage requirements affecting a consumer's
 180   direct link dependencies.
 181
 182 * The :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY` target property was
 183   added to specify which header sets should be verified by
 184   :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS`.
 185
 186 * The :prop_tgt:`LINK_LIBRARIES` target property now supports
 187   the :genex:`$<LINK_ONLY:...>` generator expression.
 188   See policy :policy:`CMP0131`.
 189
 190 * The :prop_tgt:`VS_DOTNET_STARTUP_OBJECT` target property was added to
 191   tell :ref:`Visual Studio Generators` which startup class shall be used
 192   when the program or project is executed. This is necessary when more
 193   than one ``static void Main(string[])`` function signature is available
 194   in a managed .NET project.
 195
 196 Modules
 197 -------
 198
 199 * The :module:`ExternalProject` module :command:`ExternalProject_Add`
 200   command gained a new ``DOWNLOAD_EXTRACT_TIMESTAMP`` option for
 201   controlling whether the timestamps of extracted contents are set to
 202   match those in the archive when the ``URL`` download method is used.
 203   Policy :policy:`CMP0135` was added to enable the option by default.
 204
 205 * The :module:`FetchContent` module and the :command:`find_package` command
 206   now support integration capabilities:
 207
 208   * :command:`FetchContent_MakeAvailable` can now try to satisfy a dependency
 209     by calling :command:`find_package` first.  A new
 210     :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable controls whether
 211     this is done by default for all dependencies, is opt-in per dependency,
 212     or is disabled entirely.
 213
 214   * :command:`find_package` can be re-routed to call
 215     :command:`FetchContent_MakeAvailable` instead.  A new read-only
 216     :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable points to a
 217     directory where config package files can be located to facilitate these
 218     re-routed calls.
 219
 220 * The :module:`FindJNI` module now provides imported targets.
 221
 222 * The :module:`FindMatlab` module :command:`matlab_add_mex` function
 223   gained a ``NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES`` option to disable
 224   automatic linking of MATLAB libraries.
 225
 226 * The :module:`FindVulkan` module now supports components to select which
 227   VulkanSDK tool and libraries to find in addition to the Vulkan SDK headers
 228   and library.
 229
 230 * The :module:`FindZLIB` gained a new ``ZLIB_USE_STATIC_LIBS`` variable to
 231   search only for static libraries.
 232
 233 Generator Expressions
 234 ---------------------
 235
 236 * The :genex:`LINK_LIBRARY` generator expression was added to manage how
 237   libraries are specified during the link step.
 238   The :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and
 239   :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables are used to define
 240   features usable by the :genex:`LINK_LIBRARY` generator expression.
 241   Moreover, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
 242   :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties are
 243   available to resolve incompatible features.
 244
 245   The :genex:`LINK_LIBRARY` generator expression can link frameworks in
 246   various ways when targeting ``Apple`` platforms.
 247   The following features were added:
 248
 249   * ``FRAMEWORK``
 250   * ``NEEDED_FRAMEWORK``
 251   * ``REEXPORT_FRAMEWORK``
 252   * ``WEAK_FRAMEWORK``
 253
 254   The :genex:`LINK_LIBRARY` generator expression can link libraries in
 255   various ways when targeting ``Apple`` platforms.
 256   The following features were added:
 257
 258   * ``NEEDED_LIBRARY``
 259   * ``REEXPORT_LIBRARY``
 260   * ``WEAK_LIBRARY``
 261
 262   The :genex:`LINK_LIBRARY` generator expression gained the feature
 263   ``WHOLE_ARCHIVE`` to force load of all members in a static library.
 264   This feature is supported on the following target platforms:
 265
 266   * all ``Apple`` variants
 267   * ``Linux``
 268   * all ``BSD`` variants
 269   * ``SunOS``
 270   * ``Windows``
 271   * ``CYGWIN``
 272   * ``MSYS``
 273
 274 * The :genex:`LINK_GROUP` generator expression was added to manage the
 275   grouping of libraries during the link step.  The
 276   :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` and
 277   :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variables are used to define
 278   features usable with the :genex:`LINK_GROUP` generator expression.
 279   This release defines the ``RESCAN`` feature, which can be used to handle
 280   circular references among static libraries when using toolchains for
 281   Linux, BSD, SunOS and GNU toolchains for Windows.
 282
 283 * The :genex:`PATH` generator expression was added to manage paths.
 284
 285 * The :genex:`PATH_EQUAL` generator expression was added to manage path
 286   comparisons.
 287
 288 * The :genex:`TARGET_BUNDLE_DIR_NAME` generator expression
 289   was added to evaluate to the name of the bundle directory
 290   for a given bundle target.
 291
 292 CTest
 293 -----
 294
 295 * :manual:`ctest(1)` gained a
 296   :option:`--test-output-truncation <ctest --test-output-truncation>` option
 297   (and corresponding :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable)
 298   to specify the truncation mode once the maximum test output size has been
 299   reached. Possible values are ``tail`` (default), ``middle`` or ``head``.
 300
 301 CPack
 302 -----
 303
 304 * The :cpack_gen:`CPack WIX Generator` gained a new variable,
 305   :variable:`CPACK_WIX_ARCHITECTURE`, to specify the installer architecture
 306   in order to support computers running Windows for ARM.
 307
 308 * CPack now supports the :variable:`CPACK_THREADS` option for ``zstd``
 309   compression when compiled with libarchive 3.6 or higher.  It is
 310   supported by official CMake binaries available on `cmake.org`_.
 311
 312 Deprecated and Removed Features
 313 ===============================
 314
 315 * The :module:`CPack` module no longer enables the SLA by default in the
 316   :cpack_gen:`CPack DragNDrop Generator`.  See policy :policy:`CMP0133`
 317   and the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` variable.
 318
 319 * The deprecated :cpack_gen:`CPack PackageMaker Generator` has been removed.
 320
 321 * The :module:`FindGLUT` module no longer provides the undocumented
 322   ``GLUT_LIBRARY`` and ``GLUT_INCLUDE_PATH`` result variables.
 323
 324 * The :module:`FindVulkan` module no longer silently ignores unknown
 325   components requested by a ``find_package(Vulkan REQUIRED ...)`` call.
 326   With the addition of support for components, requests for unknown
 327   components now produce an error.
 328
 329 Other Changes
 330 =============
 331
 332 * CMake no longer sets environment variables like :envvar:`CC`, :envvar:`CXX`,
 333   etc. when enabling the corresponding language during the first CMake run in
 334   a build directory.  See policy :policy:`CMP0132`.
 335
 336 * The :module:`CheckIPOSupported` module :command:`check_ipo_supported`
 337   command now uses the caller's :variable:`CMAKE_<LANG>_FLAGS`
 338   and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values.
 339   See policy :policy:`CMP0138`.
 340
 341 * The :generator:`MSYS Makefiles` and :generator:`MinGW Makefiles`
 342   generators, when a compiler is not explicitly specified, now select
 343   the first compiler (of any name) found in directories listed by the
 344   ``PATH`` environment variable.
 345
 346 * The :command:`try_compile` command
 347   :ref:`whole-project <Try Compiling Whole Projects>` signature
 348   now propagates platform variables.  See policy :policy:`CMP0137`.
 349
 350 * The :command:`while` command now diagnoses errors during condition
 351   evaluation.  See policy :policy:`CMP0130`.
 352
 353 * The precompiled macOS binaries provided on `cmake.org`_ no longer attach a
 354   SLA to the ``.dmg`` packages.  This was removed because macOS 12 deprecated
 355   the tools used to attach ``.dmg`` resources.
 356
 357 * A precompiled Windows ``arm64`` binary is now provided on `cmake.org`_.
 358
 359 .. _`cmake.org`: https://cmake.org/download/
 360
 361 Updates
 362 =======
 363
 364 Changes made since CMake 3.24.0 include the following.
 365
 366 3.24.1, 3.24.2
 367 --------------
 368
 369 * These versions made no changes to documented features or interfaces.
 370   Some implementation updates were made to support ecosystem changes
 371   and/or fix regressions.
 372
 373 3.24.3
 374 ------
 375
 376 * The ``LLVMFlang`` Fortran compiler support added in 3.24.0 has been extended:
 377
 378   * It now supports mixed-language linking between Fortran and C or CXX.
 379   * It now supports the GNU ABI (MinGW) on Windows, but not yet the MSVC ABI.
 380
 381 * Some implementation updates were made to support ecosystem changes
 382   and/or fix regressions.