install(EXPORT): Export find_dependency() calls

Issue: #20511
Co-Authored-by: Brad King <brad.king@kitware.com>
Co-Authored-by: Robert Maynard <rmaynard@nvidia.com>

Help/command/export.rst

@@ -15,6 +15,7 @@ Synopsis
   export(`TARGETS`_ <target>... [...])
   export(`EXPORT`_ <export-name> [...])
   export(`PACKAGE`_ <PackageName>)
+  export(`SETUP`_ <export-name> [...])
 
 Exporting Targets
 ^^^^^^^^^^^^^^^^^
@@ -108,7 +109,7 @@ Exporting Targets matching install(EXPORT)
 .. code-block:: cmake
 
   export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]
-         [CXX_MODULES_DIRECTORY <directory>])
+         [CXX_MODULES_DIRECTORY <directory>] [EXPORT_PACKAGE_DEPENDENCIES])
 
 Creates a file ``<filename>`` that may be included by outside projects to
 import targets from the current project's build tree.  This is the same
@@ -118,6 +119,12 @@ the installation export ``<export-name>``.  Target installations may be
 associated with the export ``<export-name>`` using the ``EXPORT`` option
 of the :command:`install(TARGETS)` command.
 
+``EXPORT_PACKAGE_DEPENDENCIES``
+  .. versionadded:: 3.29
+
+  Specify that :command:`find_dependency` calls should be exported. See
+  :command:`install(EXPORT)` for details on how this works.
+
 Exporting Packages
 ^^^^^^^^^^^^^^^^^^
 
@@ -149,3 +156,49 @@ registry.
   outside the source and build trees.  Set the
   :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable to add build directories
   to the CMake user package registry.
+
+Configuring Exports
+^^^^^^^^^^^^^^^^^^^
+
+.. signature::
+  export(SETUP <export-name> [...])
+
+.. code-block:: cmake
+
+  export(SETUP <export-name>
+         [PACKAGE_DEPENDENCY <dep>
+          [ENABLED (<bool-true>|<bool-false>|AUTO)]
+          [EXTRA_ARGS <args>...]
+         ] [...]
+         )
+
+.. versionadded:: 3.29
+
+Configure the parameters of an export. The arguments are as follows:
+
+``PACKAGE_DEPENDENCY <dep>``
+  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
+  name of a package to export. This argument accepts the following additional
+  arguments:
+
+  ``ENABLED``
+    Manually control whether or not the dependency is exported. This accepts
+    the following values:
+
+    ``<bool-true>``
+      Any value that CMake recognizes as "true". Always export the dependency,
+      even if no exported targets depend on it. This can be used to manually
+      add :command:`find_dependency` calls to the export.
+
+    ``<bool-false>``
+      Any value that CMake recognizes as "false". Never export the dependency,
+      even if an exported target depends on it.
+
+    ``AUTO``
+      Only export the dependency if an exported target depends on it.
+
+  ``EXTRA_ARGS <args>``
+    Specify additional arguments to pass to :command:`find_dependency` after
+    the ``REQUIRED`` argument.

Help/command/install.rst

@@ -784,7 +784,8 @@ Signatures
             [CXX_MODULES_DIRECTORY <directory>]
             [EXPORT_LINK_INTERFACE_LIBRARIES]
             [COMPONENT <component>]
-            [EXCLUDE_FROM_ALL])
+            [EXCLUDE_FROM_ALL]
+            [EXPORT_PACKAGE_DEPENDENCIES])
     install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
 
   The ``EXPORT`` form generates and installs a CMake file containing code to
@@ -848,6 +849,34 @@ Signatures
     without this information, none of the C++ modules which are part of the
     targets in the export set will support being imported in consuming targets.
 
+  ``EXPORT_PACKAGE_DEPENDENCIES``
+    .. versionadded:: 3.29
+
+    Specify that :command:`find_dependency` calls should be exported. If this
+    argument is specified, CMake examines all targets in the export set and
+    gathers their ``INTERFACE`` link targets. If any such targets either were
+    found with :command:`find_package` or have the
+    :prop_tgt:`EXPORT_FIND_PACKAGE_NAME` property set, and such package
+    dependency was not disabled by passing ``ENABLED OFF`` to
+    :command:`export(SETUP)`, then a :command:`find_dependency` call is
+    written with the target's corresponding package name, a ``REQUIRED``
+    argument, and any additional arguments specified by the ``EXTRA_ARGS``
+    argument of :command:`export(SETUP)`. Any package dependencies that were
+    manually specified by passing ``ENABLED ON`` to :command:`export(SETUP)`
+    are also added, even if the exported targets don't depend on any targets
+    from them.
+
+    The :command:`find_dependency` calls are written in the following order:
+
+    1. Any package dependencies that were listed in :command:`export(SETUP)`
+       are written in the order they were first specified, regardless of
+       whether or not they contain ``INTERFACE`` dependencies of the
+       exported targets.
+    2. Any package dependencies that contain ``INTERFACE`` link dependencies
+       of the exported targets and that were never specified in
+       :command:`export(SETUP)` are written in the order they were first
+       found.
+
   The ``EXPORT`` form is useful to help outside projects use targets built
   and installed by the current project.  For example, the code