3.19.rst 11.5 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
17
* :manual:`cmake(1)` and :manual:`cmake-gui(1)` now recognize
  ``CMakePresets.json`` and ``CMakeUserPresets.json`` files.
18

19
20
Generators
----------
21

22
23
24
25
* 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.
26

27
28
29
30
31
32
* 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.
33

34
35
36
37
* 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.
38

39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
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.

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.
61

62
63
Command-Line
------------
64

65
66
67
68
* 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
69
70
  that can be used to create hardlinks between files.

71
72
73
74
75
76
77
78
79
80
81
82
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`.
83
84
85
86
87
88
89
90
91
92

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

* The :command:`cmake_path` command was added for operations on
  filesystem paths.

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

93
94
* The :command:`execute_process` command gained a ``COMMAND_ERROR_IS_FATAL``
  option to specify a fatal error.
95

96
97
* The :command:`file(ARCHIVE_CREATE)` command gained a ``COMPRESSION_LEVEL``
  option to specify the compression level.
98

99
100
* The :command:`file(CHMOD)` and :command:`file(CHMOD_RECURSE)` subcommands
  were added to set permissions of files and directories.
101

102
103
* The :command:`file(DOWNLOAD)` command ``<file>`` argument is now
  optional.  If it is not specified, the file is not saved.
104

105
106
* The :command:`file(GENERATE)` command gained a new ``TARGET`` keyword to
  support resolving target-dependent generator expressions.
107

108
109
* The :command:`file` gained sub-command `REAL_PATH` to compute a path with
  symlinks resolved.
110

111
* The :command:`find_package` command learned to handle a version range.
112

113
114
* The :command:`separate_arguments` command gained new ``PROGRAM`` option to
  search program.
115

116
117
118
119
* The :command:`set_property`, :command:`get_property`,
  and :command:`get_directory_property` commands' ``DIRECTORY``
  options now accept references to binary directory paths,
  such as the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
120

121
122
* The :command:`string` command gained set of new ``JSON`` sub commands
  to provide JSON parsing capabilities.
123

124
125
Variables
---------
126

127
128
129
* 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.
130

131
* The :variable:`CMAKE_MFC_FLAG` variable now supports generator expressions.
132

133
134
135
* 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.
136

137
138
139
140
141
142
* 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
----------
143

144
* The :prop_tgt:`EXCLUDE_FROM_ALL` target property now supports
145
146
  :manual:`generator expressions <cmake-generator-expressions(7)>`.

147
148
* The :prop_tgt:`OPTIMIZE_DEPENDENCIES` target property was added to
  avoid unnecessarily building dependencies for a static library.
149

150
151
152
153
* The :prop_tgt:`PCH_INSTANTIATE_TEMPLATES` target property was added to enable
  template instantiation in the precompiled header. This is enabled by default
  and offers a roughly 20% compile time improvement. Currently only supported
  by Clang 11.
154

155
156
* The :prop_tgt:`WIN32_EXECUTABLE` target property now supports
  :manual:`generator expressions <cmake-generator-expressions(7)>`.
157

158
159
Modules
-------
160

161
162
163
164
* 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.
165

166
* The :module:`CheckLinkerFlag` module now supports the ``CUDA`` language.
167

168
169
170
171
* 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.
172

173
174
175
176
* The :module:`CheckSourceRuns` module has been added to
  generalize :module:`CheckCSourceRuns` and
  :module:`CheckCXXSourceRuns` to more languages.
  It also supports the ``CUDA`` language.
177

178
* :module:`CMakePackageConfigHelpers` module learned to manage version range.
179

180
181
182
* 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.
183

184
185
186
187
* The :module:`FindPackageHandleStandardArgs` module learned to handle
  version range. It also gained the ``find_package_check_version()`` command to
  check the validity of a version against version-related arguments of
  :command:`find_package` command.
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205

* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
  modules gained the capability to manage a version range.

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

  * imported target ``SDL::SDL``,

  * result variables ``SDL_LIBRARIES`` and ``SDL_INCLUDE_DIRS``,

  * version variables ``SDL_VERSION``, ``SDL_VERSION_MAJOR``
    ``SDL_VERSION_MINOR``, and ``SDL_VERSION_PATCH``.

* :module:`FindSWIG` module gains the capability to manage a version range.

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

206
207
208
* 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.
209

210
211
* :module:`UseSWIG` module gains new source file properties ``OUTPUT_DIR`` and
  ``OUTFILE_DIR`` to manage output directories on per source basis.
212

213
214
CTest
-----
215

216
217
218
219
220
* :manual:`ctest(1)` now supports ``compute-sanitizer`` (``cuda-memcheck``) as
  ``CTEST_MEMORYCHECK_COMMAND``.  The different tools (memcheck, racecheck,
  synccheck, initcheck) supplied by ``compute-sanitizer`` can be selected by
  adding appropriate flags to the ``CTEST_MEMORYCHECK_COMMAND_OPTIONS``
  variable.  The default flags are ``--tool memcheck --leak-check full``.
221

222
223
CPack
-----
224

225
226
227
* CPack gained the :variable:`CPACK_PRE_BUILD_SCRIPTS`,
  :variable:`CPACK_POST_BUILD_SCRIPTS`, and :variable:`CPACK_PACKAGE_FILES`
  variables.
228

229
230
* The :cpack_gen:`CPack External Generator` gained the
  :variable:`CPACK_EXTERNAL_BUILT_PACKAGES` variable.
231

232
233
* The :cpack_gen:`CPack WIX Generator` gained a
  :variable:`CPACK_WIX_CUSTOM_XMLNS` option to specify custom XML namespaces.
234

235
236
Other
-----
237

238
239
240
* :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.
241

242
243
Deprecated and Removed Features
===============================
244

245
246
247
248
* 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.
249

250
251
252
253
254
* 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.
255

256
* macOS SDKs older than 10.5 are no longer supported.
257

258
259
* :manual:`cmake-gui(1)` now requires Qt5.
  Support for compiling with Qt4 has been removed.
260

261
262
263
* 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.
264

265
266
Documentation
=============
267

268
The following guides have been added:
269

270
271
* :guide:`IDE Integration Guide`
* :guide:`Importing and Exporting Guide`
272

273
274
Other Changes
=============
275

276
277
278
279
* 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.
280

281
282
283
* The :variable:`CMAKE_<LANG>_COMPILER` variable may now be used to
  store "mandatory" compiler flags like the :envvar:`CC` and other environment
  variables.
284

285
286
287
* 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.
288

289
290
* The :command:`find_program` command now requires permission to execute
  but not to read the file found.  See policy :policy:`CMP0109`.
291

292
293
* An imported target with a missing location now fails during generation
  if the location is used.  See policy :policy:`CMP0111`.
294

295
296
297
* 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`.
298

299
300
301
302
303
304
305
306
307
308
  - ``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``
309

310
311
* :ref:`Makefile Generators` no longer repeat custom commands from target
  dependencies.  See policy :policy:`CMP0113`.
312

313
314
* The :module:`ExternalProject` module handling of step target dependencies
  has been revised.  See policy :policy:`CMP0114`.
315

316
317
318
319
320
321
* 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.