CMake 3.24 Release Notes ************************ .. only:: html .. contents:: Changes made since CMake 3.23 include the following. New Features ============ Presets ------- * :manual:`cmake-presets(7)` files now support schema version ``5``. * :manual:`cmake-presets(7)` files now support a ``${pathListSep}`` macro, which expands to ``:`` or ``;`` based on the platform. * :manual:`cmake-presets(7)` files gained support for specifying a ``testOutputTruncation`` field in test presets, which specifies the truncation mode once the maximum test output size has been reached. Generators ---------- * The :generator:`Green Hills MULTI` generator now generates build rules to re-run CMake if any CMake files are updated. * The :ref:`Visual Studio Generators` now support ``SYSTEM`` headers. Command-Line ------------ * :manual:`cmake(1)` gained the ``--fresh`` command-line option to remove any existing ``CMakeCache.txt`` when configuring a build tree, thus starting a new configuration as if the build tree were freshly created. * :manual:`cmake(1)` gained the ``--compile-no-warning-as-error`` command-line option which causes the effects of the :prop_tgt:`COMPILE_WARNING_AS_ERROR` target property and :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable to be ignored. * The :manual:`cmake(1)` ``--trace=json-v1`` trace format gained fields ``global_frame`` and ``line_end``. * The :manual:`cmake(1)` ``-E`` commands ``cat`` and ``env`` learned to respect a double dash (``--``) argument that acts as a delimiter indicating the end of options. Any following arguments are treated as operands/positional arguments, even if they begin with a dash ``-`` character. * The :manual:`cmake(1)` ``-E tar`` command gained the ``--touch`` option to keep the current local timestamp instead of extracting file timestamps from the archive. Compilers --------- * LLVM's `flang`_ Fortran compiler is now supported on some platforms, with compiler id ``LLVMFlang``. .. _`flang`: https://github.com/llvm/llvm-project/tree/main/flang * ADSP compiler support (SHARC and Blackfin) now covers both CCES and VDSP++ installations, with required configuration now done in the compiler module itself rather than the ``Generic-ADSP`` platform module. Platforms --------- * A dedicated ``ADSP`` platform has been added to replace the existing ``Generic-ADSP`` implementation. This features automatic detection of the latest CCES/VDSP++ install and compiler selection (``cc21k`` vs. ``ccblkfn``) based off of the :variable:`CMAKE_SYSTEM_PROCESSOR` variable. Commands -------- * The :command:`cmake_host_system_information` command, on Windows, gained a ``QUERY WINDOWS_REGISTRY`` mode. See its :ref:`Query Windows registry` section. * The :command:`cmake_language` command gained a new ``SET_DEPENDENCY_PROVIDER`` sub-command. When a dependency provider is set, calls to :command:`find_package` and :command:`FetchContent_MakeAvailable` can be redirected through a custom command, which can choose to fulfill the request directly, modify how the request is processed, or leave it to be fulfilled by the built-in implementation. See :ref:`dependency_providers`. * The :command:`file(DOWNLOAD)` command gained options ``RANGE_START`` and ``RANGE_END`` to specify a range of bytes to download. This can be useful for downloading parts of big binary files. * The :command:`find_file`, :command:`find_library`, :command:`find_path`, :command:`find_package`, and :command:`find_program` commands have gained the ``NO_CMAKE_INSTALL_PREFIX`` option to control searching :variable:`CMAKE_INSTALL_PREFIX`. * The :command:`find_file`, :command:`find_path`, :command:`find_library`, :command:`find_program`, and :command:`find_package` commands gained the capability to specify which Windows Registry views must be queried. * The :command:`find_package` command gained a ``GLOBAL`` option that allows for the promotion of imported targets to global scope for the duration of the :command:`find_package` call. * The :command:`if` command gained the capability to compare paths by using the ``PATH_EQUAL`` operator. See policy :policy:`CMP0139`. Variables --------- * The :variable:`CMAKE_COLOR_DIAGNOSTICS` variable was added to control color diagnostics generated by compilers. This variable also controls color build system messages with :ref:`Makefile Generators`, replacing :variable:`CMAKE_COLOR_MAKEFILE`. The :envvar:`CMAKE_COLOR_DIAGNOSTICS` environment was added to set a default value for :variable:`CMAKE_COLOR_DIAGNOSTICS`. * The :variable:`CMAKE_COMPILE_WARNING_AS_ERROR` variable and corresponding :prop_tgt:`COMPILE_WARNING_AS_ERROR` target property were added to enable compilation with a compiler-specific flag to treat warnings as errors, such as ``-Werror``. * The :variable:`CMAKE_CUDA_ARCHITECTURES` variable and associated :prop_tgt:`CUDA_ARCHITECTURES` target property now support the special ``native`` value to compile for the architectures(s) of the host's GPU(s). * The :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL` variable was added to toggle behavior of the :command:`find_package` command's new ``GLOBAL`` option. * The :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` variable was added to toggle behavior of the :command:`find_file`, :command:`find_library`, :command:`find_path`, :command:`find_package`, and :command:`find_program` commands' new ``NO_CMAKE_INSTALL_PREFIX`` option. * The :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable was added to allow injecting custom code at the site of the first :command:`project` call, after the host and target platform details have been determined. * The :variable:`CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES` variable was added to tell the :command:`try_compile` command not to pass any platform variables to the test project. * The :variable:`CMAKE_VERIFY_INTERFACE_HEADER_SETS` variable and corresponding :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS` target property were added to enable build rules that verify all headers in header sets can be used on their own. * The :variable:`CMAKE_WATCOM_RUNTIME_LIBRARY` variable and :prop_tgt:`WATCOM_RUNTIME_LIBRARY` target property were introduced to select the runtime library used by compilers targeting the Watcom ABI. See policy :policy:`CMP0136`. * The :variable:`CMAKE_XCODE_XCCONFIG` variable and corresponding :prop_tgt:`XCODE_XCCONFIG` target property were added to tell the :generator:`Xcode` generator to handle ``xcconfig`` files. Properties ---------- * The :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` and :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE` target properties were added to express usage requirements affecting a consumer's direct link dependencies. * The :prop_tgt:`INTERFACE_HEADER_SETS_TO_VERIFY` target property was added to specify which header sets should be verified by :prop_tgt:`VERIFY_INTERFACE_HEADER_SETS`. * The :prop_tgt:`LINK_LIBRARIES` target property now supports the :genex:`$` generator expression. See policy :policy:`CMP0131`. * The :prop_tgt:`VS_DOTNET_STARTUP_OBJECT` target property was added to tell :ref:`Visual Studio Generators` which startup class shall be used when the program or project is executed. This is necessary when more than one ``static void Main(string[])`` function signature is available in a managed .NET project. * The :prop_tgt:`VS_NO_COMPILE_BATCHING` target property was added to tell :ref:`Visual Studio Generators` whether to disable compiler parallelism and call the compiler with one source file at a time. Modules ------- * The :module:`ExternalProject` module :command:`ExternalProject_Add` command gained a new ``DOWNLOAD_EXTRACT_TIMESTAMP`` option for controlling whether the timestamps of extracted contents are set to match those in the archive when the ``URL`` download method is used. Policy :policy:`CMP0135` was added to enable the option by default. * The :module:`FetchContent` module and the :command:`find_package` command now support integration capabilities: * :command:`FetchContent_MakeAvailable` can now try to satisfy a dependency by calling :command:`find_package` first. A new :variable:`FETCHCONTENT_TRY_FIND_PACKAGE_MODE` variable controls whether this is done by default for all dependencies, is opt-in per dependency, or is disabled entirely. * :command:`find_package` can be re-routed to call :command:`FetchContent_MakeAvailable` instead. A new read-only :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` variable points to a directory where config package files can be located to facilitate these re-routed calls. * The :module:`FindJNI` module now provides imported targets. * The :module:`FindMatlab` module :command:`matlab_add_mex` function gained a ``NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES`` option to disable automatic linking of MATLAB libraries. * The :module:`FindPkgConfig` module learned to find static libraries in addition to the default search for shared libraries. :command:`pkg_check_modules` gained a ``STATIC_TARGET`` option to make the imported target reference static libraries. * The :module:`FindZLIB` gained a new ``ZLIB_USE_STATIC_LIBS`` variable to search only for static libraries. Generator Expressions --------------------- * The :genex:`LINK_LIBRARY` generator expression was added to manage how libraries are specified during the link step. The variables :variable:`CMAKE__LINK_LIBRARY_USING_` and :variable:`CMAKE_LINK_LIBRARY_USING_` are used to define features usable by the :genex:`LINK_LIBRARY` generator expression. Moreover, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` and :prop_tgt:`LINK_LIBRARY_OVERRIDE_` target properties are available to resolve incompatible features. The :genex:`LINK_LIBRARY` generator expression can link frameworks in various ways when targeting ``Apple`` platforms. The following features were added: * ``FRAMEWORK`` * ``NEEDED_FRAMEWORK`` * ``REEXPORT_FRAMEWORK`` * ``WEAK_FRAMEWORK`` The :genex:`LINK_LIBRARY` generator expression can link libraries in various ways when targeting ``Apple`` platforms. The following features were added: * ``NEEDED_LIBRARY`` * ``REEXPORT_LIBRARY`` * ``WEAK_LIBRARY`` The :genex:`LINK_LIBRARY` generator expression gained the feature ``WHOLE_ARCHIVE`` to force load of all members in a static library. This feature is supported on the following target platforms: * all ``Apple`` variants * ``Linux`` * all ``BSD`` variants * ``SunOS`` * ``Windows`` * ``CYGWIN`` * ``MSYS`` * The :genex:`LINK_GROUP` generator expression was added to manage the grouping of libraries during the link step. The variables :variable:`CMAKE__LINK_GROUP_USING_` and :variable:`CMAKE_LINK_GROUP_USING_` are used to define features usable by the :genex:`LINK_GROUP` generator expression. The :genex:`LINK_GROUP` generator expression can manage, on ``Linux`` and ``BSD`` systems, circular references among static libraries by using the ``RESCAN`` feature. * The :genex:`PATH` generator expression was added to manage paths. * The :genex:`PATH_EQUAL` generator expression was added to manage path comparisons. * The :genex:`TARGET_BUNDLE_DIR_NAME` generator expression was added to evaluate to the name of the bundle directory for a given bundle target. CTest ----- * :manual:`ctest(1)` gained a ``--test-output-truncation`` option (and corresponding :variable:`CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable) to specify the truncation mode once the maximum test output size has been reached. Possible values are ``tail`` (default), ``middle`` or ``head``. CPack ----- * The :cpack_gen:`CPack WIX Generator` gained a new variable, :variable:`CPACK_WIX_ARCHITECTURE`, to specify the installer architecture in order to support computers running Windows for ARM. * CPack now supports the :variable:`CPACK_THREADS` option for ``zstd`` compression when compiled with libarchive 3.6 or higher. It is supported by official CMake binaries available on ``cmake.org``. Deprecated and Removed Features =============================== * The :module:`CPack` module no longer enables the SLA by default in the :cpack_gen:`CPack DragNDrop Generator`. See policy :policy:`CMP0133` and the :variable:`CPACK_DMG_SLA_USE_RESOURCE_FILE_LICENSE` variable. * The deprecated :cpack_gen:`CPack PackageMaker Generator` has been removed. * The :module:`FindGLUT` module no longer provides the undocumented result variables ``GLUT_LIBRARY`` and ``GLUT_INCLUDE_PATH``. Other Changes ============= * With MSVC compilers, debug configurations now use ``-ZI`` by default instead of ``/Zi``. See policy :policy:`CMP0138`. * CMake no longer sets environment variables like :envvar:`CC`, :envvar:`CXX`, etc. when enabling the corresponding language during the first CMake run in a build directory. See policy :policy:`CMP0132`. * The :generator:`MSYS Makefiles` and :generator:`MinGW Makefiles` generators, when a compiler is not explicitly specified, now select the first compiler (of any name) found in directories listed by the ``PATH`` environment variable. * The :command:`try_compile` command :ref:`whole-project ` signature now propagates platform variables. See policy :policy:`CMP0137`. * The :command:`while` command now diagnoses errors during condition evaluation. See policy :policy:`CMP0130`. * The precompiled macOS binaries provided on `cmake.org `_ no longer attach a SLA to the ``.dmg`` packages. This was removed because macOS 12 deprecated the tools used to attach ``.dmg`` resources.