CMake 3.21 Release Notes — CMake 4.0.2 Documentation (original) (raw)

Contents

• CMake 3.21 Release Notes
  • New Features
    * Presets
    * Generators
    * Languages
    * Command-Line
    * Compilers
    * Platforms
    * File-Based API
    * Commands
    * Variables
    * Properties
    * Modules
    * Generator Expressions
    * CTest
    * CPack
  • Deprecated and Removed Features
  • Other Changes
  • Updates
    * 3.21.1
    * 3.21.2
    * 3.21.3
    * 3.21.4
    * 3.21.5, 3.21.6, 3.21.7

Changes made since CMake 3.20 include the following.

New Features¶

Presets¶

• cmake-presets(7) gained support for specifying the install prefix in a configure preset.
• cmake-presets(7) gained support for conditional enabling of presets.
• cmake-presets(7) gained support for a ${hostSystemName} macro.
• cmake-presets(7) gained support for omitting the generator andbinaryDir fields.

Generators¶

• The [Visual Studio 17 2022](../generator/Visual%20Studio%2017%202022.html#generator:Visual Studio 17 2022 "Visual Studio 17 2022") generator was added.
• The Makefile Generators and the Ninja generator learned to add linker launcher tools along with the linker for C,CXX, OBJC, and OBJCXX languages. See the CMAKE__LINKER_LAUNCHER variable and _LINKER_LAUNCHER target property for details.

Languages¶

• CMake learned to support HIP as a first-class language that can be enabled via the project() and enable_language() commands.
• C_STANDARD, OBJC_STANDARD, and theCompile Features functionality gained support for C17 and C23.
• Source file extensions .ixx and .cppm are now treated as C++.

Command-Line¶

• cmake(1) gained the --install-prefixcommand-line option to specify the location of the install prefix.
• cmake(1) gained the --toolchaincommand-line option to specify a toolchain file.
• cmake(1) -E capabilities output, for some generators, may now contain a supportedPlatforms field listing platforms known to be supported in CMAKE_GENERATOR_PLATFORM.
• Messages printed to a terminal now may be colored by message type.

Compilers¶

• The Fujitsu compiler is now supported using compiler id Fujitsuin traditional (Trad) mode, and compiler id FujitsuClangin Clang mode.

Platforms¶

• CMake now supports the MSYS runtime environment, much like CYGWIN.

File-Based API¶

• The cmake-file-api(7) "codemodel" version 2 version field has been updated to 2.3.
• The cmake-file-api(7) "codemodel" version 2 gained a new "directory" object containing directory-level information. This includes a list of installers generated by the install()command.

Commands¶

• The add_custom_command() command DEPFILE option:
  • may now usegenerator expressions,
  • is now supported by Visual Studio Generators for VS 2012 and above, and
  • is now supported by the Xcode generator.
• The add_custom_command(TARGET) command (for Build Events) gained support for resolving target-dependent generator expressions.
• The build_command() command gained a PARALLEL_LEVEL option.
• The file(COPY_FILE) command was added to copy a single file.
• The file(GET_RUNTIME_DEPENDENCIES) command gained newPOST_INCLUDE_FILES and POST_EXCLUDE_FILES arguments.
• The file(REAL_PATH) command gained the option EXPAND_TILDE to replace any leading tilde with the path to the user's home directory.
• The file(RENAME) command learned to optionally capture failure in a result variable. It also gained a NO_REPLACEoption to fail if the destination exists.
• The install() command gained a new IMPORTED_RUNTIME_ARTIFACTSmode, which can be used to install the runtime artifacts of imported targets.
• The install() command gained a new RUNTIME_DEPENDENCY_SET mode, which can be used to install runtime dependencies usingfile(GET_RUNTIME_DEPENDENCIES).
• The install(TARGETS) command gained new RUNTIME_DEPENDENCIESand RUNTIME_DEPENDENCY_SET arguments, which can be used to install runtime dependencies using file(GET_RUNTIME_DEPENDENCIES).
• The install(SCRIPT|CODE) command supports a new option ALL_COMPONENTS which allows the corresponding code to run for every component of a per component installation.
• The project() command now sets variablesPROJECT_IS_TOP_LEVEL and _IS_TOP_LEVELto indicate whether it was called in a top-level CMakeLists.txt file.

Variables¶

• The CMAKE_TOOLCHAIN_FILE environment variable was added to provide a default value for the CMAKE_TOOLCHAIN_FILE variable.

Properties¶

• The IMPORTED_TARGETS directory property was added to get a list of Imported Targets created in the current directory.
• The XCODE_EMBED_APP_EXTENSIONS target property was added to tell the Xcode generator to embed app extensions such as iMessage sticker packs. Aspects of the embedding can be customized with theXCODE_EMBED_APP_EXTENSIONS_PATH,XCODE_EMBED_APP_EXTENSIONS_CODE_SIGN_ON_COPY andXCODE_EMBED_APP_EXTENSIONS_REMOVE_HEADERS_ON_COPYproperties.

Modules¶

• The FindBLAS and FindLAPACK modules learned to support the serial Fujitsu_SSL2 and parallel Fujitsu_SSL2BLAMP libraries.
• The FindDevIL module now provides imported targets.
• The FindIconv module now has version support.
• The FindIntl module now has version support.
• The FindMPI module learned to support Fujitsu andFujitsuClang in both host and cross compiling modes.
• The FindMsys module was added to find MSYS installations. Like FindCygwin, it is used automatically by some other find modules to locate UNIX-style tools on Windows.
• The FindOpenMP module learned to support Fujitsu andFujitsuClang.
• The FindVulkan module gained imported targetsVulkan::Headers and Vulkan::glslangValidator.
• The UseJava module command add_jar gained a RESOURCESoption to allow explicit naming of resources with non-optional namespace.
• The UseSWIG module use now standard library naming conventions for the CSharp language. See policy CMP0122.
• The UseSWIG module now supports using the swig tool to generate implicit dependencies with the Xcode generator.

Generator Expressions¶

• A new TARGET_RUNTIME_DLLS generator expression was added.

CTest¶

• ctest(1) gained documentation for its ability to captureAdditional Test Measurements.
• ctest(1) learned to recognize files attached to a test at run time. Previously it was only possible to attach files to tests at configure time by using the ATTACHED_FILES orATTACHED_FILES_ON_FAIL test properties. See Additional Test Measurements for more information.
• ctest(1) gained a --output-junitoption to write test results to a JUnit XML file.
• The ctest_build() command gained a PARALLEL_LEVEL option.

CPack¶

• The [CPack DragNDrop Generator](../cpack%5Fgen/dmg.html#cpack%5Fgen:CPack DragNDrop Generator "CPack DragNDrop Generator") gained optionCPACK_DMG_FILESYSTEM to control the .dmg filesystem.
• The [CPack IFW Generator](../cpack%5Fgen/ifw.html#cpack%5Fgen:CPack IFW Generator "CPack IFW Generator") now supports hyphens in names given to cpack_ifw_configure_component() orcpack_ifw_configure_component_group() as DEPENDS orDEPENDENCIES arguments. This requires QtIFW 3.1 or later.
• The [CPack NSIS Generator](../cpack%5Fgen/nsis.html#cpack%5Fgen:CPack NSIS Generator "CPack NSIS Generator") gained a newCPACK_NSIS_EXECUTABLE variable to specify the makensisexecutable to use instead of the default one.
• The CPACK_CUSTOM_INSTALL_VARIABLES variable was added to set variables in cmake_install.cmake script invocations made by CPack.

Deprecated and Removed Features¶

• Undocumented CMAKE_SYSTEM_NAME version-stripping behavior has been removed entirely. If it is set by a -D flag or by atoolchain file, it is left unaltered, even if it still contains a version number. Similar CMAKE_HOST_SYSTEM_NAME version-stripping behavior, also undocumented, has been moved earlier, before project() orenable_language() is called.
• ARMClang cpu/arch compile and link flags are no longer added automatically based on the CMAKE_SYSTEM_PROCESSORvariable or the undocumented CMAKE_SYSTEM_ARCH variable. They must be specified explicitly. See policy CMP0123.

Other Changes¶

• The find_file(), find_path(), find_program(), and find_library() commands handle cache variables in the same way regardless how they are defined. See policy CMP0125 for details.
• The find_file(), find_path(), find_program(), and find_library() commands gained the option NO_CACHE to store find result in normal variable.
• The foreach() command now isolates loop variables in the loop scope. See policy CMP0124 for details.
• The list() command's GET, INSERT, SUBLIST, andREMOVE_AT subcommands now error with invalid (i.e., non-integer) values are given as any of their index arguments based on the setting of policyCMP0121.
• The set(CACHE) command no longer removes a normal variable of the same name, if any. See policy CMP0126.
• target_link_libraries() calls referencing object libraries via the TARGET_OBJECTS generator expression now place the object files before all libraries on the link line, regardless of their specified order. See documentation onLinking Object Libraries via $<TARGET_OBJECTS> for details.
• The Ninja Generators now pass source files and include directories to the compiler using absolute paths. This makes diagnostic messages and debug symbols more consistent, and matches the Makefile Generators.
• The [NMake Makefiles](../generator/NMake%20Makefiles.html#generator:NMake Makefiles "NMake Makefiles") generator now encodes the generated makefiles as UTF-8 with a BOM when using nmake from VS 9 or above.
• The Visual Studio Generators for VS 2010 and above now place per-source preprocessor definitions after target-wide preprocssor definitions. This makes VS consistent with the Ninja Generatorsand the Makefile Generators.
• The precompiled binaries provided oncmake.org now supportliblzma multi-threading. See the CPACK_THREADS andCPACK_ARCHIVE_THREADS variables.

Updates¶

Changes made since CMake 3.21.0 include the following.

3.21.1¶

• The [Visual Studio 17 2022](../generator/Visual%20Studio%2017%202022.html#generator:Visual Studio 17 2022 "Visual Studio 17 2022") generator is now based on "Visual Studio 2022 Preview 2". Previously it was based on "Preview 1.1".

3.21.2¶

• CUDA targets with CUDA_SEPARABLE_COMPILATION enabled are now correctly generated in non-root directories.
• The [Visual Studio 17 2022](../generator/Visual%20Studio%2017%202022.html#generator:Visual Studio 17 2022 "Visual Studio 17 2022") generator is now based on "Visual Studio 2022 Preview 3.1". Previously it was based on "Preview 2".

3.21.3¶

• The [Visual Studio 17 2022](../generator/Visual%20Studio%2017%202022.html#generator:Visual Studio 17 2022 "Visual Studio 17 2022") generator is now based on "Visual Studio 2022 Preview 4". Previously it was based on "Preview 3.1".
• The AMD ROCm Platform hipcc compiler was identified by CMake 3.21.0 through 3.21.2 as a distinct compiler with id ROCMClang. This has been removed because it caused regressions. Instead:
  • hipcc may no longer be used as a HIP compiler because it interferes with flags CMake needs to pass to Clang. Use Clang directly.
  • hipcc may once again be used as a CXX compiler, and is treated as whatever compiler it selects underneath, as CMake 3.20 and below did.

3.21.4¶

• The [Visual Studio 17 2022](../generator/Visual%20Studio%2017%202022.html#generator:Visual Studio 17 2022 "Visual Studio 17 2022") generator is now based on the "Visual Studio 2022" release candidates. Previously it was based on preview versions.

3.21.5, 3.21.6, 3.21.7¶

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