CMake 3.20 Release Notes¶
Changes made since CMake 3.19 include the following.
New Features¶
Presets¶
cmake-presets(7)gained support for build and test presets.
Generators¶
Makefile Generators, for some toolchains, now use the compiler to extract implicit dependencies while compiling source files.
Languages¶
C++23 compiler modes may now be specified via the
CXX_STANDARD,CUDA_STANDARD, orOBJCXX_STANDARDtarget properties, or via theCompile Featuresfunctionality'scxx_std_23meta-feature.CUDAlanguage support now works whennvccis a symbolic link, for example due to accacheorcolornvccwrapper script.The
CUDAARCHSenvironment variable was added for initializingCMAKE_CUDA_ARCHITECTURES. Useful in cases where the compiler default is unsuitable for the machine's GPU.
Compilers¶
The NVIDIA HPC SDK compilers are now supported with compiler id
NVHPC.The Intel oneAPI NextGen LLVM compilers are now supported with compiler id
IntelLLVM:The
icx/icpxC/C++ compilers on Linux, and theicxC/C++ compiler on Windows, are fully supported as of oneAPI 2021.1.The
ifxFortran compiler on Linux is supported as of oneAPI 2021.1.The
ifxFortran compiler on Windows is not yet supported.
The Intel oneAPI Classic compilers (
icc,icpc, andifort) continue to be supported with compiler idIntel.Support was added for the IAR STM8 compiler.
Platforms¶
CMake's support for Cross Compiling for Android is now merged with the Android NDK's toolchain file. They now have similar behavior, though some variable names differ. User-facing changes include:
find_*functions will search NDK ABI / API specific paths by default.The default
CMAKE_BUILD_TYPEfor Android is nowRelWithDebInfo.The
CMAKE_ANDROID_NDK_VERSIONvariable was added to report the version of the NDK.
File-Based API¶
The
cmake-file-api(7)gained a new "toolchains" object kind that describes the compiler used for each enabled language.
Commands¶
add_custom_command()andadd_custom_target()now supportgenerator expressionsin theirOUTPUTandBYPRODUCTSoptions.Their
COMMAND,WORKING_DIRECTORY, andDEPENDSoptions gained support for new generator expressions$<COMMAND_CONFIG:...>and$<OUTPUT_CONFIG:...>that control cross-config handling when using theNinja Multi-Configgenerator.The
add_custom_command()command gainedDEPFILEsupport on Makefile Generators.The
add_library()command previously prohibited imported object libraries when using potentially multi-architecture configurations. This mostly affected theXcodegenerator, e.g. when targeting iOS or one of the other device platforms. This restriction has now been removed.The
cmake_path()command was added for operations on filesystem paths.The
configure_file()command gainedUSE_SOURCE_PERMISSIONSandFILE_PERMISSIONSoptions to support copying of permissions of the source file and using specified permissions respectively.The
file(GENERATE)command gained aNEWLINE_STYLEoption to specify how newlines are handled for the generated file.The
file(GENERATE)command gainedNO_SOURCE_PERMISSIONS,USE_SOURCE_PERMISSIONS, andFILE_PERMISSIONSoptions for controlling the permissions of the generated file.The
install(FILES)commandRENAMEoption learned to supportgenerator expressions.The
target_include_directories()command gained a new optionAFTER.The
target_sources()command now supports targets created by theadd_custom_target()command.The
try_run()command gained aWORKING_DIRECTORYoption to set the working directory in which to run the compiled check executable.
Variables¶
The
CMAKE_<LANG>_BYTE_ORDERvariable was added to provide the target architecture byte order detected from the toolchain.The
CMAKE_RUNTIME_OUTPUT_DIRECTORY,CMAKE_LIBRARY_OUTPUT_DIRECTORY, andCMAKE_ARCHIVE_OUTPUT_DIRECTORYvariables now support target-dependent generator expressions.
Properties¶
The
<LANG>_CLANG_TIDYtarget property and the associatedCMAKE_<LANG>_CLANG_TIDYvariable learned to support theOBJCandOBJCXXlanguages.The
EXPORT_COMPILE_COMMANDStarget property was added for the associatedCMAKE_EXPORT_COMPILE_COMMANDSvariable to allow for configuration of exporting compile commands per target.Generated sources may be used across directories without manual marking. Additionally, the
GENERATEDsource file property can no longer be turned off once turned on, nor can it be set to other than boolean values. See policyCMP0118.The
UNITY_BUILD_UNIQUE_IDtarget property was added to support generation of an identifier that is unique per source file in unity builds. It can help to resolve duplicate symbol problems with anonymous namespaces.The
WIN32_EXECUTABLEtarget property now works with Clang on Windows.The
XCODE_EMBED_FRAMEWORKStarget property was added to tell theXcodegenerator to embed frameworks. Aspects of the embedding can be customized with theXCODE_EMBED_FRAMEWORKS_PATH,XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY, andXCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPYtarget properties.
Modules¶
The
ExternalDatamoduleExternalData_Add_Target()function gained aSHOW_PROGRESS <bool>option for controlling whether or not to show progress output during the build.The
ExternalProjectmoduleExternalProject_Add()function gained aCONFIGURE_HANDLED_BY_BUILDoption. This can be used to make subsequent runs of the configure step be triggered by the build step when an external project dependency rebuilds instead of always re-running the configure step in such cases.The
FindBoostmodule gained aBoost_NO_WARN_NEW_VERSIONSoption to silence the warning about unknown dependencies for new Boost versions.The
FindCUDAToolkitmodule gained support for finding CUDA toolkits whennvccis a symbolic link, for example due to accacheorcolornvccwrapper script.The
FindGDALmodule has been improved to document and mark as advanced its cache variables. There is a newFindGDAL_SKIP_GDAL_CONFIGvariable which may be used to skip over thegdal-config-based search. Users may also setGDAL_ADDITIONAL_LIBRARY_VERSIONSto add additional versions to the library name search strategy.The
FindIntlmodule now provides an imported target.The
FindOpenSSLmodule learned to support a version range.The
FindPython3,FindPython2andFindPythonmodules gained options controlling how unversioned interpreter names are searched.The
UseJavamoduleadd_jar()command'sGENERATE_NATIVE_HEADERSfeature gained options to export the generated target.The
UseSWIGmodule gained the capability, for Makefile and Ninja generators, to use theswigtool to generate implicit dependencies.
Autogen¶
The AUTOMOC feature now works with per-config sources.
CTest¶
ctest(1)gained a--test-diroption to specify the directory in which to look for tests.
CPack¶
CPackgained theCPACK_THREADSvariable to control the number of threads used for parallelized operations, such as compressing the installer package.The
CPack DEB Generatorlearned a newCPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRSvariable to specify additional search directories for resolving private library dependencies when usingdpkg-shlibdeps.The
CPack IFW Generatorgained a newCPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LISTvariable to control visibility of the widget listing installer pages on the left side of the wizard. This feature available only since QtIFW 4.0.The
CPack NSIS Generatorgained newCPACK_NSIS_BRANDING_TEXTandCPACK_NSIS_BRANDING_TEXT_TRIM_POSITIONvariables to change the text at the bottom of the install window and change its trim positionThe
CPack NSIS Generatornow correctly handles Unicode characters. If you want to have aCPACK_RESOURCE_FILE_LICENSEwith UTF-8 characters, it needs to be encoded in UTF-8 BOM.The
CPack NuGet Generatorgained options:CPACK_NUGET_PACKAGE_ICONandCPACK_NUGET_<compName>_PACKAGE_ICONallow package icons to be specified by local files.CPACK_NUGET_PACKAGE_LICENSE_EXPRESSIONandCPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSIONadd support for specifying licenses recognized by the Software Package Data Exchange (SPDX).CPACK_NUGET_PACKAGE_LICENSE_FILE_NAMEandCPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAMEallow licenses to be specified by local files.CPACK_NUGET_PACKAGE_LANGUAGEandCPACK_NUGET_<compName>_PACKAGE_LANGUAGEallow the locale for a package to be specified, for exampleen_CA.
Deprecated and Removed Features¶
The
cmake-server(7)mode has been removed. Clients should use thecmake-file-api(7)instead.The
WriteCompilerDetectionHeadermodule has been deprecated via policyCMP0120. Projects should be ported away from it.The
TestBigEndianmodule has been deprecated in favor of theCMAKE_<LANG>_BYTE_ORDERvariable.The
AddFileDependenciesmodule is deprecated. Port projects to useset_property()directly.The
CPack NuGet Generatordeprecated some variables to reflect changes in the NuGet specification:CPACK_NUGET_PACKAGE_ICONURLandCPACK_NUGET_<compName>_PACKAGE_ICONURLhave been deprecated; replace with a reference to a local icon file.CPACK_NUGET_PACKAGE_LICENSEURLandCPACK_NUGET_<compName>_PACKAGE_LICENSEURLhave been deprecated; replace with a reference to the project's license file or SPDX license expression.
Other Changes¶
When running
cmake(1)to Generate a Project Buildsystem, unknown command-line arguments starting with a hyphen (-) are now rejected with an error. Previously they were silently ignored.Source file extensions must now be explicit. See policy
CMP0115for details.The
LANGUAGEsource file property now forces compilation as the specified language. See policyCMP0119.On AIX, installation of XCOFF executables and shared libraries no longer requires relinking to change the runtime search path from the build-tree RPATH to the install-tree RPATH. CMake now edits the XCOFF binaries directly during installation, as has long been done on ELF platforms.
With MSVC-like compilers the value of
CMAKE_CXX_FLAGSno longer contains the/GRflag for runtime type information by default. See policyCMP0117.Ninja generators now transform the
DEPFILEgenerated by anadd_custom_command(). See policyCMP0116for details.The precompiled Linux binaries provided on cmake.org have changed their naming pattern to
cmake-$ver-linux-$arch, where$archis eitherx86_64oraarch64.The precompiled Windows binaries provided on cmake.org have changed their naming pattern to
cmake-$ver-windows-$arch, where$archis eitherx86_64ori386.
Updates¶
Changes made since CMake 3.20.0 include the following.
3.20.1¶
The
FindIntlmodule in CMake 3.20.0 added checksIntl_HAVE_GETTEXT_BUILTIN,Intl_HAVE_DCGETTEXT_BUILTIN, andIntl_IS_BUILTIN, but they were not implemented correctly. These have been removed and replaced with a singleIntl_IS_BUILT_INcheck, whose name is consistent with theFindIconvmodule.The
-rpathlinker flag is now specified as supported on all Apple platforms, not just macOS. Theinstall_name_dirused for iOS, tvOS and watchOS should now default to@rpathinstead of using a full absolute path and failing at runtime when the library or framework is embedded in an application bundle (seeXCODE_EMBED_<type>).
3.20.2¶
The Intel Classic 2021 compiler version numbers are now detected correctly as having major version 2021. CMake 3.20.1 and below were not aware of a change to the identification macro version scheme made by Intel starting in version 2021, and detected the version as 20.2.
The Intel oneAPI Fortran compiler is now identified as
IntelLLVM. The oneAPI 2021.1 Fortran compiler is missing an identification macro, so CMake 3.20.1 and below identified it asIntel. CMake now has a special case to recognize oneAPI 2021.1 Fortran asIntelLLVM. The oneAPI 2021.2 Fortran compiler defines the proper identification macro and so is identified asIntelLLVMby all CMake 3.20 versions.
3.20.3, 3.20.4, 3.20.5, 3.20.6¶
These versions made no changes to documented features or interfaces. Some implementation updates were made to support ecosystem changes and/or fix regressions.