3.14.rst 14 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 17 18
* The :generator:`Visual Studio 16 2019` generator was added.  This is
  experimental and based on "Visual Studio 2019 Preview 2" because this
  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
File-Based API
--------------
30

31 32 33
* 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.
34

35 36
Platforms
---------
37

38 39
* CMake now supports :ref:`Cross Compiling for iOS, tvOS, or watchOS`
  using simple toolchain files.
40

41 42
Command-Line
------------
43

44 45 46 47 48 49 50 51
* 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.
52 53 54 55

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

56 57
Commands
--------
58

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

62 63
* The :command:`file` command gained a ``SIZE`` mode to get the size
  of a file on disk.
64

65 66 67
* 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.
68

69 70 71
* 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.
72

73 74
* The :command:`if` command gained support for checking if cache variables
  are defined with the  ``DEFINED CACHE{VAR}`` syntax.
75

76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
* 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.

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.
115 116 117 118 119

* 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.

120 121 122 123
* 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`.
124

125 126
* :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` target property gains the
  support of :manual:`generator expressions <cmake-generator-expressions(7)>`.
127

128 129
Modules
-------
130

131 132 133 134 135 136
* 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.
137 138 139 140 141 142 143 144 145 146 147 148

* 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.

* The :module:`ExternalProject` module's ``ExternalProject_Add`` command
  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``.

149 150 151 152 153
* 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.
154

155 156 157
* 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`.
158 159 160 161 162 163

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

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

164
* The :module:`FindGDAL` module now provides imported targets.
165 166 167

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

168 169
* The :module:`FindGit` module now provides an imported target for the
  Git executable.
170

171 172
* The :module:`FindIce` module learned to find ``slice2confluence``
  and ``slice2matlab``.
173 174 175

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

176
* The :module:`FindLibLZMA` module now provides imported targets.
177 178 179 180 181 182 183 184

* 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.

* A :module:`FindOctave` module was added to find GNU octave.

185
* The :module:`FindPostgreSQL` module now provides imported targets.
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223

* 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``.
224

225 226
* The :module:`FindX11` now provides imported targets.

227 228 229 230 231 232 233 234 235 236 237 238 239
* 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
---------------------

240 241 242
* The ``$<Fortran_COMPILER_ID:...>`` and ``$<Fortran_COMPILER_VERSION:...>``
  :manual:`generator expressions <cmake-generator-expressions(7)>` were added.

243 244
* The ``$<IN_LIST:...>`` generator expression now correctly handles an
  empty argument. See :policy:`CMP0085` for details.
245

246 247
Autogen
-------
248

249 250 251 252
* 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.
253

254 255
  Setting these will also prevent the configure time testing for these
  executables. This is mainly useful when you build these tools yourself.
256

257 258 259 260 261
* 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.
262

263 264 265 266
* 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.
267

268 269
CTest
-----
270

271 272 273
* :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.
274

275 276
* 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.
277

278 279 280 281
* 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.
282

283 284
Deprecated and Removed Features
===============================
285

286 287 288 289 290 291 292 293 294 295 296 297 298 299 300
* 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`.
301 302 303 304 305 306 307 308 309

* 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``.

310 311
Other Changes
=============
312

313 314
* Object library linking has been fixed to propagate transitive link
  dependencies of object libraries to consuming targets.
315

316 317
* Install rules under :command:`add_subdirectory` now interleave with those in
  the calling directory. See policy :policy:`CMP0082` for details.
318

319 320 321
* 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`.
322

323 324 325 326 327 328 329 330 331 332
* 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`.
333 334 335 336

* :ref:`Visual Studio Generators` for VS 2010 and above learned
  to support the ``VS_DEBUGGER_*`` properties on targets created
  via :command:`add_custom_target`.
337 338 339 340 341

* 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.