CMake 3.21 Release Notes — CMake 3.29.5 Documentation

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