Merge topic 'doc-3.29-relnotes'

ab29be4ce1 Help: Organize and revise 3.29 release notes
ca7ef81c39 Help: Consolidate 3.29 release notes
2ce6337503 Help: Reword if(EXISTS) suggestion to prefer if(IS_READABLE)
23d7863375 Help: Fix cmake_language(EXIT) signature anchor

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !9218
This commit is contained in:
Brad King
2024-02-06 19:47:02 +00:00
committed by Kitware Robot
34 changed files with 205 additions and 225 deletions

View File

@@ -513,11 +513,6 @@ Terminating Scripts
.. versionadded:: 3.29
.. _EXIT:
.. _exit-code:
.. code-block:: cmake
.. signature::
cmake_language(EXIT <exit-code>)

View File

@@ -178,10 +178,9 @@ File Operations
False if the given path is an empty string.
.. warning::
To check the readability of a file, use preferably ``if(IS_READABLE)``
because this test will evolve to check file existence only in a future
release.
.. note::
Prefer ``if(IS_READABLE)`` to check file readability. ``if(EXISTS)``
may be changed in the future to to only check file existence.
.. signature:: if(IS_READABLE <path-to-file-or-directory>)

201
Help/release/3.29.rst Normal file
View File

@@ -0,0 +1,201 @@
CMake 3.29 Release Notes
************************
.. only:: html
.. contents::
Changes made since CMake 3.28 include the following.
New Features
============
Command-Line
------------
* :manual:`cmake(1)` :option:`-E cat <cmake-E cat>` can now print the standard
input by passing the ``-`` argument.
Generators
----------
* :ref:`Visual Studio Generators` now support selecting between the
Intel oneAPI Fortran compiler (``ifx``) and the Intel classic Fortran
compiler (``ifort``) using a ``fortran=`` field in
:variable:`CMAKE_GENERATOR_TOOLSET`.
File-Based API
--------------
* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
been updated to 2.7.
* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained
a new "launchers" field.
Compilers
---------
* The LLVM/Clang GNU-like frontend on Windows (``clang++``) may now be used
to compile ``CUDA`` language sources.
Commands
--------
* The :ref:`add_custom_command(TARGET) <add_custom_command(TARGET)>`
signature now supports adding build events through :ref:`Alias Targets`.
* The :command:`cmake_language(EXIT)` sub-command was added to terminate
:option:`cmake -P` scripts with a specified exit code.
* The :command:`export(SETUP)` sub-command was added to configure export sets.
Its ``PACKAGE_DEPENDENCY`` option configures how :command:`find_dependency`
calls are exported. Its ``TARGET`` option's ``XCFRAMEWORK_LOCATION``
setting specifies the location of a ``.xcframework`` that can be
substituted for an installed target.
* The :command:`if` command gained new tests ``IS_READABLE``, ``IS_WRITABLE``
and ``IS_EXECUTABLE`` to check file or directory permissions.
* :command:`install(EXPORT)` and :command:`export(EXPORT)` learned a new
``EXPORT_PACKAGE_DEPENDENCIES`` argument, which can be used to generate
:command:`find_dependency` calls based on what targets the exported targets
depend on.
Variables
---------
* The :envvar:`CMAKE_INSTALL_PREFIX` environment variable was added to
provide a default value for the :variable:`CMAKE_INSTALL_PREFIX` variable.
* The :variable:`CMAKE_LINKER_TYPE` variable and corresponding
:prop_tgt:`LINKER_TYPE` target property were added to specify
what linker to use with some toolchains.
* The :variable:`CMAKE_<LANG>_COMPILER_LINKER`,
:variable:`CMAKE_<LANG>_COMPILER_LINKER_ID`,
:variable:`CMAKE_<LANG>_COMPILER_LINKER_VERSION` and
:variable:`CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT` variables
were added to describe the linker used by the language's link step.
* The :variable:`CMAKE_PROJECT_INCLUDE`,
:variable:`CMAKE_PROJECT_INCLUDE_BEFORE`,
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, and
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables learned
to support a :ref:`semicolon-separated list <CMake Language Lists>` of
CMake language files to be included sequentially. These variables can also
reference module names to be found in :variable:`CMAKE_MODULE_PATH` or
builtin to CMake.
* The :variable:`CMAKE_SKIP_TEST_ALL_DEPENDENCY` variable was added
to control whether the ``test`` (or ``RUN_TESTS``) buildsystem
target depends on the ``all`` (or ``ALL_BUILD``) target.
* A :variable:`CMAKE_TEST_LAUNCHER` variable and corresponding
:prop_tgt:`TEST_LAUNCHER` target property were added to specify
a launcher to be used by executable targets when invoked by
tests added by the :command:`add_test` command.
Properties
----------
* The :prop_tgt:`CROSSCOMPILING_EMULATOR` target property now
supports :manual:`generator expressions <cmake-generator-expressions(7)>`.
* The :prop_tgt:`EXPORT_FIND_PACKAGE_NAME` target property was added to
allow targets to specify what package name to pass when exporting
:command:`find_dependency` calls. This property is initialized with a new
:variable:`CMAKE_EXPORT_FIND_PACKAGE_NAME` variable.
* The :prop_tgt:`UNITY_BUILD` target property now supports the
Objective C (``OBJC``) and Objective C++ (``OBJCXX``) languages.
* The :prop_tgt:`XCODE_EMBED_XPC_SERVICES <XCODE_EMBED_<type>>` target property
was added to tell the :generator:`Xcode` generator what targets to put in
the ``Embed XPC Resources`` build phase.
Modules
-------
* The :module:`CMakePackageConfigHelpers` module gained new
:command:`generate_apple_platform_selection_file` and
:command:`generate_apple_architecture_selection_file` functions, which can
be used to generate a file that includes another Apple-platform-specific
file or the includes an architecture-specific implementation of a package
for an Apple platform, respectively.
* The :module:`FindOpenGL` module learned to find a GLU include
directory different than the GL include directory. A new
``OPENGL_INCLUDE_DIRS`` result variable provides all include
directories.
CTest
-----
* :manual:`ctest(1)` gained a :option:`--http-header <ctest --http-header>`
option to add custom headers on submission to CDash.
* :manual:`ctest(1)` gained the :option:`--tests-from-file <ctest
--tests-from-file>` and :option:`--exclude-from-file <ctest
--exclude-from-file>` options to run or exclude tests named in a file.
* :manual:`ctest(1)` now supports :ref:`job server integration
<ctest-job-server-integration>` on POSIX systems.
* The :command:`ctest_test` command gained options
``INCLUDE_FROM_FILE`` and ``EXCLUDE_FROM_FILE`` to run or exclude
tests named in a file.
CPack
-----
* The :cpack_gen:`CPack DEB Generator` :variable:`CPACK_DEBIAN_FILE_NAME`
variable may now be set without any suffix, and the ``.deb`` suffix
will be added automatically.
* The :cpack_gen:`CPack RPM Generator` :variable:`CPACK_RPM_FILE_NAME`
variable may now be set without any suffix, and the ``.rpm`` suffix
will be added automatically.
* The :cpack_gen:`CPack WIX Generator` gained a new variable,
:variable:`CPACK_WIX_INSTALL_SCOPE`, to control the
``InstallScope`` property of WiX MSI installers.
Other Changes
=============
* CMake learned to de-duplicate libraries on link lines based on linker
capabilities. See policy :policy:`CMP0156`.
* The :command:`add_test` command now honors
:variable:`CMAKE_CROSSCOMPILING_EMULATOR` only when cross-compiling.
See policy :policy:`CMP0158`.
* :command:`FetchContent_MakeAvailable` now sets the
:variable:`CMAKE_EXPORT_FIND_PACKAGE_NAME` variable for CMake projects.
* On Windows, when targeting the MSVC ABI, the :command:`find_library` command
now accepts ``.a`` file names after first considering ``.lib``. This is
symmetric with existing behavior when targeting the GNU ABI, in which the
command accepts ``.lib`` file names after first considering ``.a``.
* On Windows, when targeting the MSVC ABI, the :command:`find_library` command
now considers ``.dll.lib`` file names before ``.lib``. This is the default
suffix for DLL import libraries created by Rust toolchains for the MSVC ABI.
* The :generator:`Ninja` and :generator:`NMake Makefiles` generators now use
the ``-external:I`` flag for system includes when using IntelLLVM as of
version 2021.4. The ``-external:W0`` flag is also used as of version 2022.2.
* The :command:`create_test_sourcelist` command now provides a full path to
the generated driver source file.
* The :variable:`CPACK_PRODUCTBUILD_DOMAINS` variable now defaults to true.
See policy :policy:`CMP0161`.
* The :cpack_gen:`CPack WIX Generator` now produces WiX MSI installers
that create start menu and uninstall entries for all users by default,
as documented by the :variable:`CPACK_WIX_INSTALL_SCOPE` variable
``perMachine`` value. Previously, without a custom WiX template,
it produced installers that would only create start menu and uninstall
entries for the current user, even though they install for all users.

View File

@@ -1,6 +0,0 @@
IntelLLVM-isystem-flag
----------------------
* The :generator:`Ninja` and :generator:`NMake Makefiles` generators now use
the ``-external:I`` flag for system includes when using IntelLLVM as of
version 2021.4. The ``-external:W0`` flag is also used as of version 2022.2.

View File

@@ -1,6 +0,0 @@
Linker-user-selection
---------------------
* The linker tool can now be specified for a selection of compilers/platforms
by setting :variable:`CMAKE_LINKER_TYPE` variable or :prop_tgt:`LINKER_TYPE`
target property.

View File

@@ -1,5 +0,0 @@
add_custom_command-target-alias
-------------------------------
* The :ref:`add_custom_command(TARGET) <add_custom_command(TARGET)>`
signature now supports adding build events through :ref:`Alias Targets`.

View File

@@ -1,5 +0,0 @@
cmake-E-cat-stdin
-----------------
* :manual:`cmake(1)` :option:`-E cat <cmake-E cat>` can now print the standard
input by passing the ``-`` argument.

View File

@@ -1,5 +0,0 @@
cmake-language-exit
-------------------
* The :command:`cmake_language()` command gained a new ``EXIT``
sub-command to exit scripts with a specified exit code.

View File

@@ -1,14 +0,0 @@
cmake-test-launcher
-------------------
* A :variable:`CMAKE_TEST_LAUNCHER` variable and corresponding
:prop_tgt:`TEST_LAUNCHER` target property were added to specify
a launcher to be used by executable targets when invoked by
tests added by the :command:`add_test` command.
* The :command:`add_test` command now honors
:variable:`CMAKE_CROSSCOMPILING_EMULATOR` only when cross-compiling.
See policy :policy:`CMP0158`.
* The :prop_tgt:`CROSSCOMPILING_EMULATOR` target property now
supports :manual:`generator expressions <cmake-generator-expressions(7)>`.

View File

@@ -1,8 +0,0 @@
compiler-linker
---------------
* The linker effectively used for the link step is now documented with the
:variable:`CMAKE_<LANG>_COMPILER_LINKER`,
:variable:`CMAKE_<LANG>_COMPILER_LINKER_ID`,
:variable:`CMAKE_<LANG>_COMPILER_LINKER_VERSION` and
:variable:`CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT` variables.

View File

@@ -1,10 +0,0 @@
cpack-auto-suffixes
-------------------
* The :cpack_gen:`CPack DEB Generator` :variable:`CPACK_DEBIAN_FILE_NAME`
variable may now be set without any suffix, and the ``.deb`` suffix
will be added automatically.
* The :cpack_gen:`CPack RPM Generator` :variable:`CPACK_RPM_FILE_NAME`
variable may now be set without any suffix, and the ``.rpm`` suffix
will be added automatically.

View File

@@ -1,5 +0,0 @@
create_test_sourcelist-full-filepath
------------------------------------
* The :command:`create_test_sourcelist` command now provides a full path to
the generated driver source file.

View File

@@ -1,5 +0,0 @@
ctest-cli-http-headers
----------------------
* :manual:`ctest(1)` gained a :option:`--http-header <ctest --http-header>`
option to add custom headers on submission to CDash.

View File

@@ -1,5 +0,0 @@
ctest-jobserver-client
----------------------
* :manual:`ctest(1)` now supports :ref:`job server integration
<ctest-job-server-integration>` on POSIX systems.

View File

@@ -1,10 +0,0 @@
ctest-tests-from-file
---------------------
* :manual:`ctest(1)` gained the :option:`--tests-from-file <ctest
--tests-from-file>` and :option:`--exclude-from-file <ctest
--exclude-from-file>` options to run or exclude tests named in a file.
* The :command:`ctest_test` command gained options
``INCLUDE_FROM_FILE`` and ``EXCLUDE_FROM_FILE`` to run or exclude
tests named in a file.

View File

@@ -1,5 +0,0 @@
cuda-clang-windows
------------------
* The ``CUDA`` language can now be compiled with Clang on Windows
using its GNU-like frontend, ``clang++``.

View File

@@ -1,5 +0,0 @@
env-cmake-install-prefix
------------------------
* The :envvar:`CMAKE_INSTALL_PREFIX` environment variable was added to
provide a default value for the :variable:`CMAKE_BUILD_TYPE` variable.

View File

@@ -1,16 +0,0 @@
export-find_dependency-calls
----------------------------
* :command:`install(EXPORT)` and :command:`export(EXPORT)` learned a new
``EXPORT_PACKAGE_DEPENDENCIES`` argument, which can be used to generate
:command:`find_dependency` calls based on what targets the exported targets
depend on.
* A new :command:`export(SETUP)` signature was created to configure export
sets. This can be used to configure how :command:`find_dependency` calls are
exported.
* A new :prop_tgt:`EXPORT_FIND_PACKAGE_NAME` target property was created to
allow targets to specify what package name to pass when exporting
:command:`find_dependency` calls. This property is initialized with a new
:variable:`CMAKE_EXPORT_FIND_PACKAGE_NAME` variable.
* :command:`FetchContent_MakeAvailable` now sets the
:variable:`CMAKE_EXPORT_FIND_PACKAGE_NAME` variable for CMake projects.

View File

@@ -1,7 +0,0 @@
fileapi-exe-launcher
--------------------
* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
been updated to 2.7.
* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object gained
a new "launchers" field.

View File

@@ -1,6 +0,0 @@
find-rustc-importlibs
---------------------
* On Windows, when targeting the MSVC ABI, the :command:`find_library` command
now considers ``.dll.lib`` file names before ``.lib``. This is the default
suffix for DLL import libraries created by Rust toolchains for the MSVC ABI.

View File

@@ -1,7 +0,0 @@
find_library-msvc-libfoo.a
--------------------------
* On Windows, when targeting the MSVC ABI, the :command:`find_library` command
now accepts ``.a`` file names after first considering ``.lib``. This is
symmetric with existing behavior when targeting the GNU ABI, in which the
command accepts ``.lib`` file names after first considering ``.a``.

View File

@@ -1,7 +0,0 @@
findopengl-glu-include-dir
--------------------------
* The :module:`FindOpenGL` module learned to find a GLU include
directory different than the GL include directory. A new
``OPENGL_INCLUDE_DIRS`` result variable provides all include
directories.

View File

@@ -1,5 +0,0 @@
if-check-file-permissions
-------------------------
* The :command:`if` command gained new tests ``IS_READABLE``, ``IS_WRITABLE``
and ``IS_EXECUTABLE`` to check file or directory permissions.

View File

@@ -1,9 +0,0 @@
install-export-xcframework
--------------------------
* The :command:`export(SETUP)` command gained a new ``XCFRAMEWORK_LOCATION``
argument, which can be used to specify the location of a ``.xcframework``
that can be substituted for the installed library.
* The :module:`CMakePackageConfigHelpers` module gained a new
:command:`generate_apple_platform_selection_file` function, which can be
used to generate a file that includes another Apple-platform-specific file.

View File

@@ -1,5 +0,0 @@
link-deduplicate-libs
---------------------
* CMake learned to de-duplicate libraries on link lines based on linker
capabilities. See policy :policy:`CMP0156`.

View File

@@ -1,6 +0,0 @@
make-test-depend-on-all
-----------------------
* The :variable:`CMAKE_SKIP_TEST_ALL_DEPENDENCY` variable was added
to control whether the ``test`` (or ``RUN_TESTS``) buildsystem
target depends on the ``all`` (or ``ALL_BUILD``) target.

View File

@@ -1,7 +0,0 @@
package-dispatch-apple
----------------------
* The :module:`CMakePackageConfigHelpers` module gained a new
:command:`generate_apple_architecture_selection_file` function, which can be
used to generate a file that includes an architecture-specific implementation
of a package for an Apple platform.

View File

@@ -1,5 +0,0 @@
productbuild-domains-policy
---------------------------
* The :variable:`CPACK_PRODUCTBUILD_DOMAINS` variable now defaults to true.
See policy :policy:`CMP0161`.

View File

@@ -1,11 +0,0 @@
project-include-multiple
------------------------
* The :variable:`CMAKE_PROJECT_INCLUDE`,
:variable:`CMAKE_PROJECT_INCLUDE_BEFORE`,
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`, and
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables learned
to support a :ref:`semicolon-separated list <CMake Language Lists>` of
CMake language files to be included sequentially. These variables can also
reference module names to be found in :variable:`CMAKE_MODULE_PATH` or
builtin to CMake.

View File

@@ -1,5 +0,0 @@
unity-build-objc
----------------
* The :prop_tgt:`UNITY_BUILD` target property now supports the
Objective C (``OBJC``) and Objective C++ (``OBJCXX``) languages.

View File

@@ -1,7 +0,0 @@
vs-ifx
------
* :ref:`Visual Studio Generators` now support selecting between the
Intel oneAPI Fortran compiler (``ifx``) and the Intel classic Fortran
compiler (``ifort``) using a ``fortran=`` field in
:variable:`CMAKE_GENERATOR_TOOLSET`.

View File

@@ -1,13 +0,0 @@
wix-installscope
----------------
* The :cpack_gen:`CPack WIX Generator` gained a new variable,
:variable:`CPACK_WIX_INSTALL_SCOPE`, to control the
``InstallScope`` property of WiX MSI installers.
* The :cpack_gen:`CPack WIX Generator` now produces WiX MSI installers
that create start menu and uninstall entries for all users by default,
as documented by the :variable:`CPACK_WIX_INSTALL_SCOPE` variable
``perMachine`` value. Previously, without a custom WiX template,
it produced installers that would only create start menu and uninstall
entries for the current user, even though they install for all users.

View File

@@ -1,6 +0,0 @@
xcode-embed-xpc-services
------------------------
* The :prop_tgt:`XCODE_EMBED_XPC_SERVICES <XCODE_EMBED_<type>>` target property
was added to tell the :generator:`Xcode` generator what targets to put in
the ``Embed XPC Resources`` build phase.

View File

@@ -15,6 +15,7 @@ Releases
.. toctree::
:maxdepth: 1
3.29 <3.29>
3.28 <3.28>
3.27 <3.27>
3.26 <3.26>