CMake 3.21 Release Notes

Contents

• CMake 3.21 Release Notes
  • New Features
    • Presets
    • Generators
    • Languages
    • Command-Line
    • Compilers
    • Platforms
    • File-Based API
    • Commands
    • Variables
    • Properties
    • Modules
    • Generator Expressions
    • CTest
    • CPack
  • Deprecated and Removed Features
  • Other Changes
  • Updates
    • 3.21.1
    • 3.21.2

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. 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 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 <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 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".