summaryrefslogtreecommitdiff
path: root/Help/release/3.20.rst
blob: f77304fcffdebcbba2dcbebf4bcfb576de1f68e5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
CMake 3.20 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.19 include the following.

New Features
============

Presets
-------

* :manual:`cmake-presets(7)` gained support for build and test presets.

Generators
----------

* :ref:`Makefile Generators`, for some toolchains, now use the compiler
  to extract implicit dependencies while compiling source files.

Languages
---------

* C++23 compiler modes may now be specified via the :prop_tgt:`CXX_STANDARD`,
  :prop_tgt:`CUDA_STANDARD`, or :prop_tgt:`OBJCXX_STANDARD` target properties,
  or via the :manual:`Compile Features <cmake-compile-features(7)>`
  functionality's ``cxx_std_23`` meta-feature.

* ``CUDA`` language support now works when ``nvcc`` is a symbolic link,
  for example due to a ``ccache`` or ``colornvcc`` wrapper script.

* The :envvar:`CUDAARCHS` environment variable was added for initializing
  :variable:`CMAKE_CUDA_ARCHITECTURES`. Useful in cases where the compiler
  default is unsuitable for the machine's GPU.

Compilers
---------

* The NVIDIA HPC SDK compilers are now supported with compiler id ``NVHPC``.

* The Intel oneAPI NextGen LLVM compilers are now supported with
  compiler id ``IntelLLVM``:

  * The ``icx``/``icpx`` C/C++ compilers on Linux, and the ``icx``
    C/C++ compiler on Windows, are fully supported as of oneAPI 2021.1.

  * The ``ifx`` Fortran compiler on Linux is supported as of oneAPI 2021.1.

  * The ``ifx`` Fortran compiler on Windows is not yet supported.

  The Intel oneAPI Classic compilers (``icc``, ``icpc``, and ``ifort``)
  continue to be supported with compiler id ``Intel``.

* Support was added for the IAR STM8 compiler.

Platforms
---------

* CMake's support for :ref:`Cross Compiling for Android`
  is now merged with the Android NDK's toolchain file.
  They now have similar behavior, though some variable names differ.
  User-facing changes include:

  - ``find_*`` functions will search NDK ABI / API specific paths by default.

  - The default :variable:`CMAKE_BUILD_TYPE` for Android is
    now ``RelWithDebInfo``.

  - The :variable:`CMAKE_ANDROID_NDK_VERSION` variable was added to
    report the version of the NDK.

File-Based API
--------------

* The :manual:`cmake-file-api(7)` gained a new "toolchains" object
  kind that describes the compiler used for each enabled language.

Commands
--------

* :command:`add_custom_command` and :command:`add_custom_target` now
  support :manual:`generator expressions <cmake-generator-expressions(7)>`
  in their ``OUTPUT`` and ``BYPRODUCTS`` options.

  Their ``COMMAND``, ``WORKING_DIRECTORY``, and ``DEPENDS`` options gained
  support for new generator expressions ``$<COMMAND_CONFIG:...>`` and
  ``$<OUTPUT_CONFIG:...>`` that control cross-config handling when using
  the :generator:`Ninja Multi-Config` generator.

* The :command:`add_custom_command` command gained ``DEPFILE`` support on
  :ref:`Makefile Generators`.

* The :command:`add_library` command previously prohibited imported object
  libraries when using potentially multi-architecture configurations.
  This mostly affected the :generator:`Xcode` generator, e.g. when targeting
  iOS or one of the other device platforms.  This restriction has now been
  removed.

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

* The :command:`configure_file` command gained ``USE_SOURCE_PERMISSIONS``
  and ``FILE_PERMISSIONS`` options to support copying of permissions of the
  source file and using specified permissions respectively.

* The :command:`file(GENERATE)` command gained a ``NEWLINE_STYLE`` option to
  specify how newlines are handled for the generated file.

* The :command:`file(GENERATE)` command gained ``NO_SOURCE_PERMISSIONS``,
  ``USE_SOURCE_PERMISSIONS``, and ``FILE_PERMISSIONS`` options for controlling
  the permissions of the generated file.

* The :command:`install(FILES)` command ``RENAME`` option learned to
  support :manual:`generator expressions <cmake-generator-expressions(7)>`.

* The :command:`target_include_directories` command gained a new option
  ``AFTER``.

* The :command:`target_sources` command now supports targets created
  by the :command:`add_custom_target` command.

* The :command:`try_run` command gained a ``WORKING_DIRECTORY`` option to
  set the working directory in which to run the compiled check executable.

Variables
---------

* The :variable:`CMAKE_<LANG>_BYTE_ORDER` variable was added to provide the
  target architecture byte order detected from the toolchain.

* The :variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY`,
  :variable:`CMAKE_LIBRARY_OUTPUT_DIRECTORY`, and
  :variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY` variables now support
  target-dependent generator expressions.

Properties
----------

* The :prop_tgt:`<LANG>_CLANG_TIDY` target property and the associated
  :variable:`CMAKE_<LANG>_CLANG_TIDY` variable learned to support
  the ``OBJC`` and ``OBJCXX`` languages.

* The :prop_tgt:`EXPORT_COMPILE_COMMANDS` target property was added
  for the associated :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable
  to allow for configuration of exporting compile commands per target.

* The :prop_sf:`GENERATED` source-file property is now visible
  from any directory scope, regardless of the scope in which it is set.
  See policy :policy:`CMP0118`.

* The :prop_tgt:`UNITY_BUILD_UNIQUE_ID` target property
  was added to support generation of an identifier that is
  unique per source file in unity builds.  It can help to
  resolve duplicate symbol problems with anonymous namespaces.

* The :prop_tgt:`WIN32_EXECUTABLE` target property now works with Clang
  on Windows.

* The :prop_tgt:`XCODE_EMBED_FRAMEWORKS <XCODE_EMBED_<type>>` target property
  was added to tell the :generator:`Xcode` generator to embed frameworks.
  Aspects of the embedding can be customized with the
  :prop_tgt:`XCODE_EMBED_FRAMEWORKS_PATH <XCODE_EMBED_<type>>`,
  :prop_tgt:`XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY`, and
  :prop_tgt:`XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY` target properties.

Modules
-------

* The :module:`ExternalData` module :command:`ExternalData_Add_Target`
  function gained a ``SHOW_PROGRESS <bool>`` option for controlling whether
  or not to show progress output during the build.

* The :module:`ExternalProject` module :command:`ExternalProject_Add` function
  gained a ``CONFIGURE_HANDLED_BY_BUILD`` option.  This can be used to make
  subsequent runs of the configure step be triggered by the build step when
  an external project dependency rebuilds instead of always re-running the
  configure step in such cases.

* The :module:`FindBoost` module gained a ``Boost_NO_WARN_NEW_VERSIONS``
  option to silence the warning about unknown dependencies for new
  Boost versions.

* The :module:`FindCUDAToolkit` module gained support for finding CUDA
  toolkits when ``nvcc`` is a symbolic link,
  for example due to a ``ccache`` or ``colornvcc`` wrapper script.

* The :module:`FindGDAL` module has been improved to document and mark as
  advanced its cache variables. There is a new ``FindGDAL_SKIP_GDAL_CONFIG``
  variable which may be used to skip over the ``gdal-config``-based search.
  Users may also set ``GDAL_ADDITIONAL_LIBRARY_VERSIONS`` to add additional
  versions to the library name search strategy.

* The :module:`FindIntl` module now provides an imported target.

* The :module:`FindOpenSSL` module learned to support a version range.

* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
  modules gained options controlling how unversioned interpreter names are
  searched.

* The :module:`UseJava` module ``add_jar()`` command's
  ``GENERATE_NATIVE_HEADERS`` feature gained options to export the
  generated target.

* The :module:`UseSWIG` module gained the capability, for
  :ref:`Makefile <Makefile Generators>` and :ref:`Ninja <Ninja Generators>`
  generators, to use the ``swig`` tool to generate implicit dependencies.

Autogen
-------

* The :ref:`Qt AUTOMOC` feature now works with per-config sources.

CTest
-----

* :manual:`ctest(1)` gained a ``--test-dir`` option to specify the directory
  in which to look for tests.

CPack
-----

* :module:`CPack` gained the :variable:`CPACK_THREADS` variable to
  control the number of threads used for parallelized operations,
  such as compressing the installer package.

* The :cpack_gen:`CPack DEB Generator` learned a new
  :variable:`CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS`
  variable to specify additional search directories for
  resolving private library dependencies when using
  ``dpkg-shlibdeps``.

* The :cpack_gen:`CPack IFW Generator` gained a new
  :variable:`CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST` variable to
  control visibility of the widget listing installer pages on the left side
  of the wizard. This feature available only since QtIFW 4.0.

* The :cpack_gen:`CPack NSIS Generator` gained new
  :variable:`CPACK_NSIS_BRANDING_TEXT` and
  :variable:`CPACK_NSIS_BRANDING_TEXT_TRIM_POSITION` variables to change
  the text at the bottom of the install window and change its trim position

* The :cpack_gen:`CPack NSIS Generator` now correctly handles Unicode
  characters.  If you want to have a :variable:`CPACK_RESOURCE_FILE_LICENSE`
  with UTF-8 characters, it needs to be encoded in UTF-8 BOM.

* The :cpack_gen:`CPack NuGet Generator` gained options:

  - :variable:`CPACK_NUGET_PACKAGE_ICON` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_ICON`
    allow package icons to be specified by local files.
  - :variable:`CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION` add
    support for specifying licenses recognized by the
    `Software Package Data Exchange`_ (SPDX).
  - :variable:`CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME` allow
    licenses to be specified by local files.
  - :variable:`CPACK_NUGET_PACKAGE_LANGUAGE` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LANGUAGE` allow the locale
    for a package to be specified, for example ``en_CA``.

.. _Software Package Data Exchange: https://spdx.org/

Deprecated and Removed Features
===============================

* The :manual:`cmake-server(7)` mode has been removed.
  Clients should use the :manual:`cmake-file-api(7)` instead.

* The :module:`WriteCompilerDetectionHeader` module has been deprecated
  via policy :policy:`CMP0120`.  Projects should be ported away from it.

* The :module:`TestBigEndian` module has been deprecated in favor
  of the :variable:`CMAKE_<LANG>_BYTE_ORDER` variable.

* The :module:`AddFileDependencies` module is deprecated.
  Port projects to use :command:`set_property` directly.

* The :cpack_gen:`CPack NuGet Generator` deprecated some variables to reflect
  changes in the NuGet specification:

  - :variable:`CPACK_NUGET_PACKAGE_ICONURL` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_ICONURL` have been deprecated;
    replace with a reference to a local icon file.
  - :variable:`CPACK_NUGET_PACKAGE_LICENSEURL` and
    :variable:`CPACK_NUGET_<compName>_PACKAGE_LICENSEURL` have been deprecated;
    replace with a reference to the project's license file or SPDX
    license expression.

Other Changes
=============

* When running :manual:`cmake(1)` to :ref:`Generate a Project Buildsystem`,
  unknown command-line arguments starting with a hyphen (``-``) are now
  rejected with an error.  Previously they were silently ignored.

* Source file extensions must now be explicit.
  See policy :policy:`CMP0115` for details.

* The :prop_sf:`LANGUAGE` source file property now forces compilation
  as the specified language.  See policy :policy:`CMP0119`.

* On AIX, installation of XCOFF executables and shared libraries
  no longer requires relinking to change the runtime search path
  from the build-tree RPATH to the install-tree RPATH.  CMake now
  edits the XCOFF binaries directly during installation, as has
  long been done on ELF platforms.

* With MSVC-like compilers the value of
  :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` no longer contains
  the ``/GR`` flag for runtime type information by default.
  See policy :policy:`CMP0117`.

* Ninja generators now transform the ``DEPFILE`` generated by an
  :command:`add_custom_command`. See policy :policy:`CMP0116` for details.

* The precompiled Linux binaries provided on
  `cmake.org <https://cmake.org/download/>`_ have changed their naming pattern
  to ``cmake-$ver-linux-$arch``, where ``$arch`` is either ``x86_64`` or
  ``aarch64``.

* The precompiled Windows binaries provided on
  `cmake.org <https://cmake.org/download/>`_ have changed their naming pattern
  to ``cmake-$ver-windows-$arch``, where ``$arch`` is either ``x86_64`` or
  ``i386``.

Updates
=======

Changes made since CMake 3.20.0 include the following.

3.20.1
------

* The :module:`FindIntl` module in CMake 3.20.0 added checks
  ``Intl_HAVE_GETTEXT_BUILTIN``, ``Intl_HAVE_DCGETTEXT_BUILTIN``,
  and ``Intl_IS_BUILTIN``, but they were not implemented correctly.
  These have been removed and replaced with a single ``Intl_IS_BUILT_IN``
  check, whose name is consistent with the :module:`FindIconv` module.

* The ``-rpath`` linker flag is now specified as supported on all Apple
  platforms, not just macOS.  The ``install_name_dir`` used for
  iOS, tvOS and watchOS should now default to ``@rpath`` instead of using
  a full absolute path and failing at runtime when the library or framework
  is embedded in an application bundle (see :prop_tgt:`XCODE_EMBED_<type>`).

3.20.2
------

* The Intel Classic 2021 compiler version numbers are now detected correctly
  as having major version 2021.  CMake 3.20.1 and below were not aware of a
  change to the identification macro version scheme made by Intel starting
  in version 2021, and detected the version as 20.2.

* The Intel oneAPI Fortran compiler is now identified as ``IntelLLVM``.
  The oneAPI 2021.1 Fortran compiler is missing an identification macro,
  so CMake 3.20.1 and below identified it as ``Intel``.  CMake now has
  a special case to recognize oneAPI 2021.1 Fortran as ``IntelLLVM``.
  The oneAPI 2021.2 Fortran compiler defines the proper identification
  macro and so is identified as ``IntelLLVM`` by all CMake 3.20 versions.