CMake 3.17 Release Notes¶
Changes made since CMake 3.16 include the following.
New Features¶
Generators¶
cmake(1)gained aNinja Multi-Configgenerator, which is similar to theNinjagenerator 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
VCTargetsPathvalue for project files inCMAKE_GENERATOR_TOOLSETsetting.Visual Studio Generators for VS 2010 and above learned to support .NET Standard and .NET Core. See the
DOTNET_TARGET_FRAMEWORKtarget property and associatedCMAKE_DOTNET_TARGET_FRAMEWORKvariable.
Languages¶
The
Compile Featuresfunctionality now offers meta-features for the CUDA language standard levels (e.g.cuda_std_03,cuda_std_14). SeeCMAKE_CUDA_KNOWN_FEATURES.
Compilers¶
The IBM XL Fortran compiler is now supported by the
Ninjagenerator.
Command-Line¶
cmake(1)gained a--debug-findcommand-line option to enable additional human-readable output on wherefind_*commands search.cmake(1)gained a--trace-formatcommand-line option that can be used to set the--traceoutput 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 rmcommand-line tool that can be used to remove directories and files. This supersedes the existing-E removeand-E remove_directorytools and has better semantics.
Commands¶
The
add_custom_command()command learned to interpret paths inDEPENDSarguments that are specified relative to the current binary directory.The
foreach()command learned a newZIP_LISTSoption to iterate over multiple lists simultaneously.The
load_cache(READ_WITH_PREFIX)command mode is now allowed when usingcmake -Pto Run a Script.The
message()command learned to output context provided in theCMAKE_MESSAGE_CONTEXTvariable for log levelsNOTICEand below. Enable this output with the new--log-contextcommand-line option orCMAKE_MESSAGE_CONTEXT_SHOWvariable.The
message()command gained new keywordsCHECK_START,CHECK_PASSandCHECK_FAIL.The
target_compile_options()command now honors theBEFOREkeyword more consistently. See policyCMP0101.
Variables¶
A
CMAKE_CTEST_ARGUMENTSvariable 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_LIBRARYvariable andCUDA_RUNTIME_LIBRARYtarget property were introduced to select the CUDA runtime library used when linking targets that use CUDA.The
CMAKE_FIND_DEBUG_MODEvariable 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_COMMANDSvariable now takes its initial value from theCMAKE_EXPORT_COMPILE_COMMANDSenvironment variable if no explicit configuration is given.The
CMAKE_<LANG>_COMPILER_LAUNCHERvariable, if not set explicitly, now takes its initial value from theCMAKE_<LANG>_COMPILER_LAUNCHERenvironment variable.The
CMAKE_MESSAGE_LOG_LEVELvariable can now be used to persist a log level between CMake runs, unlike the--log-levelcommand line option which only applies to that particular run.The
CMAKE_XCODE_SCHEME_ENVIRONMENTvariable was added to initialize theXCODE_SCHEME_ENVIRONMENTtarget property.The
CMAKE_XCODE_SCHEME_WORKING_DIRECTORYvariable and associatedXCODE_SCHEME_WORKING_DIRECTORYtarget property were added to tell theXcodegenerator to set the value of theCustom Working Directoryschema option.
Properties¶
The
AIX_EXPORT_ALL_SYMBOLStarget property and associatedCMAKE_AIX_EXPORT_ALL_SYMBOLSvariable were created to optionally explicitly disable automatic export of symbols from shared libraries on AIX.The
DEPRECATIONtarget 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_DIRtarget 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_VERSIONandMACHO_CURRENT_VERSIONwere added to set thecompatibility_versionandcurent_version, respectively, for Mach-O binaries. For backwards compatibility, if these properties are not set,SOVERSIONandVERSIONare used respectively as fallbacks.The
VS_DOTNET_DOCUMENTATION_FILEtarget property was added to tell Visual Studio Generators to generate aDocumentationFilereference in.csprojfiles.
Modules¶
The
ExternalProjectmoduleExternalProject_Add()command gained aGIT_SUBMODULES_RECURSEoption to specify whether Git submodules should be updated recursively. The default is on to preserve existing behavior.The
FindCUDAToolkitmodule was added to find the CUDA Toolkit without enabling CUDA as a language.The
FindCURLmodule learned to find CURL using theCURLConfig.cmakepackage configuration file generated by CURL's cmake buildsystem. It also gained a newCURL_NO_CURL_CMAKEoption to disable this behavior.The
FindFLEXmodule'sFLEX_TARGETcommand now runsflexwithCMAKE_CURRENT_BINARY_DIRas the working directory. See policyCMP0098.The
FindLibArchivemodule now provides an imported target for libarchive.The
FindPythonmodule has learned to find Python components in active virtual environments managed byconda.The
FindPython3andFindPythonmodules gained, respectively, variablePython3_SOABIandPython_SOABIgiving the standard extension suffix for modules. Moreover, commandsPython3_add_library()andPython_add_library()gained the optionWITH_SOABIto prefix the library suffix with the value ofSOABI.The
FindLibXml2module now provides an imported target for thexmllintexecutable.
Autogen¶
CTest¶
The
CTEST_CONFIGURATION_TYPEvariable 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-passandafter-timeout.The
ctest_test()command gained aREPEAT <mode>:<n>option to specify conditions in which to repeat tests.
CPack¶
The
CPack DragNDrop Generatorlearned to use theCPACK_DMG_<component>_FILE_NAMEvariable to set a custom filename when packaging components into their own DMGs.The
CPack DragNDrop Generatorlearned to handle RTF formatted license files. WhenCPACK_DMG_SLA_DIRvariable is set,<language>.license.rtfis considered, but only as a fallback when the plaintext (.txt) file is not found in order to maintain backwards compatibility.The
CPack NSIS Generatorgained a new variableCPACK_NSIS_MUI_HEADERIMAGEto set the header image. To not break existing setups, it still defaults toCPACK_PACKAGE_ICONif the new variable is not set.The
CPack NSIS Generatornow supportsCPACK_NSIS_UNINSTALL_NAME. This can be used to specify the name of the Uninstall program.The
CPack NSIS Generatornow supportsCPACK_NSIS_WELCOME_TITLEandCPACK_NSIS_WELCOME_TITLE_3LINES. These can be used to specify the welcome page title and display it in 3 lines.The
CPack NSIS Generatornow supportsCPACK_NSIS_FINISH_TITLEandCPACK_NSIS_FINISH_TITLE_3LINES. These can be used to specify the finish page title and display it in 3 lines.The
CPack productbuild Generatorgained support for aCPACK_PRODUCTBUILD_BACKGROUNDvariable to specify a background image for the macOS installer.
Other¶
Deprecated and Removed Features¶
An explicit deprecation diagnostic was added for policy
CMP0068and policyCMP0069(CMP0067and 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 Generatorgenerator has been deprecated because Xcode no longer distributes the PackageMaker tools. The undocumentedOSXX11generator has also been deprecated.The
cmake(1)command-line-E removeand-E remove_directorytools are deprecated in favor of the new-E rmtool. 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 Generatornow requires NSIS 3.0 or later.
Other Changes¶
The
file APIindex file now emits amultiConfigflag specifying whether or not the generator supports multiple output configurations.Target link properties
INTERFACE_LINK_OPTIONS,INTERFACE_LINK_DIRECTORIESandINTERFACE_LINK_DEPENDSare now transitive over private dependencies on static libraries. See policyCMP0099.When using MinGW tools, the
find_library()command no longer finds.dllfiles by default. Instead, it expects.dll.aimport libraries to be available.The
MinGW Makefilesgenerator no longer issues an error ifsh.exeis present in the environment'sPATH.The
Ninjagenerator now prefers the first ninja build tool to appear in thePATHno matter whether it is calledninja-build,ninja, orsamu. Previously the first of those names to appear anywhere in thePATHwould be preferred.With SDCC the
sdartool is now preferred oversdcclibas 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_GLOBALSvariable value now applies during compiler identification and in targets created by theadd_custom_target()command.The
Xcodegenerator no longer hard-codes-Wmost,-Wno-four-char-constants, and-Wno-unknown-pragmaswarning flags.
Updates¶
Changes made since CMake 3.17.0 include the following.
3.17.1¶
CMake 3.17.0 updated the
CPack NSIS Generatorwith 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
CCorCXXenvironment variable if theOBJCorOBJCXXenvironment variable is not set.The
FindPkgConfigmodule now extracts include directories prefixed with-isysteminto the*_INCLUDE_DIRSvariables andINTERFACE_INCLUDE_DIRECTORIEStarget properties. Previously they would be places in*_CFLAGS_OTHERvariables andINTERFACE_COMPILE_OPTIONStarget properties.
3.17.5¶
The default value of
CMAKE_AUTOMOC_PATH_PREFIXwas changed toOFFbecause this feature can break existing projects that have identically named header files in different include directories. This restores compatibility with behavior of CMake 3.15 and below. The default was also changed toOFFin 3.16.9.