1 CMake 3.17 Release Notes
2 ************************
8 Changes made since CMake 3.16 include the following.
16 * :manual:`cmake(1)` gained a :generator:`Ninja Multi-Config` generator,
17 which is similar to the :generator:`Ninja` generator but can be used to build
18 multiple configurations at once.
20 * :ref:`Visual Studio Generators` learned to support per-config sources.
21 Previously only :ref:`Command-Line Build Tool Generators` supported them.
23 * :ref:`Visual Studio Generators` for VS 2010 and above now support
24 specifying the ``VCTargetsPath`` value for project files in
25 :variable:`CMAKE_GENERATOR_TOOLSET` setting.
27 * :ref:`Visual Studio Generators` for VS 2010 and above learned to
28 support .NET Standard and .NET Core. See the
29 :prop_tgt:`DOTNET_TARGET_FRAMEWORK` target property and
30 associated :variable:`CMAKE_DOTNET_TARGET_FRAMEWORK` variable.
35 * The :manual:`Compile Features <cmake-compile-features(7)>` functionality
36 now offers meta-features for the CUDA language standard levels
37 (e.g. ``cuda_std_03``, ``cuda_std_14``). See
38 :prop_gbl:`CMAKE_CUDA_KNOWN_FEATURES`.
43 * The IBM XL Fortran compiler is now supported by the :generator:`Ninja`
49 * :manual:`cmake(1)` gained a ``--debug-find`` command-line option to
50 enable additional human-readable output on where ``find_*`` commands search.
52 * :manual:`cmake(1)` gained a ``--trace-format`` command-line option that
53 can be used to set the ``--trace`` output format. Currently, the old
54 human readable and the new JSON format are supported. The new JSON format
55 is easier to parse automatically than the existing format.
57 * :manual:`cmake(1)` gained a ``-E rm`` command-line tool that can be
58 used to remove directories and files. This supersedes the existing
59 ``-E remove`` and ``-E remove_directory`` tools and has better semantics.
64 * The :command:`add_custom_command` command learned to interpret paths in
65 ``DEPENDS`` arguments that are specified relative to the current
68 * The :command:`foreach` command learned a new ``ZIP_LISTS`` option to iterate
69 over multiple lists simultaneously.
71 * The :command:`load_cache(READ_WITH_PREFIX)` command mode is now allowed
72 when using ``cmake -P`` to :ref:`Run a Script <Script Processing Mode>`.
74 * The :command:`message` command learned to output context provided in
75 the :variable:`CMAKE_MESSAGE_CONTEXT` variable for log levels
76 ``NOTICE`` and below. Enable this output with the new ``--log-context``
77 command-line option or :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` variable.
79 * The :command:`message` command gained new keywords ``CHECK_START``,
80 ``CHECK_PASS`` and ``CHECK_FAIL``.
82 * The :command:`target_compile_options` command now honors the ``BEFORE``
83 keyword more consistently. See policy :policy:`CMP0101`.
88 * A :variable:`CMAKE_CTEST_ARGUMENTS` variable was added to specify a list
89 of command-line arguments passed to CTest when running through the
90 ``test`` (or ``RUN_TESTS``) target of the generated build system.
92 * The following variables are now defined inside a :command:`function`:
94 - :variable:`CMAKE_CURRENT_FUNCTION`
95 - :variable:`CMAKE_CURRENT_FUNCTION_LIST_DIR`
96 - :variable:`CMAKE_CURRENT_FUNCTION_LIST_FILE`
97 - :variable:`CMAKE_CURRENT_FUNCTION_LIST_LINE`
99 * The :variable:`CMAKE_CUDA_RUNTIME_LIBRARY` variable and
100 :prop_tgt:`CUDA_RUNTIME_LIBRARY` target property were introduced to
101 select the CUDA runtime library used when linking targets that
104 * The :variable:`CMAKE_FIND_DEBUG_MODE` variable was introduced to
105 print extra ``find_*`` call information during the cmake run to standard
106 error. Output is designed for human consumption and not for parsing.
108 * The :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` variable now takes its
109 initial value from the :envvar:`CMAKE_EXPORT_COMPILE_COMMANDS` environment
110 variable if no explicit configuration is given.
112 * The :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable, if not set
113 explicitly, now takes its initial value from the
114 :envvar:`CMAKE_<LANG>_COMPILER_LAUNCHER` environment variable.
116 * The :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable can now be used
117 to persist a log level between CMake runs, unlike the ``--log-level``
118 command line option which only applies to that particular run.
120 * The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable was added
121 to initialize the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property.
123 * The :variable:`CMAKE_XCODE_SCHEME_WORKING_DIRECTORY` variable and
124 associated :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` target property
125 were added to tell the :generator:`Xcode` generator to set the value of
126 the ``Custom Working Directory`` schema option.
131 * The :prop_tgt:`AIX_EXPORT_ALL_SYMBOLS` target property and associated
132 :variable:`CMAKE_AIX_EXPORT_ALL_SYMBOLS` variable were created to
133 optionally explicitly disable automatic export of symbols from shared
136 * The :prop_tgt:`DEPRECATION` target property was added to mark
137 a target as deprecated. If a linked target is marked as
138 deprecated, a warning with the deprecation message is issued
141 * The :prop_tgt:`INSTALL_NAME_DIR` target property now supports
142 :manual:`generator expressions <cmake-generator-expressions(7)>`.
143 In particular, the ``$<INSTALL_PREFIX>`` generator expression can
144 be used to set the directory relative to the install-time prefix.
146 * Target properties :prop_tgt:`MACHO_COMPATIBILITY_VERSION` and
147 :prop_tgt:`MACHO_CURRENT_VERSION` were added to set the
148 ``compatibility_version`` and ``curent_version``, respectively,
149 for Mach-O binaries. For backwards compatibility, if these properties
150 are not set, :prop_tgt:`SOVERSION` and :prop_tgt:`VERSION`
151 are used respectively as fallbacks.
153 * The :prop_tgt:`VS_DOTNET_DOCUMENTATION_FILE` target property was added
154 to tell :ref:`Visual Studio Generators` to generate a ``DocumentationFile``
155 reference in ``.csproj`` files.
160 * The :module:`ExternalProject` module :command:`ExternalProject_Add`
161 command gained a ``GIT_SUBMODULES_RECURSE`` option to specify whether
162 Git submodules should be updated recursively. The default is on to
163 preserve existing behavior.
165 * The :module:`FindCUDAToolkit` module was added to find the
166 CUDA Toolkit without enabling CUDA as a language.
168 * The :module:`FindCURL` module learned to find CURL using
169 the ``CURLConfig.cmake`` package configuration file generated by
170 CURL's cmake buildsystem. It also gained a new ``CURL_NO_CURL_CMAKE``
171 option to disable this behavior.
173 * The :module:`FindFLEX` module's ``FLEX_TARGET`` command now runs ``flex``
174 with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory.
175 See policy :policy:`CMP0098`.
177 * The :module:`FindLibArchive` module now provides an imported target
180 * The :module:`FindPython` module has learned to find Python components
181 in active virtual environments managed by ``conda``.
183 * The :module:`FindPython3` and :module:`FindPython` modules gained,
184 respectively, variable ``Python3_SOABI`` and ``Python_SOABI`` giving
185 the standard extension suffix for modules. Moreover, commands
186 ``Python3_add_library()`` and ``Python_add_library()`` gained the option
187 ``WITH_SOABI`` to prefix the library suffix with the value of ``SOABI``.
189 * The :module:`FindLibXml2` module now provides an imported target for the
190 ``xmllint`` executable.
195 * :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` learned to process headers
196 with a ``.hh`` extension. See policy :policy:`CMP0100`.
201 * The :variable:`CTEST_CONFIGURATION_TYPE` variable is now set from the
202 command line when :manual:`ctest(1)` is invoked with ``-C <cfg>``.
204 * The :manual:`ctest(1)` tool gained support for Dr. Memory to run
207 * The :manual:`ctest(1)` tool gained a ``--no-tests=<[error|ignore]>`` option
208 to explicitly set and unify the behavior between direct invocation and
209 script mode if no tests were found.
211 * The :manual:`ctest(1)` tool gained a ``--repeat <mode>:<n>`` option
212 to specify conditions in which to repeat tests. This generalizes
213 the existing ``--repeat-until-fail <n>`` option to add modes for
214 ``until-pass`` and ``after-timeout``.
216 * The :command:`ctest_test` command gained a ``REPEAT <mode>:<n>`` option
217 to specify conditions in which to repeat tests.
222 * The :cpack_gen:`CPack DragNDrop Generator` learned to use
223 the :variable:`CPACK_DMG_<component>_FILE_NAME` variable
224 to set a custom filename when packaging components into
227 * The :cpack_gen:`CPack DragNDrop Generator` learned to handle
228 RTF formatted license files. When :variable:`CPACK_DMG_SLA_DIR`
229 variable is set, ``<language>.license.rtf`` is considered, but
230 only as a fallback when the plaintext (``.txt``) file is not found
231 in order to maintain backwards compatibility.
233 * The :cpack_gen:`CPack NSIS Generator` gained a new variable
234 :variable:`CPACK_NSIS_MUI_HEADERIMAGE` to set the header image.
235 To not break existing setups, it still defaults to
236 :variable:`CPACK_PACKAGE_ICON` if the new variable is not set.
238 * The :cpack_gen:`CPack NSIS Generator` now supports
239 :variable:`CPACK_NSIS_UNINSTALL_NAME`.
240 This can be used to specify the name of the Uninstall program.
242 * The :cpack_gen:`CPack NSIS Generator` now supports
243 :variable:`CPACK_NSIS_WELCOME_TITLE` and
244 :variable:`CPACK_NSIS_WELCOME_TITLE_3LINES`.
245 These can be used to specify the welcome page title and display it in 3 lines.
247 * The :cpack_gen:`CPack NSIS Generator` now supports
248 :variable:`CPACK_NSIS_FINISH_TITLE` and
249 :variable:`CPACK_NSIS_FINISH_TITLE_3LINES`.
250 These can be used to specify the finish page title and display it in 3 lines.
252 * The :cpack_gen:`CPack productbuild Generator` gained support for a
253 :variable:`CPACK_PRODUCTBUILD_BACKGROUND` variable to specify a background
254 image for the macOS installer.
259 * :manual:`ccmake(1)` now displays cache values using colors
260 based on the entry type if the terminal supports color.
262 * :manual:`ccmake(1)` now displays messages and a progress bar during
263 configure and generate. It will keep the output displayed if any
264 errors or warnings occurred.
266 Deprecated and Removed Features
267 ===============================
269 * An explicit deprecation diagnostic was added for policy ``CMP0068``
270 and policy ``CMP0069`` (``CMP0067`` and below were already deprecated).
271 The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
272 of all policies are deprecated and that projects should port to the
275 * The :cpack_gen:`CPack PackageMaker Generator` generator has been
276 deprecated because Xcode no longer distributes the PackageMaker tools.
277 The undocumented ``OSXX11`` generator has also been deprecated.
279 * The :manual:`cmake(1)` command-line ``-E remove`` and ``-E remove_directory``
280 tools are deprecated in favor of the new ``-E rm`` tool. The older tools
281 always returned 0 if a named path did not exist even without the force
282 option and cannot be fixed without breaking compatibility, and so have
285 * The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.0 or later.
290 * The :manual:`file API <cmake-file-api(7)>` index file now emits a
291 ``multiConfig`` flag specifying whether or not the generator supports
292 multiple output configurations.
294 * Target link properties :prop_tgt:`INTERFACE_LINK_OPTIONS`,
295 :prop_tgt:`INTERFACE_LINK_DIRECTORIES` and
296 :prop_tgt:`INTERFACE_LINK_DEPENDS` are now transitive over private
297 dependencies on static libraries.
298 See policy :policy:`CMP0099`.
300 * When using MinGW tools, the :command:`find_library` command no longer
301 finds ``.dll`` files by default. Instead, it expects ``.dll.a`` import
302 libraries to be available.
304 * The :generator:`MinGW Makefiles` generator no longer issues an error if
305 ``sh.exe`` is present in the environment's ``PATH``.
307 * The :generator:`Ninja` generator now prefers the first ninja build
308 tool to appear in the ``PATH`` no matter whether it is called
309 ``ninja-build``, ``ninja``, or ``samu``. Previously the first
310 of those names to appear anywhere in the ``PATH`` would be preferred.
312 * With SDCC the ``sdar`` tool is now preferred over ``sdcclib`` as librarian.
313 The latter was deprecated by SDCC 3.2.0 and removed in SDCC 3.8.6.
315 * With SDCC the default flags no longer include any target-specific flags.
316 Previously the default flags were hard-coded for 8051.
318 * The :variable:`CMAKE_VS_GLOBALS` variable value now applies during
319 compiler identification and in targets created by the
320 :command:`add_custom_target` command.
322 * The :generator:`Xcode` generator no longer hard-codes ``-Wmost``,
323 ``-Wno-four-char-constants``, and ``-Wno-unknown-pragmas`` warning flags.
328 Changes made since CMake 3.17.0 include the following.
333 * CMake 3.17.0 updated the :cpack_gen:`CPack NSIS Generator` with changes
334 that require NSIS 3.0 or later. CMake 3.17.1 now enforces the use
335 of a sufficiently new version.
340 * Selection of the Objective C or C++ compiler now considers the
341 :envvar:`CC` or :envvar:`CXX` environment variable if the
342 :envvar:`OBJC` or :envvar:`OBJCXX` environment variable is not set.
344 * The :module:`FindPkgConfig` module now extracts include directories
345 prefixed with ``-isystem`` into the ``*_INCLUDE_DIRS`` variables and
346 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target properties.
347 Previously they would be places in ``*_CFLAGS_OTHER`` variables and
348 :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties.
353 * The default value of :variable:`CMAKE_AUTOMOC_PATH_PREFIX` was changed to
354 ``OFF`` because this feature can break existing projects that have
355 identically named header files in different include directories.
356 This restores compatibility with behavior of CMake 3.15 and below.
357 The default was also changed to ``OFF`` in 3.16.9.