CMake 3.14 Release Notes¶
Changes made since CMake 3.13 include the following.
New Features¶
Generators¶
- The - Visual Studio 16 2019generator 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 - CMAKE_GENERATOR_PLATFORMmust be used, e.g. through the- -Acommand-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 - Green Hills MULTIgenerator has been updated:- Now supports Object Libraries. 
- Now warns on unsupported project types such as shared libraries. 
- Now generates a top-level - <PROJECT-NAME>.top.gpjfor each directory calling the- project()command. The top-level project file- default.gpjis no longer created.
- Now honors target renaming and destination output control properties such as - RUNTIME_OUTPUT_DIRECTORYand- OUTPUT_NAME. This also fixes support for installation rules generated by- install().
- Now honors source file properties - INCLUDE_DIRECTORIES,- COMPILE_DEFINITIONS, and- COMPILE_OPTIONS.
- Now supports Dynamic Download Integrity Applications which did not include Integrate Files via - GHS_INTEGRITY_APPand setting a target link flag of- -dynamic.
- The contents of project files now sorts sources groups and files by name. Set the - GHS_NO_SOURCE_GROUP_FILEtarget property to- ONto generate a single project file for the target instead of a project file for each source group. Set the- CMAKE_GHS_NO_SOURCE_GROUP_FILEvariable 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 - cmake-file-api(7)manual. This is intended to replace the- cmake-server(7)mode for IDEs.
Platforms¶
- CMake now supports Cross Compiling for iOS, tvOS, or watchOS using simple toolchain files. 
Command-Line¶
- The - cmake(1)Build Tool Mode (- cmake --build) gained- --verboseand- -voptions to specify verbose build output. Some generators such as Xcode don't support this option currently.
- The - cmake(1)- -E compare_filescommand learned a new- --ignore-eoloption to specify that end-of-line differences (e.g. LF vs CRLF) should be ignored when comparing files.
- The - cmake-gui(1)dialog gained new- -Sand- -Barguments to explicitly specify source and build directories.
Commands¶
- The - file()command learned a new sub-command,- CREATE_LINK, which can be used to create hard or symbolic links.
- The - file()command learned a new sub-command,- READ_SYMLINK, which can be used to determine the path that a symlink points to.
- The - file()command gained a- SIZEmode to get the size of a file on disk.
- The - find_package()command learned to optionally resolve symbolic links in the paths to package configuration files. See the- CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKSvariable.
- The - get_filename_component()command gained new- LAST_EXTand- NAME_WLEvariants to work with the extension after the last- .in the name.
- The - if()command gained support for checking if cache variables are defined with the- DEFINED CACHE{VAR}syntax.
- The - install(CODE)and- install(SCRIPT)commands learned to support generator expressions. See policy- CMP0087.
- The - install(TARGETS)command learned how to install to an appropriate default directory for a given target type, based on variables from the- GNUInstallDirsmodule and built-in defaults, in lieu of a- DESTINATIONargument.
- The - install(FILES)and- 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- GNUInstallDirsand built-in defaults, in lieu of a- DESTINATIONargument.
- The - list()operations- REMOVE_ITEM,- REMOVE_DUPLICATES,- SORT,- REVERSE, and- FILTERall now accept a non-existent variable as the list since these operations on empty lists is also the empty list.
- The - list()operation- REMOVE_ATnow indicates that the given indices are invalid for a non-existent variable or empty list.
- The - try_compile()and- try_run()commands gained a new- LINK_OPTIONSoption.
Variables¶
- A - CMAKE_BUILD_RPATH_USE_ORIGINvariable and corresponding- BUILD_RPATH_USE_ORIGINtarget 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 - CMAKE_VS_PLATFORM_NAME_DEFAULTvariable was added for Visual Studio Generators to report their default platform used when- CMAKE_GENERATOR_PLATFORMis not set explicitly.
Properties¶
- A - CMAKE_ROLEglobal property was added to allow scripts to determine whether they're running in project mode, script mode, find-package mode, CTest, or CPack.
- The - CUDA_RESOLVE_DEVICE_SYMBOLStarget property is now supported on shared library, module library, and executable targets. Previously it was only honored on static libraries.
- The - EXCLUDE_FROM_ALLtarget property was created to override the setting of its directory. A target will now be built as part of "all" if its- EXCLUDE_FROM_ALLproperty is set to- OFF, even if its containing directory is marked as- EXCLUDE_FROM_ALL.
- INTERFACE_POSITION_INDEPENDENT_CODEtarget property gains the support of- generator expressions.
Modules¶
- The family of modules to check capabilities (like - CheckCSourceCompiles) gain capability to manage- LINK_OPTIONS.
- A - CheckFortranSourceRunsmodule was added to provide a- check_fortran_source_runs()command to check if a Fortran source snippet compiles and runs.
- The - CMakePackageConfigHelpersmodule's- write_basic_package_version_file()command gained a new- ARCH_INDEPENDENToption for supporting architecture-independent packages.
- The - ExternalProjectmodule- ExternalProject_Add()command gained- LOG_DIRand- LOG_MERGED_STDOUTERRoptions to control logging.
- The - ExternalProjectmodule- ExternalProject_Add()command gained- LOG_PATCHto optionally log the patch step.
- The - ExternalProjectmodule- ExternalProject_Add()command learned to apply- SOURCE_SUBDIRwhen- BUILD_IN_SOURCEis also used. The- BUILD_COMMANDis run in the given- SOURCE_SUBDIRof the- SOURCE_DIR.
- The - FetchContentmodule gained a new- 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 - FindBISONmodule's- BISON_TARGETcommand now runs- bisonwith- CMAKE_CURRENT_BINARY_DIRas the working directory. See policy- CMP0088.
- The - FindCURLmodule gained support for requesting protocols as package components.
- The - FindFontconfigmodule was added to find fontconfig.
- The - FindGDALmodule now provides imported targets.
- The - FindGIFmodule now provides imported targets.
- The - FindGitmodule now provides an imported target for the Git executable.
- The - FindIcemodule learned to find- slice2confluenceand- slice2matlab.
- The - FindLibinputmodule was added to find libinput.
- The - FindLibLZMAmodule now provides imported targets.
- The - FindMatlabmodule gained new options- R2017band- R2018ato specify the MEX API version to use; these options mirror the new options to the- mexcommand in MATLAB R2018a. The option- MX_LIBRARYis no longer needed.
- The - FindPostgreSQLmodule now provides imported targets.
- The - FindPython,- FindPython2, and- FindPython3modules gained support for- NumPycomponent.
- The - FindPython2,- FindPython3, and- FindPythonmodules now support running in script mode by skipping the creation of imported targets and helper functions.
- The - FindSQLite3module was added to find the SQLite v3.x library.
- The - FindX11had 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_PATHinstead of- X11_xf86misc_INCLUDE_PATH
- X11_Xxf86misc_LIBinstead of- X11_xf86misc_LIB
- X11_Xxf86misc_FOUNDinstead of- X11_xf86misc_FOUND
- X11_Xxf86vm_INCLUDE_PATHinstead of- X11_xf86vmode_INCLUDE_PATH
- X11_Xxf86vm_LIBinstead of- X11_xf86vmode_LIB
- X11_Xxf86vm_FOUNDinstead of- X11_xf86vmode_FOUND
- X11_xkbfile_INCLUDE_PATHinstead of- X11_Xkbfile_INCLUDE_PATH
- X11_xkbfile_LIBinstead of- X11_Xkbfile_LIB
- X11_xkbfile_FOUNDinstead of- X11_Xkbfile_FOUND
- X11_Xtst_INCLUDE_PATHinstead of- X11_XTest_INCLUDE_PATH
- X11_Xtst_LIBinstead of- X11_XTest_LIB
- X11_Xtst_FOUNDinstead of- X11_XTest_FOUND
- X11_Xss_INCLUDE_PATHinstead of- X11_Xscreensaver_INCLUDE_PATH
- X11_Xss_LIBinstead of- X11_Xscreensaver_LIB
- X11_Xss_FOUNDinstead 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 - FindX11now provides- X11_Xext_INCLUDE_PATH.
- The - FindX11now provides imported targets.
- The - UseSWIGmodule learned to pass- -module <module_name>to the- SWIGcompiler if the file property- SWIG_MODULE_NAMEis defined. See policy- CMP0086.
- The - UseSWIGmodule gained an option to specify- SWIGsource file extensions.
Generator Expressions¶
- The - $<Fortran_COMPILER_ID:...>and- $<Fortran_COMPILER_VERSION:...>- generator expressionswere added.
- The - $<IN_LIST:...>generator expression now correctly handles an empty argument. See- CMP0085for details.
Autogen¶
- The - AUTOMOC_EXECUTABLE,- AUTORCC_EXECUTABLE, and- AUTOUIC_EXECUTABLEtarget 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 - CMAKE_GLOBAL_AUTOGEN_TARGET,- CMAKE_GLOBAL_AUTOGEN_TARGET_NAME,- CMAKE_GLOBAL_AUTORCC_TARGETand- CMAKE_GLOBAL_AUTORCC_TARGET_NAMEcontrol the generation of global- autogenand- autorcctargets.
- A new - CMAKE_AUTOGEN_ORIGIN_DEPENDSvariable and- AUTOGEN_ORIGIN_DEPENDStarget property may be set to enable or disable forwarding of the origin target dependencies to the corresponding The <ORIGIN>_autogen target target.
CTest¶
- ctest(1)gained a- --show-only=json-v1option to show the list of tests in a machine-readable JSON format. See the Show as JSON Object Model section of the manual.
- The - ctest_submit()command learned a new- Donepart 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 - SubmitURLsetting in- ctest(1), the- CTEST_SUBMIT_URLvariable, and the- SUBMIT_URLargument of the- ctest_submit()command.
Deprecated and Removed Features¶
- An explicit deprecation diagnostic was added for policies - CMP0064and- CMP0065(- CMP0063and below were already deprecated). The- cmake-policies(7)manual explains that the OLD behaviors of all policies are deprecated and that projects should port to the NEW behaviors.
- The - Xcodegenerator deprecated support for Xcode versions prior to Xcode 5. Support for those will be dropped in a future version of CMake.
- The - FindQtmodule is no longer used by the- find_package()command as a find module. This allows the Qt Project upstream to optionally provide its own- QtConfig.cmakepackage configuration file and have applications use it via- find_package(Qt)rather than- find_package(Qt CONFIG). See policy- CMP0084.
- Support for running CMake on Windows XP and Windows Vista has been dropped. The precompiled Windows binaries provided on - cmake.orgnow 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- httpand- https.
Other Changes¶
- Object library linking has been fixed to propagate private link libraries of object libraries to consuming targets. 
- Install rules under - add_subdirectory()now interleave with those in the calling directory. See policy- CMP0082for 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 - CMAKE_MAXIMUM_RECURSION_DEPTH.
- When using cppcheck via the - CMAKE_<LANG>_CPPCHECKvariable or- <LANG>_CPPCHECKproperty, the build will now fail if- cppcheckreturns non-zero as configured by its command-line options.
- Required link options to manage Position Independent Executable are now added when - POSITION_INDEPENDENT_CODEis set. The project is responsible for using the- CheckPIESupportedmodule to check for- PIEsupport to ensure that the- POSITION_INDEPENDENT_CODEtarget property will be honored at link time for executables. This behavior is controlled by policy- CMP0083.
- Visual Studio Generators for VS 2010 and above learned to support the - VS_DEBUGGER_*properties on targets created via- add_custom_target().
- The - CPackmodule no longer defaults to the- paxrvalue in the- CPACK_DEBIAN_ARCHIVE_TYPEvariable, because- dpkghas never supported the PAX tar format. The- paxrvalue will be mapped to- gnutarand a deprecation message emitted.
- CMake no longer issues a warning if a target listed in an - install(TARGETS)command has its- EXCLUDE_FROM_ALLproperty set to true.
Updates¶
Changes made since CMake 3.14.0 include the following.
3.14.1¶
- The - FindFontconfigmodule 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 - CMAKE_VS_PLATFORM_NAME_DEFAULTvariable was added to help toolchain files work with the- Visual Studio 16 2019generator where the default platform now depends on the host platform.
3.14.4¶
- In CMake 3.14.0 through 3.14.3, calling - target_link_libraries()to add- PRIVATEdependencies to a static library created in another directory (under policy- CMP0079- NEWbehavior) 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 - CPATHenvironment variable are no longer excluded from explicit use via- include_directories()and- target_include_directories()as they were in CMake 3.14.0 through 3.14.4.
3.14.6¶
3.14.7¶
- In CMake 3.14.0 through 3.14.6, the - EXCLUDE_FROM_ALLdirectory 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.
