Merge topic 'doc-3.28-relnotes'

5df79d1930 Help: Update Sphinx versionadded directives for 3.28 release
4eb2386901 Help: Organize and revise 3.28 release notes
32f3966521 Help: Consolidate 3.28 release notes
2c4f579124 Help: Fix versionadded indentation in cmake-generator-expressions(7) manual

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !8855
This commit is contained in:
Brad King
2023-10-03 15:20:24 +00:00
committed by Kitware Robot
36 changed files with 208 additions and 218 deletions
@@ -195,7 +195,7 @@ Two forms of conditional generator expressions are supported:
if ``condition`` is ``0``. Any other value for ``condition`` results in an
error.
.. versionadded:: 3.28
.. versionadded:: 3.28
This generator expression short-circuits such that generator expressions in
``false_string`` will not evaluate when ``condition`` is ``1``, and generator
@@ -258,7 +258,7 @@ The common boolean logic operators are supported:
``condition`` must be ``0`` or ``1``. The result of the expression is
``0`` if ``condition`` is ``1``, else ``1``.
.. versionadded:: 3.28
.. versionadded:: 3.28
Logical operators short-circuit such that generator expressions in the
arguments list will not be evaluated once a return value can be determined.
+2
View File
@@ -1,6 +1,8 @@
CMP0153
-------
.. versionadded:: 3.28
The :command:`exec_program` command should not be called.
This command has long been superseded by the :command:`execute_process`
+203
View File
@@ -0,0 +1,203 @@
CMake 3.28 Release Notes
************************
.. only:: html
.. contents::
Changes made since CMake 3.27 include the following.
New Features
============
Languages
---------
* C++ 20 named modules are now supported by :ref:`Ninja Generators`
and :ref:`Visual Studio Generators` for VS 2022 and newer, in combination
with the MSVC 14.34 toolset (provided with VS 17.4) and newer, LLVM/Clang
16.0 and newer, and GCC 14 (after the 2023-09-20 daily bump) and newer.
See :manual:`cmake-cxxmodules(7)` for details.
* ``HIP`` language code may now be compiled for NVIDIA GPUs
using the NVIDIA CUDA Compiler (NVCC).
See the :variable:`CMAKE_HIP_PLATFORM` variable.
Platforms
---------
* On Apple platforms, ``.xcframework`` folders are now supported:
* The :command:`find_library` command now finds ``.xcframework`` folders.
* The :command:`target_link_libraries` command now supports
linking against a ``.xcframework`` folder.
* The :prop_tgt:`IMPORTED_LOCATION` target property of an imported
library target may now be the path to a ``.xcframework`` folder.
* Apple visionOS and its ``xros`` and ``xrsimulator`` SDKs are now supported.
Compiling for Apple visionOS can be requested by setting
:variable:`CMAKE_SYSTEM_NAME` to ``visionOS``.
See :ref:`Cross Compiling for iOS, tvOS, visionOS, or watchOS`
for more information.
Presets
-------
* :manual:`cmake-presets(7)` files now support schema version ``8``.
It adds support for a ``$schema`` field.
Compilers
---------
* Cray Clang-based compilers are now supported with
:variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``CrayClang``.
* The OrangeC compiler is now supported with
:variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``OrangeC``.
Commands
--------
* The :command:`add_custom_command` and :command:`add_custom_target`
commands gained a ``JOB_SERVER_AWARE`` option.
* The :command:`cmake_host_system_information` command gained a
``MSYSTEM_PREFIX`` query for the installation prefix of a MSYS
or MinGW development environment on Windows hosts.
* The :command:`set_property` command ``TEST`` mode gained a ``DIRECTORY``
option to set properties on tests in other directories.
* The :command:`set_tests_properties` command gained a ``DIRECTORY``
option to set properties on tests in other directories.
* The :command:`get_property` command ``TEST`` mode gained a ``DIRECTORY``
option to get properties on tests in other directories.
* The :command:`get_test_property` command gained a ``DIRECTORY``
option to get properties on tests in other directories.
Variables
---------
* The :envvar:`CMAKE_CROSSCOMPILING_EMULATOR` environment variable
was added to initialize the :variable:`CMAKE_CROSSCOMPILING_EMULATOR`
cache variable.
* The :variable:`CMAKE_HIP_PLATFORM` variable was added to specify
the GPU platform for which HIP language sources are to be compiled
(``amd`` or ``nvidia``).
Properties
----------
* On imported shared libraries, the :prop_tgt:`IMPORTED_IMPLIB` target
property may now be used without :prop_tgt:`IMPORTED_LOCATION`.
This can be used to represent a stub library whose location should not
be added as a runtime search path to dependents that link it.
* The :prop_tgt:`IMPORTED_LOCATION` property of a macOS framework
may now be a path to the ``.framework`` folder itself.
* The :prop_tgt:`XCODE_EMBED_RESOURCES <XCODE_EMBED_<type>>` target property
was added to tell the :generator:`Xcode` generator what targets to put in
the ``Embed Resources`` build phase.
Modules
-------
* The :module:`ExternalProject` module now includes the
``BUILD_JOB_SERVER_AWARE`` option for the
:command:`ExternalProject_Add` command. This option enables
the integration of the GNU Make job server when using an
explicit ``BUILD_COMMAND`` with certain :ref:`Makefile Generators`.
Additionally, the :command:`ExternalProject_Add_Step` command
has been updated to support the new ``JOB_SERVER_AWARE`` option.
* The :module:`ExternalProject` module now declares ``BYPRODUCTS`` for the
downloaded file for generated ``download`` steps. Previously, if multiple
external projects downloaded to the same file, hash verification could fail.
Now, when using the :ref:`Ninja Generators`, this scenario is detected and
Ninja will raise an error stating that multiple rules generate the same file.
* The :module:`FetchContent` module's :command:`FetchContent_Declare` command
gained an ``EXCLUDE_FROM_ALL`` option, which propagates through to the
:command:`add_subdirectory` call made by
:command:`FetchContent_MakeAvailable` for the dependency.
* The :module:`FindCURL` module gained a ``CURL_USE_STATIC_LIBS`` hint
to select static libraries.
* The :module:`FindEXPAT` module gained an ``EXPAT_USE_STATIC_LIBS`` hint
to select static libraries.
* The :module:`FindPkgConfig` module :command:`pkg_get_variable` command
gained a ``DEFINE_VARIABLES`` option to pass variables to ``pkg-config``.
Generator Expressions
---------------------
* The :manual:`generator expressions <cmake-generator-expressions(7)>`
:genex:`$<IF:...>`, :genex:`$<AND:...>`, and :genex:`$<OR:...>`
short-circuit to avoid unnecessary evaluation of parameters.
CTest
-----
* CTest may now take a :ref:`dynamically-generated resource spec file
<ctest-resource-dynamically-generated-spec-file>`, which can be specified by the
:prop_test:`GENERATED_RESOURCE_SPEC_FILE` test property.
Deprecated and Removed Features
===============================
* The :command:`exec_program` command, which has been deprecated
since CMake 3.0, has been removed by policy :policy:`CMP0153`.
Use the :command:`execute_process` command instead.
* The :generator:`Visual Studio 11 2012` generator has been removed.
* The :generator:`Visual Studio 12 2013` generator is now deprecated
and will be removed in a future version of CMake.
* The :prop_tgt:`IOS_INSTALL_COMBINED` target property and corresponding
:variable:`CMAKE_IOS_INSTALL_COMBINED` variable have been deprecated.
Their functionality does not make sense on Apple Silicon hosts.
* The :generator:`Xcode` generator will now issue a fatal error if
the Legacy Build System has been selected for Xcode 14 and
newer. Those Xcode versions dropped support for the Legacy Build
System and expect the project to be set-up for their current
Build System.
Other Changes
=============
* Generated files, in targets using :ref:`file sets`, are now considered
private by default. Generated public headers must be specified using
file sets. This allows :ref:`Ninja Generators` to produce more
efficient build graphs. See policy :policy:`CMP0154`.
* The :command:`find_library`, :command:`find_path`, and :command:`find_file`
commands no longer search in installation prefixes derived from the ``PATH``
environment variable. This behavior was added in CMake 3.3 to support
MSYS and MinGW (``MSYSTEM``) development environments on Windows, but
it can search undesired prefixes that happen to be in the ``PATH`` for
unrelated reasons. Users who keep some ``<prefix>/bin`` directories in
the ``PATH`` just for their tools do not necessarily want any corresponding
``<prefix>/lib`` or ``<prefix>/include`` directories searched.
The behavior was reverted for non-Windows platforms by CMake 3.6.
Now it has been reverted on Windows platforms too.
One may set the ``CMAKE_PREFIX_PATH`` environment variable with a
:ref:`semicolon-separated list <CMake Language Lists>` of prefixes
that are to be searched.
* When using MinGW tools in a ``MSYSTEM`` environment on Windows,
the ``$MSYSTEM_PREFIX/local`` and ``$MSYSTEM_PREFIX`` prefixes are
now added to :variable:`CMAKE_SYSTEM_PREFIX_PATH`.
* The precompiled Linux ``x86_64`` binaries provided on
`cmake.org <https://cmake.org/download/>`_ now require GLIBC 2.17 or higher.
@@ -1,6 +0,0 @@
CMAKE_CROSSCOMPILING_EMULATOR-env-variable
------------------------------------------
* The :envvar:`CMAKE_CROSSCOMPILING_EMULATOR` environment variable
was added to initialize the :variable:`CMAKE_CROSSCOMPILING_EMULATOR`
cache variable.
-5
View File
@@ -1,5 +0,0 @@
CrayClang-compiler
------------------
* Cray Clang-based compilers are now supported with
:variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``CrayClang``.
@@ -1,10 +0,0 @@
ExternalProject-build-jobserver
-------------------------------
* The :module:`ExternalProject` module now includes the
``BUILD_JOB_SERVER_AWARE`` option for the
:command:`ExternalProject_Add` command. This option enables
the integration of the GNU Make job server when using an
explicit ``BUILD_COMMAND`` with certain :ref:`Makefile Generators`.
Additionally, the :command:`ExternalProject_Add_Step` command
has been updated to support the new ``JOB_SERVER_AWARE`` option.
@@ -1,8 +0,0 @@
ExternalProject-declare-download-byproducts
-------------------------------------------
* The :module:`ExternalProject` module now declares ``BYPRODUCTS`` for the
downloaded file for generated ``download`` steps. Previously, if multiple
external projects downloaded to the same file, hash verification could fail.
Now, when using the :ref:`Ninja Generators`, this scenario is detected and
Ninja will raise an error stating that multiple rules generate the same file.
@@ -1,7 +0,0 @@
FetchContent-exclude-from-all
-----------------------------
* The :module:`FetchContent` module's :command:`FetchContent_Declare` command
gained an ``EXCLUDE_FROM_ALL`` option, which propagates through to the
:command:`add_subdirectory` call made by
:command:`FetchContent_MakeAvailable` for the dependency.
-5
View File
@@ -1,5 +0,0 @@
FindCURL-static
---------------
* The :module:`FindCURL` module gained a ``CURL_USE_STATIC_LIBS`` hint
to select static libraries.
-5
View File
@@ -1,5 +0,0 @@
FindEXPAT-static
----------------
* The :module:`FindEXPAT` module gained a ``EXPAT_USE_STATIC_LIBS`` hint
to select static libraries.
@@ -1,5 +0,0 @@
FindPkgConfig-override
----------------------
* The :module:`FindPkgConfig` module :command:`pkg_get_variable` function
gained a ``DEFINE_VARIABLES`` option to pass variables to ``pkg-config``.
-7
View File
@@ -1,7 +0,0 @@
apple-visionos
--------------
* CMake learned about Apple visionOS and its `xros` and `xrsimulator` SDKs.
Compiling for Apple visionOS can be requested by setting
:variable:`CMAKE_SYSTEM_NAME` to ``visionOS``. For more
information see :manual:`cmake-toolchains(7)`.
@@ -1,5 +0,0 @@
command-job-server-aware
------------------------
* The :command:`add_custom_command` and :command:`add_custom_target`
commands gained a ``JOB_SERVER_AWARE`` option.
@@ -1,8 +0,0 @@
cxxmodules-no-longer-experimental
---------------------------------
* C++ 20 named modules are now supported by :ref:`Ninja Generators`
and :ref:`Visual Studio Generators` for VS 2022 and newer, in combination
with the MSVC 14.34 toolset (provided with VS 17.4) and newer, LLVM/Clang
16.0 and newer, and GCC 14 (after the 2023-09-20 daily bump) and newer.
See :manual:`cmake-cxxmodules(7)` for details.
@@ -1,6 +0,0 @@
deprecate-install-combined
--------------------------
* The :prop_tgt:`IOS_INSTALL_COMBINED` target property and corresponding
:variable:`CMAKE_IOS_INSTALL_COMBINED` variable have been deprecated.
Their functionality does not make sense on Apple Silicon hosts.
@@ -1,6 +0,0 @@
dynamically-generated-resource-spec-file
----------------------------------------
* CTest may now take a :ref:`dynamically-generated resource spec file
<ctest-resource-dynamically-generated-spec-file>`, which can be specified by the
:prop_test:`GENERATED_RESOURCE_SPEC_FILE` test property.
-6
View File
@@ -1,6 +0,0 @@
exec_program-policy
-------------------
* The :command:`exec_program` command, which has been deprecated since CMake
3.0, has been removed by policy :policy:`CMP0153`. Use the
:command:`execute_process` command instead.
-7
View File
@@ -1,7 +0,0 @@
fileset-private-dep
-------------------
* Generated files, in targets using :ref:`file sets`, are now considered
private by default. Generated public headers must be specified using
file sets. This allows :ref:`Ninja Generators` to produce more
efficient build graphs. See policy :policy:`CMP0154`.
@@ -1,17 +0,0 @@
find-windows-no-PATH-prefixes
-----------------------------
* The :command:`find_library`, :command:`find_path`, and :command:`find_file`
commands no longer search in installation prefixes derived from the ``PATH``
environment variable. This behavior was added in CMake 3.3 to support
MSYS and MinGW (``MSYSTEM``) development environments on Windows, but
it can search undesired prefixes that happen to be in the ``PATH`` for
unrelated reasons. Users that keep some ``<prefix>/bin`` directories in
the ``PATH`` just for their tools do not necessarily want any corresponding
``<prefix>/lib`` or ``<prefix>/include`` directories searched.
The behavior was reverted for non-Windows platforms by CMake 3.6.
Now it has been reverted on Windows platforms too.
One may set the ``CMAKE_PREFIX_PATH`` environment variable with a
:ref:`semicolon-separated list <CMake Language Lists>` of prefixes
that are to be searched.
-5
View File
@@ -1,5 +0,0 @@
genexp-no-eval
--------------
* :manual:`generator expressions <cmake-generator-expressions(7)>`
short-circuit to avoid unnecessary evaluation of parameters.
-9
View File
@@ -1,9 +0,0 @@
hip-nvidia
----------
* ``HIP`` language code may now be compiled for NVIDIA GPUs
using the NVIDIA CUDA Compiler (NVCC).
* The :variable:`CMAKE_HIP_PLATFORM` variable was added to specify
the GPU platform for which HIP language sources are to be compiled
(``amd`` or ``nvidia``).
-6
View File
@@ -1,6 +0,0 @@
host-msystem-prefix
-------------------
* The :command:`cmake_host_system_information` command gained a
``MSYSTEM_PREFIX`` query for the installation prefix of a MSYS
or MinGW development environment on Windows hosts.
@@ -1,7 +0,0 @@
imported-implib-only
--------------------
* On imported shared libraries, the :prop_tgt:`IMPORTED_IMPLIB` target
property may now be used without :prop_tgt:`IMPORTED_LOCATION`.
This can be used to represent a stub library whose location should not
be added as a runtime search path to dependents that link it.
@@ -1,5 +0,0 @@
imported-target-framework-path
------------------------------
* The :prop_tgt:`IMPORTED_LOCATION` property of a macOS framework may now be
the location of the framework folder itself.
@@ -1,6 +0,0 @@
mingw-search-prefixes
---------------------
* When using MinGW tools in a ``MSYSTEM`` environment on Windows,
the ``$MSYSTEM_PREFIX/local`` and ``$MSYSTEM_PREFIX`` prefixes are
now added to :variable:`CMAKE_SYSTEM_PREFIX_PATH`.
-5
View File
@@ -1,5 +0,0 @@
orangec-compiler
----------------
* The OrangeC compiler is now supported with
:variable:`compiler id <CMAKE_<LANG>_COMPILER_ID>` ``OrangeC``.
-5
View File
@@ -1,5 +0,0 @@
presets-schema
--------------
* :manual:`cmake-presets(7)` files now support schema version ``8``.
It adds support for a ``$schema`` field.
-5
View File
@@ -1,5 +0,0 @@
rel-linux-x86_64
----------------
* The precompiled Linux ``x86_64`` binaries provided on
`cmake.org <https://cmake.org/download/>`_ now require GLIBC 2.17 or higher.
@@ -1,4 +0,0 @@
remove-vs11-generator
---------------------
* The :generator:`Visual Studio 11 2012` generator has been removed.
@@ -1,15 +0,0 @@
test-properties-directory
-------------------------
* The ``TEST`` mode of the :command:`set_property` command gained a
``DIRECTORY`` sub-option, which allows you to set properties on tests in
other directories.
* The :command:`set_tests_properties` command gained a ``DIRECTORY``
sub-option, which allows you to set properties on tests in other
directories.
* The ``TEST`` mode of the :command:`get_property` command gained a
``DIRECTORY`` sub-option, which allows you to get properties on tests in
other directories.
* The :command:`get_test_property` command gained a ``DIRECTORY``
sub-option, which allows you to get properties on tests in other
directories.
-5
View File
@@ -1,5 +0,0 @@
vs12-deprecate
--------------
* The :generator:`Visual Studio 12 2013` generator is now deprecated
and will be removed in a future version of CMake.
@@ -1,5 +0,0 @@
xcframework-find-library
------------------------
* The :command:`find_library` command can now find ``.xcframework`` folders on
Apple platforms.
@@ -1,7 +0,0 @@
xcframework-target-link-libraries
---------------------------------
* Targets may now link against an ``.xcframework`` folder in
:command:`target_link_libraries`.
* The :prop_tgt:`IMPORTED_LOCATION` property of a target may now be an
``.xcframework`` folder.
@@ -1,6 +0,0 @@
xcode-embed-resources
---------------------
* The :prop_tgt:`XCODE_EMBED_RESOURCES <XCODE_EMBED_<type>>` target property
was added to tell the :generator:`Xcode` generator what targets to put in
the ``Embed Resources`` build phase.
@@ -1,8 +0,0 @@
xcode-no-legacy-buildsystem
---------------------------
* The :generator:`Xcode` generator will now issue a fatal error if
the Legacy Build System has been selected for Xcode 14 and
newer. Those Xcode versions dropped support for the Legacy Build
System and expect the project being set-up for their current
Build System.
+1
View File
@@ -15,6 +15,7 @@ Releases
.. toctree::
:maxdepth: 1
3.28 <3.28>
3.27 <3.27>
3.26 <3.26>
3.25 <3.25>