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, or OBJCXX_STANDARD target properties, or via the Compile Features functionality's cxx_std_23 meta-feature.

• CUDA language support now works when nvcc is a symbolic link, for example due to a ccache or colornvcc wrapper script.

• The CUDAARCHS environment variable was added for initializing CMAKE_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/icpx C/C++ compilers on Linux, and the icx C/C++ compiler on Windows, are fully supported as of oneAPI 2021.1.

  • The ifx Fortran compiler on Linux is supported as of oneAPI 2021.1.

  • The ifx Fortran compiler on Windows is not yet supported.

  The Intel oneAPI Classic compilers (icc, icpc, and ifort) continue to be supported with compiler id Intel.

• 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_TYPE for Android is now RelWithDebInfo.

  • The CMAKE_ANDROID_NDK_VERSION variable 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() and add_custom_target() now support generator expressions in their OUTPUT and BYPRODUCTS options.

  Their COMMAND, WORKING_DIRECTORY, and DEPENDS options gained support for new generator expressions $<COMMAND_CONFIG:...> and $<OUTPUT_CONFIG:...> that control cross-config handling when using the Ninja Multi-Config generator.

• The add_custom_command() command gained DEPFILE support on Makefile Generators.

• The add_library() command previously prohibited imported object libraries when using potentially multi-architecture configurations. This mostly affected the Xcode generator, 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 gained USE_SOURCE_PERMISSIONS and FILE_PERMISSIONS options to support copying of permissions of the source file and using specified permissions respectively.

• The file(GENERATE) command gained a NEWLINE_STYLE option to specify how newlines are handled for the generated file.

• The file(GENERATE) command gained NO_SOURCE_PERMISSIONS, USE_SOURCE_PERMISSIONS, and FILE_PERMISSIONS options for controlling the permissions of the generated file.

• The install(FILES) command RENAME option learned to support generator expressions.

• The target_include_directories() command gained a new option AFTER.

• The target_sources() command now supports targets created by the add_custom_target() command.

• The try_run() command gained a WORKING_DIRECTORY option to set the working directory in which to run the compiled check executable.

Variables

• The CMAKE_<LANG>_BYTE_ORDER variable was added to provide the target architecture byte order detected from the toolchain.

• The CMAKE_RUNTIME_OUTPUT_DIRECTORY, CMAKE_LIBRARY_OUTPUT_DIRECTORY, and CMAKE_ARCHIVE_OUTPUT_DIRECTORY variables now support target-dependent generator expressions.

Properties

• The <LANG>_CLANG_TIDY target property and the associated CMAKE_<LANG>_CLANG_TIDY variable learned to support the OBJC and OBJCXX languages.

• The EXPORT_COMPILE_COMMANDS target property was added for the associated CMAKE_EXPORT_COMPILE_COMMANDS variable to allow for configuration of exporting compile commands per target.

• Generated sources may be used across directories without manual marking. Additionally, the GENERATED source file property can no longer be turned off once turned on, nor can it be set to other than boolean values. See policy CMP0118.

• The UNITY_BUILD_UNIQUE_ID target 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_EXECUTABLE target property now works with Clang on Windows.

• The XCODE_EMBED_FRAMEWORKS target property was added to tell the Xcode generator to embed frameworks. Aspects of the embedding can be customized with the XCODE_EMBED_FRAMEWORKS_PATH, XCODE_EMBED_FRAMEWORKS_CODE_SIGN_ON_COPY, and XCODE_EMBED_FRAMEWORKS_REMOVE_HEADERS_ON_COPY target properties.

Modules

• The ExternalData module ExternalData_Add_Target() function gained a SHOW_PROGRESS <bool> option for controlling whether or not to show progress output during the build.

• The ExternalProject module ExternalProject_Add() function gained a CONFIGURE_HANDLED_BY_BUILD option. 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 FindBoost module gained a Boost_NO_WARN_NEW_VERSIONS option to silence the warning about unknown dependencies for new Boost versions.

• The FindCUDAToolkit module gained support for finding CUDA toolkits when nvcc is a symbolic link, for example due to a ccache or colornvcc wrapper script.

• The FindGDAL module has been improved to document and mark as advanced its cache variables. There is a new FindGDAL_SKIP_GDAL_CONFIG variable which may be used to skip over the gdal-config-based search. Users may also set GDAL_ADDITIONAL_LIBRARY_VERSIONS to add additional versions to the library name search strategy.

• The FindIntl module now provides an imported target.

• The FindOpenSSL module learned to support a version range.

• The FindPython3, FindPython2 and FindPython modules gained options controlling how unversioned interpreter names are searched.

• The UseJava module add_jar() command's GENERATE_NATIVE_HEADERS feature gained options to export the generated target.

• The UseSWIG module gained the capability, for Makefile and Ninja generators, to use the swig tool to generate implicit dependencies.

Autogen

• The AUTOMOC feature now works with per-config sources.

CTest

• ctest(1) gained a --test-dir option to specify the directory in which to look for tests.

CPack

• CPack gained the CPACK_THREADS variable to control the number of threads used for parallelized operations, such as compressing the installer package.

• The CPack DEB Generator learned a new CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRS variable to specify additional search directories for resolving private library dependencies when using dpkg-shlibdeps.

• The CPack IFW Generator gained a new CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST variable 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 Generator gained new CPACK_NSIS_BRANDING_TEXT and CPACK_NSIS_BRANDING_TEXT_TRIM_POSITION variables to change the text at the bottom of the install window and change its trim position

• The CPack NSIS Generator now correctly handles Unicode characters. If you want to have a CPACK_RESOURCE_FILE_LICENSE with UTF-8 characters, it needs to be encoded in UTF-8 BOM.

• The CPack NuGet Generator gained options:

  • CPACK_NUGET_PACKAGE_ICON and CPACK_NUGET_<compName>_PACKAGE_ICON allow package icons to be specified by local files.

  • CPACK_NUGET_PACKAGE_LICENSE_EXPRESSION and CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSION add support for specifying licenses recognized by the Software Package Data Exchange (SPDX).

  • CPACK_NUGET_PACKAGE_LICENSE_FILE_NAME and CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAME allow licenses to be specified by local files.

  • CPACK_NUGET_PACKAGE_LANGUAGE and CPACK_NUGET_<compName>_PACKAGE_LANGUAGE allow the locale for a package to be specified, for example en_CA.

Deprecated and Removed Features

• The cmake-server(7) mode has been removed. Clients should use the cmake-file-api(7) instead.

• The WriteCompilerDetectionHeader module has been deprecated via policy CMP0120. Projects should be ported away from it.

• The TestBigEndian module has been deprecated in favor of the CMAKE_<LANG>_BYTE_ORDER variable.

• The AddFileDependencies module is deprecated. Port projects to use set_property() directly.

• The CPack NuGet Generator deprecated some variables to reflect changes in the NuGet specification:

  • CPACK_NUGET_PACKAGE_ICONURL and CPACK_NUGET_<compName>_PACKAGE_ICONURL have been deprecated; replace with a reference to a local icon file.

  • CPACK_NUGET_PACKAGE_LICENSEURL and CPACK_NUGET_<compName>_PACKAGE_LICENSEURL have 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 CMP0115 for details.

• The LANGUAGE source file property now forces compilation as the specified language. See policy CMP0119.

• 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_FLAGS no longer contains the /GR flag for runtime type information by default. See policy CMP0117.

• Ninja generators now transform the DEPFILE generated by an add_custom_command(). See policy CMP0116 for details.

• The precompiled Linux binaries provided on cmake.org have changed their naming pattern to cmake-$ver-linux-$arch, where $arch is either x86_64 or aarch64.

• The precompiled Windows binaries provided on cmake.org have changed their naming pattern to cmake-$ver-windows-$arch, where $arch is either x86_64 or i386.

Updates

Changes made since CMake 3.20.0 include the following.

3.20.1

• The FindIntl module in CMake 3.20.0 added checks Intl_HAVE_GETTEXT_BUILTIN, Intl_HAVE_DCGETTEXT_BUILTIN, and Intl_IS_BUILTIN, but they were not implemented correctly. These have been removed and replaced with a single Intl_IS_BUILT_IN check, whose name is consistent with the FindIconv module.

• The -rpath linker flag is now specified as supported on all Apple platforms, not just macOS. The install_name_dir used for iOS, tvOS and watchOS should now default to @rpath instead of using a full absolute path and failing at runtime when the library or framework is embedded in an application bundle (see XCODE_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 as Intel. CMake now has a special case to recognize oneAPI 2021.1 Fortran as IntelLLVM. The oneAPI 2021.2 Fortran compiler defines the proper identification macro and so is identified as IntelLLVM by 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.