CMake 3.20 Release Notes — CMake 4.0.1 Documentation

# 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.