CMake 3.17 Release Notes¶
Contents
Changes made since CMake 3.16 include the following.
New Features¶
Generators¶
- cmake(1)gained a- Ninja Multi-Configgenerator, which is similar to the- Ninjagenerator 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 where- find_*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.
