1CMake 3.15 Release Notes
2************************
3
4.. only:: html
5
6  .. contents::
7
8Changes made since CMake 3.14 include the following.
9
10New Features
11============
12
13Generators
14----------
15
16* The :generator:`Xcode` generator now supports per-target schemes.
17  See the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable and
18  :prop_tgt:`XCODE_GENERATE_SCHEME` target property.
19
20* The :generator:`Green Hills MULTI` generator has been updated:
21
22  * It now supports the :command:`add_custom_command` and
23    :command:`add_custom_target` commands.
24
25  * It is now available on Linux.
26
27Languages
28---------
29
30* Preliminary support for the ``Swift`` language was added to the
31  :generator:`Ninja` generator:
32
33  * Use the :envvar:`SWIFTC` environment variable to specify a compiler.
34
35  * The :prop_tgt:`Swift_DEPENDENCIES_FILE` target property and
36    :prop_sf:`Swift_DEPENDENCIES_FILE` source file property were added
37    to customize dependency files.
38
39  * The :prop_tgt:`Swift_MODULE_NAME` target property was added to
40    customize the Swift module name.
41
42  * The :prop_sf:`Swift_DIAGNOSTICS_FILE` source property was added to
43    indicate where to write the serialized Swift diagnostics.
44
45  The Swift support is experimental, not considered stable, and may change
46  in future releases of CMake.
47
48Compilers
49---------
50
51* The ``Clang`` compiler variant on Windows that targets the MSVC ABI
52  but has a GNU-like command line is now supported.
53
54* Support for the Clang-based ARM compiler was added with compiler id
55  ``ARMClang``.
56
57* Support was added for the IAR compiler architectures Renesas RX,
58  RL78, RH850 and Texas Instruments MSP430.
59
60* Support was added for the IAR compilers built for Linux (IAR BuildLx).
61
62Command-Line
63------------
64
65* The :envvar:`CMAKE_GENERATOR` environment variable was added
66  to specify a default generator to use when :manual:`cmake(1)` is
67  run without a ``-G`` option.  Additionally, environment variables
68  :envvar:`CMAKE_GENERATOR_PLATFORM`, :envvar:`CMAKE_GENERATOR_TOOLSET`,
69  and :envvar:`CMAKE_GENERATOR_INSTANCE` were created to configure
70  the generator.
71
72* The :manual:`cmake(1)` ``--build`` tool ``--target`` parameter gained support
73  for multiple targets, e.g. ``cmake --build . --target Library1 Library2``.
74  It now also has a short form ``-t`` alias, e.g.
75  ``cmake --build . -t Library1 Library2``.
76
77* The :manual:`cmake(1)` command gained a new ``--install`` option.
78  This may be used after building a project to run installation without
79  using the generated build system or the native build tool.
80
81* The :manual:`cmake(1)` command learned a new CLI option ``--loglevel``.
82
83* The :manual:`cmake(1)` ``-E remove_directory`` command-line tool learned
84  to support removing multiple directories.
85
86* The :manual:`cmake(1)` ``-E tar`` tool has been improved:
87
88  * It now continues adding files to an archive even if some of the files
89    are not readable.  This behavior is more consistent with the
90    classic ``tar`` tool.
91
92  * It now parses all flags, and if an invalid flag was provided, a
93    warning is issued.
94
95  * It now displays an error if no action flag was specified, along with a
96    list of possible actions: ``t`` (list), ``c`` (create) or ``x`` (extract).
97
98  * It now supports extracting (``-x``) or listing (``-t``) only specific
99    files or directories.
100
101  * It now supports Zstandard compression with a ``--zstd`` option.
102    Zstandard was designed to give a compression ratio comparable to that
103    of the DEFLATE (zip) algorithm, but faster, especially for decompression.
104
105Commands
106--------
107
108* The :command:`add_custom_command` and :command:`add_custom_target` commands
109  gained a new ``JOB_POOL`` option that works with the :generator:`Ninja`
110  generator to set the pool variable on the build statement.
111
112* The :command:`add_library` command ``ALIAS`` option learned to support
113  import libraries of the ``UNKNOWN`` type.
114
115* The :command:`cmake_parse_arguments` command gained an additional
116  ``<prefix>_KEYWORDS_MISSING_VALUES`` output variable to report
117  keyword arguments that were given by the caller with no values.
118
119* The :command:`execute_process` command gained a ``COMMAND_ECHO`` option
120  and supporting :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ECHO` variable
121  to enable echoing of the command-line string before execution.
122
123* The :command:`file(INSTALL)` command learned a new argument,
124  ``FOLLOW_SYMLINK_CHAIN``, which can be used to recursively resolve and
125  install symlinks.
126
127* :command:`list` learned new sub-commands:
128  ``PREPEND``, ``POP_FRONT`` and ``POP_BACK``.
129
130* The :command:`message` command learned new types:
131  ``NOTICE``, ``VERBOSE``, ``DEBUG`` and ``TRACE``.
132
133* The :command:`string` learned a new sub-command ``REPEAT``.
134
135Variables
136---------
137
138* The :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable and corresponding
139  :prop_tgt:`CROSSCOMPILING_EMULATOR` target property learned to support
140  arguments to the emulator.
141
142* The :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable was added to tell
143  :command:`find_package` calls to look for a package configuration
144  file first even if a find module is available.
145
146* The :variable:`CMAKE_FRAMEWORK` variable was added to initialize the
147  :prop_tgt:`FRAMEWORK` property on all targets.
148
149* The :variable:`CMAKE_VS_JUST_MY_CODE_DEBUGGING` variable and
150  :prop_tgt:`VS_JUST_MY_CODE_DEBUGGING` target property were added to
151  enable the Just My Code feature of the Visual Studio Debugger when
152  compiling with MSVC cl 19.05 and higher.
153
154* The :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` variable and
155  :prop_tgt:`MSVC_RUNTIME_LIBRARY` target property were introduced to
156  select the runtime library used by compilers targeting the MSVC ABI.
157  See policy :policy:`CMP0091`.
158
159* The :variable:`CMAKE_PROJECT_INCLUDE` and
160  :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variables were added to allow
161  injection of custom code at the sites of :command:`project` calls
162  without knowing the project name a priori.
163
164Properties
165----------
166
167* The :prop_tgt:`ADDITIONAL_CLEAN_FILES` target property and
168  :prop_dir:`ADDITIONAL_CLEAN_FILES` directory property were added.
169  They allow to register additional files that should be removed during
170  the clean stage.
171
172* The :prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` properties
173  may now be set on :ref:`Interface Libraries`. The headers specified by those
174  properties can be installed using the :command:`install(TARGETS)` command by
175  passing the ``PUBLIC_HEADER`` and ``PRIVATE_HEADER`` arguments respectively.
176
177* The :prop_tgt:`VS_PACKAGE_REFERENCES` target property was added to
178  tell :ref:`Visual Studio Generators` to add references to ``nuget``
179  packages.
180
181* The :prop_tgt:`VS_PROJECT_IMPORT` target property was added to allow
182  managed Visual Studio project files to import external ``.props`` files.
183
184* The :prop_tgt:`VS_NO_SOLUTION_DEPLOY` target property was added to
185  tell :ref:`Visual Studio Generators` whether to deploy an artifact
186  to the WinCE or Windows Phone target device.
187
188Modules
189-------
190
191* The :module:`FindBoost` module was reworked to expose a more consistent
192  user experience between its "Config" and "Module" modes and with other
193  find modules in general.
194
195  * A new imported target ``Boost::headers`` is now defined (same
196    as ``Boost::boost``).
197
198  * New output variables ``Boost_VERSION_MACRO``,
199    ``Boost_VERSION_MAJOR``, ``Boost_VERSION_MINOR``,
200    ``Boost_VERSION_PATCH``, and ``Boost_VERSION_COUNT``
201    were added.
202
203  * The ``QUIET`` argument passed to :command:`find_package` is no
204    longer ignored in config mode.  Note that the CMake package shipped with
205    Boost ``1.70.0`` ignores the ``QUIET`` argument passed to
206    :command:`find_package`.  This is fixed in the next Boost release.
207
208  * The input switch ``Boost_DETAILED_FAILURE_MSG`` was removed.
209
210  * ``Boost_VERSION`` now reports the version in ``x.y.z``
211    format in module mode.  See policy :policy:`CMP0093`.
212
213* The :module:`FindCups` module now provides imported targets.
214
215* The :module:`FindEnvModules` module was added to use Lua- and TCL-based
216  environment modules in :ref:`CTest Scripts <CTest Script>`.
217
218* The :module:`FindGLEW` module now provides an interface more consistent
219  with what upstream GLEW provides in its own CMake package files.
220
221* The :module:`FindPkgConfig` now populates :prop_tgt:`INTERFACE_LINK_OPTIONS`
222  property of imported targets with other (non-library) linker flags.
223
224* The :module:`FindPostgreSQL` module learned to find debug and release
225  variants separately.
226
227* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
228  gained additional lookup strategies and controls, and a new default.
229  See policy :policy:`CMP0094`.
230
231* Modules :module:`FindPython`, :module:`FindPython2` and :module:`FindPython3`
232  gain a new target (respectively ``Python::Module``, ``Python2::Module``
233  and ``Python3::Module``) which can be used to develop Python modules.
234
235* Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
236  gain capability to control how virtual environments are handled.
237
238* The :module:`UseSWIG` module learned to manage alternate library names
239  by passing ``-interface <library_name>`` for ``python`` language or
240  ``-dllimport <library_name>`` for ``CSharp`` language to the ``SWIG``
241  compiler.
242
243Generator Expressions
244---------------------
245
246* The :manual:`generator expressions <cmake-generator-expressions(7)>`
247  ``C_COMPILER_ID``, ``CXX_COMPILER_ID``, ``CUDA_COMPILER_ID``,
248  ``Fortran_COMPILER_ID``, ``COMPILE_LANGUAGE``, ``COMPILE_LANG_AND_ID``, and
249  ``PLATFORM_ID`` learned to support matching one value from a comma-separated
250  list.
251
252* The ``$<CUDA_COMPILER_ID:...>`` and ``$<CUDA_COMPILER_VERSION:...>``
253  :manual:`generator expressions <cmake-generator-expressions(7)>` were added.
254
255* The ``$<COMPILE_LANG_AND_ID:...>`` generator expression was introduced to
256  allow specification of compile options for target files based on the
257  :variable:`CMAKE_<LANG>_COMPILER_ID` and :prop_sf:`LANGUAGE` of
258  each source file.
259
260* A ``$<FILTER:list,INCLUDE|EXCLUDE,regex>``
261  :manual:`generator expression <cmake-generator-expressions(7)>`
262  has been added.
263
264* A ``$<REMOVE_DUPLICATES:list>``
265  :manual:`generator expression <cmake-generator-expressions(7)>`
266  has been added.
267
268* The ``$<SHELL_PATH:...>`` :manual:`generator expression
269  <cmake-generator-expressions(7)>` gained support for a list of paths.
270
271* New ``$<TARGET_FILE*>`` :manual:`generator expressions
272  <cmake-generator-expressions(7)>` were added to retrieve the prefix, base
273  name, and suffix of the file names of various artifacts:
274
275  * ``$<TARGET_FILE_PREFIX:...>``
276  * ``$<TARGET_FILE_BASE_NAME:...>``
277  * ``$<TARGET_FILE_SUFFIX:...>``
278  * ``$<TARGET_LINKER_FILE_PREFIX:...>``
279  * ``$<TARGET_LINKER_FILE_BASE_NAME:...>``
280  * ``$<TARGET_LINKER_FILE_SUFFIX:...>``
281  * ``$<TARGET_PDB_FILE_BASE_NAME:...>``
282
283* The ``$<TARGET_OBJECTS:...>`` :manual:`generator expression
284  <cmake-generator-expressions(7)>` is now supported on ``SHARED``,
285  ``STATIC``, ``MODULE`` libraries and executables.
286
287CTest
288-----
289
290* The :command:`ctest_submit` command learned a new option: ``BUILD_ID``.
291  This can be used to store the ID assigned to this build by CDash to a
292  variable.
293
294* The :command:`ctest_update` command learned to honor a new variable:
295  :variable:`CTEST_UPDATE_VERSION_OVERRIDE`. This can be used to specify
296  the current version of your source tree rather than using the update
297  command to discover the current version that is checked out.
298
299CPack
300-----
301
302* The :cpack_gen:`CPack IFW Generator` gained a new
303  :variable:`CPACK_IFW_PACKAGE_STYLE_SHEET` variable to customize the
304  installer stylesheet.
305
306Deprecated and Removed Features
307===============================
308
309* The :manual:`cmake-server(7)` mode has been deprecated and will be
310  removed from a future version of CMake.  Please port clients to use
311  the :manual:`cmake-file-api(7)` instead.
312
313* The :prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES` directory property is now
314  deprecated.  Use the :prop_dir:`ADDITIONAL_CLEAN_FILES` directory property
315  instead.
316
317* The variable :variable:`CMAKE_AUTOMOC_RELAXED_MODE` is considered
318  deprecated.  Support still exists but will be removed in future versions.
319
320* The :command:`export(PACKAGE)` command now does nothing unless
321  enabled via :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY`.
322  See policy :policy:`CMP0090`.
323
324* The :generator:`Xcode` generator now requires at least Xcode 5.
325
326* An explicit deprecation diagnostic was added for policy ``CMP0066``
327  (``CMP0065`` and below were already deprecated).
328  The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
329  of all policies are deprecated and that projects should port to the
330  NEW behaviors.
331
332Other Changes
333=============
334
335* If a feature specified by :command:`target_compile_features` is available
336  in the compiler's default standard level, CMake 3.14 and below incorrectly
337  added unnecessary ``-std=`` flags that could lower the standard level.
338  This bug has been fixed in CMake 3.15.  This behavior change may expose
339  bugs in existing projects that were relying on undocumented implementation
340  details.  Specifying compile features only ensures that the compiler runs
341  in a mode that has those features, not that any specific standard level is
342  used or explicit ``-std=`` flag passed.
343
344* CMake learned how to compile C++14 with the IBM AIX XL compiler
345  and the SunPro compiler and to compile C++20 with the AppleClang compiler.
346
347* With MSVC-like compilers the value of :variable:`CMAKE_<LANG>_FLAGS`
348  no longer contains warning flags like ``/W3`` by default.
349  See policy :policy:`CMP0092`.
350
351* IBM Clang-based XL compilers that define ``__ibmxl__`` now use the
352  compiler id ``XLClang`` instead of ``XL``.  See policy :policy:`CMP0089`.
353
354* The :command:`file(REMOVE)` and :command:`file(REMOVE_RECURSE)` commands
355  were changed to ignore empty arguments with a warning instead of treating
356  them as a relative path and removing the contents of the current directory.
357
358Updates
359=======
360
361Changes made since CMake 3.15.0 include the following.
362
3633.15.1
364------
365
366* In CMake 3.15.0 support for the GNU-like ``Clang`` compiler targeting the
367  MSVC ABI implemented :variable:`CMAKE_CXX_STANDARD` values 98 and 11 using
368  the corresponding ``-std=`` flags.  However, these modes do not work with
369  the MSVC standard library.  Therefore CMake 3.15.1 passes C++14 standard
370  flags even for C++98 and C++11.  This is consistent with MSVC itself which
371  always runs in a mode aware of C++14.
372
373* Preliminary Swift support added in 3.15.0 has been updated.
374
3753.15.2
376------
377
378* In CMake 3.15.0 and 3.15.1 the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG`
379  variable caused the :command:`find_package` command to fail on a missing
380  package even without the ``REQUIRED`` option.  This has been fixed.
381
3823.15.3
383------
384
385* ``CrayPrgEnv`` compiler wrapper support has been updated for the 19.06
386  release of the Cray Programming Environment for which the default linking
387  mode on XC Cray systems is now dynamic instead of static.
388
3893.15.4
390------
391
392* In CMake 3.15.0 through 3.15.3, the :prop_dir:`EXCLUDE_FROM_ALL`
393  directory property was regressed from pre-3.14 behavior and caused
394  targets within the directory to be excluded even from its own "all".
395  This has been fixed.
396  The bug also existed in 3.14.0 through 3.14.6 and is fixed in 3.14.7.
397