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

 CMake 4.0 Release Notes
 ***********************

 .. only:: html

   .. contents::

 Changes made since CMake 3.31 include the following.

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

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

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

 * The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object
   gained a new ``debugger`` field.

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

 * The :option:`cmake --link-no-warning-as-error` option was added to suppress
   the effects of the :prop_tgt:`LINK_WARNING_AS_ERROR` target property and
   :variable:`CMAKE_LINK_WARNING_AS_ERROR` variable.

 * The :option:`cmake --project-file` option was added to specify an alternate
   filename for ``CMakeLists.txt`` files.  This is intended for temporary use
   by developers during an incremental transition and not for publication of a
   final product.  CMake will always emit a warning when the project file is
   anything other than ``CMakeLists.txt``.

 Commands
 --------

 * The :command:`target_link_libraries` command now supports the ``LINKER:``
   prefix.

 Variables
 ---------

 * The :variable:`AIX` and :variable:`CMAKE_HOST_AIX` variables are
   now set to true when the target or host system is AIX, respectively.

 * Linker flag variables learned to support the ``LINKER:`` prefix:

   * :variable:`CMAKE_EXE_LINKER_FLAGS`
   * :variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>`
   * :variable:`CMAKE_SHARED_LINKER_FLAGS`
   * :variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>`
   * :variable:`CMAKE_MODULE_LINKER_FLAGS`
   * :variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>`

   See policy :policy:`CMP0181`.

 * The :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ERROR_IS_FATAL` variable
   was added to specify the :command:`execute_process` command's
   default ``COMMAND_ERROR_IS_FATAL`` behavior.

 * The :variable:`CMAKE_<LANG>_LINK_MODE` and
   :variable:`CMAKE_<LANG>_DEVICE_LINK_MODE` variables were added to provide
   information on how the link step is done.

 * The :variable:`CMAKE_LINK_WARNING_AS_ERROR` variable and corresponding
   :prop_tgt:`LINK_WARNING_AS_ERROR` target property were added to link
   using a linker-specific flag to treat warnings as errors.

 * The :variable:`CMAKE_MSVC_RUNTIME_CHECKS` variable and
   :prop_tgt:`MSVC_RUNTIME_CHECKS` target property were introduced
   to select runtime checks for compilers targeting the MSVC ABI.
   See policy :policy:`CMP0184`.

 * The :variable:`CMAKE_POLICY_VERSION_MINIMUM` variable was added to
   help pacakgers and end users try to configure existing projects that
   have not been updated to work with supported CMake versions.

 * The :variable:`CMAKE_XCODE_SCHEME_LLDB_INIT_FILE` variable and corresponding
   :prop_tgt:`XCODE_SCHEME_LLDB_INIT_FILE` target property were added to tell
   the :generator:`Xcode` generator what to put in the scheme's "LLDB Init File"
   setting.

 * The :variable:`CMAKE_XCODE_SCHEME_TEST_CONFIGURATION` variable and corresponding
   :prop_tgt:`XCODE_SCHEME_TEST_CONFIGURATION` target property were added to tell
   the :generator:`Xcode` generator what to put in the scheme's "Build Configuration"
   setting for the test action.

 Properties
 ----------

 * The :prop_tgt:`DEBUGGER_WORKING_DIRECTORY` target property and corresponding
   :variable:`CMAKE_DEBUGGER_WORKING_DIRECTORY` variable were added to tell
   generators what debugger working directory should be set for targets.

 * The :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property now supports an
   ``ARCHIVER:`` prefix to pass options to the archiver through the compiler
   driver in a portable way.

 * The :prop_tgt:`Swift_MODULE_DIRECTORY` target property now supports
   :manual:`generator expressions <cmake-generator-expressions(7)>`.

 * The :prop_sf:`VS_CUSTOM_COMMAND_DISABLE_PARALLEL_BUILD` source file property
   was added to tell :ref:`Visual Studio Generators` not to run a custom command
   in parallel.

 * The :prop_dir:`VS_SOLUTION_ITEMS` directory property was added
   to tell :ref:`Visual Studio Generators` to attach files directly
   to the Solution (``.sln``).

 Modules
 -------

 * The :module:`ExternalData` module gained a
   :variable:`ExternalData_HTTPHEADERS` variable to specify HTTP headers.

 * The :module:`ExternalProject` module's :command:`ExternalProject_Add`
   command gained an ``INSTALL_JOB_SERVER_AWARE`` option to enable
   integration of the GNU Make job server when using an explicit
   ``INSTALL_COMMAND`` with :ref:`Makefile Generators`.

 * The :module:`FeatureSummary` module :command:`add_feature_info`
   command now supports full :ref:`Condition Syntax`.
   See policy :policy:`CMP0183`.

 * The :module:`FindBISON` module :command:`bison_target` command gained an
   ``OPTIONS`` option to specify Bison command-line options.

 * The :module:`FindCURL` module now provides a ``CURL_VERSION`` result
   variable to match upstream cURL's CMake package.

 * The :module:`FindFLEX` module :command:`flex_target` command gained an
   ``OPTIONS`` option to specify Flex command-line options.

 * The :module:`FindPatch` module now supports running in
   :ref:`cmake -P <Script Processing Mode>` script mode by skipping
   the creation of the imported target.

 * The :module:`FindProtobuf` module :command:`protobuf_generate` command
   gained a ``PROTOC_EXE`` option to specify a custom ``protoc`` executable.

 * The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3`
   modules gained the possibility to do multiple calls in the same directory by
   using, respectively, the variables ``Python_ARTIFACTS_PREFIX``,
   ``Python2_ARTIFACTS_PREFIX``, and ``Python3_ARTIFACTS_PREFIX``.

 * The :module:`FindRuby` module learned to find rbenv-provided installations.

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

 * The :genex:`$<PATH>` generator expression gained the ``NATIVE_PATH``
   operation to convert a CMake path into a native one.

 CTest
 -----

 * The :option:`ctest --interactive-debug-mode` option on Windows
   now enables Windows Error Reporting by default in test processes,
   allowing them to creating debug popup windows and core dumps.
   This restores behavior previously removed by CMake 3.11 after
   updates to ``libuv`` made it possible.

 CPack
 -----

 * The :cpack_gen:`CPack Archive Generator` learned to generated ``.tar``
   packages without compression.

 * The :cpack_gen:`CPack Archive Generator` now honors the
   :variable:`CPACK_ARCHIVE_FILE_NAME` variable for all packages.
   Previously, this variable worked only for component-based packages.

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

 * Compatibility with versions of CMake older than 3.5 has been removed.
   Calls to :command:`cmake_minimum_required` or :command:`cmake_policy`
   that set the policy version to an older value now issue an error.
   Note that calls to those commands can still support older versions of
   CMake by using their ``VERSION`` arguments' ``<min>...<max>`` syntax.
   This requires only the ``<min>`` version of CMake, but when running a
   newer version, sets policies up to the ``<max>`` version.

 * The :generator:`Visual Studio 14 2015` and :generator:`Visual Studio 15 2017`
   generators no longer support specifying a platform as part of the generator
   name.  See :ref:`Visual Studio Platform Selection`.

 * The :variable:`CMAKE_<LANG>_USING_LINKER_MODE` variable is no longer used to
   determine the type of the contents of the
   :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` variable. The
   :variable:`CMAKE_<LANG>_LINK_MODE` variable, set by CMake, is used instead.

 * The :module:`FindGDAL` module is now deprecated in favor of upstream
   GDAL's official CMake package configuration file. Port projects to
   the latter by calling ``find_package(GDAL CONFIG)``.  For further
   details, see `GDAL's documentation on CMake integration
   <https://gdal.org/en/latest/development/cmake.html>`_.

 * The :module:`FindRuby` module no longer provides variables with the
   upper-case ``RUBY_`` prefix.  See policy :policy:`CMP0185`.

 * CTest's undocumented declarative scripting mode has been removed.
   This mode used to be triggered by a :option:`ctest -S` script which did not
   call any :ref:`CTest Commands` unless :variable:`CTEST_RUN_CURRENT_SCRIPT`
   was explicitly set to ``OFF``.

 * The :command:`ctest_run_script` command may no longer be called without any
   arguments.

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

 * On macOS with :ref:`Ninja Generators` and :ref:`Makefile Generators`, when
   a compiler is found in ``/usr/bin``, it is now used as-is and is no longer
   mapped to the corresponding compiler inside Xcode.  The mapping was
   introduced by CMake 3.2 to allow build trees to continue to work with their
   original compiler even when ``xcode-select`` switches to a different
   Xcode installation.  However, the compilers inside Xcode cannot be used
   without explicit ``-isysroot`` flags and are therefore not suitable for
   passing to arbitrary third-party build systems.  Furthermore, the mapping
   behavior can override user-specified compiler paths.  Therefore, this
   behavior has been reverted.

 * Builds targeting macOS no longer choose any SDK or pass an ``-isysroot``
   flag to the compiler by default.  Instead, compilers are expected to
   choose a default macOS SDK on their own.  In order to use a compiler that
   does not do this, users must now specify ``-DCMAKE_OSX_SYSROOT=macosx``
   when configuring their build.

 * On AIX, ``SHARED`` library targets now produce a shared library archive
   by default.  See policy :policy:`CMP0182`.

 * The :option:`cmake --preset` command no longer outputs a summary of the
   preset's CMake cache and environment variables by default.  That summary is
   now only shown when the message log level is set to ``VERBOSE``, ``DEBUG``,
   or ``TRACE`` via the   :option:`cmake --log-level` option or the
   :variable:`CMAKE_MESSAGE_LOG_LEVEL` cache variable.

 * Precompiled SunOS ``sparc`` and ``i386`` binaries are now provided
   on `cmake.org`_.

 .. _`cmake.org`: https://cmake.org/download/
	CMake 4.0 Release Notes
	***********************

	.. only:: html

	.. contents::

	Changes made since CMake 3.31 include the following.

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

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

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

	* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object
	gained a new ``debugger`` field.

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

	* The :option:`cmake --link-no-warning-as-error` option was added to suppress
	the effects of the :prop_tgt:`LINK_WARNING_AS_ERROR` target property and
	:variable:`CMAKE_LINK_WARNING_AS_ERROR` variable.

	* The :option:`cmake --project-file` option was added to specify an alternate
	filename for ``CMakeLists.txt`` files. This is intended for temporary use
	by developers during an incremental transition and not for publication of a
	final product. CMake will always emit a warning when the project file is
	anything other than ``CMakeLists.txt``.

	Commands
	--------

	* The :command:`target_link_libraries` command now supports the ``LINKER:``
	prefix.

	Variables
	---------

	* The :variable:`AIX` and :variable:`CMAKE_HOST_AIX` variables are
	now set to true when the target or host system is AIX, respectively.

	* Linker flag variables learned to support the ``LINKER:`` prefix:

	* :variable:`CMAKE_EXE_LINKER_FLAGS`
	* :variable:`CMAKE_EXE_LINKER_FLAGS_<CONFIG>`
	* :variable:`CMAKE_SHARED_LINKER_FLAGS`
	* :variable:`CMAKE_SHARED_LINKER_FLAGS_<CONFIG>`
	* :variable:`CMAKE_MODULE_LINKER_FLAGS`
	* :variable:`CMAKE_MODULE_LINKER_FLAGS_<CONFIG>`

	See policy :policy:`CMP0181`.

	* The :variable:`CMAKE_EXECUTE_PROCESS_COMMAND_ERROR_IS_FATAL` variable
	was added to specify the :command:`execute_process` command's
	default ``COMMAND_ERROR_IS_FATAL`` behavior.

	* The :variable:`CMAKE_<LANG>_LINK_MODE` and
	:variable:`CMAKE_<LANG>_DEVICE_LINK_MODE` variables were added to provide
	information on how the link step is done.

	* The :variable:`CMAKE_LINK_WARNING_AS_ERROR` variable and corresponding
	:prop_tgt:`LINK_WARNING_AS_ERROR` target property were added to link
	using a linker-specific flag to treat warnings as errors.

	* The :variable:`CMAKE_MSVC_RUNTIME_CHECKS` variable and
	:prop_tgt:`MSVC_RUNTIME_CHECKS` target property were introduced
	to select runtime checks for compilers targeting the MSVC ABI.
	See policy :policy:`CMP0184`.

	* The :variable:`CMAKE_POLICY_VERSION_MINIMUM` variable was added to
	help pacakgers and end users try to configure existing projects that
	have not been updated to work with supported CMake versions.

	* The :variable:`CMAKE_XCODE_SCHEME_LLDB_INIT_FILE` variable and corresponding
	:prop_tgt:`XCODE_SCHEME_LLDB_INIT_FILE` target property were added to tell
	the :generator:`Xcode` generator what to put in the scheme's "LLDB Init File"
	setting.

	* The :variable:`CMAKE_XCODE_SCHEME_TEST_CONFIGURATION` variable and corresponding
	:prop_tgt:`XCODE_SCHEME_TEST_CONFIGURATION` target property were added to tell
	the :generator:`Xcode` generator what to put in the scheme's "Build Configuration"
	setting for the test action.

	Properties
	----------

	* The :prop_tgt:`DEBUGGER_WORKING_DIRECTORY` target property and corresponding
	:variable:`CMAKE_DEBUGGER_WORKING_DIRECTORY` variable were added to tell
	generators what debugger working directory should be set for targets.

	* The :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property now supports an
	``ARCHIVER:`` prefix to pass options to the archiver through the compiler
	driver in a portable way.

	* The :prop_tgt:`Swift_MODULE_DIRECTORY` target property now supports
	:manual:`generator expressions <cmake-generator-expressions(7)>`.

	* The :prop_sf:`VS_CUSTOM_COMMAND_DISABLE_PARALLEL_BUILD` source file property
	was added to tell :ref:`Visual Studio Generators` not to run a custom command
	in parallel.

	* The :prop_dir:`VS_SOLUTION_ITEMS` directory property was added
	to tell :ref:`Visual Studio Generators` to attach files directly
	to the Solution (``.sln``).

	Modules
	-------

	* The :module:`ExternalData` module gained a
	:variable:`ExternalData_HTTPHEADERS` variable to specify HTTP headers.

	* The :module:`ExternalProject` module's :command:`ExternalProject_Add`
	command gained an ``INSTALL_JOB_SERVER_AWARE`` option to enable
	integration of the GNU Make job server when using an explicit
	``INSTALL_COMMAND`` with :ref:`Makefile Generators`.

	* The :module:`FeatureSummary` module :command:`add_feature_info`
	command now supports full :ref:`Condition Syntax`.
	See policy :policy:`CMP0183`.

	* The :module:`FindBISON` module :command:`bison_target` command gained an
	``OPTIONS`` option to specify Bison command-line options.

	* The :module:`FindCURL` module now provides a ``CURL_VERSION`` result
	variable to match upstream cURL's CMake package.

	* The :module:`FindFLEX` module :command:`flex_target` command gained an
	``OPTIONS`` option to specify Flex command-line options.

	* The :module:`FindPatch` module now supports running in
	:ref:`cmake -P <Script Processing Mode>` script mode by skipping
	the creation of the imported target.

	* The :module:`FindProtobuf` module :command:`protobuf_generate` command
	gained a ``PROTOC_EXE`` option to specify a custom ``protoc`` executable.

	* The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3`
	modules gained the possibility to do multiple calls in the same directory by
	using, respectively, the variables ``Python_ARTIFACTS_PREFIX``,
	``Python2_ARTIFACTS_PREFIX``, and ``Python3_ARTIFACTS_PREFIX``.

	* The :module:`FindRuby` module learned to find rbenv-provided installations.

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

	* The :genex:`$<PATH>` generator expression gained the ``NATIVE_PATH``
	operation to convert a CMake path into a native one.

	CTest
	-----

	* The :option:`ctest --interactive-debug-mode` option on Windows
	now enables Windows Error Reporting by default in test processes,
	allowing them to creating debug popup windows and core dumps.
	This restores behavior previously removed by CMake 3.11 after
	updates to ``libuv`` made it possible.

	CPack
	-----

	* The :cpack_gen:`CPack Archive Generator` learned to generated ``.tar``
	packages without compression.

	* The :cpack_gen:`CPack Archive Generator` now honors the
	:variable:`CPACK_ARCHIVE_FILE_NAME` variable for all packages.
	Previously, this variable worked only for component-based packages.

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

	* Compatibility with versions of CMake older than 3.5 has been removed.
	Calls to :command:`cmake_minimum_required` or :command:`cmake_policy`
	that set the policy version to an older value now issue an error.
	Note that calls to those commands can still support older versions of
	CMake by using their ``VERSION`` arguments' ``<min>...<max>`` syntax.
	This requires only the ``<min>`` version of CMake, but when running a
	newer version, sets policies up to the ``<max>`` version.

	* The :generator:`Visual Studio 14 2015` and :generator:`Visual Studio 15 2017`
	generators no longer support specifying a platform as part of the generator
	name. See :ref:`Visual Studio Platform Selection`.

	* The :variable:`CMAKE_<LANG>_USING_LINKER_MODE` variable is no longer used to
	determine the type of the contents of the
	:variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` variable. The
	:variable:`CMAKE_<LANG>_LINK_MODE` variable, set by CMake, is used instead.

	* The :module:`FindGDAL` module is now deprecated in favor of upstream
	GDAL's official CMake package configuration file. Port projects to
	the latter by calling ``find_package(GDAL CONFIG)``. For further
	details, see `GDAL's documentation on CMake integration
	<https://gdal.org/en/latest/development/cmake.html>`_.

	* The :module:`FindRuby` module no longer provides variables with the
	upper-case ``RUBY_`` prefix. See policy :policy:`CMP0185`.

	* CTest's undocumented declarative scripting mode has been removed.
	This mode used to be triggered by a :option:`ctest -S` script which did not
	call any :ref:`CTest Commands` unless :variable:`CTEST_RUN_CURRENT_SCRIPT`
	was explicitly set to ``OFF``.

	* The :command:`ctest_run_script` command may no longer be called without any
	arguments.

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

	* On macOS with :ref:`Ninja Generators` and :ref:`Makefile Generators`, when
	a compiler is found in ``/usr/bin``, it is now used as-is and is no longer
	mapped to the corresponding compiler inside Xcode. The mapping was
	introduced by CMake 3.2 to allow build trees to continue to work with their
	original compiler even when ``xcode-select`` switches to a different
	Xcode installation. However, the compilers inside Xcode cannot be used
	without explicit ``-isysroot`` flags and are therefore not suitable for
	passing to arbitrary third-party build systems. Furthermore, the mapping
	behavior can override user-specified compiler paths. Therefore, this
	behavior has been reverted.

	* Builds targeting macOS no longer choose any SDK or pass an ``-isysroot``
	flag to the compiler by default. Instead, compilers are expected to
	choose a default macOS SDK on their own. In order to use a compiler that
	does not do this, users must now specify ``-DCMAKE_OSX_SYSROOT=macosx``
	when configuring their build.

	* On AIX, ``SHARED`` library targets now produce a shared library archive
	by default. See policy :policy:`CMP0182`.

	* The :option:`cmake --preset` command no longer outputs a summary of the
	preset's CMake cache and environment variables by default. That summary is
	now only shown when the message log level is set to ``VERBOSE``, ``DEBUG``,
	or ``TRACE`` via the :option:`cmake --log-level` option or the
	:variable:`CMAKE_MESSAGE_LOG_LEVEL` cache variable.

	* Precompiled SunOS ``sparc`` and ``i386`` binaries are now provided
	on `cmake.org`_.

	.. _`cmake.org`: https://cmake.org/download/