Help/release/3.21.rst

   1 CMake 3.21 Release Notes
   2 ************************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 3.20 include the following.
   9
  10 New Features
  11 ============
  12
  13 Presets
  14 -------
  15
  16 * :manual:`cmake-presets(7)` gained support for specifying the install prefix
  17   in a configure preset.
  18
  19 * :manual:`cmake-presets(7)` gained support for conditional enabling of presets.
  20
  21 * :manual:`cmake-presets(7)` gained support for a ``${hostSystemName}`` macro.
  22
  23 * :manual:`cmake-presets(7)` gained support for omitting the ``generator`` and
  24   ``binaryDir`` fields.
  25
  26 Generators
  27 ----------
  28
  29 * The :generator:`Visual Studio 17 2022` generator was added.
  30
  31 * The :ref:`Makefile Generators` and the :generator:`Ninja` generator
  32   learned to add linker launcher tools along with the linker for ``C``,
  33   ``CXX``, ``OBJC``, and ``OBJCXX`` languages.
  34   See the :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` variable
  35   and :prop_tgt:`<LANG>_LINKER_LAUNCHER` target property for details.
  36
  37 Languages
  38 ---------
  39
  40 * CMake learned to support ``HIP`` as a first-class language that can be
  41   enabled via the :command:`project` and :command:`enable_language` commands.
  42
  43 * :prop_tgt:`C_STANDARD`, :prop_tgt:`OBJC_STANDARD`, and the
  44   :manual:`Compile Features <cmake-compile-features(7)>` functionality gained
  45   support for C17 and C23.
  46
  47 * Source file extensions ``.ixx`` and ``.cppm`` are now treated as C++.
  48
  49 Command-Line
  50 ------------
  51
  52 * :manual:`cmake(1)` gained the ``--install-prefix <dir>``
  53   command-line option to specify the location of the install prefix.
  54
  55 * :manual:`cmake(1)` gained the ``--toolchain <path/to/file>``
  56   command-line option to specify a toolchain file.
  57
  58 * :manual:`cmake(1)` ``-E capabilities`` output, for some generators,
  59   may now contain a ``supportedPlatforms`` field listing platforms
  60   known to be supported in :variable:`CMAKE_GENERATOR_PLATFORM`.
  61
  62 * Messages printed to a terminal now may be colored by message type.
  63
  64 Compilers
  65 ---------
  66
  67 * The Fujitsu compiler is now supported using compiler id ``Fujitsu``
  68   in traditional (``Trad``) mode, and compiler id ``FujitsuClang``
  69   in ``Clang`` mode.
  70
  71 Platforms
  72 ---------
  73
  74 * CMake now supports the MSYS runtime environment, much like CYGWIN.
  75
  76 File-Based API
  77 --------------
  78
  79 * The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field
  80   has been updated to 2.3.
  81
  82 * The :manual:`cmake-file-api(7)` "codemodel" version 2 gained a
  83   new "directory" object containing directory-level information.
  84   This includes a list of installers generated by the :command:`install`
  85   command.
  86
  87 Commands
  88 --------
  89
  90 * The :command:`add_custom_command` command ``DEPFILE`` option:
  91
  92   * may now use
  93     :manual:`generator expressions <cmake-generator-expressions(7)>`,
  94
  95   * is now supported by :ref:`Visual Studio Generators` for VS 2012
  96     and above, and
  97
  98   * is now supported by the :generator:`Xcode` generator.
  99
 100 * The :command:`add_custom_command(TARGET)` command
 101   (for :ref:`Build Events <add_custom_command(TARGET)>`)
 102   gained support for resolving target-dependent generator expressions.
 103
 104 * The :command:`build_command` command gained a ``PARALLEL_LEVEL`` option.
 105
 106 * The :command:`file(COPY_FILE)` command was added to copy a single file.
 107
 108 * The :command:`file(GET_RUNTIME_DEPENDENCIES)` command gained new
 109   ``POST_INCLUDE_FILES`` and ``POST_EXCLUDE_FILES`` arguments.
 110
 111 * The :command:`file(REAL_PATH)` command gained the option ``EXPAND_TILDE`` to
 112   replace any leading tilde with the path to the user's home directory.
 113
 114 * The :command:`file(RENAME)` command learned to optionally capture
 115   failure in a result variable.  It also gained a ``NO_REPLACE``
 116   option to fail if the destination exists.
 117
 118 * The :command:`install` command gained a new ``IMPORTED_RUNTIME_ARTIFACTS``
 119   mode, which can be used to install the runtime artifacts of imported targets.
 120
 121 * The :command:`install` command gained a new ``RUNTIME_DEPENDENCY_SET`` mode,
 122   which can be used to install runtime dependencies using
 123   :command:`file(GET_RUNTIME_DEPENDENCIES)`.
 124
 125 * The :command:`install(TARGETS)` command gained new ``RUNTIME_DEPENDENCIES``
 126   and ``RUNTIME_DEPENDENCY_SET`` arguments, which can be used to install
 127   runtime dependencies using :command:`file(GET_RUNTIME_DEPENDENCIES)`.
 128
 129 * The :command:`install(SCRIPT|CODE)` command
 130   supports a new option ``ALL_COMPONENTS`` which allows
 131   the corresponding code to run for every component of
 132   a per component installation.
 133
 134 * The :command:`project` command now sets variables
 135   :variable:`PROJECT_IS_TOP_LEVEL` and :variable:`<PROJECT-NAME>_IS_TOP_LEVEL`
 136   to indicate whether it was called in a top-level ``CMakeLists.txt`` file.
 137
 138 Variables
 139 ---------
 140
 141 * The :envvar:`CMAKE_TOOLCHAIN_FILE` environment variable was added to
 142   provide a default value for the :variable:`CMAKE_TOOLCHAIN_FILE` variable.
 143
 144 Properties
 145 ----------
 146
 147 * The :prop_dir:`IMPORTED_TARGETS` directory property was added to
 148   get a list of :ref:`Imported Targets` created in the current
 149   directory.
 150
 151 * The :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS <XCODE_EMBED_<type>>` target property
 152   was added to tell the :generator:`Xcode` generator to embed app extensions
 153   such as iMessage sticker packs.
 154   Aspects of the embedding can be customized with the
 155   :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_PATH <XCODE_EMBED_<type>>`,
 156   :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_CODE_SIGN_ON_COPY <XCODE_EMBED_<type>_CODE_SIGN_ON_COPY>` and
 157   :prop_tgt:`XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY <XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY>`
 158   properties.
 159
 160 Modules
 161 -------
 162
 163 * The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support
 164   the serial ``Fujitsu_SSL2`` and parallel ``Fujitsu_SSL2BLAMP`` libraries.
 165
 166 * The :module:`FindDevIL` module now provides imported targets.
 167
 168 * The :module:`FindIconv` module now has version support.
 169
 170 * The :module:`FindIntl` module now has version support.
 171
 172 * The :module:`FindMPI` module learned to support ``Fujitsu`` and
 173   ``FujitsuClang`` in both host and cross compiling modes.
 174
 175 * The :module:`FindMsys` module was added to find MSYS installations.
 176   Like :module:`FindCygwin`, it is used automatically by some other
 177   find modules to locate UNIX-style tools on Windows.
 178
 179 * The :module:`FindOpenMP` module learned to support ``Fujitsu`` and
 180   ``FujitsuClang``.
 181
 182 * The :module:`FindVulkan` module gained imported targets
 183   ``Vulkan::Headers`` and ``Vulkan::glslangValidator``.
 184
 185 * The :module:`UseJava` module command ``add_jar`` gained a ``RESOURCES``
 186   option to allow explicit naming of resources with non-optional namespace.
 187
 188 * The :module:`UseSWIG` module use now standard library naming conventions
 189   for the ``CSharp`` language. See policy :policy:`CMP0122`.
 190
 191 * The :module:`UseSWIG` module now supports using the ``swig`` tool to
 192   generate implicit dependencies with the :generator:`Xcode` generator.
 193
 194 Generator Expressions
 195 ---------------------
 196
 197 * A new :genex:`TARGET_RUNTIME_DLLS` generator expression was added.
 198
 199 CTest
 200 -----
 201
 202 * :manual:`ctest(1)` gained documentation for its ability to capture
 203   :ref:`Additional Test Measurements`.
 204
 205 * :manual:`ctest(1)` learned to recognize files attached to a test at run time.
 206   Previously it was only possible to attach files to tests at configure time
 207   by using the :prop_test:`ATTACHED_FILES` or
 208   :prop_test:`ATTACHED_FILES_ON_FAIL` test properties.
 209   See :ref:`Additional Test Measurements` for more information.
 210
 211 * :manual:`ctest(1)` gained a ``--output-junit`` option to write test results
 212   to a JUnit XML file.
 213
 214 * The :command:`ctest_build` command gained a ``PARALLEL_LEVEL`` option.
 215
 216 CPack
 217 -----
 218
 219 * The :cpack_gen:`CPack DragNDrop Generator` gained option
 220   :variable:`CPACK_DMG_FILESYSTEM` to control the ``.dmg`` filesystem.
 221
 222 * The :cpack_gen:`CPack IFW Generator` now supports hyphens in names
 223   given to :command:`cpack_ifw_configure_component` or
 224   :command:`cpack_ifw_configure_component_group` as ``DEPENDS`` or
 225   ``DEPENDENCIES`` arguments.  This requires QtIFW 3.1 or later.
 226
 227 * The :cpack_gen:`CPack NSIS Generator` gained a new
 228   :variable:`CPACK_NSIS_EXECUTABLE` variable to specify the ``makensis``
 229   executable to use instead of the default one.
 230
 231 * The :variable:`CPACK_CUSTOM_INSTALL_VARIABLES` variable was added to set
 232   variables in ``cmake_install.cmake`` script invocations made by CPack.
 233
 234 Deprecated and Removed Features
 235 ===============================
 236
 237 * Undocumented :variable:`CMAKE_SYSTEM_NAME` version-stripping behavior has
 238   been removed entirely. If it is set by a ``-D`` flag or by a
 239   :manual:`toolchain file <cmake-toolchains(7)>`, it is left unaltered,
 240   even if it still contains a version number.
 241   Similar :variable:`CMAKE_HOST_SYSTEM_NAME` version-stripping behavior,
 242   also undocumented, has been moved earlier, before :command:`project` or
 243   :command:`enable_language` is called.
 244
 245 * ``ARMClang`` cpu/arch compile and link flags are no longer added
 246   automatically based on the :variable:`CMAKE_SYSTEM_PROCESSOR`
 247   variable or the undocumented ``CMAKE_SYSTEM_ARCH`` variable.
 248   They must be specified explicitly.  See policy :policy:`CMP0123`.
 249
 250 Other Changes
 251 =============
 252
 253 * The :command:`find_file`, :command:`find_path`, :command:`find_program`,
 254   and :command:`find_library` commands handle cache variables in the same way
 255   regardless how they are defined. See policy :policy:`CMP0125` for details.
 256
 257 * The :command:`find_file`, :command:`find_path`, :command:`find_program`,
 258   and :command:`find_library` commands gained the option ``NO_CACHE`` to store
 259   find result in normal variable.
 260
 261 * The :command:`foreach` command now isolates loop variables in the loop scope.
 262   See policy :policy:`CMP0124` for details.
 263
 264 * The :command:`list` command's ``GET``, ``INSERT``, ``SUBLIST``, and
 265   ``REMOVE_AT`` subcommands now error with invalid (i.e., non-integer) values
 266   are given as any of their index arguments based on the setting of policy
 267   :policy:`CMP0121`.
 268
 269 * The :command:`set(CACHE)` command no longer removes a normal variable
 270   of the same name, if any. See policy :policy:`CMP0126`.
 271
 272 * :command:`target_link_libraries` calls referencing object libraries
 273   via the :genex:`TARGET_OBJECTS` generator expression now place the
 274   object files before all libraries on the link line, regardless of
 275   their specified order.  See documentation on
 276   :ref:`Linking Object Libraries via \$\<TARGET_OBJECTS\>` for details.
 277
 278 * The :ref:`Ninja Generators` now pass source files and include directories
 279   to the compiler using absolute paths.  This makes diagnostic messages and
 280   debug symbols more consistent, and matches the :ref:`Makefile Generators`.
 281
 282 * The :generator:`NMake Makefiles` generator now encodes the generated
 283   makefiles as UTF-8 with a BOM when using ``nmake`` from VS 9 or above.
 284
 285 * The :ref:`Visual Studio Generators` for VS 2010 and above now place
 286   per-source preprocessor definitions after target-wide preprocssor
 287   definitions.  This makes VS consistent with the :ref:`Ninja Generators`
 288   and the :ref:`Makefile Generators`.
 289
 290 * The precompiled binaries provided on
 291   `cmake.org <https://cmake.org/download/>`_ now support
 292   ``liblzma`` multi-threading.  See the :variable:`CPACK_THREADS` and
 293   :variable:`CPACK_ARCHIVE_THREADS` variables.
 294
 295 Updates
 296 =======
 297
 298 Changes made since CMake 3.21.0 include the following.
 299
 300 3.21.1
 301 ------
 302
 303 * The :generator:`Visual Studio 17 2022` generator is now based on
 304   "Visual Studio 2022 Preview 2".  Previously it was based on "Preview 1.1".
 305
 306 3.21.2
 307 ------
 308
 309 * ``CUDA`` targets with :prop_tgt:`CUDA_SEPARABLE_COMPILATION` enabled are now
 310   correctly generated in non-root directories.
 311
 312 * The :generator:`Visual Studio 17 2022` generator is now based on
 313   "Visual Studio 2022 Preview 3.1".  Previously it was based on "Preview 2".
 314
 315 3.21.3
 316 ------
 317
 318 * The :generator:`Visual Studio 17 2022` generator is now based on
 319   "Visual Studio 2022 Preview 4".  Previously it was based on "Preview 3.1".
 320
 321 * The AMD ROCm Platform ``hipcc`` compiler was identifed by CMake 3.21.0
 322   through 3.21.2 as a distinct compiler with id ``ROCMClang``.  This has
 323   been removed because it caused regressions.  Instead:
 324
 325   * ``hipcc`` may no longer be used as a ``HIP`` compiler because it
 326     interferes with flags CMake needs to pass to Clang.  Use Clang directly.
 327
 328   * ``hipcc`` may once again be used as a ``CXX`` compiler, and is treated as
 329     whatever compiler it selects underneath, as CMake 3.20 and below did.
 330
 331 3.21.4
 332 ------
 333
 334 * The :generator:`Visual Studio 17 2022` generator is now based on the
 335   "Visual Studio 2022" release candidates.  Previously it was based on
 336   preview versions.
 337
 338 3.21.5, 3.21.6
 339 --------------
 340
 341 These versions made no changes to documented features or interfaces.
 342 Some implementation updates were made to support ecosystem changes
 343 and/or fix regressions.