CMake 3.24 Release Notes — CMake 3.27.7 Documentation

# CMake 3.24 Release Notes

Changes made since CMake 3.23 include the following.

## New Features

### Presets

- `cmake-presets(7)` files now support schema version `5`.

- `cmake-presets(7)` files now support a `${pathListSep}` macro, which expands to `:` or `;` based on the platform.

- `cmake-presets(7)` files gained support for specifying a `testOutputTruncation` field in test presets, which specifies the truncation mode once the maximum test output size has been reached.

### Generators

- The `Green Hills MULTI` generator now generates build rules to re-run CMake if any CMake files are updated.

- The Visual Studio Generators now support `SYSTEM` headers when using VS 2019 Update 11 or later.

### Command-Line

- `cmake(1)` gained the `--fresh` command-line option to remove any existing `CMakeCache.txt` file and associated `CMakeFiles/` directory, when configuring a build tree, thus starting a new configuration as if the build tree were freshly created.

- `cmake(1)` gained the `--compile-no-warning-as-error` command-line option which causes the effects of the `COMPILE_WARNING_AS_ERROR` target property and `CMAKE_COMPILE_WARNING_AS_ERROR` variable to be ignored.

- The `cmake(1)` `--trace=json-v1` trace format gained fields `global_frame` and `line_end`.

- The `cmake(1)` `-E` commands `cat` and `env` learned to respect a double dash (`--`) argument that acts as a delimiter indicating the end of options. Any following arguments are treated as operands/positional arguments, even if they begin with a dash `-` character.

- The `cmake(1)` `-E tar` command gained the `--touch` option to keep the current local timestamp instead of extracting file timestamps from the archive.

### Compilers

- LLVM's flang Fortran compiler is now supported on some platforms, with compiler id `LLVMFlang`.

- ADSP compiler support (SHARC and Blackfin) now covers both CCES and VDSP++ installations, with required configuration now done in the compiler module itself rather than the `Generic-ADSP` platform module.

### Platforms

- A dedicated `ADSP` platform has been added to replace the existing `Generic-ADSP` implementation. This features automatic detection of the latest CCES/VDSP++ install and compiler selection (`cc21k` vs. `ccblkfn`) based off of the `CMAKE_SYSTEM_PROCESSOR` variable.

### Commands

- The `cmake_host_system_information()` command, on Windows, gained a `QUERY WINDOWS_REGISTRY` mode. See its Query Windows registry section.

- The `cmake_language()` command gained a new `SET_DEPENDENCY_PROVIDER` sub-command. When a dependency provider is set, calls to `find_package()` and `FetchContent_MakeAvailable()` can be redirected through a custom command, which can choose to fulfill the request directly, modify how the request is processed, or leave it to be fulfilled by the built-in implementation. See Dependency Providers.

- The `file(DOWNLOAD)` command gained options `RANGE_START` and `RANGE_END` to specify a range of bytes to download. This can be useful for downloading parts of big binary files.

- The `find_file()`, `find_path()`, `find_library()`, `find_program()`, and `find_package()` commands gained the `NO_CMAKE_INSTALL_PREFIX` option to control searching `CMAKE_INSTALL_PREFIX`.

- The `find_file()`, `find_path()`, `find_library()`, `find_program()`, and `find_package()` commands gained the ability to specify which Windows Registry views must be queried.

- The `find_package()` command gained a `GLOBAL` option that allows for the promotion of imported targets to global scope for the duration of the `find_package()` call.

- The `if()` command gained the capability to compare paths by using the `PATH_EQUAL` operator. See policy `CMP0139`.

### Variables

- The `CMAKE_COLOR_DIAGNOSTICS` variable was added to control color diagnostics generated by compilers. This variable also controls color build system messages with Makefile Generators, replacing `CMAKE_COLOR_MAKEFILE`.

  The `CMAKE_COLOR_DIAGNOSTICS` environment variable was added to set a default value for `CMAKE_COLOR_DIAGNOSTICS`.

- The `CMAKE_COMPILE_WARNING_AS_ERROR` variable and corresponding `COMPILE_WARNING_AS_ERROR` target property were added to enable compilation with a compiler-specific flag to treat warnings as errors, such as `-Werror`.

- The `CMAKE_CUDA_ARCHITECTURES` variable and associated `CUDA_ARCHITECTURES` target property now support the special `native` value to compile for the architectures(s) of the host's GPU(s).

- The `CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` variable was added to toggle behavior of the `find_package()` command's new `GLOBAL` option.

- The `CMAKE_FIND_USE_INSTALL_PREFIX` variable was added to toggle behavior of the `find_file()`, `find_library()`, `find_path()`, `find_package()`, and `find_program()` commands' new `NO_CMAKE_INSTALL_PREFIX` option.

- The `CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable was added to allow injecting custom code at the site of the first `project()` call, after the host and target platform details have been determined.

- The `CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable was added to tell the `try_compile()` command not to pass any platform variables to the test project.

- The `CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable and corresponding `VERIFY_INTERFACE_HEADER_SETS` target property were added to enable build rules that verify all headers in header sets can be used on their own.

- The `CMAKE_VS_NO_COMPILE_BATCHING` variable and corresponding `VS_NO_COMPILE_BATCHING` target property were added to tell Visual Studio Generators whether to disable compiler parallelism and call the compiler with one source file at a time.

- The `CMAKE_WATCOM_RUNTIME_LIBRARY` variable and `WATCOM_RUNTIME_LIBRARY` target property were introduced to select the runtime library used by compilers targeting the Watcom ABI. See policy `CMP0136`.

- The `CMAKE_XCODE_XCCONFIG` variable and corresponding `XCODE_XCCONFIG` target property were added to tell the `Xcode` generator to handle `xcconfig` files.

### Properties

- The `INTERFACE_LINK_LIBRARIES_DIRECT` and `INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties were added to express usage requirements affecting a consumer's direct link dependencies.

- The `INTERFACE_HEADER_SETS_TO_VERIFY` target property was added to specify which header sets should be verified by `VERIFY_INTERFACE_HEADER_SETS`.

- The `LINK_LIBRARIES` target property now supports the `$<LINK_ONLY:...>` generator expression. See policy `CMP0131`.

- The `VS_DOTNET_STARTUP_OBJECT` target property was added to tell Visual Studio Generators which startup class shall be used when the program or project is executed. This is necessary when more than one `static void Main(string[])` function signature is available in a managed .NET project.

### Modules

- The `ExternalProject` module `ExternalProject_Add()` command gained a new `DOWNLOAD_EXTRACT_TIMESTAMP` option for controlling whether the timestamps of extracted contents are set to match those in the archive when the `URL` download method is used. Policy `CMP0135` was added to enable the option by default.

- The `FetchContent` module and the `find_package()` command now support integration capabilities:

  - `FetchContent_MakeAvailable()` can now try to satisfy a dependency by calling `find_package()` first. A new `FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable controls whether this is done by default for all dependencies, is opt-in per dependency, or is disabled entirely.

  - `find_package()` can be re-routed to call `FetchContent_MakeAvailable()` instead. A new read-only `CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable points to a directory where config package files can be located to facilitate these re-routed calls.

- The `FindJNI` module now provides imported targets.

- The `FindMatlab` module `matlab_add_mex()` function gained a `NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES` option to disable automatic linking of MATLAB libraries.

- The `FindVulkan` module now supports components to select which VulkanSDK tool and libraries to find in addition to the Vulkan SDK headers and library.

- The `FindZLIB` gained a new `ZLIB_USE_STATIC_LIBS` variable to search only for static libraries.

### Generator Expressions

- The `LINK_LIBRARY` generator expression was added to manage how libraries are specified during the link step. The `CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` and `CMAKE_LINK_LIBRARY_USING_<FEATURE>` variables are used to define features usable by the `LINK_LIBRARY` generator expression. Moreover, the `LINK_LIBRARY_OVERRIDE` and `LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties are available to resolve incompatible features.

  The `LINK_LIBRARY` generator expression can link frameworks in various ways when targeting `Apple` platforms. The following features were added:

  - `FRAMEWORK`

  - `NEEDED_FRAMEWORK`

  - `REEXPORT_FRAMEWORK`

  - `WEAK_FRAMEWORK`

  The `LINK_LIBRARY` generator expression can link libraries in various ways when targeting `Apple` platforms. The following features were added:

  - `NEEDED_LIBRARY`

  - `REEXPORT_LIBRARY`

  - `WEAK_LIBRARY`

  The `LINK_LIBRARY` generator expression gained the feature `WHOLE_ARCHIVE` to force load of all members in a static library. This feature is supported on the following target platforms:

  - all `Apple` variants

  - `Linux`

  - all `BSD` variants

  - `SunOS`

  - `Windows`

  - `CYGWIN`

  - `MSYS`

- The `LINK_GROUP` generator expression was added to manage the grouping of libraries during the link step. The `CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` and `CMAKE_LINK_GROUP_USING_<FEATURE>` variables are used to define features usable with the `LINK_GROUP` generator expression. This release defines the `RESCAN` feature, which can be used to handle circular references among static libraries when using toolchains for Linux, BSD, SunOS and GNU toolchains for Windows.

- The `PATH` generator expression was added to manage paths.

- The `PATH_EQUAL` generator expression was added to manage path comparisons.

- The `TARGET_BUNDLE_DIR_NAME` generator expression was added to evaluate to the name of the bundle directory for a given bundle target.

### CTest

- `ctest(1)` gained a `--test-output-truncation` option (and corresponding `CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable) to specify the truncation mode once the maximum test output size has been reached. Possible values are `tail` (default), `middle` or `head`.

### CPack

- The `CPack WIX Generator` gained a new variable, `CPACK_WIX_ARCHITECTURE`, to specify the installer architecture in order to support computers running Windows for ARM.

- CPack now supports the `CPACK_THREADS` option for `zstd` compression when compiled with libarchive 3.6 or higher. It is supported by official CMake binaries available on cmake.org.

## Deprecated and Removed Features

- The `CPack` module no longer enables the SLA by default in the `CPack DragNDrop Generator`. See policy `CMP0133` and the `CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` variable.

- The deprecated `CPack PackageMaker Generator` has been removed.

- The `FindGLUT` module no longer provides the undocumented `GLUT_LIBRARY` and `GLUT_INCLUDE_PATH` result variables.

- The `FindVulkan` module no longer silently ignores unknown components requested by a `find_package(Vulkan REQUIRED ...)` call. With the addition of support for components, requests for unknown components now produce an error.

## Other Changes

- CMake no longer sets environment variables like `CC`, `CXX`, etc. when enabling the corresponding language during the first CMake run in a build directory. See policy `CMP0132`.

- The `CheckIPOSupported` module `check_ipo_supported()` command now uses the caller's `CMAKE_<LANG>_FLAGS` and `CMAKE_<LANG>_FLAGS_<CONFIG>` values. See policy `CMP0138`.

- The `MSYS Makefiles` and `MinGW Makefiles` generators, when a compiler is not explicitly specified, now select the first compiler (of any name) found in directories listed by the `PATH` environment variable.

- The `try_compile()` command whole-project signature now propagates platform variables. See policy `CMP0137`.

- The `while()` command now diagnoses errors during condition evaluation. See policy `CMP0130`.

- The precompiled macOS binaries provided on cmake.org no longer attach a SLA to the `.dmg` packages. This was removed because macOS 12 deprecated the tools used to attach `.dmg` resources.

- A precompiled Windows `arm64` binary is now provided on cmake.org.

## Updates

Changes made since CMake 3.24.0 include the following.

### 3.24.1, 3.24.2

- These versions made no changes to documented features or interfaces. Some implementation updates were made to support ecosystem changes and/or fix regressions.

### 3.24.3

- The `LLVMFlang` Fortran compiler support added in 3.24.0 has been extended:

  - It now supports mixed-language linking between Fortran and C or CXX.

  - It now supports the GNU ABI (MinGW) on Windows, but not yet the MSVC ABI.

- Some implementation updates were made to support ecosystem changes and/or fix regressions.

### 3.24.4

- This version made no changes to documented features or interfaces. Some implementation updates were made to support ecosystem changes and/or fix regressions.