Merge topic 'export-EXPORT-subcommand'

98b9f52 Help: Document export(EXPORT) in the cmake-packages manual.
a1d2bda Don't copy find_dependency in configure_package_config_file.
f4f6529 Help: cmake-packages: Add missing slash.
cbe7e8f export: Implement EXPORT subcommand (#9822)

2 files changed, 43 insertions, 15 deletions

diff --git a/Help/command/export.rst b/Help/command/export.rst
index c293340..6b83587 100644
--- a/Help/command/export.rst
+++ b/Help/command/export.rst
@@ -5,8 +5,7 @@ Export targets from the build tree for use by outside projects.
 
 ::
 
-  export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
-         [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
+  export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
 
 Create a file <filename> that may be included by outside projects to
 import targets from the current project's build tree.  This is useful
@@ -14,14 +13,10 @@ during cross-compiling to build utility executables that can run on
 the host platform in one project and then import them into another
 project being compiled for the target platform.  If the NAMESPACE
 option is given the <namespace> string will be prepended to all target
-names written to the file.  If the APPEND option is given the
-generated code will be appended to the file instead of overwriting it.
-The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the
-contents of the properties matching
-``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when
-policy CMP0022 is NEW.  If a library target is included in the export
-but a target to which it links is not included the behavior is
-unspecified.
+names written to the file.
+
+Target installations are associated with the export <export-name>
+using the ``EXPORT`` option of the :command:`install(TARGETS)` command.
 
 The file created by this command is specific to the build tree and
 should never be installed.  See the install(EXPORT) command to export
@@ -32,6 +27,21 @@ same values as the final values of the input TARGETS.
 
 ::
 
+  export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
+         [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
+
+This signature is similar to the ``EXPORT`` signature, but targets are listed
+explicitly rather than specified as an export-name.  If the APPEND option is
+given the generated code will be appended to the file instead of overwriting it.
+The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the
+contents of the properties matching
+``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when
+policy CMP0022 is NEW.  If a library target is included in the export
+but a target to which it links is not included the behavior is
+unspecified.
+
+::
+
   export(PACKAGE <name>)
 
 Store the current build directory in the CMake user package registry
diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst
index 952da3c..dc301ba 100644
--- a/Help/manual/cmake-packages.7.rst
+++ b/Help/manual/cmake-packages.7.rst
@@ -266,6 +266,7 @@ shared library:
   project(UpstreamLib)
 
   set(CMAKE_INCLUDE_CURRENT_DIR ON)
+  set(CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE ON)
 
   set(Upstream_VERSION 3.4.1)
 
@@ -292,11 +293,20 @@ shared library:
 
   include(CMakePackageConfigHelpers)
   write_basic_package_version_file(
-    "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStatsConfigVersion.cmake"
+    "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
     VERSION ${Upstream_VERSION}
     COMPATIBILITY AnyNewerVersion
   )
 
+  export(EXPORT ClimbingStatsTargets
+    FILE "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsTargets.cmake"
+    NAMESPACE Upstream::
+  )
+  configure_file(cmake/ClimbingStatsConfig.cmake
+    "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfig.cmake"
+    COPY_ONLY
+  )
+
   set(ConfigPackageLocation lib/cmake/ClimbingStats)
   install(EXPORT ClimbingStatsTargets
     FILE
@@ -309,7 +319,7 @@ shared library:
   install(
     FILES
       cmake/ClimbingStatsConfig.cmake
-      "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStatsConfigVersion.cmake"
+      "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
     DESTINATION
       ${ConfigPackageLocation}
     COMPONENT
@@ -354,6 +364,14 @@ should be provided by the ``ClimbingStats`` package, they should
 be in a separate file which is installed to the same location as the
 ``ClimbingStatsConfig.cmake`` file, and included from there.
 
+The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets
+definition file which is specific to the build-tree.  This can similiarly be
+used with a suitable package configuration file and package version file to
+define a package for the build tree which may be used without installation.
+Consumers of the build tree can simply ensure that the
+:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the
+``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache.
+
 This can also be extended to cover dependencies:
 
 .. code-block:: cmake
@@ -375,7 +393,7 @@ dependencies of a package should be found in the ``Config.cmake`` file:
 
 .. code-block:: cmake
 
-  include(CMakePackageConfigHelpers)
+  include(CMakeFindDependencyMacro)
   find_dependency(Stats 2.6.4)
 
   include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
@@ -392,7 +410,7 @@ be true. This can be tested with logic in the package configuration file:
 
 .. code-block:: cmake
 
-  include(CMakePackageConfigHelpers)
+  include(CMakeFindDependencyMacro)
   find_dependency(Stats 2.6.4)
 
   include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
@@ -405,7 +423,7 @@ be true. This can be tested with logic in the package configuration file:
       set(ClimbingStats_FOUND False)
       set(ClimbingStats_NOTFOUND_MESSAGE "Specified unsupported component: ${_comp}")
     endif()
-    include("${CMAKE_CURRENT_LIST_DIR}ClimbingStats${_comp}Targets.cmake")
+    include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStats${_comp}Targets.cmake")
   endforeach()
 
 Here, the ``ClimbingStats_NOTFOUND_MESSAGE`` is set to a diagnosis that the package