Merge topic 'export-find_dependency-calls'

3a739d4dcb EXPORT_PACKAGE_DEPENDENCIES: Add experimental feature gate

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: buildbot <buildbot@kitware.com>
Merge-request: !9336

6 files changed, 44 insertions, 21 deletions

diff --git a/Help/command/export.rst b/Help/command/export.rst
index f190df7..349522e 100644
--- a/Help/command/export.rst
+++ b/Help/command/export.rst
@@ -120,7 +120,9 @@ associated with the export ``<export-name>`` using the ``EXPORT`` option
 of the :command:`install(TARGETS)` command.
 
 ``EXPORT_PACKAGE_DEPENDENCIES``
-  .. versionadded:: 3.29
+  .. note::
+
+    Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES``.
 
   Specify that :command:`find_dependency` calls should be exported. See
   :command:`install(EXPORT)` for details on how this works.
@@ -180,6 +182,10 @@ Configuring Exports
 Configure the parameters of an export. The arguments are as follows:
 
 ``PACKAGE_DEPENDENCY <dep>``
+  .. note::
+
+    Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES``.
+
   Specify a package dependency to configure. This changes how
   :command:`find_dependency` calls are written during
   :command:`export(EXPORT)` and :command:`install(EXPORT)`. ``<dep>`` is the
diff --git a/Help/command/install.rst b/Help/command/install.rst
index 674b770..6da077e 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -853,7 +853,9 @@ Signatures
     targets in the export set will support being imported in consuming targets.
 
   ``EXPORT_PACKAGE_DEPENDENCIES``
-    .. versionadded:: 3.29
+    .. note::
+
+      Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES``.
 
     Specify that :command:`find_dependency` calls should be exported. If this
     argument is specified, CMake examines all targets in the export set and
diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst
index 87ac031..fc4ac8b 100644
--- a/Help/dev/experimental.rst
+++ b/Help/dev/experimental.rst
@@ -13,3 +13,28 @@ specific values will change over time to reinforce their experimental nature.
 When used, a warning will be generated to indicate that an experimental
 feature is in use and that the affected behavior in the project is not part of
 CMake's stability guarantees.
+
+Export Package Dependencies
+===========================
+
+In order to activate support for this experimental feature, set
+
+* variable ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES`` to
+* value ``1942b4fa-b2c5-4546-9385-83f254070067``.
+
+This UUID may change in future versions of CMake.  Be sure to use the value
+documented here by the source tree of the version of CMake with which you are
+experimenting.
+
+When activated, this experimental feature provides the following:
+
+* The ``install(EXPORT)`` and ``export(EXPORT)`` commands have experimental
+  ``EXPORT_PACKAGE_DEPENDENCIES`` arguments to generate ``find_dependency``
+  calls automatically.
+
+* Details of the calls may be configured using the ``export(SETUP)``
+  command's ``PACKAGE_DEPENDENCY`` argument.
+
+* The package name associated with specific targets may be specified
+  using the ``CMAKE_EXPORT_FIND_PACKAGE_NAME`` variable and/or
+``EXPORT_FIND_PACKAGE_NAME`` target property.
diff --git a/Help/prop_tgt/EXPORT_FIND_PACKAGE_NAME.rst b/Help/prop_tgt/EXPORT_FIND_PACKAGE_NAME.rst
index b49f005..b7405d6 100644
--- a/Help/prop_tgt/EXPORT_FIND_PACKAGE_NAME.rst
+++ b/Help/prop_tgt/EXPORT_FIND_PACKAGE_NAME.rst
@@ -1,7 +1,9 @@
 EXPORT_FIND_PACKAGE_NAME
 ------------------------
 
-.. versionadded:: 3.29
+.. note::
+
+  Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES``.
 
 Control the package name associated with a dependency target when exporting a
 :command:`find_dependency` call in :command:`install(EXPORT)` or
diff --git a/Help/release/3.29.rst b/Help/release/3.29.rst
index 42f6491..f6d829d 100644
--- a/Help/release/3.29.rst
+++ b/Help/release/3.29.rst
@@ -57,19 +57,13 @@ Commands
   :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.
+  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
 ---------
 
@@ -110,11 +104,6 @@ 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.
 
@@ -185,9 +174,6 @@ Other Changes
   :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
diff --git a/Help/variable/CMAKE_EXPORT_FIND_PACKAGE_NAME.rst b/Help/variable/CMAKE_EXPORT_FIND_PACKAGE_NAME.rst
index b6c8b76..dbab579 100644
--- a/Help/variable/CMAKE_EXPORT_FIND_PACKAGE_NAME.rst
+++ b/Help/variable/CMAKE_EXPORT_FIND_PACKAGE_NAME.rst
@@ -1,6 +1,8 @@
 CMAKE_EXPORT_FIND_PACKAGE_NAME
 ------------------------------
 
-.. versionadded:: 3.29
+.. note::
+
+  Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES``.
 
 Initializes the value of :prop_tgt:`EXPORT_FIND_PACKAGE_NAME`.