Help/release/3.17.rst

   1 CMake 3.17 Release Notes
   2 ************************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 3.16 include the following.
   9
  10 New Features
  11 ============
  12
  13 Generators
  14 ----------
  15
  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.
  19
  20 * :ref:`Visual Studio Generators` learned to support per-config sources.
  21   Previously only :ref:`Command-Line Build Tool Generators` supported them.
  22
  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.
  26
  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.
  31
  32 Languages
  33 ---------
  34
  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`.
  39
  40 Compilers
  41 ---------
  42
  43 * The IBM XL Fortran compiler is now supported by the :generator:`Ninja`
  44   generator.
  45
  46 Command-Line
  47 ------------
  48
  49 * :manual:`cmake(1)` gained a ``--debug-find`` command-line option to
  50   enable additional human-readable output on where ``find_*`` commands search.
  51
  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.
  56
  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.
  60
  61 Commands
  62 --------
  63
  64 * The :command:`add_custom_command` command learned to interpret paths in
  65   ``DEPENDS`` arguments that are specified relative to the current
  66   binary directory.
  67
  68 * The :command:`foreach` command learned a new ``ZIP_LISTS`` option to iterate
  69   over multiple lists simultaneously.
  70
  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>`.
  73
  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.
  78
  79 * The :command:`message` command gained new keywords ``CHECK_START``,
  80   ``CHECK_PASS`` and ``CHECK_FAIL``.
  81
  82 * The :command:`target_compile_options` command now honors the ``BEFORE``
  83   keyword more consistently.  See policy :policy:`CMP0101`.
  84
  85 Variables
  86 ---------
  87
  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.
  91
  92 * The following variables are now defined inside a :command:`function`:
  93
  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`
  98
  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
 102   use CUDA.
 103
 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.
 107
 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.
 111
 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.
 115
 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.
 119
 120 * The :variable:`CMAKE_XCODE_SCHEME_ENVIRONMENT` variable was added
 121   to initialize the :prop_tgt:`XCODE_SCHEME_ENVIRONMENT` target property.
 122
 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.
 127
 128 Properties
 129 ----------
 130
 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
 134   libraries on AIX.
 135
 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
 139   at generate time.
 140
 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.
 145
 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.
 152
 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.
 156
 157 Modules
 158 -------
 159
 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.
 164
 165 * The :module:`FindCUDAToolkit` module was added to find the
 166   CUDA Toolkit without enabling CUDA as a language.
 167
 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.
 172
 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`.
 176
 177 * The :module:`FindLibArchive` module now provides an imported target
 178   for libarchive.
 179
 180 * The :module:`FindPython` module has learned to find Python components
 181   in active virtual environments managed by ``conda``.
 182
 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``.
 188
 189 * The :module:`FindLibXml2` module now provides an imported target for the
 190   ``xmllint`` executable.
 191
 192 Autogen
 193 -------
 194
 195 * :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` learned to process headers
 196   with a ``.hh`` extension.  See policy :policy:`CMP0100`.
 197
 198 CTest
 199 -----
 200
 201 * The :variable:`CTEST_CONFIGURATION_TYPE` variable is now set from the
 202   command line when :manual:`ctest(1)` is invoked with ``-C <cfg>``.
 203
 204 * The :manual:`ctest(1)` tool gained support for Dr. Memory to run
 205   memcheck runs.
 206
 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.
 210
 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``.
 215
 216 * The :command:`ctest_test` command gained a ``REPEAT <mode>:<n>`` option
 217   to specify conditions in which to repeat tests.
 218
 219 CPack
 220 -----
 221
 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
 225   their own DMGs.
 226
 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.
 232
 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.
 237
 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.
 241
 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.
 246
 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.
 251
 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.
 255
 256 Other
 257 -----
 258
 259 * :manual:`ccmake(1)` now displays cache values using colors
 260   based on the entry type if the terminal supports color.
 261
 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.
 265
 266 Deprecated and Removed Features
 267 ===============================
 268
 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
 273   NEW behaviors.
 274
 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.
 278
 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
 283   been superseded.
 284
 285 * The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.0 or later.
 286
 287 Other Changes
 288 =============
 289
 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.
 293
 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`.
 299
 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.
 303
 304 * The :generator:`MinGW Makefiles` generator no longer issues an error if
 305   ``sh.exe`` is present in the environment's ``PATH``.
 306
 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.
 311
 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.
 314
 315 * With SDCC the default flags no longer include any target-specific flags.
 316   Previously the default flags were hard-coded for 8051.
 317
 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.
 321
 322 * The :generator:`Xcode` generator no longer hard-codes ``-Wmost``,
 323   ``-Wno-four-char-constants``, and ``-Wno-unknown-pragmas`` warning flags.
 324
 325 Updates
 326 =======
 327
 328 Changes made since CMake 3.17.0 include the following.
 329
 330 3.17.1
 331 ------
 332
 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.