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.