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_STANDARDtarget properties, or via the- Compile Featuresfunctionality's- cxx_std_23meta-feature.
- CUDAlanguage support now works when- nvccis a symbolic link, for example due to a- ccacheor- colornvccwrapper script.
- The - CUDAARCHSenvironment 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/- icpxC/C++ compilers on Linux, and the- icxC/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, 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_TYPEfor Android is now- RelWithDebInfo.
- 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()and- add_custom_target()now support- generator expressionsin their- OUTPUTand- BYPRODUCTSoptions.- Their - COMMAND,- WORKING_DIRECTORY, and- DEPENDSoptions gained support for new generator expressions- $<COMMAND_CONFIG:...>and- $<OUTPUT_CONFIG:...>that control cross-config handling when using the- Ninja Multi-Configgenerator.
- The - add_custom_command()command gained- DEPFILEsupport on Makefile Generators.
- The - add_library()command previously prohibited imported object libraries when using potentially multi-architecture configurations. This mostly affected the- Xcodegenerator, 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_PERMISSIONSand- FILE_PERMISSIONSoptions to support copying of permissions of the source file and using specified permissions respectively.
- The - file(GENERATE)command gained a- NEWLINE_STYLEoption to specify how newlines are handled for the generated file.
- The - file(GENERATE)command gained- NO_SOURCE_PERMISSIONS,- USE_SOURCE_PERMISSIONS, and- FILE_PERMISSIONSoptions for controlling the permissions of the generated file.
- The - install(FILES)command- RENAMEoption 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_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, and- CMAKE_ARCHIVE_OUTPUT_DIRECTORYvariables now support target-dependent generator expressions.
Properties¶
- The - <LANG>_CLANG_TIDYtarget property and the associated- CMAKE_<LANG>_CLANG_TIDYvariable learned to support the- OBJCand- OBJCXXlanguages.
- The - EXPORT_COMPILE_COMMANDStarget property was added for the associated- CMAKE_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 policy- CMP0118.
- 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 the- Xcodegenerator 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_COPYtarget properties.
Modules¶
- The - ExternalDatamodule- ExternalData_Add_Target()function gained a- SHOW_PROGRESS <bool>option for controlling whether or not to show progress output during the build.
- The - ExternalProjectmodule- ExternalProject_Add()function gained a- CONFIGURE_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 a- Boost_NO_WARN_NEW_VERSIONSoption to silence the warning about unknown dependencies for new Boost versions.
- The - FindCUDAToolkitmodule gained support for finding CUDA toolkits when- nvccis a symbolic link, for example due to a- ccacheor- colornvccwrapper script.
- The - FindGDALmodule has been improved to document and mark as advanced its cache variables. There is a new- FindGDAL_SKIP_GDAL_CONFIGvariable which may be used to skip over the- gdal-config-based search. Users may also set- GDAL_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,- FindPython2and- FindPythonmodules gained options controlling how unversioned interpreter names are searched.
- The - UseJavamodule- add_jar()command's- GENERATE_NATIVE_HEADERSfeature gained options to export the generated target.
- The - UseSWIGmodule gained the capability, for Makefile and Ninja generators, to use the- swigtool 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 the- CPACK_THREADSvariable to control the number of threads used for parallelized operations, such as compressing the installer package.
- The - CPack DEB Generatorlearned a new- CPACK_DEBIAN_PACKAGE_SHLIBDEPS_PRIVATE_DIRSvariable to specify additional search directories for resolving private library dependencies when using- dpkg-shlibdeps.
- The - CPack IFW Generatorgained a new- CPACK_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 new- CPACK_NSIS_BRANDING_TEXTand- CPACK_NSIS_BRANDING_TEXT_TRIM_POSITIONvariables to change the text at the bottom of the install window and change its trim position
- The - CPack NSIS Generatornow correctly handles Unicode characters. If you want to have a- CPACK_RESOURCE_FILE_LICENSEwith UTF-8 characters, it needs to be encoded in UTF-8 BOM.
- The - CPack NuGet Generatorgained options:- CPACK_NUGET_PACKAGE_ICONand- CPACK_NUGET_<compName>_PACKAGE_ICONallow package icons to be specified by local files.
- CPACK_NUGET_PACKAGE_LICENSE_EXPRESSIONand- CPACK_NUGET_<compName>_PACKAGE_LICENSE_EXPRESSIONadd support for specifying licenses recognized by the Software Package Data Exchange (SPDX).
- CPACK_NUGET_PACKAGE_LICENSE_FILE_NAMEand- CPACK_NUGET_<compName>_PACKAGE_LICENSE_FILE_NAMEallow licenses to be specified by local files.
- CPACK_NUGET_PACKAGE_LANGUAGEand- CPACK_NUGET_<compName>_PACKAGE_LANGUAGEallow 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 - WriteCompilerDetectionHeadermodule has been deprecated via policy- CMP0120. Projects should be ported away from it.
- The - TestBigEndianmodule has been deprecated in favor of the- CMAKE_<LANG>_BYTE_ORDERvariable.
- The - AddFileDependenciesmodule is deprecated. Port projects to use- set_property()directly.
- The - CPack NuGet Generatordeprecated some variables to reflect changes in the NuGet specification:- CPACK_NUGET_PACKAGE_ICONURLand- CPACK_NUGET_<compName>_PACKAGE_ICONURLhave been deprecated; replace with a reference to a local icon file.
- CPACK_NUGET_PACKAGE_LICENSEURLand- CPACK_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 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_FLAGSno longer contains the- /GRflag for runtime type information by default. See policy- CMP0117.
- Ninja generators now transform the - DEPFILEgenerated by an- add_custom_command(). See policy- CMP0116for details.
- The precompiled Linux binaries provided on cmake.org have changed their naming pattern to - cmake-$ver-linux-$arch, where- $archis either- x86_64or- aarch64.
- The precompiled Windows binaries provided on cmake.org have changed their naming pattern to - cmake-$ver-windows-$arch, where- $archis either- x86_64or- i386.
Updates¶
Changes made since CMake 3.20.0 include the following.
3.20.1¶
- The - FindIntlmodule 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_INcheck, whose name is consistent with the- FindIconvmodule.
- The - -rpathlinker flag is now specified as supported on all Apple platforms, not just macOS. The- install_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 (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- IntelLLVMby 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.
