CMake 3.17 Release Notes¶
Contents
Changes made since CMake 3.16 include the following.
New Features¶
Generators¶
cmake(1)
gained aNinja Multi-Config
generator, which is similar to theNinja
generator but can be used to build multiple configurations at once.- Visual Studio Generators learned to support per-config sources. Previously only Command-Line Build Tool Generators supported them.
- Visual Studio Generators for VS 2010 and above now support
specifying the
VCTargetsPath
value for project files inCMAKE_GENERATOR_TOOLSET
setting. - Visual Studio Generators for VS 2010 and above learned to
support .NET Standard and .NET Core. See the
DOTNET_TARGET_FRAMEWORK
target property and associatedCMAKE_DOTNET_TARGET_FRAMEWORK
variable.
Languages¶
- The
Compile Features
functionality now offers meta-features for the CUDA language standard levels (e.g.cuda_std_03
,cuda_std_14
). SeeCMAKE_CUDA_KNOWN_FEATURES
.
Command-Line¶
cmake(1)
gained a--debug-find
command-line option to enable additional human-readable output on wherefind_*
commands search.cmake(1)
gained a--trace-format
command-line option that can be used to set the--trace
output format. Currently, the old human readable and the new JSON format are supported. The new JSON format is easier to parse automatically than the existing format.cmake(1)
gained a-E rm
command-line tool that can be used to remove directories and files. This supersedes the existing-E remove
and-E remove_directory
tools and has better semantics.
Commands¶
- The
add_custom_command()
command learned to interpret paths inDEPENDS
arguments that are specified relative to the current binary directory. - The
foreach()
command learned a newZIP_LISTS
option to iterate over multiple lists simultaneously. - The
load_cache(READ_WITH_PREFIX)
command mode is now allowed when usingcmake -P
to Run a Script. - The
message()
command learned to output context provided in theCMAKE_MESSAGE_CONTEXT
variable for log levelsNOTICE
and below. Enable this output with the new--log-context
command-line option orCMAKE_MESSAGE_CONTEXT_SHOW
variable. - The
message()
command gained new keywordsCHECK_START
,CHECK_PASS
andCHECK_FAIL
. - The
target_compile_options()
command now honors theBEFORE
keyword more consistently. See policyCMP0101
.
Variables¶
- A
CMAKE_CTEST_ARGUMENTS
variable was added to specify a list of command-line arguments passed to CTest when running through thetest
(orRUN_TESTS
) target of the generated build system. - The following variables are now defined inside a
function()
: - The
CMAKE_CUDA_RUNTIME_LIBRARY
variable andCUDA_RUNTIME_LIBRARY
target property were introduced to select the CUDA runtime library used when linking targets that use CUDA. - The
CMAKE_FIND_DEBUG_MODE
variable was introduced to print extrafind_*
call information during the cmake run to standard error. Output is designed for human consumption and not for parsing. - The
CMAKE_EXPORT_COMPILE_COMMANDS
variable now takes its initial value from theCMAKE_EXPORT_COMPILE_COMMANDS
environment variable if no explicit configuration is given. - The
CMAKE_<LANG>_COMPILER_LAUNCHER
variable, if not set explicitly, now takes its initial value from theCMAKE_<LANG>_COMPILER_LAUNCHER
environment variable. - The
CMAKE_MESSAGE_LOG_LEVEL
variable can now be used to persist a log level between CMake runs, unlike the--log-level
command line option which only applies to that particular run. - The
CMAKE_XCODE_SCHEME_ENVIRONMENT
variable was added to initialize theXCODE_SCHEME_ENVIRONMENT
target property. - The
CMAKE_XCODE_SCHEME_WORKING_DIRECTORY
variable and associatedXCODE_SCHEME_WORKING_DIRECTORY
target property were added to tell theXcode
generator to set the value of theCustom Working Directory
schema option.
Properties¶
- The
AIX_EXPORT_ALL_SYMBOLS
target property and associatedCMAKE_AIX_EXPORT_ALL_SYMBOLS
variable were created to optionally explicitly disable automatic export of symbols from shared libraries on AIX. - The
DEPRECATION
target property was added to mark a target as deprecated. If a linked target is marked as deprecated, a warning with the deprecation message is issued at generate time. - The
INSTALL_NAME_DIR
target property now supportsgenerator expressions
. In particular, the$<INSTALL_PREFIX>
generator expression can be used to set the directory relative to the install-time prefix. - Target properties
MACHO_COMPATIBILITY_VERSION
andMACHO_CURRENT_VERSION
were added to set thecompatibility_version
andcurent_version
, respectively, for Mach-O binaries. For backwards compatibility, if these properties are not set,SOVERSION
andVERSION
are used respectively as fallbacks. - The
VS_DOTNET_DOCUMENTATION_FILE
target property was added to tell Visual Studio Generators to generate aDocumentationFile
reference in.csproj
files.
Modules¶
- The
ExternalProject
moduleExternalProject_Add()
command gained aGIT_SUBMODULES_RECURSE
option to specify whether Git submodules should be updated recursively. The default is on to preserve existing behavior. - The
FindCUDAToolkit
module was added to find the CUDA Toolkit without enabling CUDA as a language. - The
FindCURL
module learned to find CURL using theCURLConfig.cmake
package configuration file generated by CURL’s cmake buildsystem. It also gained a newCURL_NO_CURL_CMAKE
option to disable this behavior. - The
FindFLEX
module’sFLEX_TARGET
command now runsflex
withCMAKE_CURRENT_BINARY_DIR
as the working directory. See policyCMP0098
. - The
FindLibArchive
module now provides an imported target for libarchive. - The
FindPython
module has learned to find Python components in active virtual environments managed byconda
. - The
FindPython3
andFindPython
modules gained, respectively, variablePython3_SOABI
andPython_SOABI
giving the standard extension suffix for modules. Moreover, commandsPython3_add_library()
andPython_add_library()
gained the optionWITH_SOABI
to prefix the library suffix with the value ofSOABI
. - The
FindLibXml2
module now provides an imported target for thexmllint
executable.
CTest¶
- The
CTEST_CONFIGURATION_TYPE
variable is now set from the command line whenctest(1)
is invoked with-C <cfg>
. - The
ctest(1)
tool gained support for Dr. Memory to run memcheck runs. - The
ctest(1)
tool gained a--no-tests=<[error|ignore]>
option to explicitly set and unify the behavior between direct invocation and script mode if no tests were found. - The
ctest(1)
tool gained a--repeat <mode>:<n>
option to specify conditions in which to repeat tests. This generalizes the existing--repeat-until-fail <n>
option to add modes foruntil-pass
andafter-timeout
. - The
ctest_test()
command gained aREPEAT <mode>:<n>
option to specify conditions in which to repeat tests.
CPack¶
- The
CPack DragNDrop Generator
learned to use theCPACK_DMG_<component>_FILE_NAME
variable to set a custom filename when packaging components into their own DMGs. - The
CPack DragNDrop Generator
learned to handle RTF formatted license files. WhenCPACK_DMG_SLA_DIR
variable is set,<language>.license.rtf
is considered, but only as a fallback when the plaintext (.txt
) file is not found in order to maintain backwards compatibility. - The
CPack NSIS Generator
gained a new variableCPACK_NSIS_MUI_HEADERIMAGE
to set the header image. To not break existing setups, it still defaults toCPACK_PACKAGE_ICON
if the new variable is not set. - The
CPack NSIS Generator
now supportsCPACK_NSIS_UNINSTALL_NAME
. This can be used to specify the name of the Uninstall program. - The
CPack NSIS Generator
now supportsCPACK_NSIS_WELCOME_TITLE
andCPACK_NSIS_WELCOME_TITLE_3LINES
. These can be used to specify the welcome page title and display it in 3 lines. - The
CPack NSIS Generator
now supportsCPACK_NSIS_FINISH_TITLE
andCPACK_NSIS_FINISH_TITLE_3LINES
. These can be used to specify the finish page title and display it in 3 lines. - The
CPack productbuild Generator
gained support for aCPACK_PRODUCTBUILD_BACKGROUND
variable to specify a background image for the macOS installer.
Deprecated and Removed Features¶
- An explicit deprecation diagnostic was added for policy
CMP0068
and policyCMP0069
(CMP0067
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
CPack PackageMaker Generator
generator has been deprecated because Xcode no longer distributes the PackageMaker tools. The undocumentedOSXX11
generator has also been deprecated. - The
cmake(1)
command-line-E remove
and-E remove_directory
tools are deprecated in favor of the new-E rm
tool. The older tools always returned 0 if a named path did not exist even without the force option and cannot be fixed without breaking compatibility, and so have been superseded. - The
CPack NSIS Generator
now requires NSIS 3.0 or later.
Other Changes¶
- The
file API
index file now emits amultiConfig
flag specifying whether or not the generator supports multiple output configurations. - Target link properties
INTERFACE_LINK_OPTIONS
,INTERFACE_LINK_DIRECTORIES
andINTERFACE_LINK_DEPENDS
are now transitive over private dependencies on static libraries. See policyCMP0099
. - When using MinGW tools, the
find_library()
command no longer finds.dll
files by default. Instead, it expects.dll.a
import libraries to be available. - The
MinGW Makefiles
generator no longer issues an error ifsh.exe
is present in the environment’sPATH
. - The
Ninja
generator now prefers the first ninja build tool to appear in thePATH
no matter whether it is calledninja-build
,ninja
, orsamu
. Previously the first of those names to appear anywhere in thePATH
would be preferred. - With SDCC the
sdar
tool is now preferred oversdcclib
as librarian. The latter was deprecated by SDCC 3.2.0 and removed in SDCC 3.8.6. - With SDCC the default flags no longer include any target-specific flags. Previously the default flags were hard-coded for 8051.
- The
CMAKE_VS_GLOBALS
variable value now applies during compiler identification and in targets created by theadd_custom_target()
command. - The
Xcode
generator no longer hard-codes-Wmost
,-Wno-four-char-constants
, and-Wno-unknown-pragmas
warning flags.
Updates¶
Changes made since CMake 3.17.0 include the following.
3.17.1¶
- CMake 3.17.0 updated the
CPack NSIS Generator
with changes that require NSIS 3.0 or later. CMake 3.17.1 now enforces the use of a sufficiently new version.
3.17.3¶
- Selection of the Objective C or C++ compiler now considers the
CC
orCXX
environment variable if theOBJC
orOBJCXX
environment variable is not set. - The
FindPkgConfig
module now extracts include directories prefixed with-isystem
into the*_INCLUDE_DIRS
variables andINTERFACE_INCLUDE_DIRECTORIES
target properties. Previously they would be places in*_CFLAGS_OTHER
variables andINTERFACE_COMPILE_OPTIONS
target properties.