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.

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.