3.14.rst 17.7 KB
Newer Older
1 2 3 4 5 6 7 8 9
CMake 3.14 Release Notes
************************

.. only:: html

  .. contents::

Changes made since CMake 3.13 include the following.

10 11
New Features
============
12

13 14
Generators
----------
15

16
* The :generator:`Visual Studio 16 2019` generator was added.  This is
17
  experimental and based on "Visual Studio 2019 Preview 4" because this
18
  version of VS has not been released.
19

20 21 22 23 24 25 26
  The VS 2019 generator differs from generators for earlier versions
  in that it does not provide variants that specify the target platform
  in the generator name.  Instead :variable:`CMAKE_GENERATOR_PLATFORM`
  must be used, e.g. through the ``-A`` command-line option.  Furthermore,
  the default target platform (architecture) is now based on the *host*
  platform.  The VS host toolset selection is now based on the host
  architecture as well.
27

28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
* The :generator:`Green Hills MULTI` generator has been updated:

  * Now supports :ref:`Object Libraries`.

  * Now warns on unsupported project types such as shared libraries.

  * Now generates a top-level ``<PROJECT-NAME>.top.gpj`` for each directory
    calling the :command:`project` command.  The top-level project file
    ``default.gpj`` is no longer created.

  * Now honors target renaming and destination output control properties
    such as :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`OUTPUT_NAME`.
    This also fixes support for installation rules generated by
    :command:`install`.

  * Now honors source file properties :prop_sf:`INCLUDE_DIRECTORIES`,
    :prop_sf:`COMPILE_DEFINITIONS`, and :prop_sf:`COMPILE_OPTIONS`.

  * Now supports Dynamic Download Integrity Applications which did not include
    Integrate Files via :prop_tgt:`GHS_INTEGRITY_APP` and setting a target
    link flag of ``-dynamic``.

  * The contents of project files now sorts sources groups and files by name.
    Set the :prop_tgt:`GHS_NO_SOURCE_GROUP_FILE` target property to ``ON`` to
    generate a single project file for the target instead of a project file for
    each source group.  Set the :variable:`CMAKE_GHS_NO_SOURCE_GROUP_FILE`
    variable to enable this for all targets.

56 57
File-Based API
--------------
58

59 60 61
* A file-based api for clients to get semantic buildsystem information
  has been added.  See the :manual:`cmake-file-api(7)` manual.
  This is intended to replace the :manual:`cmake-server(7)` mode for IDEs.
62

63 64
Platforms
---------
65

66 67
* CMake now supports :ref:`Cross Compiling for iOS, tvOS, or watchOS`
  using simple toolchain files.
68

69 70
Command-Line
------------
71

72 73 74 75 76 77 78 79
* The :manual:`cmake(1)` :ref:`Build Tool Mode <Build Tool Mode>`
  (``cmake --build``) gained ``--verbose`` and ``-v`` options to
  specify verbose build output. Some generators such as Xcode don't
  support this option currently.

* The :manual:`cmake(1)` ``-E compare_files`` command learned a new
  ``--ignore-eol`` option to specify that end-of-line differences
  (e.g. LF vs CRLF) should be ignored when comparing files.
80 81 82 83

* The :manual:`cmake-gui(1)` dialog gained new ``-S`` and ``-B`` arguments to
  explicitly specify source and build directories.

84 85
Commands
--------
86

87 88 89
* The :command:`file` command learned a new sub-command, ``CREATE_LINK``,
  which can be used to create hard or symbolic links.

90 91
* The :command:`file` command learned a new sub-command, ``READ_SYMLINK``,
  which can be used to determine the path that a symlink points to.
92

93 94
* The :command:`file` command gained a ``SIZE`` mode to get the size
  of a file on disk.
95

96 97 98
* The :command:`find_package` command learned to optionally resolve
  symbolic links in the paths to package configuration files.
  See the :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` variable.
99

100 101 102
* The :command:`get_filename_component` command gained new
  ``LAST_EXT`` and ``NAME_WLE`` variants to work with the
  extension after the last ``.`` in the name.
103

104 105
* The :command:`if` command gained support for checking if cache variables
  are defined with the  ``DEFINED CACHE{VAR}`` syntax.
106

107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands
  learned to support generator expressions.  See policy :policy:`CMP0087`.

* The :command:`install(TARGETS)` command learned how to install to an
  appropriate default directory for a given target type, based on
  variables from the :module:`GNUInstallDirs` module and built-in defaults,
  in lieu of a ``DESTINATION`` argument.

* The :command:`install(FILES)` and :command:`install(DIRECTORY)` commands
  learned a new set of parameters for installing files as a file type,
  setting the destination based on the appropriate variables from
  :module:`GNUInstallDirs` and built-in defaults, in lieu of a
  ``DESTINATION`` argument.

* The :command:`list` operations ``REMOVE_ITEM``, ``REMOVE_DUPLICATES``,
  ``SORT``, ``REVERSE``, and ``FILTER`` all now accept a non-existent variable
  as the list since these operations on empty lists is also the empty list.

* The :command:`list` operation ``REMOVE_AT`` now indicates that the given
  indices are invalid for a non-existent variable or empty list.

* The :command:`try_compile` and :command:`try_run` commands gained a new
  ``LINK_OPTIONS`` option.

Variables
---------

* A :variable:`CMAKE_BUILD_RPATH_USE_ORIGIN` variable and corresponding
  :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target property were added to
  enable use of relative runtime paths (RPATHs). This helps achieving
  relocatable and reproducible builds that are invariant of the build
  directory.

140 141 142 143
* A :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable was added for
  :ref:`Visual Studio Generators` to report their default platform used
  when :variable:`CMAKE_GENERATOR_PLATFORM` is not set explicitly.

144 145 146 147 148 149
Properties
----------

* A :prop_gbl:`CMAKE_ROLE` global property was added to allow scripts to
  determine whether they're running in project mode, script mode,
  find-package mode, CTest, or CPack.
150 151 152 153 154

* The :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target property is now supported
  on shared library, module library, and executable targets.  Previously it was
  only honored on static libraries.

155 156 157 158
* The :prop_tgt:`EXCLUDE_FROM_ALL` target property was created to override
  the setting of its directory. A target will now be built as part of "all"
  if its :prop_tgt:`EXCLUDE_FROM_ALL` property is set to ``OFF``, even if its
  containing directory is marked as :prop_dir:`EXCLUDE_FROM_ALL`.
159

160 161
* :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` target property gains the
  support of :manual:`generator expressions <cmake-generator-expressions(7)>`.
162

163 164
Modules
-------
165

166 167 168 169 170 171
* The family of modules to check capabilities (like
  :module:`CheckCSourceCompiles`) gain capability to manage ``LINK_OPTIONS``.

* A :module:`CheckFortranSourceRuns` module was added to provide a
  :command:`check_fortran_source_runs` command to check if a Fortran
  source snippet compiles and runs.
172

173 174 175 176 177
* The :module:`CMakePackageConfigHelpers` module's
  :command:`write_basic_package_version_file` command gained a new
  ``ARCH_INDEPENDENT`` option for supporting architecture-independent
  packages.

178 179 180 181 182 183
* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
  gained ``LOG_DIR`` and ``LOG_MERGED_STDOUTERR`` options to control logging.

* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
  gained ``LOG_PATCH`` to optionally log the patch step.

184
* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
185 186 187 188
  learned to apply ``SOURCE_SUBDIR`` when ``BUILD_IN_SOURCE`` is also used.
  The ``BUILD_COMMAND`` is run in the given ``SOURCE_SUBDIR`` of the
  ``SOURCE_DIR``.

189 190 191 192 193
* The :module:`FetchContent` module gained a new
  :command:`FetchContent_MakeAvailable` command.  It accepts a list of
  dependency names, which it then iterates over, populating and adding
  each one to the main build using the canonical pattern.  This
  significantly reduces the amount of boilerplate needed in a project.
194

195 196 197
* The :module:`FindBISON` module's ``BISON_TARGET`` command now runs ``bison``
  with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory.
  See policy :policy:`CMP0088`.
198 199 200 201 202 203

* The :module:`FindCURL` module gained support for requesting
  protocols as package components.

* The :module:`FindFontconfig` module was added to find `fontconfig`_.

204
* The :module:`FindGDAL` module now provides imported targets.
205 206 207

* The :module:`FindGIF` module now provides imported targets.

208 209
* The :module:`FindGit` module now provides an imported target for the
  Git executable.
210

211 212
* The :module:`FindIce` module learned to find ``slice2confluence``
  and ``slice2matlab``.
213 214 215

* The :module:`FindLibinput` module was added to find `libinput`_.

216
* The :module:`FindLibLZMA` module now provides imported targets.
217 218 219 220 221 222

* The :module:`FindMatlab` module gained new options ``R2017b`` and
  ``R2018a`` to specify the MEX API version to use; these options
  mirror the new options to the ``mex`` command in MATLAB R2018a.
  The option ``MX_LIBRARY`` is no longer needed.

223
* The :module:`FindPostgreSQL` module now provides imported targets.
224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261

* The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3`
  modules gained support for ``NumPy`` component.

* The :module:`FindPython2`, :module:`FindPython3`, and :module:`FindPython`
  modules now support running in script mode by skipping the creation of
  imported targets and helper functions.

* The :module:`FindSQLite3` module was added to find the SQLite v3.x library.

* The :module:`FindX11` had the following variables renamed in order to match
  their library names rather than header names. The old variables are provided
  for compatibility:

    - ``X11_Xxf86misc_INCLUDE_PATH`` instead of ``X11_xf86misc_INCLUDE_PATH``
    - ``X11_Xxf86misc_LIB`` instead of ``X11_xf86misc_LIB``
    - ``X11_Xxf86misc_FOUND`` instead of ``X11_xf86misc_FOUND``
    - ``X11_Xxf86vm_INCLUDE_PATH`` instead of ``X11_xf86vmode_INCLUDE_PATH``
    - ``X11_Xxf86vm_LIB`` instead of ``X11_xf86vmode_LIB``
    - ``X11_Xxf86vm_FOUND`` instead of ``X11_xf86vmode_FOUND``
    - ``X11_xkbfile_INCLUDE_PATH`` instead of ``X11_Xkbfile_INCLUDE_PATH``
    - ``X11_xkbfile_LIB`` instead of ``X11_Xkbfile_LIB``
    - ``X11_xkbfile_FOUND`` instead of ``X11_Xkbfile_FOUND``
    - ``X11_Xtst_INCLUDE_PATH`` instead of ``X11_XTest_INCLUDE_PATH``
    - ``X11_Xtst_LIB`` instead of ``X11_XTest_LIB``
    - ``X11_Xtst_FOUND`` instead of ``X11_XTest_FOUND``
    - ``X11_Xss_INCLUDE_PATH`` instead of ``X11_Xscreensaver_INCLUDE_PATH``
    - ``X11_Xss_LIB`` instead of ``X11_Xscreensaver_LIB``
    - ``X11_Xss_FOUND`` instead of ``X11_Xscreensaver_FOUND``

  The following variables are deprecated completely since they were
  essentially duplicates:

    - ``X11_Xinput_INCLUDE_PATH`` (use ``X11_Xi_INCLUDE_PATH``)
    - ``X11_Xinput_LIB`` (use ``X11_Xi_LIB``)
    - ``X11_Xinput_FOUND`` (use ``X11_Xi_FOUND``)

* The :module:`FindX11` now provides ``X11_Xext_INCLUDE_PATH``.
262

263 264
* The :module:`FindX11` now provides imported targets.

265 266 267 268 269 270 271 272 273 274 275 276 277
* The :module:`UseSWIG` module learned to pass ``-module <module_name>`` to
  the ``SWIG`` compiler if the file property ``SWIG_MODULE_NAME`` is defined.
  See policy :policy:`CMP0086`.

* The :module:`UseSWIG` module gained an option to specify
  ``SWIG`` source file extensions.

.. _`fontconfig`: https://www.freedesktop.org/wiki/Software/fontconfig/
.. _`libinput`: https://www.freedesktop.org/wiki/Software/libinput/

Generator Expressions
---------------------

278 279 280
* The ``$<Fortran_COMPILER_ID:...>`` and ``$<Fortran_COMPILER_VERSION:...>``
  :manual:`generator expressions <cmake-generator-expressions(7)>` were added.

281 282
* The ``$<IN_LIST:...>`` generator expression now correctly handles an
  empty argument. See :policy:`CMP0085` for details.
283

284 285
Autogen
-------
286

287 288 289 290
* The :prop_tgt:`AUTOMOC_EXECUTABLE`, :prop_tgt:`AUTORCC_EXECUTABLE`, and
  :prop_tgt:`AUTOUIC_EXECUTABLE` target properties were added.  They all
  take a path to an executable and force automoc/autorcc/autouic to use
  this executable.
291

292 293
  Setting these will also prevent the configure time testing for these
  executables. This is mainly useful when you build these tools yourself.
294

295 296 297 298 299
* The new variables :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`,
  :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`,
  :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` and
  :variable:`CMAKE_GLOBAL_AUTORCC_TARGET_NAME` control the generation
  of global ``autogen`` and ``autorcc`` targets.
300

301 302 303 304
* A new :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` variable and
  :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` target property may be set to enable or
  disable forwarding of the origin target dependencies to the corresponding
  ``_autogen`` target.
305

306 307
CTest
-----
308

309 310 311
* :manual:`ctest(1)` gained a ``--show-only=json-v1`` option to show the
  list of tests in a machine-readable JSON format.
  See the :ref:`Show as JSON Object Model` section of the manual.
312

313 314
* The :command:`ctest_submit` command learned a new ``Done`` part that can be used
  to inform CDash that a build is complete and that no more parts will be uploaded.
315

316 317 318 319
* CTest learned to accept the dashboard server submission URL from a single
  variable.  See the ``SubmitURL`` setting in :manual:`ctest(1)`,
  the :variable:`CTEST_SUBMIT_URL` variable, and the ``SUBMIT_URL``
  argument of the :command:`ctest_submit` command.
320

321 322
Deprecated and Removed Features
===============================
323

324 325 326 327 328 329 330 331 332 333 334 335 336 337 338
* An explicit deprecation diagnostic was added for policies ``CMP0064``
  and ``CMP0065`` (``CMP0063`` and below were already deprecated).
  The :manual:`cmake-policies(7)` manual explains that the OLD behaviors
  of all policies are deprecated and that projects should port to the
  NEW behaviors.

* The :generator:`Xcode` generator deprecated support for Xcode
  versions prior to Xcode 5.  Support for those will be dropped in a
  future version of CMake.

* The :module:`FindQt` module is no longer used by the :command:`find_package`
  command as a find module.  This allows the Qt Project upstream to optionally
  provide its own ``QtConfig.cmake`` package configuration file and have
  applications use it via ``find_package(Qt)`` rather than
  ``find_package(Qt CONFIG)``.  See policy :policy:`CMP0084`.
339 340 341 342 343 344 345 346 347

* Support for running CMake on Windows XP and Windows Vista has been dropped.
  The precompiled Windows binaries provided on ``cmake.org`` now require
  Windows 7 or higher.

* CTest no longer supports submissions via ``ftp``, ``scp``, ``cp``, and
  ``xmlrpc``.  CDash is the only maintained testing dashboard for CTest,
  and it only supports submissions over ``http`` and ``https``.

348 349
Other Changes
=============
350

351 352
* Object library linking has been fixed to propagate private link libraries
  of object libraries to consuming targets.
353

354 355
* Install rules under :command:`add_subdirectory` now interleave with those in
  the calling directory. See policy :policy:`CMP0082` for details.
356

357 358 359
* CMake now imposes a maximum recursion limit to prevent a stack overflow on
  scripts that recurse infinitely. The limit can be adjusted at runtime with
  :variable:`CMAKE_MAXIMUM_RECURSION_DEPTH`.
360

361 362 363 364 365 366 367 368 369 370
* When using cppcheck via the :variable:`CMAKE_<LANG>_CPPCHECK` variable
  or :prop_tgt:`<LANG>_CPPCHECK` property, the build will now fail if
  ``cppcheck`` returns non-zero as configured by its command-line options.

* Required link options to manage Position Independent Executable are now
  added when :prop_tgt:`POSITION_INDEPENDENT_CODE` is set.  The project is
  responsible for using the :module:`CheckPIESupported` module to check for
  ``PIE`` support to ensure that the :prop_tgt:`POSITION_INDEPENDENT_CODE`
  target property will be honored at link time for executables.  This behavior
  is controlled by policy :policy:`CMP0083`.
371 372 373 374

* :ref:`Visual Studio Generators` for VS 2010 and above learned
  to support the ``VS_DEBUGGER_*`` properties on targets created
  via :command:`add_custom_target`.
375 376 377 378 379

* The :module:`CPack` module no longer defaults to the ``paxr`` value in the
  :variable:`CPACK_DEBIAN_ARCHIVE_TYPE` variable, because ``dpkg`` has
  never supported the PAX tar format. The ``paxr`` value will be mapped
  to ``gnutar`` and a deprecation message emitted.
380 381 382 383

* CMake no longer issues a warning if a target listed in an
  :command:`install(TARGETS)` command has its :prop_tgt:`EXCLUDE_FROM_ALL`
  property set to true.
384 385 386 387 388 389 390 391 392 393 394 395 396 397

Updates
=======

Changes made since CMake 3.14.0 include the following.

3.14.1
------

* The :module:`FindFontconfig` module added by 3.14.0 accidentally
  used uppercase ``FONTCONFIG_*`` variable names that do not match
  our conventions.  3.14.1 revises the module to use ``Fontconfig_*``
  variable names.  This is incompatible with 3.14.0 but since the
  module is new in the 3.14 series usage should not yet be widespread.
398 399 400 401 402 403 404

3.14.3
------

* The :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable was added
  to help toolchain files work with the :generator:`Visual Studio 16 2019`
  generator where the default platform now depends on the host platform.
Brad King's avatar
Brad King committed
405 406 407 408 409 410 411 412 413 414

3.14.4
------

* In CMake 3.14.0 through 3.14.3, calling :command:`target_link_libraries`
  to add ``PRIVATE`` dependencies to a static library created in another
  directory (under policy :policy:`CMP0079` ``NEW`` behavior) would
  incorrectly propagate usage requirements of those dependencies to
  dependents that link the static library.  This has been fixed.
  The bug also existed in 3.13.0 through 3.13.4 and is fixed in 3.13.5.
415 416 417 418 419 420 421 422

3.14.5
------

* Entries of the ``CPATH`` environment variable are no longer excluded
  from explicit use via :command:`include_directories` and
  :command:`target_include_directories` as they were in CMake 3.14.0
  through 3.14.4.
423 424 425 426 427 428 429 430

3.14.6
------

* In CMake 3.14.0 through 3.14.5, the :module:`FindBISON` module
  policy :policy:`CMP0088` ``NEW`` behavior accidentally interpreted
  a relative path to the ``.y`` input as relative to the build tree
  directory instead of the source tree directory.  This has been fixed.
431 432 433 434 435 436 437 438

3.14.7
------

* In CMake 3.14.0 through 3.14.6, the :prop_dir:`EXCLUDE_FROM_ALL`
  directory property was regressed from pre-3.14 behavior and caused
  targets within the directory to be excluded even from its own "all".
  This has been fixed.