CMake 3.14 Release Notes¶
Contents
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 theproject()command. The top-level project filedefault.gpjis no longer created.
- Now honors target renaming and destination output control properties
such as RUNTIME_OUTPUT_DIRECTORYandOUTPUT_NAME. This also fixes support for installation rules generated byinstall().
- Now honors source file properties INCLUDE_DIRECTORIES,COMPILE_DEFINITIONS, andCOMPILE_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 toONto generate a single project file for the target instead of a project file for each source group. Set theCMAKE_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 thecmake-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 aSIZEmode 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 theCMAKE_FIND_PACKAGE_RESOLVE_SYMLINKSvariable.
- The get_filename_component()command gained newLAST_EXTandNAME_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 theDEFINED CACHE{VAR}syntax.
- The install(CODE)andinstall(SCRIPT)commands learned to support generator expressions. See policyCMP0087.
- The install(TARGETS)command learned how to install to an appropriate default directory for a given target type, based on variables from theGNUInstallDirsmodule and built-in defaults, in lieu of aDESTINATIONargument.
- The install(FILES)andinstall(DIRECTORY)commands learned a new set of parameters for installing files as a file type, setting the destination based on the appropriate variables fromGNUInstallDirsand built-in defaults, in lieu of aDESTINATIONargument.
- The list()operationsREMOVE_ITEM,REMOVE_DUPLICATES,SORT,REVERSE, andFILTERall now accept a non-existent variable as the list since these operations on empty lists is also the empty list.
- The list()operationREMOVE_ATnow indicates that the given indices are invalid for a non-existent variable or empty list.
- The try_compile()andtry_run()commands gained a newLINK_OPTIONSoption.
Variables¶
- A CMAKE_BUILD_RPATH_USE_ORIGINvariable and correspondingBUILD_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 whenCMAKE_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 itsEXCLUDE_FROM_ALLproperty is set toOFF, even if its containing directory is marked asEXCLUDE_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. SeeCMP0085for 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- _autogentarget.
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 newDonepart 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 inctest(1), theCTEST_SUBMIT_URLvariable, and theSUBMIT_URLargument of thectest_submit()command.
Deprecated and Removed Features¶
- An explicit deprecation diagnostic was added for policies CMP0064andCMP0065(CMP0063and below were already deprecated). Thecmake-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 thefind_package()command as a find module. This allows the Qt Project upstream to optionally provide its ownQtConfig.cmakepackage configuration file and have applications use it viafind_package(Qt)rather thanfind_package(Qt CONFIG). See policyCMP0084.
- 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, andxmlrpc. CDash is the only maintained testing dashboard for CTest, and it only supports submissions overhttpandhttps.
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 policyCMP0082for 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 ifcppcheckreturns 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 theCheckPIESupportedmodule to check forPIEsupport to ensure that thePOSITION_INDEPENDENT_CODEtarget property will be honored at link time for executables. This behavior is controlled by policyCMP0083.
- Visual Studio Generators for VS 2010 and above learned
to support the VS_DEBUGGER_*properties on targets created viaadd_custom_target().
- The CPackmodule no longer defaults to thepaxrvalue in theCPACK_DEBIAN_ARCHIVE_TYPEvariable, becausedpkghas never supported the PAX tar format. Thepaxrvalue will be mapped tognutarand a deprecation message emitted.
- CMake no longer issues a warning if a target listed in an
install(TARGETS)command has itsEXCLUDE_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 uppercaseFONTCONFIG_*variable names that do not match our conventions. 3.14.1 revises the module to useFontconfig_*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 theVisual 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 addPRIVATEdependencies to a static library created in another directory (under policyCMP0079NEWbehavior) 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 viainclude_directories()andtarget_include_directories()as they were in CMake 3.14.0 through 3.14.4.
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.
