1CMake 3.18 Release Notes
2************************
3
4.. only:: html
5
6  .. contents::
7
8Changes made since CMake 3.17 include the following.
9
10New Features
11============
12
13Languages
14---------
15
16* The ``CUDA`` language can now be compiled using Clang on non-Windows
17  platforms. Separable compilation is not yet supported on any platform.
18
19Command-Line
20------------
21
22* :manual:`cmake(1)` gained support for profiling of CMake scripts through
23  the parameters ``--profiling-output`` and ``--profiling-format``.
24
25* :manual:`cmake(1)` gained a ``cat`` command line
26  option that can be used to concatenate files and print them
27  on standard output.
28
29Commands
30--------
31
32* The :command:`add_library` and :command:`add_executable` commands
33  learned to create :ref:`Alias Targets` referencing non-``GLOBAL``
34  :ref:`Imported Targets`.
35
36* The :command:`cmake_language()` command was added for meta-operations on
37  scripted or built-in commands, starting with a mode to ``CALL`` other
38  commands, and ``EVAL CODE`` to inplace evaluate a CMake script.
39
40* The :command:`execute_process` command gained the ``ECHO_OUTPUT_VARIABLE``
41  and ``ECHO_ERROR_VARIABLE`` options.
42
43* The :command:`export` command now raise an error if used multiple times with
44  same ``FILE`` without ``APPEND``. See policy :policy:`CMP0103`.
45
46* The :command:`file` command gained the ``ARCHIVE_CREATE`` and
47  ``ARCHIVE_EXTRACT`` subcommands to expose the :manual:`cmake(1)` ``-E tar``
48  functionality to CMake scripting code.
49
50* The :command:`file(CONFIGURE)` subcommand was created in order to replicate
51  the :command:`configure_file` functionality without resorting to a
52  pre-existing file on disk as input. The content is instead passed as a
53  string.
54
55* The :command:`file(UPLOAD)` command gained ``TLS_VERIFY`` and ``TLS_CAINFO``
56  options to control server certificate verification.
57
58* The :command:`find_program`, :command:`find_library`, :command:`find_path`
59  and :command:`find_file` commands gained a new ``REQUIRED`` option that will
60  stop processing with an error message if nothing is found.
61
62* The :command:`get_property` command with ``SOURCE`` scope gained the
63  ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to get a property
64  from the provided directory scope.
65
66* The :command:`get_source_file_property` command gained the ``DIRECTORY``
67  and ``TARGET_DIRECTORY`` options to get a property from the
68  provided directory scope.
69
70* The :command:`list` operation ``SORT`` gained the ``NATURAL`` sort
71  option to sort using natural order (see ``strverscmp(3)`` manual).
72
73* The :command:`set_property` command with the ``SOURCE`` scope gained the
74  ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to set properties
75  in the provided directory scopes.
76
77* The :command:`set_source_files_properties` command gained the ``DIRECTORY``
78  and ``TARGET_DIRECTORY`` options to set properties in the provided
79  directory scopes.
80
81* The :command:`string` command learned a new ``HEX`` sub-command, which
82  converts strings into their hexadecimal representation.
83
84Variables
85---------
86
87* A :variable:`CMAKE_CUDA_ARCHITECTURES` variable was added to specify
88  CUDA output architectures.  Users are encouraged to use this instead of
89  specifying options manually, as this approach is compiler-agnostic.
90  The variable is initialized automatically when
91  :variable:`CMAKE_CUDA_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` is ``NVIDIA``.
92  The variable is used to initialize the new :prop_tgt:`CUDA_ARCHITECTURES`
93  target property.  See policy :policy:`CMP0104`.
94
95* The :variable:`CMAKE_PCH_WARN_INVALID` variable was added to initialize the
96  :prop_tgt:`PCH_WARN_INVALID` target property to allow the removal of the
97  precompiled header invalid warning.
98
99Properties
100----------
101
102* The :prop_tgt:`CUDA_ARCHITECTURES` target property was added to specify
103  CUDA output architectures. Users are encouraged to use this instead of
104  specifying options manually, as this approach is compiler-agnostic.
105  The property is initialized by the new :variable:`CMAKE_CUDA_ARCHITECTURES`
106  variable.  See policy :policy:`CMP0104`.
107
108* The :prop_tgt:`Fortran_PREPROCESS` target property and
109  :prop_sf:`Fortran_PREPROCESS` source-file property were added to
110  control preprocessing of Fortran source files.
111
112* The :prop_tgt:`FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>` target property
113  and associated :variable:`CMAKE_FRAMEWORK_MULTI_CONFIG_POSTFIX_<CONFIG>`
114  variable were created to allow adding a postfix to the name of a
115  framework file name when using a multi-config generator.
116
117* The :prop_sf:`OBJECT_OUTPUTS` source file property now supports
118  :manual:`generator expressions <cmake-generator-expressions(7)>`.
119
120* The :prop_tgt:`PCH_WARN_INVALID` target property was added to allow the
121  removal of the precompiled header invalid warning.
122
123* The :prop_tgt:`UNITY_BUILD_MODE` target property was added to tell
124  generators which algorithm to use for grouping included source
125  files.
126
127* The :prop_tgt:`VS_SOURCE_SETTINGS_<tool>` target property was added
128  to tell :ref:`Visual Studio Generators` for VS 2010 and above to add
129  metadata to non-built source files using ``<tool>``.
130
131* The :prop_sf:`VS_SETTINGS` source file property was added to tell
132  :ref:`Visual Studio Generators` for VS 2010 and above to add
133  metadata to a non-built source file.
134
135* The :prop_tgt:`VS_PLATFORM_TOOLSET` target property was added to tell
136  :ref:`Visual Studio Generators` for VS 2010 and above to override
137  the platform toolset.
138
139* The :prop_tgt:`VS_SOLUTION_DEPLOY` target property was added to tell
140  :ref:`Visual Studio Generators` for VS 2010 and above to mark a
141  target for deployment even when not building for Windows Phone/Store/CE.
142
143Modules
144-------
145
146* The :module:`CheckLinkerFlag` module has been added to provide a
147  facility to check validity of link flags.
148
149* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
150  gained a new ``GIT_REMOTE_UPDATE_STRATEGY`` keyword.  This can be used to
151  specify how failed rebase operations during a git update should be handled.
152  The ``CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY`` variable was also added as a
153  global default and is honored by both the :module:`ExternalProject` and
154  :module:`FetchContent` modules.
155
156* The :module:`FetchContent` module :command:`FetchContent_Declare` command
157  now supports a ``SOURCE_SUBDIR`` option.  It can be used to direct
158  :command:`FetchContent_MakeAvailable` to look in a different location
159  for the ``CMakeLists.txt`` file.
160
161* The :module:`FindBLAS` module now provides an imported target.
162
163* The :module:`FindCUDAToolkit` module:
164
165  * gained the variable
166    ``CUDAToolkit_LIBRARY_ROOT``, which is the directory containing the
167    ``nvvm`` directory and ``version.txt``.
168
169  * uses toolkit and library root found during ``CUDA`` compiler detection.
170
171* The :module:`FindLAPACK` module now provides an imported target.
172
173* The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
174  modules:
175
176  * gained the possibility to create per-artifact cache variables for
177    interactive editing in :manual:`cmake-gui(1)` and :manual:`ccmake(1)`.
178
179  * gained sub-components ``Development.Module`` and
180    ``Development.Embed`` under the ``Development`` component.
181
182  * gained the capability to specify which Python implementations to find,
183    including ``IronPython`` and ``PyPy``.
184
185* The :module:`FindRuby` module input and output variables were all renamed
186  from ``RUBY_`` to ``Ruby_`` for consistency with other find modules.
187  Input variables of the old case will be honored if provided, and output
188  variables of the old case are always provided.
189
190* The :module:`FindSWIG` module now accepts target languages as  ``COMPONENTS``
191  and ``OPTIONAL_COMPONENTS`` arguments to ``find_package``.
192
193* The :module:`GoogleTest` module :command:`gtest_discover_tests` command:
194
195  * gained a new ``DISCOVERY_MODE`` option to control when the test
196    discovery step is run.  It offers a new ``PRE_TEST`` setting to
197    run the discovery at test time instead of build time.  A new
198    ``CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE`` variable can be used
199    to change the default globally.
200
201  * gained a new optional parameter ``XML_OUTPUT_DIR``. When set the
202    JUnit XML test results are stored in that directory.
203
204* The :module:`FindLibXslt` module now provides imported targets.
205
206* The :module:`UseSWIG` module now supports Fortran as a target language if
207  the ``SWIG_EXECUTABLE`` is SWIG-Fortran_.
208
209.. _`SWIG-Fortran`: https://github.com/swig-fortran/swig
210
211Generator Expressions
212---------------------
213
214* The ``$<DEVICE_LINK:...>`` and ``$<HOST_LINK:...>``
215  :manual:`generator expressions <cmake-generator-expressions(7)>` were added
216  to manage device and host link steps.
217
218* The ``$<LINK_LANGUAGE:...>`` and ``$<LINK_LANG_AND_ID:...>``
219  :manual:`generator expressions <cmake-generator-expressions(7)>` were added.
220
221CTest
222-----
223
224* :manual:`ctest(1)` gained a new :variable:`CTEST_RESOURCE_SPEC_FILE`
225  variable, which can be used to specify a
226  :ref:`resource specification file <ctest-resource-specification-file>`.
227
228* :manual:`ctest(1)` gained a ``--stop-on-failure`` option,
229  which can be used to stop running the tests once one has failed.
230
231* The :command:`ctest_test` command gained a ``STOP_ON_FAILURE`` option
232  which can be used to stop running the tests once one has failed.
233
234* The :module:`CTestCoverageCollectGCOV` module
235  :command:`ctest_coverage_collect_gcov` command gained a
236  ``TARBALL_COMPRESSION`` option to control compression of the
237  tarball of collected results.
238
239CPack
240-----
241
242* The :cpack_gen:`CPack Archive Generator`'s ``TXZ`` format learned the
243  :variable:`CPACK_ARCHIVE_THREADS` variable to enable parallel compression.
244  Requires support in the ``liblzma`` used by CMake.
245
246* The :cpack_gen:`CPack NSIS Generator` gained a new variable
247  :variable:`CPACK_NSIS_MANIFEST_DPI_AWARE` to declare that the
248  installer is DPI-aware.
249
250* The :cpack_gen:`CPack RPM Generator` gained
251  :variable:`CPACK_RPM_PRE_TRANS_SCRIPT_FILE` and
252  :variable:`CPACK_RPM_POST_TRANS_SCRIPT_FILE`
253  variables to specify pre- and post-transaction scripts.
254
255Other
256-----
257
258* :manual:`cmake-gui(1)` now populates its generator selection
259  widget default value from the :envvar:`CMAKE_GENERATOR` environment
260  variable.  Additionally, environment variables
261  :envvar:`CMAKE_GENERATOR_PLATFORM` and :envvar:`CMAKE_GENERATOR_TOOLSET`
262  are used to populate their respective widget defaults.
263
264* :manual:`ccmake(1)` learned to read a :envvar:`CCMAKE_COLORS`
265  environment variable to customize colors.
266
267* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
268  is now aware of the availability of C11 features in MSVC 19.27 and 19.28,
269  including support for the ``c_restrict``, ``c_static_assert`` features and
270  the ``-std:c11`` flag.
271
272Deprecated and Removed Features
273===============================
274
275* The :module:`Documentation` module has been deprecated via
276  :policy:`CMP0106`. This module was essentially VTK code that CMake should
277  not be shipping anymore.
278
279* An explicit deprecation diagnostic was added for policy ``CMP0070``
280  and policy ``CMP0071`` (``CMP0069`` and below were already deprecated).
281  The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
282  of all policies are deprecated and that projects should port to the
283  NEW behaviors.
284
285Other Changes
286=============
287
288* On Windows, the :generator:`Ninja` and :generator:`Ninja Multi-Config`
289  generators, when a compiler is not explicitly specified, now select
290  the first compiler (of any name) found in directories listed by the
291  ``PATH`` environment variable.
292
293* The :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
294  properties are now used for the device link step.
295  See policy :policy:`CMP0105`.
296
297* Creation of an ``ALIAS`` target overwriting an existing target now raises an
298  error. See policy :policy:`CMP0107`.
299
300* Linking a target to itself through an alias now raises an error.
301  See policy :policy:`CMP0108`.
302
303* The :module:`FindPackageHandleStandardArgs` module option ``REQUIRED_VARS``
304  is now optional if ``HANDLE_COMPONENTS`` is specified.
305
306* The :command:`source_group` command now also recognizes forward slashes
307  as subgroup delimiters, not just backslashes.
308
309* :manual:`ctest(1)` now logs environment variables that it sets for each test,
310  either due to the :prop_test:`ENVIRONMENT` property or the
311  :ref:`resource allocation <ctest-resource-allocation>` feature, and submits
312  this log to CDash. It does not log environment variables that were set
313  outside of CTest.
314
315* When building CMake itself from source and not using a system-provided
316  libcurl, HTTP/2 support is now enabled for commands supporting
317  network communication via ``http(s)``, such as :command:`file(DOWNLOAD)`,
318  :command:`file(UPLOAD)`, and :command:`ctest_submit`.
319  The precompiled binaries provided on ``cmake.org`` now support HTTP/2.
320
321* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
322  been updated to 2.1.
323
324* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained
325  a new ``precompileHeaders`` field in the ``compileGroups`` objects.
326
327Updates
328=======
329
330Changes made since CMake 3.18.0 include the following.
331
3323.18.1
333------
334
335* The :generator:`Xcode` generator, when :variable:`CMAKE_OSX_ARCHITECTURES`
336  is not defined, now selects ``$(NATIVE_ARCH_ACTUAL)`` as the default
337  architecture (the Xcode ``ARCHS`` setting).  This is needed for Xcode 12
338  to select the host's architecture, which older versions of Xcode did
339  by default.
340
341* In CMake 3.18.0 the :command:`add_test` command learned to support
342  special characters in test names.  This was accidentally left out of
343  its release notes.  Unfortunately the fix breaks existing projects
344  that were using manual quoting or escaping to work around the prior
345  limitation.  This fix has been reverted in 3.18.1, but may be
346  re-introduced in future versions of CMake with a policy for compatibility.
347
3483.18.2
349------
350
351* The default value of :variable:`CMAKE_AUTOMOC_PATH_PREFIX` was changed to
352  ``OFF`` because this feature can break existing projects that have
353  identically named header files in different include directories.
354  This restores compatibility with behavior of CMake 3.15 and below.
355  The default was also changed to ``OFF`` in 3.16.9 and 3.17.5.
356
357* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
358  was updated for MSVC 19.27 as mentioned above (``c_restrict``).
359
3603.18.3
361------
362
363* The :manual:`Compile Features <cmake-compile-features(7)>` functionality
364  was updated for MSVC 19.28 as mentioned above (``c_static_assert``).
365