| 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``. | |
| * The :option:`cmake --sarif-output` option was added to enable | |
| generation of a `Static Analysis Results Interchange Format (SARIF) | |
| <https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html>`__ | |
| log file recording diagnostic messages from the run. | |
| 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_EXPORT_SARIF` variable was added to enable generation of | |
| a SARIF log file listing diagnostics recorded during configuration and | |
| generation of a CMake project. | |
| * 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 packagers and end users try to configure existing projects that | |
| have not been updated to work with supported CMake versions. | |
| The :envvar:`CMAKE_POLICY_VERSION_MINIMUM` environment variable was | |
| added to initialize it. | |
| * The :variable:`CMAKE_UNITY_BUILD_RELOCATABLE` variable and corresponding | |
| :prop_tgt:`UNITY_BUILD_RELOCATABLE` target property were added to make | |
| sources generated for :variable:`CMAKE_UNITY_BUILD` to ``#include`` the | |
| original source files using relative paths where possible. | |
| * 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 generate ``.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. | |
| * In builds targeting macOS, :variable:`CMAKE_OSX_SYSROOT` now defaults to | |
| empty, deferring to the compiler's default macOS SDK selection. In order | |
| to pass an explicit macOS SDK via the compiler's ``-isysroot`` flag, users | |
| may configure their build tree with ``-DCMAKE_OSX_SYSROOT=macosx``, or | |
| ``export SDKROOT="$(xcrun --sdk macosx --show-sdk-path)"`` in their | |
| environment. | |
| Notes: | |
| * macOS compilers in ``/usr/bin``, when not invoked with ``-isysroot``, | |
| search for headers in ``/usr/local/include`` before system SDK paths, | |
| matching the convention on many platforms. Users on macOS-x86_64 hosts | |
| with Homebrew installed in ``/usr/local`` should pass an explicit SDK, | |
| as described above, when not building with Homebrew tools. | |
| * Some Clang compilers have no default macOS SDK selection. For these, | |
| if :variable:`CMAKE_OSX_SYSROOT` is empty, CMake will automatically pass | |
| ``-isysroot`` with the macOS SDK printed by ``xcrun --show-sdk-path``. | |
| * On Windows, file paths named in project code, e.g., in ``CMakeLists.txt``, | |
| are no longer automatically converted to their on-disk upper/lower case. | |
| Projects are expected to spell source file paths consistently using | |
| their canonical case, e.g., in calls to :command:`add_library`, | |
| :command:`set_property(SOURCE)`, or :command:`set_source_files_properties`. | |
| This matches the behavior on platforms with case-sensitive filesystems. | |
| * 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 ``sparc64`` and ``x86_64`` binaries are now provided | |
| on `cmake.org`_. | |
| .. _`cmake.org`: https://cmake.org/download/ | |
| Updates | |
| ======= | |
| Changes made since CMake 4.0.0 include the following. | |
| 4.0.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.0.2 | |
| ----- | |
| * When building for macOS with a Clang that has no default macOS SDK, | |
| if :variable:`CMAKE_OSX_SYSROOT` is empty, CMake now automatically passes | |
| ``-isysroot`` with the macOS SDK printed by ``xcrun --show-sdk-path``. | |
| This restores support for using LLVM/Clang on macOS without manually | |
| setting ``CMAKE_OSX_SYSROOT``, which was broken by CMake 4.0.0's | |
| removal of a default value. | |
| * The :prop_tgt:`DEBUGGER_WORKING_DIRECTORY` target property is now | |
| used by the :generator:`Xcode` generator as a fallback for the | |
| :prop_tgt:`XCODE_SCHEME_WORKING_DIRECTORY` target property. | |
| 4.0.3, 4.0.4 | |
| ------------ | |
| * These versions made no changes to documented features or interfaces. | |
| Some implementation updates were made to support ecosystem changes | |
| and/or fix regressions. | |
| 4.0.5 | |
| ----- | |
| * When building for macOS with the :generator:`Xcode` generator, | |
| :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` once again defaults to the | |
| host's macOS version if it is older than the macOS SDK version, | |
| as it did in CMake versions prior to 4.0. | |
| * The :command:`execute_process` command once again terminates child | |
| processes when its ``TIMEOUT`` is reached. This was accidentally | |
| regressed by CMake 3.29. | |
| 4.0.6, 4.0.7 | |
| ------------ | |
| * These versions made no changes to documented features or interfaces. | |
| Some implementation updates were made to support ecosystem changes | |
| and/or fix regressions. |