Merge topic 'doc-3.26-relnotes'

385435cf78 Help: Organize and revise 3.26 release notes
4c63f031c1 Help: Consolidate 3.26 release notes
bc1ba6d56b Help: Document experimental feature gate affecting CXX_SCAN_FOR_MODULES
71f9c1943d FindImageMagick: Fix documentation syntax in usage example

Acked-by: Kitware Robot <[email protected]>
Merge-request: !8148

Help/prop_sf/CXX_SCAN_FOR_MODULES.rst

@@ -17,3 +17,8 @@ Note that scanning is only performed if C++20 or higher is enabled for the
 target and the source uses the ``CXX`` language.  Scanning for modules in
 sources belonging to file sets of type ``CXX_MODULES`` and
 ``CXX_MODULES_HEADER_UNITS`` is always performed.
+
+.. note ::
+
+  This setting is meaningful only when experimental support for C++ modules
+  has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` gate.

Help/prop_tgt/CXX_SCAN_FOR_MODULES.rst

@@ -20,3 +20,8 @@ scan the target's ``CXX`` sources at build time.
 Note that scanning is only performed if C++20 or higher is enabled for the
 target.  Scanning for modules in the target's sources belonging to file sets
 of type ``CXX_MODULES`` and ``CXX_MODULES_HEADER_UNITS`` is always performed.
+
+.. note ::
+
+  This setting is meaningful only when experimental support for C++ modules
+  has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` gate.

Help/release/3.26.rst

@@ -0,0 +1,172 @@
+CMake 3.26 Release Notes
+************************
+
+.. only:: html
+
+  .. contents::
+
+Changes made since CMake 3.25 include the following.
+
+New Features
+============
+
+Languages
+---------
+
+* The ``ASM_MARMASM`` language was added to support the
+  Microsoft ARM assembler language.
+
+Command-Line
+------------
+
+* The :option:`cmake -E copy <cmake-E copy>` command-line tool now
+  supports a ``-t`` argument.
+
+* The :option:`cmake -E copy_directory_if_different
+  <cmake-E copy_directory_if_different>` command-line tool was added.
+
+Configure Log
+-------------
+
+* CMake now writes a YAML log of configure-time checks to
+  ``CMakeFiles/CMakeConfigureLog.yaml`` under the top of the build tree.
+  See the :manual:`cmake-configure-log(7)` manual.
+
+File-Based API
+--------------
+
+* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
+  been updated to 2.5.
+
+* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object
+  gained a new ``fileSets`` field and associated ``fileSetIndex``
+  field to ``sources`` objects.
+
+* The :manual:`cmake-file-api(7)` gained a new "configureLog" object kind
+  that enables stable access to the :manual:`cmake-configure-log(7)`.
+
+Commands
+--------
+
+* The :command:`add_custom_command` and :command:`add_custom_target` commands
+  now support :manual:`generator expressions <cmake-generator-expressions(7)>`
+  in their ``COMMENT`` option.
+
+* The :command:`message` command gained a ``CONFIGURE_LOG`` mode to
+  record an entry in the :manual:`cmake-configure-log(7)`.
+
+* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` commands
+  now support the ``%z`` and ``%Z`` specifiers for the time zone.
+
+* The :command:`try_compile` and :command:`try_run` commands gained
+  a ``LOG_DESCRIPTION`` option specifying text to be recorded in the
+  :manual:`cmake-configure-log(7)`.
+
+* The :command:`try_compile` and :command:`try_run` commands gained a
+  ``NO_LOG`` option to skip recording a :manual:`cmake-configure-log(7)`
+  entry.
+
+Variables
+---------
+
+* The :variable:`CMAKE_<LANG>_COMPILER_FRONTEND_VARIANT` variable is now
+  set for ``GNU``, ``MSVC``, and ``AppleClang`` compilers that have only
+  one frontend variant.
+
+* A :variable:`CMAKE_VS_VERSION_BUILD_NUMBER` variable is now set by
+  :ref:`Visual Studio Generators` for VS 2017 and above to report the
+  four-component Visual Studio version number.
+
+Properties
+----------
+
+* The :prop_tgt:`<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR` target property was
+  added to allow the ``clang-tidy`` tool to export its suggested fixes to a
+  set of ``.yaml`` files. A new
+  :variable:`CMAKE_<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR` variable was created to
+  initialize this property.
+
+* The :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS <XCODE_EMBED_<type>>`
+  target property was added to tell the :generator:`Xcode` generator to
+  ExtensionKit-based extensions such as extensions using the Background
+  Assets framework.  Aspects of the embedding can be customized with:
+
+  * :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS_PATH <XCODE_EMBED_<type>>`
+  * :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS_CODE_SIGN_ON_COPY <XCODE_EMBED_<type>_CODE_SIGN_ON_COPY>`
+  * :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS_REMOVE_HEADERS_ON_COPY <XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY>`
+
+Modules
+-------
+
+* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
+  gained an ``INSTALL_BYPRODUCTS`` option to specify files generated by the
+  ``install`` step.
+
+* The :module:`FindCUDAToolkit` module:
+
+  * gained support for the ``sbsa-linux`` cross compilation target, and
+
+  * now provides an imported target for ``nvrtc_static``, if found.
+
+* The :module:`FindImageMagick` module now provides imported targets.
+
+* The :module:`FindPython3` and :module:`FindPython` modules gained
+  support for the `Stable Application Binary Interface`_.
+
+* The :module:`UseSWIG` module gained the support for the ``perl5`` language.
+
+.. _`Stable Application Binary Interface`: https://docs.python.org/3/c-api/stable.html
+
+Generator Expressions
+---------------------
+
+* The :genex:`$<BUILD_LOCAL_INTERFACE:...>` generator expression was added to
+  prevent usage requirements from being exported to dependent projects.
+
+CTest
+-----
+
+* The :envvar:`CTEST_NO_TESTS_ACTION` environment variable was added to
+  provide a default value for the
+  :option:`--no-tests=\<action\> <ctest --no-tests>` command line
+  argument of :manual:`ctest(1)`.
+
+Deprecated and Removed Features
+===============================
+
+* The ``CMakeFiles/CMakeOutput.log`` and ``CMakeFiles/CMakeError.log``
+  files are no longer populated by CMake's builtin modules, and
+  :manual:`cmake(1)` no longer suggests looking at them after a
+  ``CMake Error`` occurs.  Information previously logged to those
+  files is instead logged to ``CMakeFiles/CMakeConfigureLog.yaml``,
+  the :manual:`cmake-configure-log(7)`.
+
+* On CYGWIN, the undocumented ``CMAKE_LEGACY_CYGWIN_WIN32`` mode for
+  compatibility with CMake versions older than 2.8.4 has been removed.
+
+Other Changes
+=============
+
+* :ref:`Language Standard Flags`, such as ``-std=c++11``, when generated due
+  to :command:`target_compile_features` or :variable:`CMAKE_<LANG>_STANDARD`,
+  are now placed before flags added by :command:`target_compile_options`,
+  rather than after them.
+
+* For all ``COMPILE_DEFINITIONS`` properties, any leading ``-D`` on an item
+  is removed whether or not it was specified by a generator expression.
+
+* The ``compile_commands.json`` database enabled by
+  :variable:`CMAKE_EXPORT_COMPILE_COMMANDS` now provides the ``output``
+  field in the compile commands objects.  This allows multi-config
+  generators, such as the :generator:`Ninja Multi-Config` generator,
+  to provide the compile commands for all configurations.
+
+* The :prop_gbl:`USE_FOLDERS` global property is treated as ``ON`` by default.
+  See policy :policy:`CMP0143`.
+
+* The top-level :command:`project` call will now emit an author warning if the
+  documented command order in relation to :command:`cmake_minimum_required` is
+  not respected.
+
+* The :option:`cmake --trace` option now follows :command:`try_compile` and
+  :command:`try_run` invocations.

Help/release/dev/COMPILE_DEFINITIONS-property-cleanup.rst

@@ -1,6 +0,0 @@
-COMPILE_DEFINITIONS-property-cleanup
-------------------------------------
-
-* For all ``COMPILE_DEFINITIONS`` properties, any leading ``-D`` on an item
-  will be removed regardless how to was defined: as is or inside a generator
-  expression.

Help/release/dev/ExternalProject-INSTALL_BYPRODUCTS.rst

@@ -1,6 +0,0 @@
-ExternalProject-INSTALL_BYPRODUCTS
-----------------------------------
-
-* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
-  gained an ``INSTALL_BYPRODUCTS`` option to specify files generated by the
-  "install" step.

Help/release/dev/FindCUDAToolkit-arm64-sbsa.rst

@@ -1,4 +0,0 @@
-FindCUDAToolkit-arm64-sbsa
---------------------------
-
-* The :module:`FindCUDAToolkit` gained support for the `sbsa-linux` cross compilation target

Help/release/dev/FindCUDAToolkit-nvrtc.rst

@@ -1,5 +0,0 @@
-FindCUDAToolkit-nvrtc
----------------------
-
-* The :module:`FindCUDAToolkit` module now provides a target for
-  ``libnvrtc_static``, if found.

Help/release/dev/FindPython-Stable-ABI.rst

@@ -1,6 +0,0 @@
-FindPython-Stable-ABI
----------------------
-
-* The :module:`FindPython3` and :module:`FindPython` modules gain the support
-  of the
-  `Stable Application Binary Interface <https://docs.python.org/3/c-api/stable.html>`_.

Help/release/dev/UseSWIG-perl5.rst

@@ -1,4 +0,0 @@
-UseSWIG-perl5
--------------
-
-* The :module:`UseSWIG` module gained the support of ``perl5`` language.

Help/release/dev/build-local-interface-genex.rst

@@ -1,5 +0,0 @@
-build-local-interface-genex
----------------------------
-
-* The :genex:`BUILD_LOCAL_INTERFACE` generator expression was added to
-  prevent usage requirements from being exported to dependent projects.

Help/release/dev/clang-tidy-export-fixes-dir.rst

@@ -1,8 +0,0 @@
-clang-tidy-export-fixes-dir
----------------------------
-
-* A new :prop_tgt:`<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR` target property was
-  created to allow the ``clang-tidy`` tool to export its suggested fixes to a
-  set of ``.yaml`` files. A new
-  :variable:`CMAKE_<LANG>_CLANG_TIDY_EXPORT_FIXES_DIR` variable was created to
-  initialize this property.

Help/release/dev/cmake-E-copy-directory-if-different.rst

@@ -1,4 +0,0 @@
-cmake-E-copy-directory-if-different
------------------------------------
-
-* The :manual:`cmake(1)` ``-E`` option learned a new ``copy_directory_if_different`` command.

Help/release/dev/cmake-E-copy-t-arg.rst

@@ -1,4 +0,0 @@
-cmake-E-copy-t-arg
-------------------
-
-* The :option:`cmake -E copy <cmake-E copy>` argument now supports a ``-t`` argument.

Help/release/dev/compile-commands-output-field.rst

@@ -1,7 +0,0 @@
-compile-commands-output-field
------------------------------
-
-* The :prop_tgt:`EXPORT_COMPILE_COMMANDS` target property will now have the
-  ``output`` field in the compile commands objects. This allows multi-config
-  generators (namely :generator:`Ninja Multi-Config` generator) to contain the
-  compile commands for all configurations.

Help/release/dev/configure-log.rst

@@ -1,19 +0,0 @@
-Configure Log
--------------
-
-* CMake now writes a YAML log of configure-time checks.
-  See the :manual:`cmake-configure-log(7)` manual.
-
-* The :manual:`cmake-file-api(7)` gained a new "configureLog" object kind
-  that enables stable access to the :manual:`cmake-configure-log(7)`.
-
-* The :command:`message` command gained a ``CONFIGURE_LOG`` mode to
-  record an entry in the :manual:`cmake-configure-log(7)`.
-
-* The :command:`try_compile` and :command:`try_run` commands gained
-  a ``LOG_DESCRIPTION`` option specifying text to be recorded in the
-  :manual:`cmake-configure-log(7)`.
-
-* The :command:`try_compile` and :command:`try_run` commands gained a
-  ``NO_LOG`` option to skip recording a :manual:`cmake-configure-log(7)`
-  entry.

Help/release/dev/ctest-no-tests-action-env-var.rst

@@ -1,7 +0,0 @@
-ctest-no-tests-action-env-var
------------------------------
-
-* The :envvar:`CTEST_NO_TESTS_ACTION` environment variable was added to
-  provide a default value for the
-  :option:`--no-tests=\<action\> <ctest --no-tests>` command line
-  argument of :manual:`ctest(1)`.

Help/release/dev/custom-command-comment-genex.rst

@@ -1,6 +0,0 @@
-custom-command-comment-genex
-----------------------------
-
-* :command:`add_custom_command` and :command:`add_custom_target` now
-  support :manual:`generator expressions <cmake-generator-expressions(7)>`
-  in their ``COMMENT`` option.

Help/release/dev/cxx-scanning-properties.rst

@@ -1,5 +0,0 @@
-cxx-scanning-properties
------------------------
-
-* The :prop_tgt:`CXX_SCAN_FOR_MODULES` target and source file properties may
-  be used to enable or disable scanning for C++ module dependencies.

Help/release/dev/cygwin-no-legacy-win32.rst

@@ -1,5 +0,0 @@
-cygwin-no-legacy-win32
-----------------------
-
-* On CYGWIN, the undocumented ``CMAKE_LEGACY_CYGWIN_WIN32`` mode for
-  compatibility with CMake versions older than 2.8.4 has been removed.

Help/release/dev/file-api-file-sets.rst

@@ -1,9 +0,0 @@
-file-api-file-sets
-------------------
-
-* The :manual:`cmake-file-api(7)` "codemodel" version 2 ``version`` field has
-  been updated to 2.5.
-
-* The :manual:`cmake-file-api(7)` "codemodel" version 2 "target" object
-  gained a new ``fileSets`` field and associated ``fileSetIndex``
-  field to ``sources`` objects.

Help/release/dev/frontend-variant-always.rst

@@ -1,6 +0,0 @@
-frontend-variant-always
------------------------
-
-* The :variable:`CMAKE_<LANG>_COMPILER_FRONTEND_VARIANT` variable is now
-  set for ``GNU``, ``MSVC``, and ``AppleClang`` compilers that have only
-  one frontend variant.

Help/release/dev/lang-std-flag-order.rst

@@ -1,7 +0,0 @@
-lang-std-flag-order
--------------------
-
-* :ref:`Language Standard Flags`, such as ``-std=c++11``, when generated due
-  to :command:`target_compile_features` or :variable:`CMAKE_<LANG>_STANDARD`,
-  are now placed before flags added by :command:`target_compile_options`,
-  rather than after them.

Help/release/dev/marmasm-language.rst

@@ -1,4 +0,0 @@
-marmasm-language
-----------------
-
-* The ``ASM_MARMASM`` language was added to support the Microsoft ARM assembler language.

Help/release/dev/timestamp-timezone.rst

@@ -1,5 +0,0 @@
-timestamp-timezone
-------------------
-
-* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` commands
-  now support the ``%z`` and ``%Z`` specifiers for the time zone.

Help/release/dev/top-level-command-order.rst

@@ -1,6 +0,0 @@
-top-level-command-order
------------------------
-
-* The top-level :command:`project` call will now emit an author warning if the
-  documented command order in relation to :command:`cmake_minimum_required` is
-  not respected.

Help/release/dev/trace-try_compile.rst

@@ -1,5 +0,0 @@
-trace-try_compile
------------------
-
-* The :option:`cmake --trace` option now follows :command:`try_compile` and
-  :command:`try_run` invocations.

Help/release/dev/use-folder-on-by-default.rst

@@ -1,5 +0,0 @@
-use-folder-on-by-default
-------------------------
-
-* Global property :prop_gbl:`USE_FOLDERS` is treated as ``ON`` by default.
-  See policy :policy:`CMP0143`.

Help/release/dev/vs-version-var.rst

@@ -1,6 +0,0 @@
-vs-version-var
---------------
-
-* A :variable:`CMAKE_VS_VERSION_BUILD_NUMBER` variable is now set by
-  :ref:`Visual Studio Generators` for VS 2017 and above to report the
-  four-component Visual Studio version number.

Help/release/dev/xcode-ios-extensionkit.rst

@@ -1,11 +0,0 @@
-xcode-ios-extensionkit
-----------------------
-
-* The :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS <XCODE_EMBED_<type>>` target property
-  was added to tell the :generator:`Xcode` generator to ExtensionKit-based extensions
-  such as extensions using the Background Assets framework.
-  Aspects of the embedding can be customized with the
-  :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS_PATH <XCODE_EMBED_<type>>`,
-  :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS_CODE_SIGN_ON_COPY <XCODE_EMBED_<type>_CODE_SIGN_ON_COPY>` and
-  :prop_tgt:`XCODE_EMBED_EXTENSIONKIT_EXTENSIONS_REMOVE_HEADERS_ON_COPY <XCODE_EMBED_<type>_REMOVE_HEADERS_ON_COPY>`
-  properties.

Help/release/index.rst

@@ -15,6 +15,7 @@ Releases
 .. toctree::
    :maxdepth: 1
 
+   3.26 <3.26>
    3.25 <3.25>
    3.24 <3.24>
    3.23 <3.23>

Help/variable/CMAKE_CXX_SCAN_FOR_MODULES.rst

@@ -8,3 +8,8 @@ Whether to scan C++ source files for module dependencies.
 This variable is used to initialize the :prop_tgt:`CXX_SCAN_FOR_MODULES`
 property on all the targets.  See that target property for additional
 information.
+
+.. note ::
+
+  This setting is meaningful only when experimental support for C++ modules
+  has been enabled by the ``CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API`` gate.

Modules/FindImageMagick.cmake

@@ -96,19 +96,13 @@ Result Variables
   Full path to <component> libraries.
 
 
-Example Usages:
-^^^^^^^^^^^^^^^
+Example Usage
+^^^^^^^^^^^^^
 
-  find_package(ImageMagick)
-  find_package(ImageMagick COMPONENTS convert)
-  find_package(ImageMagick COMPONENTS convert mogrify display)
-  find_package(ImageMagick COMPONENTS Magick++)
-  find_package(ImageMagick COMPONENTS Magick++ convert)
+.. code-block:: cmake
 
+  find_package(ImageMagick COMPONENTS Magick++)
   target_link_libraries(example PRIVATE ImageMagick::Magick++)
-
-Note that the standard :command:`find_package` features are supported (i.e.,
-``QUIET``, ``REQUIRED``, etc.).
 #]=======================================================================]
 
 find_package(PkgConfig QUIET)