Help/release/4.2.rst - third_party/github.com/Kitware/CMake - Git at Google


            
            CMake 4.2 Release Notes

            
            ***********************


            .. only:: html


              .. contents::


            Changes made since CMake 4.1 include the following.


            New Features

            
            ============


            File-Based API

            
            --------------


            * The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has

            
              been updated to 2.9.


            * The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" and

            
              "directory" objects gained a new ``codemodelVersion`` field.


            * The :manual:`cmake-file-api(7)` "codemodel" version 2 now includes imported

            
              targets and all interface library targets in its replies.  Previously,

            
              imported targets were omitted, and only those interface targets that

            
              participated in the build system were included.  The following changes

            
              support these new additions:


              * The "target" object gained ``imported``, ``local``, and ``abstract`` fields.

            
              * The "target" object's ``type`` field can now also hold the value

            
                ``UNKNOWN_LIBRARY``.

            
              * The "codemodel" object's ``configurations`` entries gained a new

            
                ``abstractTargets`` array.

            
              * Entries in the ``directories`` and ``projects`` arrays of the "codemodel"

            
                object's ``configurations`` entries gained a new ``abstractTargetIndexes``

            
                array.


            * The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained

            
              new ``linkLibraries``, ``interfaceLinkLibraries``, ``compileDependencies``,

            
              ``interfaceCompileDependencies``, ``objectDependencies``, and

            
              ``orderDependencies`` fields.


            Generators

            
            ----------


            * The :generator:`Visual Studio 18 2026` generator was added.


            * The :generator:`FASTBuild` generator was added.


            Platforms

            
            ---------


            * CMake now supports :ref:`Cross Compiling for Emscripten` with simple

            
              toolchain files.


            Command-Line

            
            ------------


            * The :manual:`cmake(1)` command-line tool now supports

            
              ``cmake -E copy_if_newer`` and ``cmake -E copy_directory_if_newer``

            
              subcommands to copy files based on timestamp comparison instead of

            
              content comparison. These commands copy files only if the source is

            
              newer than the destination, providing better performance for build

            
              systems compared to ``copy_if_different`` which compares file contents.


            Commands

            
            --------


            * The :command:`cmake_language(TRACE)` command was added to enable or

            
              disable tracing during script execution.


            * The :command:`set(CACHE{<variable>}) <set(CACHE)>` and

            
              :command:`unset(CACHE{<variable>}) <unset(CACHE)>` commands were added to

            
              explicitly set and unset cache entries.


            * The :command:`string(REGEX QUOTE)` command was added to

            
              generate a regular expression exactly matching a string.


            Variables

            
            ---------


            * The :variable:`CMAKE_INTERMEDIATE_DIR_STRATEGY` variable and corresponding

            
              :envvar:`CMAKE_INTERMEDIATE_DIR_STRATEGY` environment variable were added

            
              to change the strategy used to name intermediate directories used for

            
              object files and other associated target metadata.


            * The :variable:`CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY` variable and

            
              corresponding :envvar:`CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY` environment

            
              variable were added to change the strategy used to name intermediate

            
              directories used for :manual:`Qt Autogen <cmake-qt(7)>` files.


            * The :variable:`CMAKE_SKIP_LINTING` variable and corresponding

            
              :prop_tgt:`SKIP_LINTING` target property were added to tell the

            
              :ref:`Command-Line Build Tool Generators` to skip linting all

            
              sources in a target.


            Properties

            
            ----------


            * The :prop_sf:`INSTALL_OBJECT_NAME` source file property was added to

            
              control names of installed object files for specific compiled sources.


            * The :prop_tgt:`INSTALL_OBJECT_NAME_STRATEGY` target property was added

            
              to control the naming strategy for installed object files.


            * The :prop_tgt:`INSTALL_OBJECT_ONLY_USE_DESTINATION` target property was

            
              added to more precisely control the installation path for object files.


            * The :prop_sf:`JOB_POOL_COMPILE` source file property was added

            
              to assign individual source compilations to :prop_gbl:`JOB_POOLS`.


            * The :prop_sf:`OBJECT_NAME` source file property was added to control

            
              object names of compiled source files.


            * The :prop_tgt:`UNITY_BUILD_FILENAME_PREFIX` target property was added

            
              to control names of source files generated by :prop_tgt:`UNITY_BUILD`.


            Modules

            
            -------


            * Nearly all find modules now provide a ``<PackageName>_VERSION`` result

            
              variable matching the casing of its module name.  Existing variants such as

            
              ``<PackageName>_VERSION_STRING`` and uppercased ``<PACKAGENAME>_VERSION``

            
              are deprecated.  See documentation of each find module for details.


            * The :module:`CheckTypeSize` module's :command:`check_type_size` command

            
              gained a new ``RESULT_VARIABLE`` keyword to customize the result variable

            
              name instead of the default ``HAVE_<size-var>``.


            * The :module:`ExternalProject` module's :command:`ExternalProject_Add`

            
              and :command:`ExternalProject_Add_Step` commands now provide options to set

            
              environment variables on the configure, build, install, and test steps.


            * The :module:`FindPython3`, :module:`FindPython2`, and :module:`FindPython`

            
              modules no longer make ``NumPy`` depend on ``Development.Module``.

            
              See policy :policy:`CMP0201`.


            * The :module:`GoogleTest` module's :command:`gtest_discover_tests()`

            
              command now sets the ``DEF_SOURCE_LINE`` test property for each

            
              discovered test if gtest supports the ``--gtest_output=json`` option.

            
              This test property is used by some IDEs to locate the source for each test.


            * The :module:`UseSWIG` module's :command:`swig_add_library` command gained a

            
              ``DEBUG_POSTFIX`` option to control the :prop_tgt:`DEBUG_POSTFIX` target

            
              property.


            Generator Expressions

            
            ---------------------


            * The :genex:`<LANG>_COMPILER_LINKER_ID <C_COMPILER_LINKER_ID>` and

            
              :genex:`<LANG>_COMPILER_LINKER_FRONTEND_VARIANT <C_COMPILER_LINKER_FRONTEND_VARIANT>`

            
              families of generator expressions were added to access the value of the

            
              associated :variable:`CMAKE_<LANG>_COMPILER_LINKER_ID` and

            
              :variable:`CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT` variables.


            * The :genex:`TARGET_FILE_BASE_NAME`, :genex:`TARGET_IMPORT_FILE_BASE_NAME`,

            
              :genex:`TARGET_LINKER_FILE_BASE_NAME`,

            
              :genex:`TARGET_LINKER_LIBRARY_FILE_BASE_NAME`,

            
              :genex:`TARGET_LINKER_IMPORT_FILE_BASE_NAME`, and

            
              :genex:`TARGET_PDB_FILE_BASE_NAME`

            
              generator expressions gained a ``POSTFIX`` option to control the inclusion

            
              of the :prop_tgt:`<CONFIG>_POSTFIX` target property as part of the base

            
              names of the corresponding files.


            * The :genex:`TARGET_INTERMEDIATE_DIR` generator expression was

            
              added to refer to a target's intermediate files directory in

            
              the build tree.


            CPack

            
            -----


            * The :cpack_gen:`CPack AppImage Generator` was added.


            * The :variable:`CPACK_PACKAGE_CHECKSUM` variable now supports multiple values.


            * The :cpack_gen:`CPack NSIS Generator` gained a

            
              :variable:`CPACK_NSIS_CRC_CHECK` variable for setting the ``CRCCheck``

            
              attribute.


            * The :cpack_gen:`CPack WIX Generator` gained a

            
              :variable:`CPACK_WIX_CAB_PER_COMPONENT` variable to enable one ``.cab``

            
              per component.


            Deprecated and Removed Features

            
            ===============================


            * All find modules now provide a ``<PackageName>_FOUND`` result variable

            
              matching the casing of its module name.  Existing variants, such as the

            
              uppercased ``<PACKAGENAME>_FOUND``, are deprecated where appropriate.

            
              See documentation of each find module for details.


            * The :module:`FindwxWidgets` module's result variable

            
              ``wxWidgets_USE_FILE`` is now deprecated in favor of including the

            
              :module:`UsewxWidgets` module directly.


            * The :generator:`Visual Studio 14 2015` generator is now deprecated

            
              and will be removed in a future version of CMake.


            Other Changes

            
            =============


            * The :genex:`$<CONFIG:cfgs>` generator expression, when appearing on an

            
              imported target, has been fixed to not match configurations that are not

            
              applicable.  See policy :policy:`CMP0199`.


            * Selection of configuration and location of imported targets is now more

            
              consistent.  See policy :policy:`CMP0200`.


            * The :variable:`CMAKE_PARENT_LIST_FILE` variable is no longer defined when

            
              processing a ``CMakeLists.txt`` file.  See policy :policy:`CMP0198`.


            * For builds targeting the MSVC ABI, all generators now add the ``_MBCS``

            
              preprocessor definition when compiling sources unless ``_UNICODE`` or

            
              ``_SBCS`` is found.  See policy :policy:`CMP0204`.


            * For builds targeting the MSVC ABI, all generators now add the ``_WINDLL``

            
              preprocessor definition when compiling sources in shared libraries.

            
              See policy :policy:`CMP0203`.


            * The :ref:`Visual Studio Generators` now suppress Visual Studio's default

            
              flags ``-fp:precise``, ``-Gd``, and ``-GS`` if they are not specified by

            
              the project or user.  This makes builds more consistent with other

            
              generators, and with what projects and users actually specify.


            Updates

            
            =======


            Changes made since CMake 4.2.0 include the following.


            4.2.1

            
            -----


            * This version made no changes to documented features or interfaces.

            
              Some implementation updates were made to support ecosystem changes

            
              and/or fix regressions.


            4.2.2

            
            -----


            * Policy :policy:`CMP0199`'s NEW behavior has been partially reverted.

            
              In 4.2.0 and 4.2.1, ``$<CONFIG:cfgs>`` only matched the configuration

            
              of the consumed target.  This broke existing use cases that rely on

            
              matching the configuration of the consuming target, and so has been

            
              partially reverted to match either as CMake 4.1 and below did.


            4.2.3, 4.2.4, 4.2.5, 4.2.6, 4.2.7, 4.2.8

            
            ----------------------------------------


            * These versions made no changes to documented features or interfaces.

            
              Some implementation updates were made to support ecosystem changes

            
              and/or fix regressions.
	CMake 4.2 Release Notes
	***********************

	.. only:: html

	.. contents::

	Changes made since CMake 4.1 include the following.

	New Features
	============

	File-Based API
	--------------

	* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
	been updated to 2.9.

	* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" and
	"directory" objects gained a new ``codemodelVersion`` field.

	* The :manual:`cmake-file-api(7)` "codemodel" version 2 now includes imported
	targets and all interface library targets in its replies. Previously,
	imported targets were omitted, and only those interface targets that
	participated in the build system were included. The following changes
	support these new additions:

	* The "target" object gained ``imported``, ``local``, and ``abstract`` fields.
	* The "target" object's ``type`` field can now also hold the value
	``UNKNOWN_LIBRARY``.
	* The "codemodel" object's ``configurations`` entries gained a new
	``abstractTargets`` array.
	* Entries in the ``directories`` and ``projects`` arrays of the "codemodel"
	object's ``configurations`` entries gained a new ``abstractTargetIndexes``
	array.

	* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained
	new ``linkLibraries``, ``interfaceLinkLibraries``, ``compileDependencies``,
	``interfaceCompileDependencies``, ``objectDependencies``, and
	``orderDependencies`` fields.

	Generators
	----------

	* The :generator:`Visual Studio 18 2026` generator was added.

	* The :generator:`FASTBuild` generator was added.

	Platforms
	---------

	* CMake now supports :ref:`Cross Compiling for Emscripten` with simple
	toolchain files.

	Command-Line
	------------

	* The :manual:`cmake(1)` command-line tool now supports
	``cmake -E copy_if_newer`` and ``cmake -E copy_directory_if_newer``
	subcommands to copy files based on timestamp comparison instead of
	content comparison. These commands copy files only if the source is
	newer than the destination, providing better performance for build
	systems compared to ``copy_if_different`` which compares file contents.

	Commands
	--------

	* The :command:`cmake_language(TRACE)` command was added to enable or
	disable tracing during script execution.

	* The :command:`set(CACHE{<variable>}) <set(CACHE)>` and
	:command:`unset(CACHE{<variable>}) <unset(CACHE)>` commands were added to
	explicitly set and unset cache entries.

	* The :command:`string(REGEX QUOTE)` command was added to
	generate a regular expression exactly matching a string.

	Variables
	---------

	* The :variable:`CMAKE_INTERMEDIATE_DIR_STRATEGY` variable and corresponding
	:envvar:`CMAKE_INTERMEDIATE_DIR_STRATEGY` environment variable were added
	to change the strategy used to name intermediate directories used for
	object files and other associated target metadata.

	* The :variable:`CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY` variable and
	corresponding :envvar:`CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY` environment
	variable were added to change the strategy used to name intermediate
	directories used for :manual:`Qt Autogen <cmake-qt(7)>` files.

	* The :variable:`CMAKE_SKIP_LINTING` variable and corresponding
	:prop_tgt:`SKIP_LINTING` target property were added to tell the
	:ref:`Command-Line Build Tool Generators` to skip linting all
	sources in a target.

	Properties
	----------

	* The :prop_sf:`INSTALL_OBJECT_NAME` source file property was added to
	control names of installed object files for specific compiled sources.

	* The :prop_tgt:`INSTALL_OBJECT_NAME_STRATEGY` target property was added
	to control the naming strategy for installed object files.

	* The :prop_tgt:`INSTALL_OBJECT_ONLY_USE_DESTINATION` target property was
	added to more precisely control the installation path for object files.

	* The :prop_sf:`JOB_POOL_COMPILE` source file property was added
	to assign individual source compilations to :prop_gbl:`JOB_POOLS`.

	* The :prop_sf:`OBJECT_NAME` source file property was added to control
	object names of compiled source files.

	* The :prop_tgt:`UNITY_BUILD_FILENAME_PREFIX` target property was added
	to control names of source files generated by :prop_tgt:`UNITY_BUILD`.

	Modules
	-------

	* Nearly all find modules now provide a ``<PackageName>_VERSION`` result
	variable matching the casing of its module name. Existing variants such as
	``<PackageName>_VERSION_STRING`` and uppercased ``<PACKAGENAME>_VERSION``
	are deprecated. See documentation of each find module for details.

	* The :module:`CheckTypeSize` module's :command:`check_type_size` command
	gained a new ``RESULT_VARIABLE`` keyword to customize the result variable
	name instead of the default ``HAVE_<size-var>``.

	* The :module:`ExternalProject` module's :command:`ExternalProject_Add`
	and :command:`ExternalProject_Add_Step` commands now provide options to set
	environment variables on the configure, build, install, and test steps.

	* The :module:`FindPython3`, :module:`FindPython2`, and :module:`FindPython`
	modules no longer make ``NumPy`` depend on ``Development.Module``.
	See policy :policy:`CMP0201`.

	* The :module:`GoogleTest` module's :command:`gtest_discover_tests()`
	command now sets the ``DEF_SOURCE_LINE`` test property for each
	discovered test if gtest supports the ``--gtest_output=json`` option.
	This test property is used by some IDEs to locate the source for each test.

	* The :module:`UseSWIG` module's :command:`swig_add_library` command gained a
	``DEBUG_POSTFIX`` option to control the :prop_tgt:`DEBUG_POSTFIX` target
	property.

	Generator Expressions
	---------------------

	* The :genex:`<LANG>_COMPILER_LINKER_ID <C_COMPILER_LINKER_ID>` and
	:genex:`<LANG>_COMPILER_LINKER_FRONTEND_VARIANT <C_COMPILER_LINKER_FRONTEND_VARIANT>`
	families of generator expressions were added to access the value of the
	associated :variable:`CMAKE_<LANG>_COMPILER_LINKER_ID` and
	:variable:`CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT` variables.

	* The :genex:`TARGET_FILE_BASE_NAME`, :genex:`TARGET_IMPORT_FILE_BASE_NAME`,
	:genex:`TARGET_LINKER_FILE_BASE_NAME`,
	:genex:`TARGET_LINKER_LIBRARY_FILE_BASE_NAME`,
	:genex:`TARGET_LINKER_IMPORT_FILE_BASE_NAME`, and
	:genex:`TARGET_PDB_FILE_BASE_NAME`
	generator expressions gained a ``POSTFIX`` option to control the inclusion
	of the :prop_tgt:`<CONFIG>_POSTFIX` target property as part of the base
	names of the corresponding files.

	* The :genex:`TARGET_INTERMEDIATE_DIR` generator expression was
	added to refer to a target's intermediate files directory in
	the build tree.

	CPack
	-----

	* The :cpack_gen:`CPack AppImage Generator` was added.

	* The :variable:`CPACK_PACKAGE_CHECKSUM` variable now supports multiple values.

	* The :cpack_gen:`CPack NSIS Generator` gained a
	:variable:`CPACK_NSIS_CRC_CHECK` variable for setting the ``CRCCheck``
	attribute.

	* The :cpack_gen:`CPack WIX Generator` gained a
	:variable:`CPACK_WIX_CAB_PER_COMPONENT` variable to enable one ``.cab``
	per component.

	Deprecated and Removed Features
	===============================

	* All find modules now provide a ``<PackageName>_FOUND`` result variable
	matching the casing of its module name. Existing variants, such as the
	uppercased ``<PACKAGENAME>_FOUND``, are deprecated where appropriate.
	See documentation of each find module for details.

	* The :module:`FindwxWidgets` module's result variable
	``wxWidgets_USE_FILE`` is now deprecated in favor of including the
	:module:`UsewxWidgets` module directly.

	* The :generator:`Visual Studio 14 2015` generator is now deprecated
	and will be removed in a future version of CMake.

	Other Changes
	=============

	* The :genex:`$<CONFIG:cfgs>` generator expression, when appearing on an
	imported target, has been fixed to not match configurations that are not
	applicable. See policy :policy:`CMP0199`.

	* Selection of configuration and location of imported targets is now more
	consistent. See policy :policy:`CMP0200`.

	* The :variable:`CMAKE_PARENT_LIST_FILE` variable is no longer defined when
	processing a ``CMakeLists.txt`` file. See policy :policy:`CMP0198`.

	* For builds targeting the MSVC ABI, all generators now add the ``_MBCS``
	preprocessor definition when compiling sources unless ``_UNICODE`` or
	``_SBCS`` is found. See policy :policy:`CMP0204`.

	* For builds targeting the MSVC ABI, all generators now add the ``_WINDLL``
	preprocessor definition when compiling sources in shared libraries.
	See policy :policy:`CMP0203`.

	* The :ref:`Visual Studio Generators` now suppress Visual Studio's default
	flags ``-fp:precise``, ``-Gd``, and ``-GS`` if they are not specified by
	the project or user. This makes builds more consistent with other
	generators, and with what projects and users actually specify.

	Updates
	=======

	Changes made since CMake 4.2.0 include the following.

	4.2.1
	-----

	* This version made no changes to documented features or interfaces.
	Some implementation updates were made to support ecosystem changes
	and/or fix regressions.

	4.2.2
	-----

	* Policy :policy:`CMP0199`'s NEW behavior has been partially reverted.
	In 4.2.0 and 4.2.1, ``$<CONFIG:cfgs>`` only matched the configuration
	of the consumed target. This broke existing use cases that rely on
	matching the configuration of the consuming target, and so has been
	partially reverted to match either as CMake 4.1 and below did.

	4.2.3, 4.2.4, 4.2.5, 4.2.6, 4.2.7, 4.2.8
	----------------------------------------

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