CMake 3.15 Release Notes¶
Contents
Changes made since CMake 3.14 include the following.
New Features¶
Generators¶
The
Xcode
generator now supports per-target schemes. See theCMAKE_XCODE_GENERATE_SCHEME
variable andXCODE_GENERATE_SCHEME
target property.The
Green Hills MULTI
generator has been updated:It now supports the
add_custom_command()
andadd_custom_target()
commands.It is now available on Linux.
Languages¶
Preliminary support for the
Swift
language was added to theNinja
generator:Use the
SWIFTC
environment variable to specify a compiler.The
Swift_DEPENDENCIES_FILE
target property andSwift_DEPENDENCIES_FILE
source file property were added to customize dependency files.The
Swift_MODULE_NAME
target property was added to customize the Swift module name.The
Swift_DIAGNOSTICS_FILE
source property was added to indicate where to write the serialised Swift diagnostics.
The Swift support is experimental, not considered stable, and may change in future releases of CMake.
Compilers¶
The
Clang
compiler variant on Windows that targets the MSVC ABI but has a GNU-like command line is now supported.Support for the Clang-based ARM compiler was added with compiler id
ARMClang
.Support was added for the IAR compiler architectures Renesas RX, RL78, RH850 and Texas Instruments MSP430.
Support was added for the IAR compilers built for Linux (IAR BuildLx).
Command-Line¶
The
CMAKE_GENERATOR
environment variable was added to specify a default generator to use whencmake(1)
is run without a-G
option. Additionally, environment variablesCMAKE_GENERATOR_PLATFORM
,CMAKE_GENERATOR_TOOLSET
, andCMAKE_GENERATOR_INSTANCE
were created to configure the generator.The
cmake(1)
--build
tool--target
parameter gained support for multiple targets, e.g.cmake --build . --target Library1 Library2
. It now also has a short form-t
alias, e.g.cmake --build . -t Library1 Library2
.The
cmake(1)
command gained a new--install
option. This may be used after building a project to run installation without using the generated build system or the native build tool.The
cmake(1)
command learned a new CLI option--loglevel
.The
cmake(1)
-E remove_directory
command-line tool learned to support removing multiple directories.The
cmake(1)
-E tar
tool has been improved:It now continues adding files to an archive even if some of the files are not readable. This behavior is more consistent with the classic
tar
tool.It now parses all flags, and if an invalid flag was provided, a warning is issued.
It now displays an error if no action flag was specified, along with a list of possible actions:
t
(list),c
(create) orx
(extract).It now supports extracting (
-x
) or listing (-t
) only specific files or directories.It now supports Zstandard compression with a
--zstd
option. Zstandard was designed to give a compression ratio comparable to that of the DEFLATE (zip) algorithm, but faster, especially for decompression.
Commands¶
The
add_custom_command()
andadd_custom_target()
commands gained a newJOB_POOL
option that works with theNinja
generator to set the pool variable on the build statement.The
add_library()
commandALIAS
option learned to support import libraries of theUNKNOWN
type.The
cmake_parse_arguments()
command gained an additional<prefix>_KEYWORDS_MISSING_VALUES
output variable to report keyword arguments that were given by the caller with no values.The
execute_process()
command gained aCOMMAND_ECHO
option and supportingCMAKE_EXECUTE_PROCESS_COMMAND_ECHO
variable to enable echoing of the command-line string before execution.The
file(INSTALL)
command learned a new argument,FOLLOW_SYMLINK_CHAIN
, which can be used to recursively resolve and install symlinks.list()
learned new sub-commands:PREPEND
,POP_FRONT
andPOP_BACK
.The
message()
command learned new types:NOTICE
,VERBOSE
,DEBUG
andTRACE
.The
string()
learned a new sub-commandREPEAT
.
Variables¶
The
CMAKE_CROSSCOMPILING_EMULATOR
variable and correspondingCROSSCOMPILING_EMULATOR
target property learned to support arguments to the emulator.The
CMAKE_FIND_PACKAGE_PREFER_CONFIG
variable was added to tellfind_package()
calls to look for a package configuration file first even if a find module is available.The
CMAKE_FRAMEWORK
variable was added to initialize theFRAMEWORK
property on all targets.The
CMAKE_VS_JUST_MY_CODE_DEBUGGING
variable andVS_JUST_MY_CODE_DEBUGGING
target property were added to enable the Just My Code feature of the Visual Studio Debugger when compiling with MSVC cl 19.05 and higher.The
CMAKE_MSVC_RUNTIME_LIBRARY
variable andMSVC_RUNTIME_LIBRARY
target property were introduced to select the runtime library used by compilers targeting the MSVC ABI. See policyCMP0091
.The
CMAKE_PROJECT_INCLUDE
andCMAKE_PROJECT_INCLUDE_BEFORE
variables were added to allow injection of custom code at the sites ofproject()
calls without knowing the project name a priori.
Properties¶
The
ADDITIONAL_CLEAN_FILES
target property andADDITIONAL_CLEAN_FILES
directory property were added. They allow to register additional files that should be removed during the clean stage.The
PUBLIC_HEADER
andPRIVATE_HEADER
properties may now be set on Interface Libraries. The headers specified by those properties can be installed using theinstall(TARGETS)
command by passing thePUBLIC_HEADER
andPRIVATE_HEADER
arguments respectively.The
VS_PACKAGE_REFERENCES
target property was added to tell Visual Studio Generators to add references tonuget
packages.The
VS_PROJECT_IMPORT
target property was added to allow managed Visual Studio project files to import external.props
files.The
VS_NO_SOLUTION_DEPLOY
target property was added to tell Visual Studio Generators whether to deploy an artifact to the WinCE or Windows Phone target device.
Modules¶
The
FindBoost
module was reworked to expose a more consistent user experience between its “Config” and “Module” modes and with other find modules in general.A new imported target
Boost::headers
is now defined (same asBoost::boost
).New output variables
Boost_VERSION_MACRO
,Boost_VERSION_MAJOR
,Boost_VERSION_MINOR
,Boost_VERSION_PATCH
, andBoost_VERSION_COUNT
were added.The
QUIET
argument passed tofind_package()
is no longer ignored in config mode. Note that the CMake package shipped with Boost1.70.0
ignores theQUIET
argument passed tofind_package()
. This is fixed in the next Boost release.The input switch
Boost_DETAILED_FAILURE_MSG
was removed.Boost_VERSION
now reports the version inx.y.z
format in module mode. See policyCMP0093
.
The
FindCups
module now provides imported targets.The
FindEnvModules
module was added to use Lua- and TCL-based environment modules in CTest Scripts.The
FindGLEW
module now provides an interface more consistent with what upstream GLEW provides in its own CMake package files.The
FindPkgConfig
now populatesINTERFACE_LINK_OPTIONS
property of imported targets with other (non-library) linker flags.The
FindPostgreSQL
module learned to find debug and release variants separately.Modules
FindPython3
,FindPython2
andFindPython
gained additional lookup strategies and controls, and a new default. See policyCMP0094
.Modules
FindPython
,FindPython2
andFindPython3
gain a new target (respectivelyPython::Module
,Python2::Module
andPython3::Module
) which can be used to develop Python modules.Modules
FindPython3
,FindPython2
andFindPython
gain capability to control how virtual environments are handled.The
UseSWIG
module learned to manage alternate library names by passing-interface <library_name>
forpython
language or-dllimport <library_name>
forCSharp
language to theSWIG
compiler.
Generator Expressions¶
The
generator expressions
C_COMPILER_ID
,CXX_COMPILER_ID
,CUDA_COMPILER_ID
,Fortran_COMPILER_ID
,COMPILE_LANGUAGE
,COMPILE_LANG_AND_ID
, andPLATFORM_ID
learned to support matching one value from a comma-separated list.The
$<CUDA_COMPILER_ID:...>
and$<CUDA_COMPILER_VERSION:...>
generator expressions
were added.The
$<COMPILE_LANG_AND_ID:...>
generator expression was introduced to allow specification of compile options for target files based on theCMAKE_<LANG>_COMPILER_ID
andLANGUAGE
of each source file.A
$<FILTER:list,INCLUDE|EXCLUDE,regex>
generator expression
has been added.A
$<REMOVE_DUPLICATES:list>
generator expression
has been added.The
$<SHELL_PATH:...>
generator expression
gained support for a list of paths.New
$<TARGET_FILE*>
generator expressions
were added to retrieve the prefix, base name, and suffix of the file names of various artifacts:$<TARGET_FILE_PREFIX:...>
$<TARGET_FILE_BASE_NAME:...>
$<TARGET_FILE_SUFFIX:...>
$<TARGET_LINKER_FILE_PREFIX:...>
$<TARGET_LINKER_FILE_BASE_NAME:...>
$<TARGET_LINKER_FILE_SUFFIX:...>
$<TARGET_PDB_FILE_BASE_NAME:...>
The
$<TARGET_OBJECTS:...>
generator expression
is now supported onSHARED
,STATIC
,MODULE
libraries and executables.
CTest¶
The
ctest_submit()
command learned a new option:BUILD_ID
. This can be used to store the ID assigned to this build by CDash to a variable.The
ctest_update()
command learned to honor a new variable:CTEST_UPDATE_VERSION_OVERRIDE
. This can be used to specify the current version of your source tree rather than using the update command to discover the current version that is checked out.
CPack¶
The
CPack IFW Generator
gained a newCPACK_IFW_PACKAGE_STYLE_SHEET
variable to customize the installer stylesheet.
Deprecated and Removed Features¶
The
cmake-server(7)
mode has been deprecated and will be removed from a future version of CMake. Please port clients to use thecmake-file-api(7)
instead.The
ADDITIONAL_MAKE_CLEAN_FILES
directory property is now deprecated. Use theADDITIONAL_CLEAN_FILES
directory property instead.The variable
CMAKE_AUTOMOC_RELAXED_MODE
is considered deprecated. Support still exists but will be removed in future versions.The
export(PACKAGE)
command now does nothing unless enabled viaCMAKE_EXPORT_PACKAGE_REGISTRY
. See policyCMP0090
.The
Xcode
generator now requires at least Xcode 5.An explicit deprecation diagnostic was added for policy
CMP0066
(CMP0065
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.
Other Changes¶
If a feature specified by
target_compile_features()
is available in the compiler’s default standard level, CMake 3.14 and below incorrectly added unnecessary-std=
flags that could lower the standard level. This bug has been fixed in CMake 3.15. This behavior change may expose bugs in existing projects that were relying on undocumented implementation details. Specifying compile features only ensures that the compiler runs in a mode that has those features, not that any specific standard level is used or explicit-std=
flag passed.CMake learned how to compile C++14 with the IBM AIX XL compiler and the SunPro compiler and to compile C++20 with the AppleClang compiler.
With MSVC-like compilers the value of
CMAKE_<LANG>_FLAGS
no longer contains warning flags like/W3
by default. See policyCMP0092
.IBM Clang-based XL compilers that define
__ibmxl__
now use the compiler idXLClang
instead ofXL
. See policyCMP0089
.The
file(REMOVE)
andfile(REMOVE_RECURSE)
commands were changed to ignore empty arguments with a warning instead of treating them as a relative path and removing the contents of the current directory.
Updates¶
Changes made since CMake 3.15.0 include the following.
3.15.1¶
In CMake 3.15.0 support for the GNU-like
Clang
compiler targeting the MSVC ABI implementedCMAKE_CXX_STANDARD
values 98 and 11 using the corresponding-std=
flags. However, these modes do not work with the MSVC standard library. Therefore CMake 3.15.1 passes C++14 standard flags even for C++98 and C++11. This is consistent with MSVC itself which always runs in a mode aware of C++14.Preliminary Swift support added in 3.15.0 has been updated.
3.15.2¶
In CMake 3.15.0 and 3.15.1 the
CMAKE_FIND_PACKAGE_PREFER_CONFIG
variable caused thefind_package()
command to fail on a missing package even without theREQUIRED
option. This has been fixed.
3.15.3¶
CrayPrgEnv
compiler wrapper support has been updated for the 19.06 release of the Cray Programming Environment for which the default linking mode on XC Cray systems is now dynamic instead of static.
3.15.4¶
In CMake 3.15.0 through 3.15.3, 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. The bug also existed in 3.14.0 through 3.14.6 and is fixed in 3.14.7.