CMake 3.31 Release Notes — CMake 4.2.6 Documentation

# CMake 3.31 Release Notes

Changes made since CMake 3.30 include the following.

## New Features

### Presets

- `cmake-presets(7)` files may now include comments using the key `$comment` at any level within the JSON object to provide documentation.

- `cmake-presets(7)` files may now request graphviz output using the `graphviz` key in a configure preset.

### Generators

- The Ninja Generators and Makefile Generators now produce a `codegen` build target. See policy `CMP0171`. It drives a subset of the build graph sufficient to run custom commands created with `add_custom_command()`'s new `CODEGEN` option.

### Command-Line

- The `cmake --workflow` mode now accepts a preset name as the first argument, allowing the simpler command line `cmake --workflow <preset>`.

- The `cmake -LR[A][H]` option was added to list cache entries whose names match a regular expression.

### Compilers

- The LFortran compiler is now supported with `compiler id` `LFortran`.

### Commands

- The `add_custom_command()` command gained a `CODEGEN` option to mark a custom command's outputs as dependencies of a `codegen` target. See policy `CMP0171`.

- The `cmake_pkg_config()` command was added as an endpoint for using CMake's native pkg-config format parser. The only supported option in this release is `EXTRACT`, which provides low-level access to the values produced by parsing a pkg-config file. For most users, this is not yet a suitable replacement for the `FindPkgConfig` module.

- The `file(ARCHIVE_CREATE)` command gained a `WORKING_DIRECTORY` option to specify a working directory for the archiving process.

- The `file(MAKE_DIRECTORY)` command gained a `RESULT` option to capture failure in a result variable.

- The `install(FILES)` and `install(DIRECTORY)` commands' `TYPE` argument gained support for a `LIBEXEC` type.

### Variables

- The `CMAKE_AIX_SHARED_LIBRARY_ARCHIVE` variable and corresponding `AIX_SHARED_LIBRARY_ARCHIVE` target property were added to create shared libraries on AIX as shared library archives.

- The `CMAKE_EXPORT_BUILD_DATABASE` variable, a corresponding `CMAKE_EXPORT_BUILD_DATABASE` environment variable, and an `EXPORT_BUILD_DATABASE` target property, were added to enable exporting C++ module compile commands. This is only supported with Ninja Generators.

- The `CMAKE_HOST_EXECUTABLE_SUFFIX` variable was added to provide the suffix for executable names on the host platform.

- The `CMAKE_<LANG>_HOST_COMPILER_ID` and `CMAKE_<LANG>_HOST_COMPILER_VERSION` variables were added, where `<LANG>` is either `CUDA` or `HIP`. They are populated when `CMAKE_<LANG>_COMPILER_ID` is `NVIDIA` to identify NVCC's host compiler.

- The `CMAKE_<LANG>_STANDARD_LINK_DIRECTORIES` variable was added. Toolchain files can set this variable to control which link library directory paths are always passed to the compiler for the specified language.

- The `CMAKE_LINK_LIBRARIES_STRATEGY` variable and corresponding `LINK_LIBRARIES_STRATEGY` target property were added to optionally specify the strategy CMake uses to generate link lines.

- The `CMAKE_CONFIG_DIR` environment variable was added to specify a CMake user-wide configuration directory for `cmake-file-api(7)` queries.

### Properties

- The `MACOSX_FRAMEWORK_BUNDLE_NAME` target property was added to set the `CFBundleName` key in an Apple `FRAMEWORK`'s `Info.plist` file.

- The `UNITY_BUILD` target property now supports the `CUDA` language.

- The `VS_FRAMEWORK_REFERENCES` target property was added to tell Visual Studio Generators to add framework references.

### Modules

- Check modules now support a `CMAKE_REQUIRED_LINK_DIRECTORIES` variable. The following modules gained this support:

  - `CMakePushCheckState`

  - `CheckCCompilerFlag`

  - `CheckCSourceCompiles`

  - `CheckCSourceRuns`

  - `CheckCXXCompilerFlag`

  - `CheckCXXSourceCompiles`

  - `CheckCXXSourceRuns`

  - `CheckCXXSymbolExists`

  - `CheckCompilerFlag`

  - `CheckFortranCompilerFlag`

  - `CheckFortranFunctionExists`

  - `CheckFortranSourceCompiles`

  - `CheckFortranSourceRuns`

  - `CheckFunctionExists`

  - `CheckIncludeFile`

  - `CheckIncludeFileCXX`

  - `CheckIncludeFiles`

  - `CheckOBJCCompilerFlag`

  - `CheckLibraryExists`

  - `CheckOBJCCompilerFlag`

  - `CheckOBJCSourceCompiles`

  - `CheckOBJCSourceRuns`

  - `CheckOBJCXXCompilerFlag`

  - `CheckOBJCXXSourceCompiles`

  - `CheckOBJCXXSourceRuns`

  - `CheckPrototypeDefinition`

  - `CheckSourceCompiles`

  - `CheckSourceRuns`

  - `CheckStructHasMember`

  - `CheckSymbolExists`

  - `CheckTypeSize`

  - `CheckVariableExists`

- The `CMakePackageConfigHelpers` module's `generate_apple_platform_selection_file()` function gained support for iOS Mac Catalyst.

- The `GoogleTest` module `gtest_discover_tests()` command gained a new `DISCOVERY_EXTRA_ARGS` keyword. It allows extra arguments to be appended to the command line when querying for the list of tests.

- The `FindCUDAToolkit` module now provides a `CUDA::nvml_static` target.

- The `FindOpenMP` module gained support for the `CUDA` language.

### CTest

- The `ctest_submit()` command and `ctest -T Submit` step now verify TLS server certificates for connections to `https://` URLs by default. See the `CTEST_TLS_VERIFY` variable for details.

- The `ctest_submit()` command and `ctest -T Submit` step now require TLS 1.2 or higher for connections to `https://` URLs by default. See the `CTEST_TLS_VERSION` variable for details.

### CPack

- The `CPack DEB Generator` gained a `CPACK_DEBIAN_PACKAGE_MULTIARCH` option to support multi-arch packages.

- The `CPack IFW Generator` gained the new `CPACK_IFW_PACKAGE_PRODUCT_IMAGE_URLS` variable to specify images associated with entries of `CPACK_IFW_PACKAGE_PRODUCT_IMAGES`. This feature is available for QtIFW 4.0 and newer.

- The `CPack RPM Generator` gained support for `zstd` as a `CPACK_RPM_COMPRESSION_TYPE` value.

- The `CPack` module enables per-machine installation by default in the `CPack WIX Generator`. See policy `CMP0172` and the `CPACK_WIX_INSTALL_SCOPE` variable.

## Deprecated and Removed Features

- Compatibility with versions of CMake older than 3.10 is now deprecated and will be removed from a future version. Calls to `cmake_minimum_required()` or `cmake_policy()` that set the policy version to an older value now issue a deprecation diagnostic.

- The `CMakeFindFrameworks` module has been deprecated via `CMP0173`. Projects should use `find_library()` instead.

- The `Visual Studio 12 2013` generator has been removed.

## Other Changes

- When static libraries on link lines are de-duplicated (by policy `CMP0156`), the first occurrence is now kept on all platforms. See policy `CMP0179`.

- Empty list elements in the `TEST_LAUNCHER` and `CROSSCOMPILING_EMULATOR` target properties are now preserved by:

  - The `add_test()` command.

  - The `ExternalData_Add_Test()` command from the `ExternalData` module.

  - The `gtest_add_tests()` and `gtest_discover_tests()` commands from the `GoogleTest` module. Empty list elements after the `EXTRA_ARGS` keyword of these two commands are also now preserved.

  See policy `CMP0178`.

- The `execute_process()` command's `ENCODING` option, meaningful on Windows, now defaults to `UTF-8`. See policy `CMP0176`.

- The `file(DOWNLOAD)` and `file(UPLOAD)` commands now verify TLS server certificates for connections to `https://` URLs by default. See the `CMAKE_TLS_VERIFY` variable for details. This change was made without a policy so that users are protected even when building projects that have not been updated. Users may set the `CMAKE_TLS_VERIFY` environment variable to `0` to restore the old default.

- The `file(DOWNLOAD)` and `file(UPLOAD)` commands now require TLS 1.2 or higher for connections to `https://` URLs by default. See the `CMAKE_TLS_VERSION` variable for details.

- The `file(GET_RUNTIME_DEPENDENCIES)` command was updated to more closely match the dynamic loader's behavior on Linux.

- The `install()` command's `DESTINATION` arguments are now normalized, with the exception of `INCLUDES DESTINATION` arguments in `install(TARGETS)`. See policy `CMP0177`.

- The `project()` command now always sets `<PROJECT-NAME>_SOURCE_DIR`, `<PROJECT-NAME>_BINARY_DIR`, and `<PROJECT-NAME>_IS_TOP_LEVEL` as both normal variables and cache entries. See policy `CMP0180`.

- The `cmake_parse_arguments(PARSE_ARGV)` command now defines a variable for an empty string after a single-value keyword. See policy `CMP0174`.

## Updates

Changes made since CMake 3.31.0 include the following.

### 3.31.1, 3.31.2, 3.31.3, 3.31.4, 3.31.5, 3.31.6, 3.31.7, 3.31.8, 3.31.9

- These versions made no changes to documented features or interfaces. Some implementation updates were made to support ecosystem changes and/or fix regressions.

### 3.31.10

- The `execute_process()` command once again terminates child processes when its `TIMEOUT` is reached. This was accidentally regressed by CMake 3.29.

### 3.31.11, 3.31.12

- These versions made no changes to documented features or interfaces. Some implementation updates were made to support ecosystem changes and/or fix regressions.