CMake 3.21 Release Notes¶
Changes made since CMake 3.20 include the following.
New Features¶
Presets¶
- cmake-presets(7)gained support for specifying the install prefix in a configure preset.
- cmake-presets(7)gained support for conditional enabling of presets.
- cmake-presets(7)gained support for a- ${hostSystemName}macro.
- cmake-presets(7)gained support for omitting the- generatorand- binaryDirfields.
Generators¶
- The - Visual Studio 17 2022generator was added.
- The Makefile Generators and the - Ninjagenerator learned to add linker launcher tools along with the linker for- C,- CXX,- OBJC, and- OBJCXXlanguages. See the- CMAKE_<LANG>_LINKER_LAUNCHERvariable and- <LANG>_LINKER_LAUNCHERtarget property for details.
Languages¶
- CMake learned to support - HIPas a first-class language that can be enabled via the- project()and- enable_language()commands.
- C_STANDARD,- OBJC_STANDARD, and the- Compile Featuresfunctionality gained support for C17 and C23.
- Source file extensions - .ixxand- .cppmare now treated as C++.
Command-Line¶
- cmake(1)gained the- --install-prefixcommand-line option to specify the location of the install prefix.
- cmake(1)gained the- --toolchaincommand-line option to specify a toolchain file.
- cmake(1)- -E capabilitiesoutput, for some generators, may now contain a- supportedPlatformsfield listing platforms known to be supported in- CMAKE_GENERATOR_PLATFORM.
- Messages printed to a terminal now may be colored by message type. 
Compilers¶
- The Fujitsu compiler is now supported using compiler id - Fujitsuin traditional (- Trad) mode, and compiler id- FujitsuClangin- Clangmode.
Platforms¶
- CMake now supports the MSYS runtime environment, much like CYGWIN. 
File-Based API¶
- The - cmake-file-api(7)"codemodel" version 2- versionfield has been updated to 2.3.
- The - cmake-file-api(7)"codemodel" version 2 gained a new "directory" object containing directory-level information. This includes a list of installers generated by the- install()command.
Commands¶
- The - add_custom_command()command- DEPFILEoption:- may now use - generator expressions,
- is now supported by Visual Studio Generators for VS 2012 and above, and 
- is now supported by the - Xcodegenerator.
 
- The - add_custom_command(TARGET)command (for Build Events) gained support for resolving target-dependent generator expressions.
- The - build_command()command gained a- PARALLEL_LEVELoption.
- The - file(COPY_FILE)command was added to copy a single file.
- The - file(GET_RUNTIME_DEPENDENCIES)command gained new- POST_INCLUDE_FILESand- POST_EXCLUDE_FILESarguments.
- The - file(REAL_PATH)command gained the option- EXPAND_TILDEto replace any leading tilde with the path to the user's home directory.
- The - file(RENAME)command learned to optionally capture failure in a result variable. It also gained a- NO_REPLACEoption to fail if the destination exists.
- The - install()command gained a new- IMPORTED_RUNTIME_ARTIFACTSmode, which can be used to install the runtime artifacts of imported targets.
- The - install()command gained a new- RUNTIME_DEPENDENCY_SETmode, which can be used to install runtime dependencies using- file(GET_RUNTIME_DEPENDENCIES).
- The - install(TARGETS)command gained new- RUNTIME_DEPENDENCIESand- RUNTIME_DEPENDENCY_SETarguments, which can be used to install runtime dependencies using- file(GET_RUNTIME_DEPENDENCIES).
- The - install(SCRIPT|CODE)command supports a new option- ALL_COMPONENTSwhich allows the corresponding code to run for every component of a per component installation.
- The - project()command now sets variables- PROJECT_IS_TOP_LEVELand- <PROJECT-NAME>_IS_TOP_LEVELto indicate whether it was called in a top-level- CMakeLists.txtfile.
Variables¶
- The - CMAKE_TOOLCHAIN_FILEenvironment variable was added to provide a default value for the- CMAKE_TOOLCHAIN_FILEvariable.
Properties¶
- The - IMPORTED_TARGETSdirectory property was added to get a list of Imported Targets created in the current directory.
- The - XCODE_EMBED_APP_EXTENSIONStarget property was added to tell the- Xcodegenerator to embed app extensions such as iMessage sticker packs. Aspects of the embedding can be customized with the- XCODE_EMBED_APP_EXTENSIONS_PATH,- XCODE_EMBED_APP_EXTENSIONS_CODE_SIGN_ON_COPYand- XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPYproperties.
Modules¶
- The - FindBLASand- FindLAPACKmodules learned to support the serial- Fujitsu_SSL2and parallel- Fujitsu_SSL2BLAMPlibraries.
- The - FindDevILmodule now provides imported targets.
- The - FindIconvmodule now has version support.
- The - FindIntlmodule now has version support.
- The - FindMPImodule learned to support- Fujitsuand- FujitsuClangin both host and cross compiling modes.
- The - FindMsysmodule was added to find MSYS installations. Like- FindCygwin, it is used automatically by some other find modules to locate UNIX-style tools on Windows.
- The - FindOpenMPmodule learned to support- Fujitsuand- FujitsuClang.
- The - FindVulkanmodule gained imported targets- Vulkan::Headersand- Vulkan::glslangValidator.
- The - UseJavamodule command- add_jargained a- RESOURCESoption to allow explicit naming of resources with non-optional namespace.
- The - UseSWIGmodule use now standard library naming conventions for the- CSharplanguage. See policy- CMP0122.
- The - UseSWIGmodule now supports using the- swigtool to generate implicit dependencies with the- Xcodegenerator.
Generator Expressions¶
- A new - TARGET_RUNTIME_DLLSgenerator expression was added.
CTest¶
- ctest(1)gained documentation for its ability to capture Additional Test Measurements.
- ctest(1)learned to recognize files attached to a test at run time. Previously it was only possible to attach files to tests at configure time by using the- ATTACHED_FILESor- ATTACHED_FILES_ON_FAILtest properties. See Additional Test Measurements for more information.
- ctest(1)gained a- --output-junitoption to write test results to a JUnit XML file.
- The - ctest_build()command gained a- PARALLEL_LEVELoption.
CPack¶
- The - CPack DragNDrop Generatorgained option- CPACK_DMG_FILESYSTEMto control the- .dmgfilesystem.
- The - CPack IFW Generatornow supports hyphens in names given to- cpack_ifw_configure_component()or- cpack_ifw_configure_component_group()as- DEPENDSor- DEPENDENCIESarguments. This requires QtIFW 3.1 or later.
- The - CPack NSIS Generatorgained a new- CPACK_NSIS_EXECUTABLEvariable to specify the- makensisexecutable to use instead of the default one.
- The - CPACK_CUSTOM_INSTALL_VARIABLESvariable was added to set variables in- cmake_install.cmakescript invocations made by CPack.
Deprecated and Removed Features¶
- Undocumented - CMAKE_SYSTEM_NAMEversion-stripping behavior has been removed entirely. If it is set by a- -Dflag or by a- toolchain file, it is left unaltered, even if it still contains a version number. Similar- CMAKE_HOST_SYSTEM_NAMEversion-stripping behavior, also undocumented, has been moved earlier, before- project()or- enable_language()is called.
- ARMClangcpu/arch compile and link flags are no longer added automatically based on the- CMAKE_SYSTEM_PROCESSORvariable or the undocumented- CMAKE_SYSTEM_ARCHvariable. They must be specified explicitly. See policy- CMP0123.
Other Changes¶
- The - find_file(),- find_path(),- find_program(), and- find_library()commands handle cache variables in the same way regardless how they are defined. See policy- CMP0125for details.
- The - find_file(),- find_path(),- find_program(), and- find_library()commands gained the option- NO_CACHEto store find result in normal variable.
- The - foreach()command now isolates loop variables in the loop scope. See policy- CMP0124for details.
- The - list()command's- GET,- INSERT,- SUBLIST, and- REMOVE_ATsubcommands now error with invalid (i.e., non-integer) values are given as any of their index arguments based on the setting of policy- CMP0121.
- The - set(CACHE)command no longer removes a normal variable of the same name, if any. See policy- CMP0126.
- target_link_libraries()calls referencing object libraries via the- TARGET_OBJECTSgenerator expression now place the object files before all libraries on the link line, regardless of their specified order. See documentation on Linking Object Libraries via $<TARGET_OBJECTS> for details.
- The Ninja Generators now pass source files and include directories to the compiler using absolute paths. This makes diagnostic messages and debug symbols more consistent, and matches the Makefile Generators. 
- The - NMake Makefilesgenerator now encodes the generated makefiles as UTF-8 with a BOM when using- nmakefrom VS 9 or above.
- The Visual Studio Generators for VS 2010 and above now place per-source preprocessor definitions after target-wide preprocssor definitions. This makes VS consistent with the Ninja Generators and the Makefile Generators. 
- The precompiled binaries provided on cmake.org now support - liblzmamulti-threading. See the- CPACK_THREADSand- CPACK_ARCHIVE_THREADSvariables.
Updates¶
Changes made since CMake 3.21.0 include the following.
3.21.1¶
- The - Visual Studio 17 2022generator is now based on "Visual Studio 2022 Preview 2". Previously it was based on "Preview 1.1".
3.21.2¶
- CUDAtargets with- CUDA_SEPARABLE_COMPILATIONenabled are now correctly generated in non-root directories.
- The - Visual Studio 17 2022generator is now based on "Visual Studio 2022 Preview 3.1". Previously it was based on "Preview 2".
3.21.3¶
- The - Visual Studio 17 2022generator is now based on "Visual Studio 2022 Preview 4". Previously it was based on "Preview 3.1".
- The AMD ROCm Platform - hipcccompiler was identified by CMake 3.21.0 through 3.21.2 as a distinct compiler with id- ROCMClang. This has been removed because it caused regressions. Instead:- hipccmay no longer be used as a- HIPcompiler because it interferes with flags CMake needs to pass to Clang. Use Clang directly.
- hipccmay once again be used as a- CXXcompiler, and is treated as whatever compiler it selects underneath, as CMake 3.20 and below did.
 
3.21.4¶
- The - Visual Studio 17 2022generator is now based on the "Visual Studio 2022" release candidates. Previously it was based on preview versions.
3.21.5, 3.21.6, 3.21.7¶
These versions made no changes to documented features or interfaces. Some implementation updates were made to support ecosystem changes and/or fix regressions.
