CMake 3.14 Release Notes ************************ .. only:: html .. contents:: Changes made since CMake 3.13 include the following. New Features ============ Generators ---------- * The :generator:`Visual Studio 16 2019` generator was added. This is experimental and based on "Visual Studio 2019 Preview 4" 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. * 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 ``.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. File-Based API -------------- * 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. Platforms --------- * CMake now supports :ref:`Cross Compiling for iOS, tvOS, or watchOS` using simple toolchain files. 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)` ``-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. Commands -------- * The :command:`file` command learned a new sub-command, ``CREATE_LINK``, which can be used to create hard or symbolic links. * 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 :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:`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 :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. * 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. 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 :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`. * :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` target property gains the support of :manual:`generator expressions `. Modules ------- * 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:`CMakePackageConfigHelpers` module's :command:`write_basic_package_version_file` command gained a new ``ARCH_INDEPENDENT`` option for supporting architecture-independent packages. * 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 :command:`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 :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 :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`_. * 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:`FindIce` module learned to find ``slice2confluence`` and ``slice2matlab``. * The :module:`FindLibinput` module was added to find `libinput`_. * 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 mirror the new options to the ``mex`` command in MATLAB R2018a. The option ``MX_LIBRARY`` is no longer needed. * The :module:`FindPostgreSQL` module now provides imported targets. * 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 :module:`UseSWIG` module learned to pass ``-module `` 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 ``$`` and ``$`` :manual:`generator expressions ` were added. * The ``$`` generator expression now correctly handles an empty argument. See :policy:`CMP0085` for details. Autogen ------- * 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. 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. CTest ----- * :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:`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. * 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. Deprecated and Removed Features =============================== * 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 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``. Other Changes ============= * Object library linking has been fixed to propagate private link libraries of object libraries to consuming targets. * Install rules under :command:`add_subdirectory` now interleave with those in the calling directory. See policy :policy:`CMP0082` for details. * 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`. * When using cppcheck via the :variable:`CMAKE__CPPCHECK` variable or :prop_tgt:`_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. * 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. 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. 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. 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. 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. 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. 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.