EXPORT_PACKAGE_DEPENDENCIES: Add experimental feature gate

Some design concerns have been raised after trying the 3.29 release
candidates.  Avoid committing to a stable public interface for now.

Issue: #25767

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

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

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.

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

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

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`.

Source/cmExperimental.cxx

@@ -19,6 +19,15 @@ namespace {
  * up-to-date.
  */
 cmExperimental::FeatureData LookupTable[] = {
+  // ExportPackageDependencies
+  { "ExportPackageDependencies",
+    "1942b4fa-b2c5-4546-9385-83f254070067",
+    "CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES",
+    "CMake's EXPORT_PACKAGE_DEPENDENCIES support is experimental. It is meant "
+    "only for experimentation and feedback to CMake developers.",
+    {},
+    cmExperimental::TryCompileCondition::Always,
+    false },
   // WindowsKernelModeDriver
   { "WindowsKernelModeDriver",
     "5c2d848d-4efa-4529-a768-efd57171bf68",

Source/cmExperimental.h

@@ -15,6 +15,7 @@ class cmExperimental
 public:
   enum class Feature
   {
+    ExportPackageDependencies,
     WindowsKernelModeDriver,
 
     Sentinel,

Source/cmExportCommand.cxx

@@ -17,6 +17,7 @@
 #include "cmArgumentParserTypes.h"
 #include "cmCryptoHash.h"
 #include "cmExecutionStatus.h"
+#include "cmExperimental.h"
 #include "cmExportBuildAndroidMKGenerator.h"
 #include "cmExportBuildFileGenerator.h"
 #include "cmExportSet.h"
@@ -83,12 +84,20 @@ bool cmExportCommand(std::vector<std::string> const& args,
       .Bind("CXX_MODULES_DIRECTORY"_s, &Arguments::CxxModulesDirectory);
 
   if (args[0] == "EXPORT") {
-    parser.Bind("EXPORT"_s, &Arguments::ExportSetName)
-      .Bind("EXPORT_PACKAGE_DEPENDENCIES"_s,
-            &Arguments::ExportPackageDependencies);
+    parser.Bind("EXPORT"_s, &Arguments::ExportSetName);
+    if (cmExperimental::HasSupportEnabled(
+          status.GetMakefile(),
+          cmExperimental::Feature::ExportPackageDependencies)) {
+      parser.Bind("EXPORT_PACKAGE_DEPENDENCIES"_s,
+                  &Arguments::ExportPackageDependencies);
+    }
   } else if (args[0] == "SETUP") {
     parser.Bind("SETUP"_s, &Arguments::ExportSetName);
-    parser.Bind("PACKAGE_DEPENDENCY"_s, &Arguments::PackageDependencyArgs);
+    if (cmExperimental::HasSupportEnabled(
+          status.GetMakefile(),
+          cmExperimental::Feature::ExportPackageDependencies)) {
+      parser.Bind("PACKAGE_DEPENDENCY"_s, &Arguments::PackageDependencyArgs);
+    }
     parser.Bind("TARGET"_s, &Arguments::TargetArgs);
   } else {
     parser.Bind("TARGETS"_s, &Arguments::Targets);

Source/cmInstallCommand.cxx

@@ -21,6 +21,7 @@
 #include "cmArgumentParser.h"
 #include "cmArgumentParserTypes.h"
 #include "cmExecutionStatus.h"
+#include "cmExperimental.h"
 #include "cmExportSet.h"
 #include "cmFileSet.h"
 #include "cmGeneratorExpression.h"
@@ -2061,7 +2062,12 @@ bool HandleExportMode(std::vector<std::string> const& args,
   ica.Bind("EXPORT_LINK_INTERFACE_LIBRARIES"_s, exportOld);
   ica.Bind("FILE"_s, filename);
   ica.Bind("CXX_MODULES_DIRECTORY"_s, cxx_modules_directory);
-  ica.Bind("EXPORT_PACKAGE_DEPENDENCIES"_s, exportPackageDependencies);
+
+  if (cmExperimental::HasSupportEnabled(
+        status.GetMakefile(),
+        cmExperimental::Feature::ExportPackageDependencies)) {
+    ica.Bind("EXPORT_PACKAGE_DEPENDENCIES"_s, exportPackageDependencies);
+  }
 
   std::vector<std::string> unknownArgs;
   ica.Parse(args, &unknownArgs);

Tests/ExportImport/Export/CMakeLists.txt

@@ -1,3 +1,4 @@
+set(CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES "1942b4fa-b2c5-4546-9385-83f254070067")
 cmake_minimum_required (VERSION 2.7.20090711)
 if(POLICY CMP0129)
   cmake_policy(SET CMP0129 NEW)

Tests/RunCMake/export/FindDependencyExport-stderr.txt

@@ -0,0 +1,6 @@
+^CMake Warning \(dev\) at FindDependencyExport\.cmake:[0-9]+ \(export\):
+  CMake's EXPORT_PACKAGE_DEPENDENCIES support is experimental\.  It is meant
+  only for experimentation and feedback to CMake developers\.
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)
+This warning is for project developers\.  Use -Wno-dev to suppress it\.$

Tests/RunCMake/export/FindDependencyExport.cmake

@@ -1,3 +1,4 @@
+set(CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES "1942b4fa-b2c5-4546-9385-83f254070067")
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/CMake)
 
 find_package(P1)

Tests/RunCMake/export/FindDependencyExportFetchContent-stderr.txt

@@ -0,0 +1,6 @@
+^CMake Warning \(dev\) at FindDependencyExportFetchContent\.cmake:[0-9]+ \(install\):
+  CMake's EXPORT_PACKAGE_DEPENDENCIES support is experimental\.  It is meant
+  only for experimentation and feedback to CMake developers\.
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)
+This warning is for project developers\.  Use -Wno-dev to suppress it\.$

Tests/RunCMake/export/FindDependencyExportFetchContent.cmake

@@ -1,3 +1,4 @@
+set(CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES "1942b4fa-b2c5-4546-9385-83f254070067")
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/CMake)
 
 enable_language(CXX)

Tests/RunCMake/export/FindDependencyExportGate-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/export/FindDependencyExportGate-stderr.txt

@@ -0,0 +1,4 @@
+^CMake Error at FindDependencyExportGate\.cmake:[0-9]+ \(export\):
+  export Unknown argument: "EXPORT_PACKAGE_DEPENDENCIES"\.
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)$

Tests/RunCMake/export/FindDependencyExportGate.cmake

@@ -0,0 +1 @@
+export(EXPORT mytargets EXPORT_PACKAGE_DEPENDENCIES)

Tests/RunCMake/export/FindDependencyExportShared-stderr.txt

@@ -0,0 +1,6 @@
+^CMake Warning \(dev\) at FindDependencyExportShared\.cmake:[0-9]+ \(export\):
+  CMake's EXPORT_PACKAGE_DEPENDENCIES support is experimental\.  It is meant
+  only for experimentation and feedback to CMake developers\.
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)
+This warning is for project developers\.  Use -Wno-dev to suppress it\.$

Tests/RunCMake/export/FindDependencyExportShared.cmake

@@ -1,3 +1,4 @@
+set(CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES "1942b4fa-b2c5-4546-9385-83f254070067")
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/CMake)
 
 enable_language(CXX)

Tests/RunCMake/export/FindDependencyExportStatic-stderr.txt

@@ -0,0 +1,6 @@
+^CMake Warning \(dev\) at FindDependencyExportStatic\.cmake:[0-9]+ \(export\):
+  CMake's EXPORT_PACKAGE_DEPENDENCIES support is experimental\.  It is meant
+  only for experimentation and feedback to CMake developers\.
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)
+This warning is for project developers\.  Use -Wno-dev to suppress it\.$

Tests/RunCMake/export/FindDependencyExportStatic.cmake

@@ -1,3 +1,4 @@
+set(CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES "1942b4fa-b2c5-4546-9385-83f254070067")
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/CMake)
 
 enable_language(CXX)

Tests/RunCMake/export/RunCMakeTest.cmake

@@ -19,6 +19,7 @@ run_cmake(UnknownExport)
 run_cmake(NamelinkOnlyExport)
 run_cmake(SeparateNamelinkExport)
 run_cmake(TryCompileExport)
+run_cmake(FindDependencyExportGate)
 run_cmake(FindDependencyExport)
 run_cmake(FindDependencyExportStatic)
 run_cmake(FindDependencyExportShared)

Tests/RunCMake/install/EXPORT-FindDependencyExport-stderr.txt

@@ -0,0 +1,6 @@
+^CMake Warning \(dev\) at EXPORT-FindDependencyExport\.cmake:[0-9]+ \(export\):
+  CMake's EXPORT_PACKAGE_DEPENDENCIES support is experimental\.  It is meant
+  only for experimentation and feedback to CMake developers\.
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)
+This warning is for project developers\.  Use -Wno-dev to suppress it\.$

Tests/RunCMake/install/EXPORT-FindDependencyExport.cmake

@@ -1,3 +1,4 @@
+set(CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_DEPENDENCIES "1942b4fa-b2c5-4546-9385-83f254070067")
 enable_language(C)
 
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake)

Tests/RunCMake/install/EXPORT-FindDependencyExportGate-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/install/EXPORT-FindDependencyExportGate-stderr.txt

@@ -0,0 +1,4 @@
+^CMake Error at EXPORT-FindDependencyExportGate\.cmake:[0-9]+ \(install\):
+  install EXPORT given unknown argument "EXPORT_PACKAGE_DEPENDENCIES"\.
+Call Stack \(most recent call first\):
+  CMakeLists\.txt:[0-9]+ \(include\)$

Tests/RunCMake/install/EXPORT-FindDependencyExportGate.cmake

@@ -0,0 +1 @@
+install(EXPORT mylib-targets EXPORT_PACKAGE_DEPENDENCIES DESTINATION lib/cmake/mylib)

Tests/RunCMake/install/RunCMakeTest.cmake

@@ -77,6 +77,7 @@ run_cmake(DIRECTORY-DESTINATION-bad)
 run_cmake(FILES-DESTINATION-bad)
 run_cmake(FILES-RENAME-bad)
 run_cmake(TARGETS-DESTINATION-bad)
+run_cmake(EXPORT-FindDependencyExportGate)
 run_cmake(EXPORT-OldIFace)
 run_cmake(EXPORT-UnknownExport)
 run_cmake(EXPORT-NamelinkOnly)