CMake 3.17 Release Notes¶
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 in- CMAKE_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 associated- CMAKE_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). See- CMAKE_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 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 in- DEPENDSarguments that are specified relative to the current binary directory.
- The - foreach()command learned a new- ZIP_LISTSoption to iterate over multiple lists simultaneously.
- The - load_cache(READ_WITH_PREFIX)command mode is now allowed when using- cmake -Pto Run a Script.
- The - message()command learned to output context provided in the- CMAKE_MESSAGE_CONTEXTvariable for log levels- NOTICEand below. Enable this output with the new- --log-contextcommand-line option or- CMAKE_MESSAGE_CONTEXT_SHOWvariable.
- The - message()command gained new keywords- CHECK_START,- CHECK_PASSand- CHECK_FAIL.
- The - target_compile_options()command now honors the- BEFOREkeyword more consistently. See policy- CMP0101.
Variables¶
- A - CMAKE_CTEST_ARGUMENTSvariable was added to specify a list of command-line arguments passed to CTest when running through the- test(or- RUN_TESTS) target of the generated build system.
- The following variables are now defined inside a - function():
- The - CMAKE_CUDA_RUNTIME_LIBRARYvariable and- CUDA_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 extra- find_*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 the- CMAKE_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 the- CMAKE_<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 the- XCODE_SCHEME_ENVIRONMENTtarget property.
- The - CMAKE_XCODE_SCHEME_WORKING_DIRECTORYvariable and associated- XCODE_SCHEME_WORKING_DIRECTORYtarget property were added to tell the- Xcodegenerator to set the value of the- Custom Working Directoryschema option.
Properties¶
- The - AIX_EXPORT_ALL_SYMBOLStarget property and associated- CMAKE_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 supports- generator 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_VERSIONand- MACHO_CURRENT_VERSIONwere added to set the- compatibility_versionand- current_version, respectively, for Mach-O binaries. For backwards compatibility, if these properties are not set,- SOVERSIONand- VERSIONare used respectively as fallbacks.
- The - VS_DOTNET_DOCUMENTATION_FILEtarget property was added to tell Visual Studio Generators to generate a- DocumentationFilereference in- .csprojfiles.
Modules¶
- The - ExternalProjectmodule- ExternalProject_Add()command gained a- GIT_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 the- CURLConfig.cmakepackage configuration file generated by CURL's cmake buildsystem. It also gained a new- CURL_NO_CURL_CMAKEoption to disable this behavior.
- The - FindFLEXmodule's- FLEX_TARGETcommand now runs- flexwith- CMAKE_CURRENT_BINARY_DIRas the working directory. See policy- CMP0098.
- The - FindLibArchivemodule now provides an imported target for libarchive.
- The - FindPythonmodule has learned to find Python components in active virtual environments managed by- conda.
- The - FindPython3and- FindPythonmodules gained, respectively, variable- Python3_SOABIand- Python_SOABIgiving the standard extension suffix for modules. Moreover, commands- Python3_add_library()and- Python_add_library()gained the option- WITH_SOABIto prefix the library suffix with the value of- SOABI.
- The - FindLibXml2module now provides an imported target for the- xmllintexecutable.
Autogen¶
CTest¶
- The - CTEST_CONFIGURATION_TYPEvariable is now set from the command line when- ctest(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 for- until-passand- after-timeout.
- The - ctest_test()command gained a- REPEAT <mode>:<n>option to specify conditions in which to repeat tests.
CPack¶
- The - CPack DragNDrop Generatorlearned to use the- CPACK_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. When- CPACK_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 variable- CPACK_NSIS_MUI_HEADERIMAGEto set the header image. To not break existing setups, it still defaults to- CPACK_PACKAGE_ICONif the new variable is not set.
- The - CPack NSIS Generatornow supports- CPACK_NSIS_UNINSTALL_NAME. This can be used to specify the name of the Uninstall program.
- The - CPack NSIS Generatornow supports- CPACK_NSIS_WELCOME_TITLEand- CPACK_NSIS_WELCOME_TITLE_3LINES. These can be used to specify the welcome page title and display it in 3 lines.
- The - CPack NSIS Generatornow supports- CPACK_NSIS_FINISH_TITLEand- CPACK_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 a- CPACK_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 policy- CMP0069(- CMP0067and below were already deprecated). The- cmake-policies(7)manual explains that the OLD behaviors of all policies are deprecated and that projects should port to the NEW behaviors.
- The CPack - PackageMakergenerator has been deprecated because Xcode no longer distributes the PackageMaker tools. The undocumented- OSXX11generator 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 a- multiConfigflag specifying whether or not the generator supports multiple output configurations.
- Target link properties - INTERFACE_LINK_OPTIONS,- INTERFACE_LINK_DIRECTORIESand- INTERFACE_LINK_DEPENDSare now transitive over private dependencies on static libraries. See policy- CMP0099.
- 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 if- sh.exeis present in the environment's- PATH.
- The - Ninjagenerator now prefers the first ninja build tool to appear in the- PATHno matter whether it is called- ninja-build,- ninja, or- samu. Previously the first of those names to appear anywhere in the- PATHwould be preferred.
- With SDCC the - sdartool is now preferred over- sdcclibas 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 the- add_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 - CCor- CXXenvironment variable if the- OBJCor- OBJCXXenvironment variable is not set.
- The - FindPkgConfigmodule now extracts include directories prefixed with- -isysteminto the- *_INCLUDE_DIRSvariables and- INTERFACE_INCLUDE_DIRECTORIEStarget properties. Previously they would be places in- *_CFLAGS_OTHERvariables and- INTERFACE_COMPILE_OPTIONStarget properties.
3.17.5¶
- The default value of - CMAKE_AUTOMOC_PATH_PREFIXwas changed to- OFFbecause 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 to- OFFin 3.16.9.
