1CMake 3.19 Release Notes
2************************
3
4.. only:: html
5
6  .. contents::
7
8Changes made since CMake 3.18 include the following.
9
10New Features
11============
12
13Presets
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
20Generators
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
40Languages
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
56Platforms
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
72File-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
81Command-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
90GUI
91---
92
93* The :manual:`CMake GUI <cmake-gui(1)>` now has an environment variable
94  editor.
95
96Commands
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
141Variables
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
161Properties
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
178Modules
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
239CTest
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
249CPack
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
262Other
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
269Deprecated 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
292Documentation
293=============
294
295The following guides have been added:
296
297* :guide:`IDE Integration Guide`
298* :guide:`Importing and Exporting Guide`
299
300Other 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
350Updates
351=======
352
353Changes made since CMake 3.19.0 include the following.
354
3553.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
3683.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
3893.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.
403
4043.19.4
405------
406
407* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM`
408  variable introduced in 3.19.0 previously worked only with the
409  :generator:`Visual Studio 14 2015` generator.  It has now been fixed to
410  work with :ref:`Visual Studio Generators` for later VS versions too.
411
4123.19.5
413------
414
415* When :prop_tgt:`IOS_INSTALL_COMBINED` is enabled and the :generator:`Xcode`
416  generator is used, it is now possible to initiate an install or package
417  creation by running ``cmake --install`` or ``cpack`` from the command line.
418  When using the Xcode new build system, these are the only supported methods
419  due to a limitation of Xcode.  Initiating these operations by building the
420  ``install`` or ``package`` targets in Xcode is only supported when using
421  the legacy build system.
422
423* The framework handling introduced in 3.19.0 as part of supporting Xcode's
424  *Link Binaries With Libraries* build phase broke the ability to switch
425  between device and simulator builds without reconfiguring.  That capability
426  has now been restored.
427
4283.19.6
429------
430
431* The :manual:`cmake-presets(7)` feature no longer allows comments in
432  ``CMakePresets.json`` or ``CMakeUserPresets.json`` files.
433  This was mistakenly allowed by the implementation in CMake 3.19.0 through
434  CMake 3.19.5, and was not documented.
435
4363.19.7
437------
438
439* With :ref:`Visual Studio Generators` for VS 2017 and higher, the
440  :variable:`CMAKE_GENERATOR_TOOLSET` field ``version=`` now accepts
441  three-component MSVC toolset versions such as ``14.28.29910``.
442  See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_VERSION` variable.
443