summaryrefslogtreecommitdiffstats
path: root/Help
diff options
context:
space:
mode:
authorBrad King <brad.king@kitware.com>2019-02-06 14:17:55 (GMT)
committerBrad King <brad.king@kitware.com>2019-02-06 14:52:35 (GMT)
commitaa9161fd577bfd6a6bf98200d4e437effe9f0628 (patch)
treeb53784978764c076bb35547d515f92f85a8132e9 /Help
parent0d1a9282c42cd278f99b09bb16cace47be421717 (diff)
downloadCMake-aa9161fd577bfd6a6bf98200d4e437effe9f0628.zip
CMake-aa9161fd577bfd6a6bf98200d4e437effe9f0628.tar.gz
CMake-aa9161fd577bfd6a6bf98200d4e437effe9f0628.tar.bz2
Help: Organize and revise 3.14 release notes
Add section headers similar to the 3.13 release notes and move each individual bullet into an appropriate section. Revise a few bullets.
Diffstat (limited to 'Help')
-rw-r--r--Help/release/3.14.rst354
1 files changed, 200 insertions, 154 deletions
diff --git a/Help/release/3.14.rst b/Help/release/3.14.rst
index a1c6e24..ff499f5 100644
--- a/Help/release/3.14.rst
+++ b/Help/release/3.14.rst
@@ -7,102 +7,133 @@ CMake 3.14 Release Notes
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.
+New Features
+============
- Setting these will also prevent the configure time testing for these
- executables. This is mainly useful when you build these tools yourself.
+Generators
+----------
-* 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.
+* 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.
-* 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 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.
-* 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.
+File-Based API
+--------------
-* The :command:`list` operation ``REMOVE_AT`` now indicates that the given
- indices are invalid for a non-existent variable or empty list.
+* 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.
-* 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`.
+Platforms
+---------
-* 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.
+* CMake now supports :ref:`Cross Compiling for iOS, tvOS, or watchOS`
+ using simple toolchain files.
-* The family of modules to check capabilities (like
- :module:`CheckCSourceCompiles`) gain capability to manage ``LINK_OPTIONS``.
+Command-Line
+------------
-* 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(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.
* 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.
+Commands
+--------
-* 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 :command:`file` command learned a new sub-command, ``READ_SYMLINK``,
+ which can be used to determine the path that a symlink points to.
-* 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.
+* The :command:`file` command gained a ``SIZE`` mode to get the size
+ of a file on disk.
-* 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:`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 :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.
+* 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.
-* :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.
+* The :command:`if` command gained support for checking if cache variables
+ are defined with the ``DEFINED CACHE{VAR}`` syntax.
-* 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 :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.
* 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`.
+* 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`.
-* 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.
+* :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` target property gains the
+ support of :manual:`generator expressions <cmake-generator-expressions(7)>`.
-* 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.
+Modules
+-------
-* 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 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.
* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
gained ``LOG_DIR`` and ``LOG_MERGED_STDOUTERR`` options to control logging.
@@ -115,43 +146,34 @@ Changes made since CMake 3.13 include the following.
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 :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.
-* The :command:`file` command gained a ``SIZE`` mode to get the size
- of a file on disk.
+* 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`.
* 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:`FindGDAL` module now provides imported targets.
* The :module:`FindGIF` module now provides imported targets.
-* The :module:`FindGit` module now provides an ``IMPORTED`` target for the Git
- executable.
+* 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:`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:`FindLibLZMA` module now provides imported targets.
* The :module:`FindMatlab` module gained new options ``R2017b`` and
``R2018a`` to specify the MEX API version to use; these options
@@ -160,11 +182,7 @@ Changes made since CMake 3.13 include the following.
* 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:`FindPostgreSQL` module now provides imported targets.
* The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3`
modules gained support for ``NumPy`` component.
@@ -203,62 +221,83 @@ Changes made since CMake 3.13 include the following.
- ``X11_Xinput_FOUND`` (use ``X11_Xi_FOUND``)
* The :module:`FindX11` now provides ``X11_Xext_INCLUDE_PATH``.
+
* The :module:`FindX11` now provides imported targets.
+* 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
+---------------------
+
* 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 ``$<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.
+Autogen
+-------
-* The :command:`if` command gained support for checking if cache variables
- are defined with the ``DEFINED CACHE{VAR}`` syntax.
+* 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.
-* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands
- learned to support generator expressions. See policy :policy:`CMP0087`.
+ Setting these will also prevent the configure time testing for these
+ executables. This is mainly useful when you build these tools yourself.
-* 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.
+* 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.
-* Install rules under :command:`add_subdirectory` now interleave with those in
- the calling directory. See policy :policy:`CMP0082` for details.
+* 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.
-* :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` target property gains the
- support of :manual:`generator expressions <cmake-generator-expressions(7)>`.
+CTest
+-----
-* CMake now supports :ref:`Cross Compiling for iOS, tvOS, or watchOS`
- using simple toolchain files.
+* :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.
-* 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`.
+* 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.
-* 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`.
+* 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.
-* Object library linking has been fixed to propagate transitive link
- dependencies of object libraries to consuming targets.
+Deprecated and Removed Features
+===============================
-* 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.
+* 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`.
* Support for running CMake on Windows XP and Windows Vista has been dropped.
The precompiled Windows binaries provided on ``cmake.org`` now require
@@ -268,28 +307,35 @@ Changes made since CMake 3.13 include the following.
``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``.
+Other Changes
+=============
-* 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`.
+* Object library linking has been fixed to propagate transitive link
+ dependencies of object libraries to consuming targets.
-* The :module:`UseSWIG` module gains capability to specify
- ``SWIG`` source file extensions.
+* Install rules under :command:`add_subdirectory` now interleave with those in
+ the calling directory. See policy :policy:`CMP0082` for details.
-* 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.
+* 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`.
- 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.
+* 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`.
* :ref:`Visual Studio Generators` for VS 2010 and above learned
to support the ``VS_DEBUGGER_*`` properties on targets created
via :command:`add_custom_target`.
+
+* 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.