Help/release/3.19.rst

   1 CMake 3.19 Release Notes
   2 ************************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 3.18 include the following.
   9
  10 New Features
  11 ============
  12
  13 Presets
  14 -------
  15
  16 * :manual:`cmake(1)` and :manual:`cmake-gui(1)` now recognize
  17   ``CMakePresets.json`` and ``CMakeUserPresets.json`` files (see
  18   :manual:`cmake-presets(7)`).
  19
  20 Generators
  21 ----------
  22
  23 * The :generator:`Xcode` generator now uses the Xcode "new build system"
  24   when generating for Xcode 12.0 or higher.
  25   See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable.
  26   One may use ``-T buildsystem=1`` to switch to the legacy build system.
  27
  28 * The :generator:`Xcode` generator gained support for linking libraries and
  29   frameworks via the *Link Binaries With Libraries* build phase instead of
  30   always by embedding linker flags directly.  This behavior is controlled by
  31   a new :prop_tgt:`XCODE_LINK_BUILD_PHASE_MODE` target property, which is
  32   initialized by a new :variable:`CMAKE_XCODE_LINK_BUILD_PHASE_MODE`
  33   variable.
  34
  35 * The :ref:`Visual Studio Generators` for VS 2015 and above gained support
  36   for the Visual Studio Tools for Android.  One may now set
  37   :variable:`CMAKE_SYSTEM_NAME` to ``Android`` to generate ``.vcxproj`` files
  38   for the Android tools.
  39
  40 Languages
  41 ---------
  42
  43 * CMake learned to support ``ISPC`` as a first-class language that can be
  44   enabled via the :command:`project` and :command:`enable_language` commands.
  45   ``ISPC`` is currently supported by the :ref:`Makefile Generators`
  46   and the :generator:`Ninja` generator on Linux, macOS, and Windows
  47   using the Intel ISPC compiler.
  48
  49 * ``CUDA`` language support for Clang now includes:
  50
  51   - separable compilation (:prop_tgt:`CUDA_SEPARABLE_COMPILATION`), and
  52   - finding scattered toolkit installations when cross-compiling.
  53
  54 * ``CUDA`` language support now works on QNX.
  55
  56 Platforms
  57 ---------
  58
  59 * Apple Silicon is now supported (since CMake 3.19.2):
  60
  61   * The :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` is selected using ``uname -m``.
  62     Since this may vary based on CMake's own architecture and that of
  63     the invoking process tree, the :variable:`CMAKE_APPLE_SILICON_PROCESSOR`
  64     variable or :envvar:`CMAKE_APPLE_SILICON_PROCESSOR` environment
  65     variable may be set to specify a host architecture explicitly.
  66
  67   * If :variable:`CMAKE_OSX_ARCHITECTURES` is not set, CMake adds explicit
  68     flags to tell the compiler to build for the
  69     :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` so the toolchain does not
  70     have to guess based on the process tree's architecture.
  71
  72 File-Based API
  73 --------------
  74
  75 * The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
  76   been updated to 2.2.
  77
  78 * The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object
  79   gained a new ``languageStandard`` field in the ``compileGroups`` objects.
  80
  81 Command-Line
  82 ------------
  83
  84 * The :manual:`cmake(1)` command-line tool's ``--install`` mode gained a
  85   ``--default-directory-permissions`` option.
  86
  87 * :manual:`cmake(1)` gained a ``-E create_hardlink`` command-line tool
  88   that can be used to create hardlinks between files.
  89
  90 GUI
  91 ---
  92
  93 * The :manual:`CMake GUI <cmake-gui(1)>` now has an environment variable
  94   editor.
  95
  96 Commands
  97 --------
  98
  99 * The :command:`add_test` command now (officially) supports whitespace and
 100   other special characters in the name for the test it creates.
 101   See policy :policy:`CMP0110`.
 102
 103 * The :command:`cmake_language` command gained a ``DEFER`` mode to
 104   schedule command calls to occur at the end of processing a directory.
 105
 106 * The :command:`configure_file` command gained a ``NO_SOURCE_PERMISSIONS``
 107   option to suppress copying the input file's permissions to the output file.
 108
 109 * The :command:`execute_process` command gained a ``COMMAND_ERROR_IS_FATAL``
 110   option to specify a fatal error.
 111
 112 * The :command:`file(ARCHIVE_CREATE)` command gained a ``COMPRESSION_LEVEL``
 113   option to specify the compression level.
 114
 115 * The :command:`file(CHMOD)` and :command:`file(CHMOD_RECURSE)` subcommands
 116   were added to set permissions of files and directories.
 117
 118 * The :command:`file(DOWNLOAD)` command ``<file>`` argument is now
 119   optional.  If it is not specified, the file is not saved.
 120
 121 * The :command:`file(GENERATE)` command gained a new ``TARGET`` keyword to
 122   support resolving target-dependent generator expressions.
 123
 124 * The :command:`file` command gained a new ``REAL_PATH`` sub-command to
 125   compute a path with symlinks resolved.
 126
 127 * The :command:`find_package` command learned to handle a version range.
 128
 129 * The :command:`separate_arguments` command gained a new ``PROGRAM`` option.
 130   It allows the arguments to be treated as a program invocation and will
 131   resolve the executable to a full path if it can be found.
 132
 133 * The ``DIRECTORY`` option of the :command:`set_property`,
 134   :command:`get_property`, and :command:`get_directory_property` commands
 135   now accepts references to binary directory paths, such as the value of
 136   :variable:`CMAKE_CURRENT_BINARY_DIR`.
 137
 138 * The :command:`string` command gained a set of new ``JSON`` sub commands
 139   that provide JSON parsing capabilities.
 140
 141 Variables
 142 ---------
 143
 144 * The :variable:`CMAKE_CLANG_VFS_OVERLAY` variable was added to tell
 145   Clang to use a VFS overlay to support the Windows SDK when
 146   cross-compiling from hosts with case-sensitive filesystems.
 147
 148 * The :variable:`CMAKE_MFC_FLAG` variable now supports generator expressions.
 149
 150 * The :variable:`CMAKE_OPTIMIZE_DEPENDENCIES` variable was added to
 151   initialize the new :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property and
 152   avoid unnecessarily building dependencies for a static library.
 153
 154 * The :variable:`CMAKE_PCH_INSTANTIATE_TEMPLATES` variable was added to
 155   initialize the new :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property.
 156
 157 * The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable
 158   was added to tell the :ref:`Visual Studio Generators` what maximum
 159   version of the Windows SDK to choose.
 160
 161 Properties
 162 ----------
 163
 164 * The :prop_tgt:`EXCLUDE_FROM_ALL` target property now supports
 165   :manual:`generator expressions <cmake-generator-expressions(7)>`.
 166
 167 * The :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property was added to
 168   avoid unnecessarily building dependencies for a static library.
 169
 170 * The :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property was added to enable
 171   template instantiation in the precompiled header. This is enabled by default
 172   and may significantly improve compile times. Currently only supported for
 173   Clang (version 11 or later).
 174
 175 * The :prop_tgt:`WIN32_EXECUTABLE` target property now supports
 176   :manual:`generator expressions <cmake-generator-expressions(7)>`.
 177
 178 Modules
 179 -------
 180
 181 * The :module:`CheckCompilerFlag` module has been added to
 182   generalize :module:`CheckCCompilerFlag` and
 183   :module:`CheckCXXCompilerFlag` to more languages.
 184   It also supports the ``CUDA`` and ``ISPC`` languages.
 185
 186 * The :module:`CheckLinkerFlag` module now supports the ``CUDA`` language.
 187
 188 * The :module:`CheckSourceCompiles` module has been added to
 189   generalize :module:`CheckCSourceCompiles` and
 190   :module:`CheckCXXSourceCompiles` to more languages.
 191   It also supports the ``CUDA`` and ``ISPC`` languages.
 192
 193 * The :module:`CheckSourceRuns` module has been added to
 194   generalize :module:`CheckCSourceRuns` and
 195   :module:`CheckCXXSourceRuns` to more languages.
 196   It also supports the ``CUDA`` language.
 197
 198 * The :module:`CMakePackageConfigHelpers` module gained support for version
 199   ranges.
 200
 201 * The :module:`FindCUDAToolkit` module gained support for finding CUDA
 202   toolkits that do not contain ``nvcc``, as well as for finding scattered
 203   toolkit installations when cross-compiling.
 204
 205 * The :module:`FindPackageHandleStandardArgs` module learned to handle
 206   version ranges. It also gained the ``find_package_check_version()`` command
 207   to check the validity of a version against version-related arguments of
 208   :command:`find_package` command.
 209
 210 * The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
 211   modules gained the ability to handle a version range.
 212
 213 * The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
 214   modules provide, respectively, the variable ``Python3_LINK_OPTIONS``,
 215   ``Python2_LINK_OPTIONS`` and ``Python_LINK_OPTIONS`` for link options.
 216
 217 * The :module:`FindSDL` module now provides:
 218
 219   * An imported target ``SDL::SDL``.
 220
 221   * Result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``.
 222
 223   * Version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``,
 224     ``SDL_VERSION_MINOR``, and ``SDL_VERSION_PATCH``.
 225
 226 * The :module:`FindSWIG` module gained the ability to handle a version range.
 227
 228 * The :module:`FindTIFF` module gained a ``CXX`` component to
 229   find the ``tiffxx`` library containing C++ bindings.
 230
 231 * The :module:`FindVulkan` module now provides a ``Vulkan::glslc`` imported
 232   target and associated ``Vulkan_GLSLC_EXECUTABLE`` variable which contain
 233   the path to the GLSL SPIR-V compiler.
 234
 235 * The :module:`UseSWIG` module gained support for new source file properties
 236   ``OUTPUT_DIR`` and ``OUTFILE_DIR`` to manage output directories on a
 237   per-source basis.
 238
 239 CTest
 240 -----
 241
 242 * :manual:`ctest(1)` now supports the CUDA ``compute-sanitizer`` checker
 243   (previously known as ``cuda-memcheck``) as the ``CTEST_MEMORYCHECK_COMMAND``.
 244   The different tools (``memcheck``, ``racecheck``, ``synccheck`` and
 245   ``initcheck``) supported by ``compute-sanitizer`` can be selected by
 246   adding appropriate flags to the ``CTEST_MEMORYCHECK_COMMAND_OPTIONS``
 247   variable.  The default flags are ``--tool memcheck --leak-check full``.
 248
 249 CPack
 250 -----
 251
 252 * CPack gained the :variable:`CPACK_PRE_BUILD_SCRIPTS`,
 253   :variable:`CPACK_POST_BUILD_SCRIPTS`, and :variable:`CPACK_PACKAGE_FILES`
 254   variables.
 255
 256 * The :cpack_gen:`CPack External Generator` gained the
 257   :variable:`CPACK_EXTERNAL_BUILT_PACKAGES` variable.
 258
 259 * The :cpack_gen:`CPack WIX Generator` gained a
 260   :variable:`CPACK_WIX_CUSTOM_XMLNS` option to specify custom XML namespaces.
 261
 262 Other
 263 -----
 264
 265 * :ref:`Interface Libraries` may now have source files added via
 266   :command:`add_library` or :command:`target_sources`.  Those
 267   with sources will be generated as part of the build system.
 268
 269 Deprecated and Removed Features
 270 ===============================
 271
 272 * Compatibility with versions of CMake older than 2.8.12 is now deprecated
 273   and will be removed from a future version.  Calls to
 274   :command:`cmake_minimum_required` or :command:`cmake_policy` that set
 275   the policy version to an older value now issue a deprecation diagnostic.
 276
 277 * An explicit deprecation diagnostic was added for policy ``CMP0071``
 278   (``CMP0071`` and below were already deprecated).
 279   The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
 280   of all policies are deprecated and that projects should port to the
 281   NEW behaviors.
 282
 283 * macOS SDKs older than 10.5 are no longer supported.
 284
 285 * :manual:`cmake-gui(1)` now requires Qt5.
 286   Support for compiling with Qt4 has been removed.
 287
 288 * The :manual:`cmake(1)` command-line option ``--warn-unused-vars`` has
 289   been removed and is now silently ignored.  The option has not worked
 290   correctly since CMake 3.3.
 291
 292 Documentation
 293 =============
 294
 295 The following guides have been added:
 296
 297 * :guide:`IDE Integration Guide`
 298 * :guide:`Importing and Exporting Guide`
 299
 300 Other Changes
 301 =============
 302
 303 * Building for macOS will now use the latest SDK available on the system,
 304   unless the user has explicitly chosen a SDK using
 305   :variable:`CMAKE_OSX_SYSROOT`.  The deployment target or system macOS
 306   version will not affect the choice of SDK.
 307
 308 * The :variable:`CMAKE_<LANG>_COMPILER` variable may now be used to
 309   store "mandatory" compiler flags like the :envvar:`CC` and other environment
 310   variables.
 311
 312 * The :variable:`CMAKE_<LANG>_FLAGS_INIT` variable will now be considered
 313   during the compiler identification check if other sources like
 314   :variable:`CMAKE_<LANG>_FLAGS` or :envvar:`CFLAGS` are not set.
 315
 316 * The :command:`find_program` command now requires permission to execute
 317   but not to read the file found.  See policy :policy:`CMP0109`.
 318
 319 * An imported target missing its location property fails during generation
 320   if the location is used.  See policy :policy:`CMP0111`.
 321
 322 * The following target-based generator expressions that query for directory or
 323   file name components no longer add a dependency on the evaluated target.
 324   See policy :policy:`CMP0112`.
 325
 326   - ``TARGET_FILE_DIR``
 327   - ``TARGET_LINKER_FILE_BASE_NAME``
 328   - ``TARGET_LINKER_FILE_NAME``
 329   - ``TARGET_LINKER_FILE_DIR``
 330   - ``TARGET_SONAME_FILE_NAME``
 331   - ``TARGET_SONAME_FILE_DIR``
 332   - ``TARGET_PDB_FILE_NAME``
 333   - ``TARGET_PDB_FILE_DIR``
 334   - ``TARGET_BUNDLE_DIR``
 335   - ``TARGET_BUNDLE_CONTENT_DIR``
 336
 337 * :ref:`Makefile Generators` no longer repeat custom commands from target
 338   dependencies.  See policy :policy:`CMP0113`.
 339
 340 * The :module:`ExternalProject` module handling of step target dependencies
 341   has been revised.  See policy :policy:`CMP0114`.
 342
 343 * The :prop_tgt:`OSX_ARCHITECTURES` target property is now respected
 344   for the ``ASM`` language.
 345
 346 * If ``CUDA`` compiler detection fails with user-specified
 347   :variable:`CMAKE_CUDA_ARCHITECTURES` or
 348   :variable:`CMAKE_CUDA_HOST_COMPILER`, an error is raised.
 349
 350 Updates
 351 =======
 352
 353 Changes made since CMake 3.19.0 include the following.
 354
 355 3.19.1
 356 ------
 357
 358 * CMake 3.19.0 compiles source files with the :prop_sf:`LANGUAGE`
 359   property by passing an explicit language flag such as ``-x c``.
 360   This is consistent with the property's documented meaning that
 361   the source file is written in the specified language.  However,
 362   it can break projects that were using the property only to
 363   cause the specified language's compiler to be used.  This has
 364   been reverted to restore behavior from CMake 3.18 and below.
 365
 366 * CUDA 11.1 support for Clang.
 367
 368 3.19.2
 369 ------
 370
 371 * The precompiled macOS binary provided on ``cmake.org`` is now a
 372   universal binary with ``x86_64`` and ``arm64`` architectures.
 373   It requires macOS 10.10 or newer.
 374   The package file naming pattern has been changed from
 375   ``cmake-$ver-Darwin-x86_64`` to ``cmake-$ver-macos-universal``.
 376
 377 * Apple Silicon host architecture selection support was updated.
 378   CMake 3.19.0 and 3.19.1 always chose ``arm64`` as the host architecture.
 379   CMake 3.19.2 returns to using ``uname -m`` as CMake 3.18 and below did.
 380   Since this may vary based on CMake's own architecture and that of
 381   the invoking process tree, the :variable:`CMAKE_APPLE_SILICON_PROCESSOR`
 382   variable or :envvar:`CMAKE_APPLE_SILICON_PROCESSOR` environment
 383   variable may be set to specify a host architecture explicitly.
 384
 385 * The :variable:`CMAKE_ISPC_HEADER_SUFFIX` variable and corresponding
 386   :prop_tgt:`ISPC_HEADER_SUFFIX` target property were added to control
 387   the header suffix used by ``ISPC`` compiler generated headers.
 388
 389 3.19.3
 390 ------
 391
 392 * A precompiled Linux ``aarch64`` binary is now provided on ``cmake.org``.
 393
 394 * Two precompiled macOS binaries are now provided on ``cmake.org``:
 395
 396   * The naming pattern ``cmake-$ver-macos-universal`` is a universal
 397     binary with ``x86_64`` and ``arm64`` architectures.  It requires
 398     macOS 10.13 or newer.
 399
 400   * The naming pattern ``cmake-$ver-macos10.10-universal`` is a universal
 401     binary with ``x86_64`` and ``arm64`` architectures.  It requires
 402     macOS 10.10 or newer.