CMake 3.21 Release Notes¶
Contents
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 thegeneratorandbinaryDirfields.
Generators¶
The
Visual Studio 17 2022generator was added.The Makefile Generators and the
Ninjagenerator learned to add linker launcher tools along with the linker forC,CXX,OBJC, andOBJCXXlanguages. See theCMAKE_<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 theproject()andenable_language()commands.C_STANDARD,OBJC_STANDARD, and theCompile Featuresfunctionality gained support for C17 and C23.Source file extensions
.ixxand.cppmare now treated as C++.
Command-Line¶
cmake(1)gained the--install-prefix <dir>command-line option to specify the location of the install prefix.cmake(1)gained the--toolchain <path/to/file>command-line option to specify a toolchain file.cmake(1)-E capabilitiesoutput, for some generators, may now contain asupportedPlatformsfield listing platforms known to be supported inCMAKE_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 idFujitsuClanginClangmode.
File-Based API¶
The
cmake-file-api(7)"codemodel" version 2versionfield 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 theinstall()command.
Commands¶
The
add_custom_command()commandDEPFILEoption: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 aPARALLEL_LEVELoption.The
file(COPY_FILE)command was added to copy a single file.The
file(GET_RUNTIME_DEPENDENCIES)command gained newPOST_INCLUDE_FILESandPOST_EXCLUDE_FILESarguments.The
file(REAL_PATH)command gained the optionEXPAND_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 aNO_REPLACEoption to fail if the destination exists.The
install()command gained a newIMPORTED_RUNTIME_ARTIFACTSmode, which can be used to install the runtime artifacts of imported targets.The
install()command gained a newRUNTIME_DEPENDENCY_SETmode, which can be used to install runtime dependencies usingfile(GET_RUNTIME_DEPENDENCIES).The
install(TARGETS)command gained newRUNTIME_DEPENDENCIESandRUNTIME_DEPENDENCY_SETarguments, which can be used to install runtime dependencies usingfile(GET_RUNTIME_DEPENDENCIES).The
install(SCRIPT|CODE)command supports a new optionALL_COMPONENTSwhich allows the corresponding code to run for every component of a per component installation.The
project()command now sets variablesPROJECT_IS_TOP_LEVELand<PROJECT-NAME>_IS_TOP_LEVELto indicate whether it was called in a top-levelCMakeLists.txtfile.
Variables¶
The
CMAKE_TOOLCHAIN_FILEenvironment variable was added to provide a default value for theCMAKE_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 theXcodegenerator to embed app extensions such as iMessage sticker packs. Aspects of the embedding can be customized with theXCODE_EMBED_APP_EXTENSIONS_PATH,XCODE_EMBED_APP_EXTENSIONS_CODE_SIGN_ON_COPYandXCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPYproperties.
Modules¶
The
FindBLASandFindLAPACKmodules learned to support the serialFujitsu_SSL2and parallelFujitsu_SSL2BLAMPlibraries.The
FindDevILmodule now provides imported targets.The
FindIconvmodule now has version support.The
FindIntlmodule now has version support.The
FindMPImodule learned to supportFujitsuandFujitsuClangin both host and cross compiling modes.The
FindMsysmodule was added to find MSYS installations. LikeFindCygwin, it is used automatically by some other find modules to locate UNIX-style tools on Windows.The
FindOpenMPmodule learned to supportFujitsuandFujitsuClang.The
FindVulkanmodule gained imported targetsVulkan::HeadersandVulkan::glslangValidator.The
UseJavamodule commandadd_jargained aRESOURCESoption to allow explicit naming of resources with non-optional namespace.The
UseSWIGmodule use now standard library naming conventions for theCSharplanguage. See policyCMP0122.The
UseSWIGmodule now supports using theswigtool to generate implicit dependencies with theXcodegenerator.
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 theATTACHED_FILESorATTACHED_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 aPARALLEL_LEVELoption.
CPack¶
The
CPack DragNDrop Generatorgained optionCPACK_DMG_FILESYSTEMto control the.dmgfilesystem.The
CPack IFW Generatornow supports hyphens in names given tocpack_ifw_configure_component()orcpack_ifw_configure_component_group()asDEPENDSorDEPENDENCIESarguments. This requires QtIFW 3.1 or later.The
CPack NSIS Generatorgained a newCPACK_NSIS_EXECUTABLEvariable to specify themakensisexecutable to use instead of the default one.The
CPACK_CUSTOM_INSTALL_VARIABLESvariable was added to set variables incmake_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 atoolchain file, it is left unaltered, even if it still contains a version number. SimilarCMAKE_HOST_SYSTEM_NAMEversion-stripping behavior, also undocumented, has been moved earlier, beforeproject()orenable_language()is called.ARMClangcpu/arch compile and link flags are no longer added automatically based on theCMAKE_SYSTEM_PROCESSORvariable or the undocumentedCMAKE_SYSTEM_ARCHvariable. They must be specified explicitly. See policyCMP0123.
Other Changes¶
The
find_file(),find_path(),find_program(), andfind_library()commands handle cache variables in the same way regardless how they are defined. See policyCMP0125for details.The
find_file(),find_path(),find_program(), andfind_library()commands gained the optionNO_CACHEto store find result in normal variable.The
foreach()command now isolates loop variables in the loop scope. See policyCMP0124for details.The
list()command'sGET,INSERT,SUBLIST, andREMOVE_ATsubcommands now error with invalid (i.e., non-integer) values are given as any of their index arguments based on the setting of policyCMP0121.The
set(CACHE)command no longer removes a normal variable of the same name, if any. See policyCMP0126.target_link_libraries()calls referencing object libraries via theTARGET_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 usingnmakefrom 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 theCPACK_THREADSandCPACK_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 withCUDA_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 identifed by CMake 3.21.0 through 3.21.2 as a distinct compiler with idROCMClang. This has been removed because it caused regressions. Instead:hipccmay no longer be used as aHIPcompiler because it interferes with flags CMake needs to pass to Clang. Use Clang directly.hipccmay once again be used as aCXXcompiler, 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.