Help/release/3.15.rst

   1 CMake 3.15 Release Notes
   2 ************************
   3
   4 .. only:: html
   5
   6   .. contents::
   7
   8 Changes made since CMake 3.14 include the following.
   9
  10 New Features
  11 ============
  12
  13 Generators
  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
  27 Languages
  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 serialised Swift diagnostics.
  44
  45   The Swift support is experimental, not considered stable, and may change
  46   in future releases of CMake.
  47
  48 Compilers
  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
  62 Command-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
 105 Commands
 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
 135 Variables
 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
 164 Properties
 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
 188 Modules
 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
 243 Generator 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
 287 CTest
 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
 299 CPack
 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
 306 Deprecated 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
 332 Other 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
 358 Updates
 359 =======
 360
 361 Changes made since CMake 3.15.0 include the following.
 362
 363 3.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
 375 3.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
 382 3.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
 389 3.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.