summaryrefslogtreecommitdiffstats
path: root/Help/release/3.15.rst
blob: 148c2d2cc293614d0eeabdeab333f2022064addd (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
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
CMake 3.15 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.14 include the following.

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

Generators
----------

* The :generator:`Xcode` generator now supports per-target schemes.
  See the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable and
  :prop_tgt:`XCODE_GENERATE_SCHEME` target property.

* The :generator:`Green Hills MULTI` generator has been updated:

  * It now supports the :command:`add_custom_command` and
    :command:`add_custom_target` commands.

  * It is now available on Linux.

Languages
---------

* Preliminary support for the ``Swift`` language was added to the
  :generator:`Ninja` generator:

  * Use the :envvar:`SWIFTC` environment variable to specify a compiler.

  * The :prop_tgt:`Swift_DEPENDENCIES_FILE` target property and
    :prop_sf:`Swift_DEPENDENCIES_FILE` source file property were added
    to customize dependency files.

  * The :prop_tgt:`Swift_MODULE_NAME` target property was added to
    customize the Swift module name.

  * The :prop_sf:`Swift_DIAGNOSTICS_FILE` source property was added to
    indicate where to write the serialised Swift diagnostics.

  The Swift support is experimental, not considered stable, and may change
  in future releases of CMake.

Compilers
---------

* The ``Clang`` compiler variant on Windows that targets the MSVC ABI
  but has a GNU-like command line is now supported.

* Support for the Clang-based ARM compiler was added with compiler id
  ``ARMClang``.

* Support was added for the IAR compiler architectures Renesas RX,
  RL78, RH850 and Texas Instruments MSP430.

* Support was added for the IAR compilers built for Linux (IAR BuildLx).

Command-Line
------------

* The :envvar:`CMAKE_GENERATOR` environment variable was added
  to specify a default generator to use when :manual:`cmake(1)` is
  run without a ``-G`` option.  Additionally, environment variables
  :envvar:`CMAKE_GENERATOR_PLATFORM`, :envvar:`CMAKE_GENERATOR_TOOLSET`,
  and :envvar:`CMAKE_GENERATOR_INSTANCE` were created to configure
  the generator.

* The :manual:`cmake(1)` ``--build`` tool ``--target`` parameter gained support
  for multiple targets, e.g. ``cmake --build . --target Library1 Library2``.
  It now also has a short form ``-t`` alias, e.g.
  ``cmake --build . -t Library1 Library2``.

* The :manual:`cmake(1)` command gained a new ``--install`` option.
  This may be used after building a project to run installation without
  using the generated build system or the native build tool.

* The :manual:`cmake(1)` command learned a new CLI option ``--loglevel``.

* The :manual:`cmake(1)` ``-E remove_directory`` command-line tool learned
  to support removing multiple directories.

* The :manual:`cmake(1)` ``-E tar`` tool has been improved:

  * It now continues adding files to an archive even if some of the files
    are not readable.  This behavior is more consistent with the
    classic ``tar`` tool.

  * It now parses all flags, and if an invalid flag was provided, a
    warning is issued.

  * It now displays an error if no action flag was specified, along with a
    list of possible actions: ``t`` (list), ``c`` (create) or ``x`` (extract).

  * It now supports extracting (``-x``) or listing (``-t``) only specific
    files or directories.

  * It now supports Zstandard compression with a ``--zstd`` option.
    Zstandard was designed to give a compression ratio comparable to that
    of the DEFLATE (zip) algorithm, but faster, especially for decompression.

Commands
--------

* The :command:`add_custom_command` and :command:`add_custom_target` commands
  gained a new ``JOB_POOL`` option that works with the :generator:`Ninja`
  generator to set the pool variable on the build statement.

* The :command:`add_library` command ``ALIAS`` option learned to support
  import libraries of the ``UNKNOWN`` type.

* The :command:`cmake_parse_arguments` command gained an additional
  ``<prefix>_KEYWORDS_MISSING_VALUES`` output variable to report
  keyword arguments that were given by the caller with no values.

* The :command:`execute_process` command gained a ``COMMAND_ECHO`` option
  and supporting :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable
  to enable echoing of the command-line string before execution.

* The :command:`file(INSTALL)` command learned a new argument,
  ``FOLLOW_SYMLINK_CHAIN``, which can be used to recursively resolve and
  install symlinks.

* :command:`list` learned new sub-commands:
  ``PREPEND``, ``POP_FRONT`` and ``POP_BACK``.

* The :command:`message` command learned new types:
  ``NOTICE``, ``VERBOSE``, ``DEBUG`` and ``TRACE``.

* The :command:`string` learned a new sub-command ``REPEAT``.

Variables
---------

* The :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable and corresponding
  :prop_tgt:`CROSSCOMPILING_EMULATOR` target property learned to support
  arguments to the emulator.

* The :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable was added to tell
  :command:`find_package` calls to look for a package configuration
  file first even if a find module is available.

* The :variable:`CMAKE_FRAMEWORK` variable was added to initialize the
  :prop_tgt:`FRAMEWORK` property on all targets.

* The :variable:`CMAKE_VS_JUST_MY_CODE_DEBUGGING` variable and
  :prop_tgt:`VS_JUST_MY_CODE_DEBUGGING` target property were added to
  enable the Just My Code feature of the Visual Studio Debugger when
  compiling with MSVC cl 19.05 and higher.

* The :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` variable and
  :prop_tgt:`MSVC_RUNTIME_LIBRARY` target property were introduced to
  select the runtime library used by compilers targeting the MSVC ABI.
  See policy :policy:`CMP0091`.

* The :variable:`CMAKE_PROJECT_INCLUDE` and
  :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables were added to allow
  injection of custom code at the sites of :command:`project` calls
  without knowing the project name a priori.

Properties
----------

* The :prop_tgt:`ADDITIONAL_CLEAN_FILES` target property and
  :prop_dir:`ADDITIONAL_CLEAN_FILES` directory property were added.
  They allow to register additional files that should be removed during
  the clean stage.

* The :prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` properties
  may now be set on :ref:`Interface Libraries`. The headers specified by those
  properties can be installed using the :command:`install(TARGETS)` command by
  passing the ``PUBLIC_HEADER`` and ``PRIVATE_HEADER`` arguments respectively.

* The :prop_tgt:`VS_PACKAGE_REFERENCES` target property was added to
  tell :ref:`Visual Studio Generators` to add references to ``nuget``
  packages.

* The :prop_tgt:`VS_PROJECT_IMPORT` target property was added to allow
  managed Visual Studio project files to import external ``.props`` files.

* The :prop_tgt:`VS_NO_SOLUTION_DEPLOY` target property was added to
  tell :ref:`Visual Studio Generators` whether to deploy an artifact
  to the WinCE or Windows Phone target device.

Modules
-------

* The :module:`FindBoost` module was reworked to expose a more consistent
  user experience between its "Config" and "Module" modes and with other
  find modules in general.

  * A new imported target ``Boost::headers`` is now defined (same
    as ``Boost::boost``).

  * New output variables ``Boost_VERSION_MACRO``,
    ``Boost_VERSION_MAJOR``, ``Boost_VERSION_MINOR``,
    ``Boost_VERSION_PATCH``, and ``Boost_VERSION_COUNT``
    were added.

  * The ``QUIET`` argument passed to :command:`find_package` is no
    longer ignored in config mode.  Note that the CMake package shipped with
    Boost ``1.70.0`` ignores the ``QUIET`` argument passed to
    :command:`find_package`.  This is fixed in the next Boost release.

  * The input switch ``Boost_DETAILED_FAILURE_MSG`` was removed.

  * ``Boost_VERSION`` now reports the version in ``x.y.z``
    format in module mode.  See policy :policy:`CMP0093`.

* The :module:`FindCups` module now provides imported targets.

* The :module:`FindEnvModules` module was added to use Lua- and TCL-based
  environment modules in :ref:`CTest Scripts <CTest Script>`.

* The :module:`FindGLEW` module now provides an interface more consistent
  with what upstream GLEW provides in its own CMake package files.

* The :module:`FindPkgConfig` now populates :prop_tgt:`INTERFACE_LINK_OPTIONS`
  property of imported targets with other (non-library) linker flags.

* The :module:`FindPostgreSQL` module learned to find debug and release
  variants separately.

* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
  gained additional lookup strategies and controls, and a new default.
  See policy :policy:`CMP0094`.

* Modules :module:`FindPython`, :module:`FindPython2` and :module:`FindPython3`
  gain a new target (respectively ``Python::Module``, ``Python2::Module``
  and ``Python3::Module``) which can be used to develop Python modules.

* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
  gain capability to control how virtual environments are handled.

* The :module:`UseSWIG` module learned to manage alternate library names
  by passing ``-interface <library_name>`` for ``python`` language or
  ``-dllimport <library_name>`` for ``CSharp`` language to the ``SWIG``
  compiler.

Generator Expressions
---------------------

* The :manual:`generator expressions <cmake-generator-expressions(7)>`
  ``C_COMPILER_ID``, ``CXX_COMPILER_ID``, ``CUDA_COMPILER_ID``,
  ``Fortran_COMPILER_ID``, ``COMPILE_LANGUAGE``, ``COMPILE_LANG_AND_ID``, and
  ``PLATFORM_ID`` learned to support matching one value from a comma-separated
  list.

* The ``$<CUDA_COMPILER_ID:...>`` and ``$<CUDA_COMPILER_VERSION:...>``
  :manual:`generator expressions <cmake-generator-expressions(7)>` were added.

* The ``$<COMPILE_LANG_AND_ID:...>`` generator expression was introduced to
  allow specification of compile options for target files based on the
  :variable:`CMAKE_<LANG>_COMPILER_ID` and :prop_sf:`LANGUAGE` of
  each source file.

* A ``$<FILTER:list,INCLUDE|EXCLUDE,regex>``
  :manual:`generator expression <cmake-generator-expressions(7)>`
  has been added.

* A ``$<REMOVE_DUPLICATES:list>``
  :manual:`generator expression <cmake-generator-expressions(7)>`
  has been added.

* The ``$<SHELL_PATH:...>`` :manual:`generator expression
  <cmake-generator-expressions(7)>` gained support for a list of paths.

* New ``$<TARGET_FILE*>`` :manual:`generator expressions
  <cmake-generator-expressions(7)>` were added to retrieve the prefix, base
  name, and suffix of the file names of various artifacts:

  * ``$<TARGET_FILE_PREFIX:...>``
  * ``$<TARGET_FILE_BASE_NAME:...>``
  * ``$<TARGET_FILE_SUFFIX:...>``
  * ``$<TARGET_LINKER_FILE_PREFIX:...>``
  * ``$<TARGET_LINKER_FILE_BASE_NAME:...>``
  * ``$<TARGET_LINKER_FILE_SUFFIX:...>``
  * ``$<TARGET_PDB_FILE_BASE_NAME:...>``

* The ``$<TARGET_OBJECTS:...>`` :manual:`generator expression
  <cmake-generator-expressions(7)>` is now supported on ``SHARED``,
  ``STATIC``, ``MODULE`` libraries and executables.

CTest
-----

* The :command:`ctest_submit` command learned a new option: ``BUILD_ID``.
  This can be used to store the ID assigned to this build by CDash to a
  variable.

* The :command:`ctest_update` command learned to honor a new variable:
  :variable:`CTEST_UPDATE_VERSION_OVERRIDE`. This can be used to specify
  the current version of your source tree rather than using the update
  command to discover the current version that is checked out.

CPack
-----

* The :cpack_gen:`CPack IFW Generator` gained a new
  :variable:`CPACK_IFW_PACKAGE_STYLE_SHEET` variable to customize the
  installer stylesheet.

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

* The :manual:`cmake-server(7)` mode has been deprecated and will be
  removed from a future version of CMake.  Please port clients to use
  the :manual:`cmake-file-api(7)` instead.

* The :prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES` directory property is now
  deprecated.  Use the :prop_dir:`ADDITIONAL_CLEAN_FILES` directory property
  instead.

* The variable :variable:`CMAKE_AUTOMOC_RELAXED_MODE` is considered
  deprecated.  Support still exists but will be removed in future versions.

* The :command:`export(PACKAGE)` command now does nothing unless
  enabled via :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY`.
  See policy :policy:`CMP0090`.

* The :generator:`Xcode` generator now requires at least Xcode 5.

* An explicit deprecation diagnostic was added for policy ``CMP0066``
  (``CMP0065`` 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.

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

* CMake learned how to compile C++14 with the IBM AIX XL compiler
  and the SunPro compiler and to compile C++20 with the AppleClang compiler.

* With MSVC-like compilers the value of :variable:`CMAKE_<LANG>_FLAGS`
  no longer contains warning flags like ``/W3`` by default.
  See policy :policy:`CMP0092`.

* IBM Clang-based XL compilers that define ``__ibmxl__`` now use the
  compiler id ``XLClang`` instead of ``XL``.  See policy :policy:`CMP0089`.

* The :command:`file(REMOVE)` and :command:`file(REMOVE_RECURSE)` commands
  were changed to ignore empty arguments with a warning instead of treating
  them as a relative path and removing the contents of the current directory.

Updates
=======

Changes made since CMake 3.15.0 include the following.

3.15.1
------

* In CMake 3.15.0 support for the GNU-like ``Clang`` compiler targeting the
  MSVC ABI implemented :variable:`CMAKE_CXX_STANDARD` values 98 and 11 using
  the corresponding ``-std=`` flags.  However, these modes do not work with
  the MSVC standard library.  Therefore CMake 3.15.1 passes C++14 standard
  flags even for C++98 and C++11.  This is consistent with MSVC itself which
  always runs in a mode aware of C++14.

* Preliminary Swift support added in 3.15.0 has been updated.

3.15.2
------

* In CMake 3.15.0 and 3.15.1 the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG`
  variable caused the :command:`find_package` command to fail on a missing
  package even without the ``REQUIRED`` option.  This has been fixed.

3.15.3
------

* ``CrayPrgEnv`` compiler wrapper support has been updated for the 19.06
  release of the Cray Programming Environment for which the default linking
  mode on XC Cray systems is now dynamic instead of static.

3.15.4
------

* In CMake 3.15.0 through 3.15.3, the :prop_dir:`EXCLUDE_FROM_ALL`
  directory property was regressed from pre-3.14 behavior and caused
  targets within the directory to be excluded even from its own "all".
  This has been fixed.