CMake 3.14 Release Notes¶
Changes made since CMake 3.13 include the following.
New Features¶
Generators¶
The
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
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
Green Hills MULTI
generator 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.gpj
for each directory calling theproject()
command. The top-level project filedefault.gpj
is no longer created.Now honors target renaming and destination output control properties such as
RUNTIME_OUTPUT_DIRECTORY
andOUTPUT_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_APP
and 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_FILE
target property toON
to generate a single project file for the target instead of a project file for each source group. Set theCMAKE_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
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--verbose
and-v
options to specify verbose build output. Some generators such as Xcode don't support this option currently.The
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
cmake-gui(1)
dialog gained new-S
and-B
arguments 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 aSIZE
mode 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_SYMLINKS
variable.The
get_filename_component()
command gained newLAST_EXT
andNAME_WLE
variants 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 theGNUInstallDirs
module and built-in defaults, in lieu of aDESTINATION
argument.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 fromGNUInstallDirs
and built-in defaults, in lieu of aDESTINATION
argument.The
list()
operationsREMOVE_ITEM
,REMOVE_DUPLICATES
,SORT
,REVERSE
, andFILTER
all now accept a non-existent variable as the list since these operations on empty lists is also the empty list.The
list()
operationREMOVE_AT
now indicates that the given indices are invalid for a non-existent variable or empty list.The
try_compile()
andtry_run()
commands gained a newLINK_OPTIONS
option.
Variables¶
A
CMAKE_BUILD_RPATH_USE_ORIGIN
variable and correspondingBUILD_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
CMAKE_VS_PLATFORM_NAME_DEFAULT
variable was added for Visual Studio Generators to report their default platform used whenCMAKE_GENERATOR_PLATFORM
is not set explicitly.
Properties¶
A
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
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
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 itsEXCLUDE_FROM_ALL
property is set toOFF
, even if its containing directory is marked asEXCLUDE_FROM_ALL
.INTERFACE_POSITION_INDEPENDENT_CODE
target property gains the support ofgenerator expressions
.
Modules¶
The family of modules to check capabilities (like
CheckCSourceCompiles
) gain capability to manageLINK_OPTIONS
.A
CheckFortranSourceRuns
module was added to provide acheck_fortran_source_runs()
command to check if a Fortran source snippet compiles and runs.The
CMakePackageConfigHelpers
module'swrite_basic_package_version_file()
command gained a newARCH_INDEPENDENT
option for supporting architecture-independent packages.The
ExternalProject
moduleExternalProject_Add()
command gainedLOG_DIR
andLOG_MERGED_STDOUTERR
options to control logging.The
ExternalProject
moduleExternalProject_Add()
command gainedLOG_PATCH
to optionally log the patch step.The
ExternalProject
moduleExternalProject_Add()
command learned to applySOURCE_SUBDIR
whenBUILD_IN_SOURCE
is also used. TheBUILD_COMMAND
is run in the givenSOURCE_SUBDIR
of theSOURCE_DIR
.The
FetchContent
module gained a newFetchContent_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
FindBISON
module'sBISON_TARGET
command now runsbison
withCMAKE_CURRENT_BINARY_DIR
as the working directory. See policyCMP0088
.The
FindCURL
module gained support for requesting protocols as package components.The
FindFontconfig
module was added to find fontconfig.The
FindGDAL
module now provides imported targets.The
FindGIF
module now provides imported targets.The
FindGit
module now provides an imported target for the Git executable.The
FindIce
module learned to findslice2confluence
andslice2matlab
.The
FindLibinput
module was added to find libinput.The
FindLibLZMA
module now provides imported targets.The
FindMatlab
module gained new optionsR2017b
andR2018a
to specify the MEX API version to use; these options mirror the new options to themex
command in MATLAB R2018a. The optionMX_LIBRARY
is no longer needed.The
FindPostgreSQL
module now provides imported targets.The
FindPython
,FindPython2
, andFindPython3
modules gained support forNumPy
component.The
FindPython2
,FindPython3
, andFindPython
modules now support running in script mode by skipping the creation of imported targets and helper functions.The
FindSQLite3
module was added to find the SQLite v3.x library.The
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 ofX11_xf86misc_INCLUDE_PATH
X11_Xxf86misc_LIB
instead ofX11_xf86misc_LIB
X11_Xxf86misc_FOUND
instead ofX11_xf86misc_FOUND
X11_Xxf86vm_INCLUDE_PATH
instead ofX11_xf86vmode_INCLUDE_PATH
X11_Xxf86vm_LIB
instead ofX11_xf86vmode_LIB
X11_Xxf86vm_FOUND
instead ofX11_xf86vmode_FOUND
X11_xkbfile_INCLUDE_PATH
instead ofX11_Xkbfile_INCLUDE_PATH
X11_xkbfile_LIB
instead ofX11_Xkbfile_LIB
X11_xkbfile_FOUND
instead ofX11_Xkbfile_FOUND
X11_Xtst_INCLUDE_PATH
instead ofX11_XTest_INCLUDE_PATH
X11_Xtst_LIB
instead ofX11_XTest_LIB
X11_Xtst_FOUND
instead ofX11_XTest_FOUND
X11_Xss_INCLUDE_PATH
instead ofX11_Xscreensaver_INCLUDE_PATH
X11_Xss_LIB
instead ofX11_Xscreensaver_LIB
X11_Xss_FOUND
instead ofX11_Xscreensaver_FOUND
The following variables are deprecated completely since they were essentially duplicates:
X11_Xinput_INCLUDE_PATH
(useX11_Xi_INCLUDE_PATH
)X11_Xinput_LIB
(useX11_Xi_LIB
)X11_Xinput_FOUND
(useX11_Xi_FOUND
)
The
FindX11
now providesX11_Xext_INCLUDE_PATH
.The
FindX11
now provides imported targets.The
UseSWIG
module learned to pass-module <module_name>
to theSWIG
compiler if the file propertySWIG_MODULE_NAME
is defined. See policyCMP0086
.The
UseSWIG
module gained an option to specifySWIG
source file extensions.
Generator Expressions¶
The
$<Fortran_COMPILER_ID:...>
and$<Fortran_COMPILER_VERSION:...>
generator expressions
were added.The
$<IN_LIST:...>
generator expression now correctly handles an empty argument. SeeCMP0085
for details.
Autogen¶
The
AUTOMOC_EXECUTABLE
,AUTORCC_EXECUTABLE
, andAUTOUIC_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
CMAKE_GLOBAL_AUTOGEN_TARGET
,CMAKE_GLOBAL_AUTOGEN_TARGET_NAME
,CMAKE_GLOBAL_AUTORCC_TARGET
andCMAKE_GLOBAL_AUTORCC_TARGET_NAME
control the generation of globalautogen
andautorcc
targets.A new
CMAKE_AUTOGEN_ORIGIN_DEPENDS
variable andAUTOGEN_ORIGIN_DEPENDS
target 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-v1
option 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 newDone
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 inctest(1)
, theCTEST_SUBMIT_URL
variable, and theSUBMIT_URL
argument of thectest_submit()
command.
Deprecated and Removed Features¶
An explicit deprecation diagnostic was added for policies
CMP0064
andCMP0065
(CMP0063
and 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
Xcode
generator deprecated support for Xcode versions prior to Xcode 5. Support for those will be dropped in a future version of CMake.The
FindQt
module is no longer used by thefind_package()
command as a find module. This allows the Qt Project upstream to optionally provide its ownQtConfig.cmake
package 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.org
now 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 overhttp
andhttps
.
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 policyCMP0082
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
CMAKE_MAXIMUM_RECURSION_DEPTH
.When using cppcheck via the
CMAKE_<LANG>_CPPCHECK
variable or<LANG>_CPPCHECK
property, the build will now fail ifcppcheck
returns non-zero as configured by its command-line options.Required link options to manage Position Independent Executable are now added when
POSITION_INDEPENDENT_CODE
is set. The project is responsible for using theCheckPIESupported
module to check forPIE
support to ensure that thePOSITION_INDEPENDENT_CODE
target 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
CPack
module no longer defaults to thepaxr
value in theCPACK_DEBIAN_ARCHIVE_TYPE
variable, becausedpkg
has never supported the PAX tar format. Thepaxr
value will be mapped tognutar
and a deprecation message emitted.CMake no longer issues a warning if a target listed in an
install(TARGETS)
command has itsEXCLUDE_FROM_ALL
property set to true.
Updates¶
Changes made since CMake 3.14.0 include the following.
3.14.1¶
The
FindFontconfig
module 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_DEFAULT
variable was added to help toolchain files work with theVisual 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
target_link_libraries()
to addPRIVATE
dependencies to a static library created in another directory (under policyCMP0079
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 viainclude_directories()
andtarget_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_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.