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 generator and binaryDir fields.

Generators

• The Visual Studio 17 2022 generator was added.

• The Makefile Generators and the Ninja generator learned to add linker launcher tools along with the linker for C, CXX, OBJC, and OBJCXX languages. See the CMAKE_<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 the project() and enable_language() commands.

• C_STANDARD, OBJC_STANDARD, and the Compile 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 command-line option to specify the location of the install prefix.

• cmake(1) gained the --toolchain command-line option to specify a toolchain file.

• cmake(1) -E capabilities output, for some generators, may now contain a supportedPlatforms field 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 Fujitsu in traditional (Trad) mode, and compiler id FujitsuClang in Clang mode.

Platforms

• CMake now supports the MSYS runtime environment, much like CYGWIN.

File-Based API

• The cmake-file-api(7) "codemodel" version 2 version 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 the install() command.

Commands

• The add_custom_command() command DEPFILE 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.

• The add_custom_command(TARGET) command (for Build Events) gained support for resolving target-dependent generator expressions.

• The build_command() command gained a PARALLEL_LEVEL option.

• The file(COPY_FILE) command was added to copy a single file.

• The file(GET_RUNTIME_DEPENDENCIES) command gained new POST_INCLUDE_FILES and POST_EXCLUDE_FILES arguments.

• The file(REAL_PATH) command gained the option EXPAND_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 a NO_REPLACE option to fail if the destination exists.

• The install() command gained a new IMPORTED_RUNTIME_ARTIFACTS mode, which can be used to install the runtime artifacts of imported targets.

• The install() command gained a new RUNTIME_DEPENDENCY_SET mode, which can be used to install runtime dependencies using file(GET_RUNTIME_DEPENDENCIES).

• The install(TARGETS) command gained new RUNTIME_DEPENDENCIES and RUNTIME_DEPENDENCY_SET arguments, which can be used to install runtime dependencies using file(GET_RUNTIME_DEPENDENCIES).

• The install(SCRIPT|CODE) command supports a new option ALL_COMPONENTS which allows the corresponding code to run for every component of a per component installation.

• The project() command now sets variables PROJECT_IS_TOP_LEVEL and <PROJECT-NAME>_IS_TOP_LEVEL to indicate whether it was called in a top-level CMakeLists.txt file.

Variables

• The CMAKE_TOOLCHAIN_FILE environment variable was added to provide a default value for the CMAKE_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 the Xcode generator 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_COPY and XCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPY properties.

Modules

• The FindBLAS and FindLAPACK modules learned to support the serial Fujitsu_SSL2 and parallel Fujitsu_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 support Fujitsu and FujitsuClang in both host and cross compiling modes.

• The FindMsys module 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 FindOpenMP module learned to support Fujitsu and FujitsuClang.

• The FindVulkan module gained imported targets Vulkan::Headers and Vulkan::glslangValidator.

• The UseJava module command add_jar gained a RESOURCES option to allow explicit naming of resources with non-optional namespace.

• The UseSWIG module use now standard library naming conventions for the CSharp language. See policy CMP0122.

• The UseSWIG module now supports using the swig tool to generate implicit dependencies with the Xcode 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 the ATTACHED_FILES or ATTACHED_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 a PARALLEL_LEVEL option.

CPack

• The CPack DragNDrop Generator gained option CPACK_DMG_FILESYSTEM to control the .dmg filesystem.

• The CPack IFW Generator now supports hyphens in names given to cpack_ifw_configure_component() or cpack_ifw_configure_component_group() as DEPENDS or DEPENDENCIES arguments. This requires QtIFW 3.1 or later.

• The CPack NSIS Generator gained a new CPACK_NSIS_EXECUTABLE variable to specify the makensis executable to use instead of the default one.

• The CPACK_CUSTOM_INSTALL_VARIABLES variable was added to set variables in cmake_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 a toolchain file, it is left unaltered, even if it still contains a version number. Similar CMAKE_HOST_SYSTEM_NAME version-stripping behavior, also undocumented, has been moved earlier, before project() or enable_language() is called.

• ARMClang cpu/arch compile and link flags are no longer added automatically based on the CMAKE_SYSTEM_PROCESSOR variable or the undocumented CMAKE_SYSTEM_ARCH variable. 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 CMP0125 for details.

• The find_file(), find_path(), find_program(), and find_library() commands gained the option NO_CACHE to store find result in normal variable.

• The foreach() command now isolates loop variables in the loop scope. See policy CMP0124 for details.

• The list() command's GET, INSERT, SUBLIST, and REMOVE_AT subcommands 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_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 using nmake 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 the CPACK_THREADS and CPACK_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 with CUDA_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".

3.21.3

• The Visual Studio 17 2022 generator is now based on "Visual Studio 2022 Preview 4". Previously it was based on "Preview 3.1".

• The AMD ROCm Platform hipcc compiler 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:

  • hipcc may no longer be used as a HIP compiler because it interferes with flags CMake needs to pass to Clang. Use Clang directly.

  • hipcc may once again be used as a CXX compiler, and is treated as whatever compiler it selects underneath, as CMake 3.20 and below did.

3.21.4

• The Visual Studio 17 2022 generator 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.