blob: a1c6e24bd0afd01b1e63d0ede0f5b8ab1e53674d [file] [log] [blame]
CMake 3.14 Release Notes
************************
.. only:: html
.. contents::
Changes made since CMake 3.13 include the following.
* The :prop_tgt:`AUTOMOC_EXECUTABLE`, :prop_tgt:`AUTORCC_EXECUTABLE` and
:prop_tgt:`AUTOUIC_EXECUTABLE` target properties all take a path to an
executable and force automoc/autorcc/autouic to use this executable.
Setting these will also prevent the configure time testing for these
executables. This is mainly useful when you build these tools yourself.
* 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.
* 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.
* 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 :module:`FindBISON` module's ``BISON_TARGET`` command now runs ``bison``
with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory.
See policy :policy:`CMP0088`.
* 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.
* The family of modules to check capabilities (like
:module:`CheckCSourceCompiles`) gain capability to manage ``LINK_OPTIONS``.
* The :manual:`cmake(1)` :ref:`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-gui(1)` dialog gained new ``-S`` and ``-B`` arguments to
explicitly specify source and build directories.
* A new global property, :prop_gbl:`CMAKE_ROLE`, was added to allow scripts to
determine whether they're running in project mode, script mode, find-package
mode, CTest, or CPack.
* 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.
* 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.
* 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.
* 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.
* :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.
* 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.
* 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.
* 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`.
* 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.
* A target's :prop_tgt:`EXCLUDE_FROM_ALL` property can now 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`.
* 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``.
* The FetchContent module gained a new :command:`FetchContent_MakeAvailable`
command. This new command 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 the project.
* A file-based api for clients to get semantic buildsystem information
has been added. See the :manual:`cmake-file-api(7)` manual.
* The :command:`file` command learned a new sub-command, ``READ_SYMLINK``,
which can be used to determine the path that a symlink points to.
* The :command:`file` command gained a ``SIZE`` mode to get the size
of a file on disk.
* The :module:`FindCURL` module gained support for requesting
protocols as package components.
* The :module:`FindFontconfig` module was added to find `fontconfig`_.
.. _`fontconfig`: https://www.freedesktop.org/wiki/Software/fontconfig/
* The :module:`FindGDAL` module now provides an imported target.
* The :module:`FindGIF` module now provides imported targets.
* The :module:`FindGit` module now provides an ``IMPORTED`` target for the Git
executable.
* The :module:`FindIce` module learned to find
``slice2confluence`` and ``slice2matlab``.
* The :module:`FindLibinput` module was added to find `libinput`_.
.. _`libinput`: https://www.freedesktop.org/wiki/Software/libinput/
* The :module:`FindLibLZMA` module now provides an imported target.
* 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.
* 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.
* The :module:`FindPostgreSQL` module now provides an imported target.
* 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``.
* The :module:`FindX11` now provides imported targets.
* The ``$<Fortran_COMPILER_ID:...>`` and ``$<Fortran_COMPILER_VERSION:...>``
:manual:`generator expressions <cmake-generator-expressions(7)>` were added.
* The $<IN_LIST:...> generator expression now correctly handles an empty
argument. See :policy:`CMP0085` for details.
* 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.
* The :command:`if` command gained support for checking if cache variables
are defined with the ``DEFINED CACHE{VAR}`` syntax.
* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands
learned to support generator expressions. See policy :policy:`CMP0087`.
* The ``TARGETS`` variant of the :command:`install` 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 ``FILES`` and ``DIRECTORY`` variants of the :command:`install` command
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.
* Install rules under :command:`add_subdirectory` now interleave with those in
the calling directory. See policy :policy:`CMP0082` for details.
* :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` target property gains the
support of :manual:`generator expressions <cmake-generator-expressions(7)>`.
* CMake now supports :ref:`Cross Compiling for iOS, tvOS, or watchOS`
using simple toolchain files.
* 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`.
* 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`.
* Object library linking has been fixed to propagate transitive link
dependencies of object libraries to consuming targets.
* 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.
* 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``.
* The commands :command:`try_compile` and :command:`try_run` gain new
option ``LINK_OPTIONS``.
* The :module:`UseSWIG` module passes option ``-module <module_name>`` to
``SWIG`` compiler if the file property ``SWIG_MODULE_NAME`` is defined.
See policy :policy:`CMP0086`.
* The :module:`UseSWIG` module gains capability to specify
``SWIG`` source file extensions.
* 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.
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.
* :ref:`Visual Studio Generators` for VS 2010 and above learned
to support the ``VS_DEBUGGER_*`` properties on targets created
via :command:`add_custom_target`.