Help/release/3.20.rst

   1 CMake 3.20 Release Notes
   2 ************************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 3.19 include the following.
   9
  10 New Features
  11 ============
  12
  13 Presets
  14 -------
  15
  16 * :manual:`cmake-presets(7)` gained support for build and test presets.
  17
  18 Generators
  19 ----------
  20
  21 * :ref:`Makefile Generators`, for some toolchains, now use the compiler
  22   to extract implicit dependencies while compiling source files.
  23
  24 Languages
  25 ---------
  26
  27 * C++23 compiler modes may now be specified via the :prop_tgt:`CXX_STANDARD`,
  28   :prop_tgt:`CUDA_STANDARD`, or :prop_tgt:`OBJCXX_STANDARD` target properties,
  29   or via the :manual:`Compile Features <cmake-compile-features(7)>`
  30   functionality's ``cxx_std_23`` meta-feature.
  31
  32 * ``CUDA`` language support now works when ``nvcc`` is a symbolic link,
  33   for example due to a ``ccache`` or ``colornvcc`` wrapper script.
  34
  35 * The :envvar:`CUDAARCHS` environment variable was added for initializing
  36   :variable:`CMAKE_CUDA_ARCHITECTURES`. Useful in cases where the compiler
  37   default is unsuitable for the machine's GPU.
  38
  39 Compilers
  40 ---------
  41
  42 * The NVIDIA HPC SDK compilers are now supported with compiler id ``NVHPC``.
  43
  44 * The Intel oneAPI NextGen LLVM compilers are now supported with
  45   compiler id ``IntelLLVM``:
  46
  47   * The ``icx``/``icpx`` C/C++ compilers on Linux, and the ``icx``
  48     C/C++ compiler on Windows, are fully supported as of oneAPI 2021.1.
  49
  50   * The ``ifx`` Fortran compiler on Linux is supported as of oneAPI 2021.1.
  51
  52   * The ``ifx`` Fortran compiler on Windows is not yet supported.
  53
  54   The Intel oneAPI Classic compilers (``icc``, ``icpc``, and ``ifort``)
  55   continue to be supported with compiler id ``Intel``.
  56
  57 * Support was added for the IAR STM8 compiler.
  58
  59 Platforms
  60 ---------
  61
  62 * CMake's support for :ref:`Cross Compiling for Android`
  63   is now merged with the Android NDK's toolchain file.
  64   They now have similar behavior, though some variable names differ.
  65   User-facing changes include:
  66
  67   - ``find_*`` functions will search NDK ABI / API specific paths by default.
  68
  69   - The default :variable:`CMAKE_BUILD_TYPE` for Android is
  70     now ``RelWithDebInfo``.
  71
  72   - The :variable:`CMAKE_ANDROID_NDK_VERSION` variable was added to
  73     report the version of the NDK.
  74
  75 File-Based API
  76 --------------
  77
  78 * The :manual:`cmake-file-api(7)` gained a new "toolchains" object
  79   kind that describes the compiler used for each enabled language.
  80
  81 Commands
  82 --------
  83
  84 * :command:`add_custom_command` and :command:`add_custom_target` now
  85   support :manual:`generator expressions <cmake-generator-expressions(7)>`
  86   in their ``OUTPUT`` and ``BYPRODUCTS`` options.
  87
  88   Their ``COMMAND``, ``WORKING_DIRECTORY``, and ``DEPENDS`` options gained
  89   support for new generator expressions ``$<COMMAND_CONFIG:...>`` and
  90   ``$<OUTPUT_CONFIG:...>`` that control cross-config handling when using
  91   the :generator:`Ninja Multi-Config` generator.
  92
  93 * The :command:`add_custom_command` command gained ``DEPFILE`` support on
  94   :ref:`Makefile Generators`.
  95
  96 * The :command:`add_library` command previously prohibited imported object
  97   libraries when using potentially multi-architecture configurations.
  98   This mostly affected the :generator:`Xcode` generator, e.g. when targeting
  99   iOS or one of the other device platforms.  This restriction has now been
 100   removed.
 101
 102 * The :command:`cmake_path` command was added for operations on
 103   filesystem paths.
 104
 105 * The :command:`configure_file` command gained ``USE_SOURCE_PERMISSIONS``
 106   and ``FILE_PERMISSIONS`` options to support copying of permissions of the
 107   source file and using specified permissions respectively.
 108
 109 * The :command:`file(GENERATE)` command gained a ``NEWLINE_STYLE`` option to
 110   specify how newlines are handled for the generated file.
 111
 112 * The :command:`file(GENERATE)` command gained ``NO_SOURCE_PERMISSIONS``,
 113   ``USE_SOURCE_PERMISSIONS``, and ``FILE_PERMISSIONS`` options for controlling
 114   the permissions of the generated file.
 115
 116 * The :command:`install(FILES)` command ``RENAME`` option learned to
 117   support :manual:`generator expressions <cmake-generator-expressions(7)>`.
 118
 119 * The :command:`target_include_directories` command gained a new option
 120   ``AFTER``.
 121
 122 * The :command:`target_sources` command now supports targets created
 123   by the :command:`add_custom_target` command.
 124
 125 * The :command:`try_run` command gained a ``WORKING_DIRECTORY`` option to
 126   set the working directory in which to run the compiled check executable.
 127
 128 Variables
 129 ---------
 130
 131 * The :variable:`CMAKE_<LANG>_BYTE_ORDER` variable was added to provide the
 132   target architecture byte order detected from the toolchain.
 133
 134 * The :variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY`,
 135   :variable:`CMAKE_LIBRARY_OUTPUT_DIRECTORY`, and
 136   :variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY` variables now support
 137   target-dependent generator expressions.
 138
 139 Properties
 140 ----------
 141
 142 * The :prop_tgt:`<LANG>_CLANG_TIDY` target property and the associated
 143   :variable:`CMAKE_<LANG>_CLANG_TIDY` variable learned to support
 144   the ``OBJC`` and ``OBJCXX`` languages.
 145
 146 * The :prop_tgt:`EXPORT_COMPILE_COMMANDS` target property was added
 147   for the associated :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable
 148   to allow for configuration of exporting compile commands per target.
 149
 150 * The :prop_sf:`GENERATED` source-file property is now visible
 151   from any directory scope, regardless of the scope in which it is set.
 152   See policy :policy:`CMP0118`.
 153
 154 * The :prop_tgt:`UNITY_BUILD_UNIQUE_ID` target property
 155   was added to support generation of an identifier that is
 156   unique per source file in unity builds.  It can help to
 157   resolve duplicate symbol problems with anonymous namespaces.
 158
 159 * The :prop_tgt:`WIN32_EXECUTABLE` target property now works with Clang
 160   on Windows.
 161
 162 * The :prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` target property
 163   was added to tell the :generator:`Xcode` generator to embed frameworks.
 164   Aspects of the embedding can be customized with the
 165   :prop_tgt:`XCODE_EMBED_FRAMEWORKS_PATH <XCODE_EMBED_<type>>`,
 166   :prop_tgt:`XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY`, and
 167   :prop_tgt:`XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY` target properties.
 168
 169 Modules
 170 -------
 171
 172 * The :module:`ExternalData` module :command:`ExternalData_Add_Target`
 173   function gained a ``SHOW_PROGRESS <bool>`` option for controlling whether
 174   or not to show progress output during the build.
 175
 176 * The :module:`ExternalProject` module :command:`ExternalProject_Add` function
 177   gained a ``CONFIGURE_HANDLED_BY_BUILD`` option.  This can be used to make
 178   subsequent runs of the configure step be triggered by the build step when
 179   an external project dependency rebuilds instead of always re-running the
 180   configure step in such cases.
 181
 182 * The :module:`FindBoost` module gained a ``Boost_NO_WARN_NEW_VERSIONS``
 183   option to silence the warning about unknown dependencies for new
 184   Boost versions.
 185
 186 * The :module:`FindCUDAToolkit` module gained support for finding CUDA
 187   toolkits when ``nvcc`` is a symbolic link,
 188   for example due to a ``ccache`` or ``colornvcc`` wrapper script.
 189
 190 * The :module:`FindGDAL` module has been improved to document and mark as
 191   advanced its cache variables. There is a new ``FindGDAL_SKIP_GDAL_CONFIG``
 192   variable which may be used to skip over the ``gdal-config``-based search.
 193   Users may also set ``GDAL_ADDITIONAL_LIBRARY_VERSIONS`` to add additional
 194   versions to the library name search strategy.
 195
 196 * The :module:`FindIntl` module now provides an imported target.
 197
 198 * The :module:`FindOpenSSL` module learned to support a version range.
 199
 200 * The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
 201   modules gained options controlling how unversioned interpreter names are
 202   searched.
 203
 204 * The :module:`UseJava` module ``add_jar()`` command's
 205   ``GENERATE_NATIVE_HEADERS`` feature gained options to export the
 206   generated target.
 207
 208 * The :module:`UseSWIG` module gained the capability, for
 209   :ref:`Makefile <Makefile Generators>` and :ref:`Ninja <Ninja Generators>`
 210   generators, to use the ``swig`` tool to generate implicit dependencies.
 211
 212 Autogen
 213 -------
 214
 215 * The :ref:`Qt AUTOMOC` feature now works with per-config sources.
 216
 217 CTest
 218 -----
 219
 220 * :manual:`ctest(1)` gained a :option:`--test-dir <ctest --test-dir>`
 221   option to specify the directory in which to look for tests.
 222
 223 CPack
 224 -----
 225
 226 * :module:`CPack` gained the :variable:`CPACK_THREADS` variable to
 227   control the number of threads used for parallelized operations,
 228   such as compressing the installer package.
 229
 230 * The :cpack_gen:`CPack DEB Generator` learned a new
 231   :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS`
 232   variable to specify additional search directories for
 233   resolving private library dependencies when using
 234   ``dpkg-shlibdeps``.
 235
 236 * The :cpack_gen:`CPack IFW Generator` gained a new
 237   :variable:`CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST` variable to
 238   control visibility of the widget listing installer pages on the left side
 239   of the wizard. This feature available only since QtIFW 4.0.
 240
 241 * The :cpack_gen:`CPack NSIS Generator` gained new
 242   :variable:`CPACK_NSIS_BRANDING_TEXT` and
 243   :variable:`CPACK_NSIS_BRANDING_TEXT_TRIM_POSITION` variables to change
 244   the text at the bottom of the install window and change its trim position
 245
 246 * The :cpack_gen:`CPack NSIS Generator` now correctly handles Unicode
 247   characters.  If you want to have a :variable:`CPACK_RESOURCE_FILE_LICENSE`
 248   with UTF-8 characters, it needs to be encoded in UTF-8 BOM.
 249
 250 * The :cpack_gen:`CPack NuGet Generator` gained options:
 251
 252   - :variable:`CPACK_NUGET_PACKAGE_ICON` and
 253     :variable:`CPACK_NUGET_<compName>_PACKAGE_ICON`
 254     allow package icons to be specified by local files.
 255   - :variable:`CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` and
 256     :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION` add
 257     support for specifying licenses recognized by the
 258     `Software Package Data Exchange`_ (SPDX).
 259   - :variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` and
 260     :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME` allow
 261     licenses to be specified by local files.
 262   - :variable:`CPACK_NUGET_PACKAGE_LANGUAGE` and
 263     :variable:`CPACK_NUGET_<compName>_PACKAGE_LANGUAGE` allow the locale
 264     for a package to be specified, for example ``en_CA``.
 265
 266 .. _Software Package Data Exchange: https://spdx.dev/
 267
 268 Deprecated and Removed Features
 269 ===============================
 270
 271 * The :manual:`cmake-server(7)` mode has been removed.
 272   Clients should use the :manual:`cmake-file-api(7)` instead.
 273
 274 * The :module:`WriteCompilerDetectionHeader` module has been deprecated
 275   via policy :policy:`CMP0120`.  Projects should be ported away from it.
 276
 277 * The :module:`TestBigEndian` module has been deprecated in favor
 278   of the :variable:`CMAKE_<LANG>_BYTE_ORDER` variable.
 279
 280 * The :module:`AddFileDependencies` module is deprecated.
 281   Port projects to use :command:`set_property` directly.
 282
 283 * The :cpack_gen:`CPack NuGet Generator` deprecated some variables to reflect
 284   changes in the NuGet specification:
 285
 286   - :variable:`CPACK_NUGET_PACKAGE_ICONURL` and
 287     :variable:`CPACK_NUGET_<compName>_PACKAGE_ICONURL` have been deprecated;
 288     replace with a reference to a local icon file.
 289   - :variable:`CPACK_NUGET_PACKAGE_LICENSEURL` and
 290     :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSEURL` have been deprecated;
 291     replace with a reference to the project's license file or SPDX
 292     license expression.
 293
 294 Other Changes
 295 =============
 296
 297 * When running :manual:`cmake(1)` to :ref:`Generate a Project Buildsystem`,
 298   unknown command-line arguments starting with a hyphen (``-``) are now
 299   rejected with an error.  Previously they were silently ignored.
 300
 301 * Source file extensions must now be explicit.
 302   See policy :policy:`CMP0115` for details.
 303
 304 * The :prop_sf:`LANGUAGE` source file property now forces compilation
 305   as the specified language.  See policy :policy:`CMP0119`.
 306
 307 * On AIX, installation of XCOFF executables and shared libraries
 308   no longer requires relinking to change the runtime search path
 309   from the build-tree RPATH to the install-tree RPATH.  CMake now
 310   edits the XCOFF binaries directly during installation, as has
 311   long been done on ELF platforms.
 312
 313 * With MSVC-like compilers the value of
 314   :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` no longer contains
 315   the ``/GR`` flag for runtime type information by default.
 316   See policy :policy:`CMP0117`.
 317
 318 * Ninja generators now transform the ``DEPFILE`` generated by an
 319   :command:`add_custom_command`. See policy :policy:`CMP0116` for details.
 320
 321 * The precompiled Linux binaries provided on
 322   `cmake.org <https://cmake.org/download/>`_ have changed their naming pattern
 323   to ``cmake-$ver-linux-$arch``, where ``$arch`` is either ``x86_64`` or
 324   ``aarch64``.
 325
 326 * The precompiled Windows binaries provided on
 327   `cmake.org <https://cmake.org/download/>`_ have changed their naming pattern
 328   to ``cmake-$ver-windows-$arch``, where ``$arch`` is either ``x86_64`` or
 329   ``i386``.
 330
 331 Updates
 332 =======
 333
 334 Changes made since CMake 3.20.0 include the following.
 335
 336 3.20.1
 337 ------
 338
 339 * The :module:`FindIntl` module in CMake 3.20.0 added checks
 340   ``Intl_HAVE_GETTEXT_BUILTIN``, ``Intl_HAVE_DCGETTEXT_BUILTIN``,
 341   and ``Intl_IS_BUILTIN``, but they were not implemented correctly.
 342   These have been removed and replaced with a single ``Intl_IS_BUILT_IN``
 343   check, whose name is consistent with the :module:`FindIconv` module.
 344
 345 * The ``-rpath`` linker flag is now specified as supported on all Apple
 346   platforms, not just macOS.  The ``install_name_dir`` used for
 347   iOS, tvOS and watchOS should now default to ``@rpath`` instead of using
 348   a full absolute path and failing at runtime when the library or framework
 349   is embedded in an application bundle (see :prop_tgt:`XCODE_EMBED_<type>`).
 350
 351 3.20.2
 352 ------
 353
 354 * The Intel Classic 2021 compiler version numbers are now detected correctly
 355   as having major version 2021.  CMake 3.20.1 and below were not aware of a
 356   change to the identification macro version scheme made by Intel starting
 357   in version 2021, and detected the version as 20.2.
 358
 359 * The Intel oneAPI Fortran compiler is now identified as ``IntelLLVM``.
 360   The oneAPI 2021.1 Fortran compiler is missing an identification macro,
 361   so CMake 3.20.1 and below identified it as ``Intel``.  CMake now has
 362   a special case to recognize oneAPI 2021.1 Fortran as ``IntelLLVM``.
 363   The oneAPI 2021.2 Fortran compiler defines the proper identification
 364   macro and so is identified as ``IntelLLVM`` by all CMake 3.20 versions.
 365
 366 3.20.3, 3.20.4, 3.20.5, 3.20.6
 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.