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 thegenerator
andbinaryDir
fields.
Generators¶
- The
Visual Studio 17 2022
generator was added. This is experimental and based on "Visual Studio 2022 Preview 3.1" because this version of VS has not been released. - The Makefile Generators and the
Ninja
generator learned to add linker launcher tools along with the linker forC
,CXX
,OBJC
, andOBJCXX
languages. See theCMAKE_<LANG>_LINKER_LAUNCHER
variable and<LANG>_LINKER_LAUNCHER
target property for details.
Languages¶
- CMake learned to support
HIP
as a first-class language that can be enabled via theproject()
andenable_language()
commands. C_STANDARD
,OBJC_STANDARD
, and theCompile Features
functionality gained support for C17 and C23.- Source file extensions
.ixx
and.cppm
are 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 capabilities
output, for some generators, may now contain asupportedPlatforms
field 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
Fujitsu
in traditional (Trad
) mode, and compiler idFujitsuClang
inClang
mode.
File-Based API¶
- The
cmake-file-api(7)
"codemodel" version 2version
field 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()
commandDEPFILE
option:- may now use
generator expressions
, - is now supported by Visual Studio Generators for VS 2012 and above, and
- is now supported by the
Xcode
generator.
- may now use
- The
add_custom_command(TARGET)
command (for Build Events) gained support for resolving target-dependent generator expressions. - The
build_command()
command gained aPARALLEL_LEVEL
option. - The
file(COPY_FILE)
command was added to copy a single file. - The
file(GET_RUNTIME_DEPENDENCIES)
command gained newPOST_INCLUDE_FILES
andPOST_EXCLUDE_FILES
arguments. - The
file(REAL_PATH)
command gained the optionEXPAND_TILDE
to 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_REPLACE
option to fail if the destination exists. - The
install()
command gained a newIMPORTED_RUNTIME_ARTIFACTS
mode, which can be used to install the runtime artifacts of imported targets. - The
install()
command gained a newRUNTIME_DEPENDENCY_SET
mode, which can be used to install runtime dependencies usingfile(GET_RUNTIME_DEPENDENCIES)
. - The
install(TARGETS)
command gained newRUNTIME_DEPENDENCIES
andRUNTIME_DEPENDENCY_SET
arguments, which can be used to install runtime dependencies usingfile(GET_RUNTIME_DEPENDENCIES)
. - The
install(SCRIPT|CODE)
command supports a new optionALL_COMPONENTS
which allows the corresponding code to run for every component of a per component installation. - The
project()
command now sets variablesPROJECT_IS_TOP_LEVEL
and<PROJECT-NAME>_IS_TOP_LEVEL
to indicate whether it was called in a top-levelCMakeLists.txt
file.
Variables¶
- The
CMAKE_TOOLCHAIN_FILE
environment variable was added to provide a default value for theCMAKE_TOOLCHAIN_FILE
variable.
Properties¶
- The
IMPORTED_TARGETS
directory property was added to get a list of Imported Targets created in the current directory. - The
XCODE_EMBED_APP_EXTENSIONS
target property was added to tell theXcode
generator 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_COPY
andXCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY
properties.
Modules¶
- The
FindBLAS
andFindLAPACK
modules learned to support the serialFujitsu_SSL2
and parallelFujitsu_SSL2BLAMP
libraries. - The
FindDevIL
module now provides imported targets. - The
FindIconv
module now has version support. - The
FindIntl
module now has version support. - The
FindMPI
module learned to supportFujitsu
andFujitsuClang
in both host and cross compiling modes. - The
FindMsys
module was added to find MSYS installations. LikeFindCygwin
, it is used automatically by some other find modules to locate UNIX-style tools on Windows. - The
FindOpenMP
module learned to supportFujitsu
andFujitsuClang
. - The
FindVulkan
module gained imported targetsVulkan::Headers
andVulkan::glslangValidator
. - The
UseJava
module commandadd_jar
gained aRESOURCES
option to allow explicit naming of resources with non-optional namespace. - The
UseSWIG
module use now standard library naming conventions for theCSharp
language. See policyCMP0122
. - The
UseSWIG
module now supports using theswig
tool to generate implicit dependencies with theXcode
generator.
Generator Expressions¶
- A new
TARGET_RUNTIME_DLLS
generator 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_FILES
orATTACHED_FILES_ON_FAIL
test properties. See Additional Test Measurements for more information.ctest(1)
gained a--output-junit
option to write test results to a JUnit XML file.- The
ctest_build()
command gained aPARALLEL_LEVEL
option.
CPack¶
- The
CPack DragNDrop Generator
gained optionCPACK_DMG_FILESYSTEM
to control the.dmg
filesystem. - The
CPack IFW Generator
now supports hyphens in names given tocpack_ifw_configure_component()
orcpack_ifw_configure_component_group()
asDEPENDS
orDEPENDENCIES
arguments. This requires QtIFW 3.1 or later. - The
CPack NSIS Generator
gained a newCPACK_NSIS_EXECUTABLE
variable to specify themakensis
executable to use instead of the default one. - The
CPACK_CUSTOM_INSTALL_VARIABLES
variable was added to set variables incmake_install.cmake
script invocations made by CPack.
Deprecated and Removed Features¶
- Undocumented
CMAKE_SYSTEM_NAME
version-stripping behavior has been removed entirely. If it is set by a-D
flag or by atoolchain file
, it is left unaltered, even if it still contains a version number. SimilarCMAKE_HOST_SYSTEM_NAME
version-stripping behavior, also undocumented, has been moved earlier, beforeproject()
orenable_language()
is called. ARMClang
cpu/arch compile and link flags are no longer added automatically based on theCMAKE_SYSTEM_PROCESSOR
variable or the undocumentedCMAKE_SYSTEM_ARCH
variable. 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 policyCMP0125
for details. - The
find_file()
,find_path()
,find_program()
, andfind_library()
commands gained the optionNO_CACHE
to store find result in normal variable. - The
foreach()
command now isolates loop variables in the loop scope. See policyCMP0124
for details. - The
list()
command'sGET
,INSERT
,SUBLIST
, andREMOVE_AT
subcommands 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_OBJECTS
generator 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 Makefiles
generator now encodes the generated makefiles as UTF-8 with a BOM when usingnmake
from 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
liblzma
multi-threading. See theCPACK_THREADS
andCPACK_ARCHIVE_THREADS
variables.
Updates¶
Changes made since CMake 3.21.0 include the following.
3.21.1¶
- The
Visual Studio 17 2022
generator is now based on "Visual Studio 2022 Preview 2". Previously it was based on "Preview 1.1".
3.21.2¶
CUDA
targets withCUDA_SEPARABLE_COMPILATION
enabled are now correctly generated in non-root directories.- The
Visual Studio 17 2022
generator is now based on "Visual Studio 2022 Preview 3.1". Previously it was based on "Preview 2".