3.19.rst 16.1 KB
Newer Older
1 2 3 4 5 6 7 8 9
CMake 3.19 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.18 include the following.

10 11
New Features
============
12

13 14
Presets
-------
15

16
* :manual:`cmake(1)` and :manual:`cmake-gui(1)` now recognize
17 18
  ``CMakePresets.json`` and ``CMakeUserPresets.json`` files (see
  :manual:`cmake-presets(7)`).
19

20 21
Generators
----------
22

23 24 25 26
* The :generator:`Xcode` generator now uses the Xcode "new build system"
  when generating for Xcode 12.0 or higher.
  See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable.
  One may use ``-T buildsystem=1`` to switch to the legacy build system.
27

28 29 30 31 32 33
* The :generator:`Xcode` generator gained support for linking libraries and
  frameworks via the *Link Binaries With Libraries* build phase instead of
  always by embedding linker flags directly.  This behavior is controlled by
  a new :prop_tgt:`XCODE_LINK_BUILD_PHASE_MODE` target property, which is
  initialized by a new :variable:`CMAKE_XCODE_LINK_BUILD_PHASE_MODE`
  variable.
34

35 36 37 38
* The :ref:`Visual Studio Generators` for VS 2015 and above gained support
  for the Visual Studio Tools for Android.  One may now set
  :variable:`CMAKE_SYSTEM_NAME` to ``Android`` to generate ``.vcxproj`` files
  for the Android tools.
39

40 41 42 43 44 45 46 47 48 49 50 51 52 53
Languages
---------

* CMake learned to support ``ISPC`` as a first-class language that can be
  enabled via the :command:`project` and :command:`enable_language` commands.
  ``ISPC`` is currently supported by the :ref:`Makefile Generators`
  and the :generator:`Ninja` generator on Linux, macOS, and Windows
  using the Intel ISPC compiler.

* ``CUDA`` language support for Clang now includes:

  - separable compilation (:prop_tgt:`CUDA_SEPARABLE_COMPILATION`), and
  - finding scattered toolkit installations when cross-compiling.

54 55
* ``CUDA`` language support now works on QNX.

56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
Platforms
---------

* Apple Silicon is now supported (since CMake 3.19.2):

  * The :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` is selected using ``uname -m``.
    Since this may vary based on CMake's own architecture and that of
    the invoking process tree, the :variable:`CMAKE_APPLE_SILICON_PROCESSOR`
    variable or :envvar:`CMAKE_APPLE_SILICON_PROCESSOR` environment
    variable may be set to specify a host architecture explicitly.

  * If :variable:`CMAKE_OSX_ARCHITECTURES` is not set, CMake adds explicit
    flags to tell the compiler to build for the
    :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` so the toolchain does not
    have to guess based on the process tree's architecture.

72 73 74 75 76 77 78 79
File-Based API
--------------

* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
  been updated to 2.2.

* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object
  gained a new ``languageStandard`` field in the ``compileGroups`` objects.
80

81 82
Command-Line
------------
83

84 85 86 87
* The :manual:`cmake(1)` command-line tool's ``--install`` mode gained a
  ``--default-directory-permissions`` option.

* :manual:`cmake(1)` gained a ``-E create_hardlink`` command-line tool
88 89
  that can be used to create hardlinks between files.

90 91 92 93 94 95 96 97 98 99 100 101
GUI
---

* The :manual:`CMake GUI <cmake-gui(1)>` now has an environment variable
  editor.

Commands
--------

* The :command:`add_test` command now (officially) supports whitespace and
  other special characters in the name for the test it creates.
  See policy :policy:`CMP0110`.
102 103 104 105 106 107 108

* The :command:`cmake_language` command gained a ``DEFER`` mode to
  schedule command calls to occur at the end of processing a directory.

* The :command:`configure_file` command gained a ``NO_SOURCE_PERMISSIONS``
  option to suppress copying the input file's permissions to the output file.

109 110
* The :command:`execute_process` command gained a ``COMMAND_ERROR_IS_FATAL``
  option to specify a fatal error.
111

112 113
* The :command:`file(ARCHIVE_CREATE)` command gained a ``COMPRESSION_LEVEL``
  option to specify the compression level.
114

115 116
* The :command:`file(CHMOD)` and :command:`file(CHMOD_RECURSE)` subcommands
  were added to set permissions of files and directories.
117

118 119
* The :command:`file(DOWNLOAD)` command ``<file>`` argument is now
  optional.  If it is not specified, the file is not saved.
120

121 122
* The :command:`file(GENERATE)` command gained a new ``TARGET`` keyword to
  support resolving target-dependent generator expressions.
123

124 125
* The :command:`file` command gained a new ``REAL_PATH`` sub-command to
  compute a path with symlinks resolved.
126

127
* The :command:`find_package` command learned to handle a version range.
128

129 130 131
* The :command:`separate_arguments` command gained a new ``PROGRAM`` option.
  It allows the arguments to be treated as a program invocation and will
  resolve the executable to a full path if it can be found.
132

133 134 135 136
* The ``DIRECTORY`` option of the :command:`set_property`,
  :command:`get_property`, and :command:`get_directory_property` commands
  now accepts references to binary directory paths, such as the value of
  :variable:`CMAKE_CURRENT_BINARY_DIR`.
137

138 139
* The :command:`string` command gained a set of new ``JSON`` sub commands
  that provide JSON parsing capabilities.
140

141 142
Variables
---------
143

144 145 146
* The :variable:`CMAKE_CLANG_VFS_OVERLAY` variable was added to tell
  Clang to use a VFS overlay to support the Windows SDK when
  cross-compiling from hosts with case-sensitive filesystems.
147

148
* The :variable:`CMAKE_MFC_FLAG` variable now supports generator expressions.
149

150 151 152
* The :variable:`CMAKE_OPTIMIZE_DEPENDENCIES` variable was added to
  initialize the new :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property and
  avoid unnecessarily building dependencies for a static library.
153

154 155 156
* The :variable:`CMAKE_PCH_INSTANTIATE_TEMPLATES` variable was added to
  initialize the new :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property.

157 158 159 160 161 162
* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM` variable
  was added to tell the :ref:`Visual Studio Generators` what maximum
  version of the Windows SDK to choose.

Properties
----------
163

164
* The :prop_tgt:`EXCLUDE_FROM_ALL` target property now supports
165 166
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

167 168
* The :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property was added to
  avoid unnecessarily building dependencies for a static library.
169

170 171
* The :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property was added to enable
  template instantiation in the precompiled header. This is enabled by default
172 173
  and may significantly improve compile times. Currently only supported for
  Clang (version 11 or later).
174

175 176
* The :prop_tgt:`WIN32_EXECUTABLE` target property now supports
  :manual:`generator expressions <cmake-generator-expressions(7)>`.
177

178 179
Modules
-------
180

181 182 183 184
* The :module:`CheckCompilerFlag` module has been added to
  generalize :module:`CheckCCompilerFlag` and
  :module:`CheckCXXCompilerFlag` to more languages.
  It also supports the ``CUDA`` and ``ISPC`` languages.
185

186
* The :module:`CheckLinkerFlag` module now supports the ``CUDA`` language.
187

188 189 190 191
* The :module:`CheckSourceCompiles` module has been added to
  generalize :module:`CheckCSourceCompiles` and
  :module:`CheckCXXSourceCompiles` to more languages.
  It also supports the ``CUDA`` and ``ISPC`` languages.
192

193 194 195 196
* The :module:`CheckSourceRuns` module has been added to
  generalize :module:`CheckCSourceRuns` and
  :module:`CheckCXXSourceRuns` to more languages.
  It also supports the ``CUDA`` language.
197

198 199
* The :module:`CMakePackageConfigHelpers` module gained support for version
  ranges.
200

201 202 203
* The :module:`FindCUDAToolkit` module gained support for finding CUDA
  toolkits that do not contain ``nvcc``, as well as for finding scattered
  toolkit installations when cross-compiling.
204

205
* The :module:`FindPackageHandleStandardArgs` module learned to handle
206 207
  version ranges. It also gained the ``find_package_check_version()`` command
  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 214 215 216
* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
  modules provide, respectively, the variable ``Python3_LINK_OPTIONS``,
  ``Python2_LINK_OPTIONS`` and ``Python_LINK_OPTIONS`` for link options.

217 218
* The :module:`FindSDL` module now provides:

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 225
    ``SDL_VERSION_MINOR``, and ``SDL_VERSION_PATCH``.

226
* The :module:`FindSWIG` module gained the ability to handle a version range.
227 228 229 230

* The :module:`FindTIFF` module gained a ``CXX`` component to
  find the ``tiffxx`` library containing C++ bindings.

231 232 233
* The :module:`FindVulkan` module now provides a ``Vulkan::glslc`` imported
  target and associated ``Vulkan_GLSLC_EXECUTABLE`` variable which contain
  the path to the GLSL SPIR-V compiler.
234

235 236 237
* The :module:`UseSWIG` module gained support for new source file properties
  ``OUTPUT_DIR`` and ``OUTFILE_DIR`` to manage output directories on a
  per-source basis.
238

239 240
CTest
-----
241

242 243 244 245
* :manual:`ctest(1)` now supports the CUDA ``compute-sanitizer`` checker
  (previously known as ``cuda-memcheck``) as the ``CTEST_MEMORYCHECK_COMMAND``.
  The different tools (``memcheck``, ``racecheck``, ``synccheck`` and
  ``initcheck``) supported by ``compute-sanitizer`` can be selected by
246 247
  adding appropriate flags to the ``CTEST_MEMORYCHECK_COMMAND_OPTIONS``
  variable.  The default flags are ``--tool memcheck --leak-check full``.
248

249 250
CPack
-----
251

252 253 254
* CPack gained the :variable:`CPACK_PRE_BUILD_SCRIPTS`,
  :variable:`CPACK_POST_BUILD_SCRIPTS`, and :variable:`CPACK_PACKAGE_FILES`
  variables.
255

256 257
* The :cpack_gen:`CPack External Generator` gained the
  :variable:`CPACK_EXTERNAL_BUILT_PACKAGES` variable.
258

259 260
* The :cpack_gen:`CPack WIX Generator` gained a
  :variable:`CPACK_WIX_CUSTOM_XMLNS` option to specify custom XML namespaces.
261

262 263
Other
-----
264

265 266 267
* :ref:`Interface Libraries` may now have source files added via
  :command:`add_library` or :command:`target_sources`.  Those
  with sources will be generated as part of the build system.
268

269 270
Deprecated and Removed Features
===============================
271

272 273 274 275
* Compatibility with versions of CMake older than 2.8.12 is now deprecated
  and will be removed from a future version.  Calls to
  :command:`cmake_minimum_required` or :command:`cmake_policy` that set
  the policy version to an older value now issue a deprecation diagnostic.
276

277 278 279 280 281
* An explicit deprecation diagnostic was added for policy ``CMP0071``
  (``CMP0071`` and below were already deprecated).
  The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
  of all policies are deprecated and that projects should port to the
  NEW behaviors.
282

283
* macOS SDKs older than 10.5 are no longer supported.
284

285 286
* :manual:`cmake-gui(1)` now requires Qt5.
  Support for compiling with Qt4 has been removed.
287

288 289 290
* The :manual:`cmake(1)` command-line option ``--warn-unused-vars`` has
  been removed and is now silently ignored.  The option has not worked
  correctly since CMake 3.3.
291

292 293
Documentation
=============
294

295
The following guides have been added:
296

297 298
* :guide:`IDE Integration Guide`
* :guide:`Importing and Exporting Guide`
299

300 301
Other Changes
=============
302

303 304 305 306
* Building for macOS will now use the latest SDK available on the system,
  unless the user has explicitly chosen a SDK using
  :variable:`CMAKE_OSX_SYSROOT`.  The deployment target or system macOS
  version will not affect the choice of SDK.
307

308 309 310
* The :variable:`CMAKE_<LANG>_COMPILER` variable may now be used to
  store "mandatory" compiler flags like the :envvar:`CC` and other environment
  variables.
311

312 313 314
* The :variable:`CMAKE_<LANG>_FLAGS_INIT` variable will now be considered
  during the compiler identification check if other sources like
  :variable:`CMAKE_<LANG>_FLAGS` or :envvar:`CFLAGS` are not set.
315

316 317
* The :command:`find_program` command now requires permission to execute
  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 323 324
* The following target-based generator expressions that query for directory or
  file name components no longer add a dependency on the evaluated target.
  See policy :policy:`CMP0112`.
325

326 327 328 329 330 331 332 333 334 335
  - ``TARGET_FILE_DIR``
  - ``TARGET_LINKER_FILE_BASE_NAME``
  - ``TARGET_LINKER_FILE_NAME``
  - ``TARGET_LINKER_FILE_DIR``
  - ``TARGET_SONAME_FILE_NAME``
  - ``TARGET_SONAME_FILE_DIR``
  - ``TARGET_PDB_FILE_NAME``
  - ``TARGET_PDB_FILE_DIR``
  - ``TARGET_BUNDLE_DIR``
  - ``TARGET_BUNDLE_CONTENT_DIR``
336

337 338
* :ref:`Makefile Generators` no longer repeat custom commands from target
  dependencies.  See policy :policy:`CMP0113`.
339

340 341
* The :module:`ExternalProject` module handling of step target dependencies
  has been revised.  See policy :policy:`CMP0114`.
342

343 344 345 346 347 348
* The :prop_tgt:`OSX_ARCHITECTURES` target property is now respected
  for the ``ASM`` language.

* If ``CUDA`` compiler detection fails with user-specified
  :variable:`CMAKE_CUDA_ARCHITECTURES` or
  :variable:`CMAKE_CUDA_HOST_COMPILER`, an error is raised.
349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364

Updates
=======

Changes made since CMake 3.19.0 include the following.

3.19.1
------

* CMake 3.19.0 compiles source files with the :prop_sf:`LANGUAGE`
  property by passing an explicit language flag such as ``-x c``.
  This is consistent with the property's documented meaning that
  the source file is written in the specified language.  However,
  it can break projects that were using the property only to
  cause the specified language's compiler to be used.  This has
  been reverted to restore behavior from CMake 3.18 and below.
Raul Tambre's avatar
Raul Tambre committed
365 366

* CUDA 11.1 support for Clang.
367 368 369 370 371 372 373 374 375

3.19.2
------

* The precompiled macOS binary provided on ``cmake.org`` is now a
  universal binary with ``x86_64`` and ``arm64`` architectures.
  It requires macOS 10.10 or newer.
  The package file naming pattern has been changed from
  ``cmake-$ver-Darwin-x86_64`` to ``cmake-$ver-macos-universal``.
376 377 378 379 380 381 382 383

* Apple Silicon host architecture selection support was updated.
  CMake 3.19.0 and 3.19.1 always chose ``arm64`` as the host architecture.
  CMake 3.19.2 returns to using ``uname -m`` as CMake 3.18 and below did.
  Since this may vary based on CMake's own architecture and that of
  the invoking process tree, the :variable:`CMAKE_APPLE_SILICON_PROCESSOR`
  variable or :envvar:`CMAKE_APPLE_SILICON_PROCESSOR` environment
  variable may be set to specify a host architecture explicitly.
384 385 386 387

* The :variable:`CMAKE_ISPC_HEADER_SUFFIX` variable and corresponding
  :prop_tgt:`ISPC_HEADER_SUFFIX` target property were added to control
  the header suffix used by ``ISPC`` compiler generated headers.
388 389 390 391 392

3.19.3
------

* A precompiled Linux ``aarch64`` binary is now provided on ``cmake.org``.
393 394 395 396 397 398 399 400 401 402

* Two precompiled macOS binaries are now provided on ``cmake.org``:

  * The naming pattern ``cmake-$ver-macos-universal`` is a universal
    binary with ``x86_64`` and ``arm64`` architectures.  It requires
    macOS 10.13 or newer.

  * The naming pattern ``cmake-$ver-macos10.10-universal`` is a universal
    binary with ``x86_64`` and ``arm64`` architectures.  It requires
    macOS 10.10 or newer.
403 404 405 406 407 408 409 410

3.19.4
------

* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM`
  variable introduced in 3.19.0 previously worked only with the
  :generator:`Visual Studio 14 2015` generator.  It has now been fixed to
  work with :ref:`Visual Studio Generators` for later VS versions too.
411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426

3.19.5
------

* When :prop_tgt:`IOS_INSTALL_COMBINED` is enabled and the :generator:`Xcode`
  generator is used, it is now possible to initiate an install or package
  creation by running ``cmake --install`` or ``cpack`` from the command line.
  When using the Xcode new build system, these are the only supported methods
  due to a limitation of Xcode.  Initiating these operations by building the
  ``install`` or ``package`` targets in Xcode is only supported when using
  the legacy build system.

* The framework handling introduced in 3.19.0 as part of supporting Xcode's
  *Link Binaries With Libraries* build phase broke the ability to switch
  between device and simulator builds without reconfiguring.  That capability
  has now been restored.
427 428 429 430 431 432 433 434

3.19.6
------

* The :manual:`cmake-presets(7)` feature no longer allows comments in
  ``CMakePresets.json`` or ``CMakeUserPresets.json`` files.
  This was mistakenly allowed by the implementation in CMake 3.19.0 through
  CMake 3.19.5, and was not documented.