CMake 3.24 Release Notes¶
Changes made since CMake 3.23 include the following.
New Features¶
Presets¶
cmake-presets(7)files now support schema version5.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 atestOutputTruncationfield in test presets, which specifies the truncation mode once the maximum test output size has been reached.
Generators¶
The
Green Hills MULTIgenerator now generates build rules to re-run CMake if any CMake files are updated.The Visual Studio Generators now support
SYSTEMheaders when using VS 2019 Update 11 or later.
Command-Line¶
cmake(1)gained the--freshcommand-line option to remove any existingCMakeCache.txtfile and associatedCMakeFiles/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-errorcommand-line option which causes the effects of theCOMPILE_WARNING_AS_ERRORtarget property andCMAKE_COMPILE_WARNING_AS_ERRORvariable to be ignored.The
cmake(1)--trace=json-v1trace format gained fieldsglobal_frameandline_end.The
cmake(1)-Ecommandscatandenvlearned 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 tarcommand gained the--touchoption 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-ADSPplatform module.
Platforms¶
A dedicated
ADSPplatform has been added to replace the existingGeneric-ADSPimplementation. This features automatic detection of the latest CCES/VDSP++ install and compiler selection (cc21kvs.ccblkfn) based off of theCMAKE_SYSTEM_PROCESSORvariable.
Commands¶
The
cmake_host_system_information()command, on Windows, gained aQUERY WINDOWS_REGISTRYmode. See its Query Windows registry section.The
cmake_language()command gained a newSET_DEPENDENCY_PROVIDERsub-command. When a dependency provider is set, calls tofind_package()andFetchContent_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 optionsRANGE_STARTandRANGE_ENDto 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(), andfind_package()commands gained theNO_CMAKE_INSTALL_PREFIXoption to control searchingCMAKE_INSTALL_PREFIX.The
find_file(),find_path(),find_library(),find_program(), andfind_package()commands gained the ability to specify which Windows Registry views must be queried.The
find_package()command gained aGLOBALoption that allows for the promotion of imported targets to global scope for the duration of thefind_package()call.The
if()command gained the capability to compare paths by using thePATH_EQUALoperator. See policyCMP0139.
Variables¶
The
CMAKE_COLOR_DIAGNOSTICSvariable was added to control color diagnostics generated by compilers. This variable also controls color build system messages with Makefile Generators, replacingCMAKE_COLOR_MAKEFILE.The
CMAKE_COLOR_DIAGNOSTICSenvironment variable was added to set a default value forCMAKE_COLOR_DIAGNOSTICS.The
CMAKE_COMPILE_WARNING_AS_ERRORvariable and correspondingCOMPILE_WARNING_AS_ERRORtarget property were added to enable compilation with a compiler-specific flag to treat warnings as errors, such as-Werror.The
CMAKE_CUDA_ARCHITECTURESvariable and associatedCUDA_ARCHITECTUREStarget property now support the specialnativevalue to compile for the architectures(s) of the host's GPU(s).The
CMAKE_FIND_PACKAGE_TARGETS_GLOBALvariable was added to toggle behavior of thefind_package()command's newGLOBALoption.The
CMAKE_FIND_USE_INSTALL_PREFIXvariable was added to toggle behavior of thefind_file(),find_library(),find_path(),find_package(), andfind_program()commands' newNO_CMAKE_INSTALL_PREFIXoption.The
CMAKE_PROJECT_TOP_LEVEL_INCLUDESvariable was added to allow injecting custom code at the site of the firstproject()call, after the host and target platform details have been determined.The
CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLESvariable was added to tell thetry_compile()command not to pass any platform variables to the test project.The
CMAKE_VERIFY_INTERFACE_HEADER_SETSvariable and correspondingVERIFY_INTERFACE_HEADER_SETStarget 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_BATCHINGvariable and correspondingVS_NO_COMPILE_BATCHINGtarget 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_LIBRARYvariable andWATCOM_RUNTIME_LIBRARYtarget property were introduced to select the runtime library used by compilers targeting the Watcom ABI. See policyCMP0136.The
CMAKE_XCODE_XCCONFIGvariable and correspondingXCODE_XCCONFIGtarget property were added to tell theXcodegenerator to handlexcconfigfiles.
Properties¶
The
INTERFACE_LINK_LIBRARIES_DIRECTandINTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDEtarget properties were added to express usage requirements affecting a consumer's direct link dependencies.The
INTERFACE_HEADER_SETS_TO_VERIFYtarget property was added to specify which header sets should be verified byVERIFY_INTERFACE_HEADER_SETS.The
LINK_LIBRARIEStarget property now supports the$<LINK_ONLY:...>generator expression. See policyCMP0131.The
VS_DOTNET_STARTUP_OBJECTtarget 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 onestatic void Main(string[])function signature is available in a managed .NET project.
Modules¶
The
ExternalProjectmoduleExternalProject_Add()command gained a newDOWNLOAD_EXTRACT_TIMESTAMPoption for controlling whether the timestamps of extracted contents are set to match those in the archive when theURLdownload method is used. PolicyCMP0135was added to enable the option by default.The
FetchContentmodule and thefind_package()command now support integration capabilities:FetchContent_MakeAvailable()can now try to satisfy a dependency by callingfind_package()first. A newFETCHCONTENT_TRY_FIND_PACKAGE_MODEvariable 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 callFetchContent_MakeAvailable()instead. A new read-onlyCMAKE_FIND_PACKAGE_REDIRECTS_DIRvariable points to a directory where config package files can be located to facilitate these re-routed calls.
The
FindJNImodule now provides imported targets.The
FindMatlabmodulematlab_add_mex()function gained aNO_IMPLICIT_LINK_TO_MATLAB_LIBRARIESoption to disable automatic linking of MATLAB libraries.The
FindVulkanmodule now supports components to select which VulkanSDK tool and libraries to find in addition to the Vulkan SDK headers and library.The
FindZLIBgained a newZLIB_USE_STATIC_LIBSvariable to search only for static libraries.
Generator Expressions¶
The
LINK_LIBRARYgenerator expression was added to manage how libraries are specified during the link step. TheCMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>andCMAKE_LINK_LIBRARY_USING_<FEATURE>variables are used to define features usable by theLINK_LIBRARYgenerator expression. Moreover, theLINK_LIBRARY_OVERRIDEandLINK_LIBRARY_OVERRIDE_<LIBRARY>target properties are available to resolve incompatible features.The
LINK_LIBRARYgenerator expression can link frameworks in various ways when targetingAppleplatforms. The following features were added:FRAMEWORKNEEDED_FRAMEWORKREEXPORT_FRAMEWORKWEAK_FRAMEWORK
The
LINK_LIBRARYgenerator expression can link libraries in various ways when targetingAppleplatforms. The following features were added:NEEDED_LIBRARYREEXPORT_LIBRARYWEAK_LIBRARY
The
LINK_LIBRARYgenerator expression gained the featureWHOLE_ARCHIVEto force load of all members in a static library. This feature is supported on the following target platforms:all
ApplevariantsLinuxall
BSDvariantsSunOSWindowsCYGWINMSYS
The
LINK_GROUPgenerator expression was added to manage the grouping of libraries during the link step. TheCMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>andCMAKE_LINK_GROUP_USING_<FEATURE>variables are used to define features usable with theLINK_GROUPgenerator expression. This release defines theRESCANfeature, which can be used to handle circular references among static libraries when using toolchains for Linux, BSD, SunOS and GNU toolchains for Windows.The
PATHgenerator expression was added to manage paths.The
PATH_EQUALgenerator expression was added to manage path comparisons.The
TARGET_BUNDLE_DIR_NAMEgenerator expression was added to evaluate to the name of the bundle directory for a given bundle target.
CTest¶
ctest(1)gained a--test-output-truncationoption (and correspondingCTEST_CUSTOM_TEST_OUTPUT_TRUNCATIONvariable) to specify the truncation mode once the maximum test output size has been reached. Possible values aretail(default),middleorhead.
CPack¶
The
CPack WIX Generatorgained 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_THREADSoption forzstdcompression when compiled with libarchive 3.6 or higher. It is supported by official CMake binaries available on cmake.org.
Deprecated and Removed Features¶
The
CPackmodule no longer enables the SLA by default in theCPack DragNDrop Generator. See policyCMP0133and theCPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSEvariable.The deprecated
CPack PackageMaker Generatorhas been removed.The
FindGLUTmodule no longer provides the undocumentedGLUT_LIBRARYandGLUT_INCLUDE_PATHresult variables.The
FindVulkanmodule no longer silently ignores unknown components requested by afind_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 policyCMP0132.The
CheckIPOSupportedmodulecheck_ipo_supported()command now uses the caller'sCMAKE_<LANG>_FLAGSandCMAKE_<LANG>_FLAGS_<CONFIG>values. See policyCMP0138.The
MSYS MakefilesandMinGW Makefilesgenerators, when a compiler is not explicitly specified, now select the first compiler (of any name) found in directories listed by thePATHenvironment variable.The
try_compile()command whole-project signature now propagates platform variables. See policyCMP0137.The
while()command now diagnoses errors during condition evaluation. See policyCMP0130.The precompiled macOS binaries provided on cmake.org no longer attach a SLA to the
.dmgpackages. This was removed because macOS 12 deprecated the tools used to attach.dmgresources.A precompiled Windows
arm64binary 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
LLVMFlangFortran 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.