CMake 3.17 Release Notes¶
Contents
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.
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.
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.
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.