1 CMake 3.18 Release Notes
2 ************************
8 Changes made since CMake 3.17 include the following.
16 * The ``CUDA`` language can now be compiled using Clang on non-Windows
17 platforms. Separable compilation is not yet supported on any platform.
22 * :manual:`cmake(1)` gained support for profiling of CMake scripts through
23 the parameters ``--profiling-output`` and ``--profiling-format``.
25 * :manual:`cmake(1)` gained a ``cat`` command line
26 option that can be used to concatenate files and print them
32 * The :command:`add_library` and :command:`add_executable` commands
33 learned to create :ref:`Alias Targets` referencing non-``GLOBAL``
34 :ref:`Imported Targets`.
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.
40 * The :command:`execute_process` command gained the ``ECHO_OUTPUT_VARIABLE``
41 and ``ECHO_ERROR_VARIABLE`` options.
43 * The :command:`export` command now raise an error if used multiple times with
44 same ``FILE`` without ``APPEND``. See policy :policy:`CMP0103`.
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.
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
55 * The :command:`file(UPLOAD)` command gained ``TLS_VERIFY`` and ``TLS_CAINFO``
56 options to control server certificate verification.
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.
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.
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.
70 * The :command:`list` operation ``SORT`` gained the ``NATURAL`` sort
71 option to sort using natural order (see ``strverscmp(3)`` manual).
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.
77 * The :command:`set_source_files_properties` command gained the ``DIRECTORY``
78 and ``TARGET_DIRECTORY`` options to set properties in the provided
81 * The :command:`string` command learned a new ``HEX`` sub-command, which
82 converts strings into their hexadecimal representation.
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`.
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.
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`.
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.
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.
117 * The :prop_sf:`OBJECT_OUTPUTS` source file property now supports
118 :manual:`generator expressions <cmake-generator-expressions(7)>`.
120 * The :prop_tgt:`PCH_WARN_INVALID` target property was added to allow the
121 removal of the precompiled header invalid warning.
123 * The :prop_tgt:`UNITY_BUILD_MODE` target property was added to tell
124 generators which algorithm to use for grouping included source
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>``.
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.
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.
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.
146 * The :module:`CheckLinkerFlag` module has been added to provide a
147 facility to check validity of link flags.
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.
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.
161 * The :module:`FindBLAS` module now provides an imported target.
163 * The :module:`FindCUDAToolkit` module:
165 * gained the variable
166 ``CUDAToolkit_LIBRARY_ROOT``, which is the directory containing the
167 ``nvvm`` directory and ``version.txt``.
169 * uses toolkit and library root found during ``CUDA`` compiler detection.
171 * The :module:`FindLAPACK` module now provides an imported target.
173 * The :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython`
176 * gained the possibility to create per-artifact cache variables for
177 interactive editing in :manual:`cmake-gui(1)` and :manual:`ccmake(1)`.
179 * gained sub-components ``Development.Module`` and
180 ``Development.Embed`` under the ``Development`` component.
182 * gained the capability to specify which Python implementations to find,
183 including ``IronPython`` and ``PyPy``.
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.
190 * The :module:`FindSWIG` module now accepts target languages as ``COMPONENTS``
191 and ``OPTIONAL_COMPONENTS`` arguments to ``find_package``.
193 * The :module:`GoogleTest` module :command:`gtest_discover_tests` command:
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.
201 * gained a new optional parameter ``XML_OUTPUT_DIR``. When set the
202 JUnit XML test results are stored in that directory.
204 * The :module:`FindLibXslt` module now provides imported targets.
206 * The :module:`UseSWIG` module now supports Fortran as a target language if
207 the ``SWIG_EXECUTABLE`` is SWIG-Fortran_.
209 .. _`SWIG-Fortran`: https://github.com/swig-fortran/swig
211 Generator Expressions
212 ---------------------
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.
218 * The ``$<LINK_LANGUAGE:...>`` and ``$<LINK_LANG_AND_ID:...>``
219 :manual:`generator expressions <cmake-generator-expressions(7)>` were added.
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>`.
228 * :manual:`ctest(1)` gained a ``--stop-on-failure`` option,
229 which can be used to stop running the tests once one has failed.
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.
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.
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.
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.
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.
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.
264 * :manual:`ccmake(1)` learned to read a :envvar:`CCMAKE_COLORS`
265 environment variable to customize colors.
267 Deprecated and Removed Features
268 ===============================
270 * The :module:`Documentation` module has been deprecated via
271 :policy:`CMP0106`. This module was essentially VTK code that CMake should
272 not be shipping anymore.
274 * An explicit deprecation diagnostic was added for policy ``CMP0070``
275 and policy ``CMP0071`` (``CMP0069`` and below were already deprecated).
276 The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
277 of all policies are deprecated and that projects should port to the
283 * On Windows, the :generator:`Ninja` and :generator:`Ninja Multi-Config`
284 generators, when a compiler is not explicitly specified, now select
285 the first compiler (of any name) found in directories listed by the
286 ``PATH`` environment variable.
288 * The :prop_tgt:`LINK_OPTIONS` and :prop_tgt:`INTERFACE_LINK_OPTIONS` target
289 properties are now used for the device link step.
290 See policy :policy:`CMP0105`.
292 * Creation of an ``ALIAS`` target overwriting an existing target now raises an
293 error. See policy :policy:`CMP0107`.
295 * Linking a target to itself through an alias now raises an error.
296 See policy :policy:`CMP0108`.
298 * The :module:`FindPackageHandleStandardArgs` module option ``REQUIRED_VARS``
299 is now optional if ``HANDLE_COMPONENTS`` is specified.
301 * The :command:`source_group` command now also recognizes forward slashes
302 as subgroup delimiters, not just backslashes.
304 * :manual:`ctest(1)` now logs environment variables that it sets for each test,
305 either due to the :prop_test:`ENVIRONMENT` property or the
306 :ref:`resource allocation <ctest-resource-allocation>` feature, and submits
307 this log to CDash. It does not log environment variables that were set
310 * When building CMake itself from source and not using a system-provided
311 libcurl, HTTP/2 support is now enabled for commands supporting
312 network communication via ``http(s)``, such as :command:`file(DOWNLOAD)`,
313 :command:`file(UPLOAD)`, and :command:`ctest_submit`.
314 The precompiled binaries provided on ``cmake.org`` now support HTTP/2.
316 * The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
319 * The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained
320 a new ``precompileHeaders`` field in the ``compileGroups`` objects.
325 Changes made since CMake 3.18.0 include the following.
330 * The :generator:`Xcode` generator, when :variable:`CMAKE_OSX_ARCHITECTURES`
331 is not defined, now selects ``$(NATIVE_ARCH_ACTUAL)`` as the default
332 architecture (the Xcode ``ARCHS`` setting). This is needed for Xcode 12
333 to select the host's architecture, which older versions of Xcode did
336 * In CMake 3.18.0 the :command:`add_test` command learned to support
337 special characters in test names. This was accidentally left out of
338 its release notes. Unfortunately the fix breaks existing projects
339 that were using manual quoting or escaping to work around the prior
340 limitation. This fix has been reverted in 3.18.1, but may be
341 re-introduced in future versions of CMake with a policy for compatibility.