Merge topic 'ExternalProject-INSTALL_BYPRODUCTS'

8c6b2928f4 ExternalProject: Add `INSTALL_BYPRODUCTS` option
6d6baffb85 Tests: Fix ExternalLibraryWithSubstitution test
4bcfff2df3 ExternalProject: Clarify `BYPRODUCTS` docs

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

5 files changed, 75 insertions, 4 deletions

diff --git a/Auxiliary/vim/syntax/cmake.vim b/Auxiliary/vim/syntax/cmake.vim
index 9eb993a..5e936c2 100644
--- a/Auxiliary/vim/syntax/cmake.vim
+++ b/Auxiliary/vim/syntax/cmake.vim
@@ -2013,6 +2013,7 @@ syn keyword cmakeKWExternalProject contained
             \ IGNORED
             \ INACTIVITY_TIMEOUT
             \ INDEPENDENT_STEP_TARGETS
+            \ INSTALL_BYPRODUCTS
             \ INSTALL_COMMAND
             \ INSTALL_DIR
             \ JOB_POOLS
diff --git a/Help/release/dev/ExternalProject-INSTALL_BYPRODUCTS.rst b/Help/release/dev/ExternalProject-INSTALL_BYPRODUCTS.rst
new file mode 100644
index 0000000..233596f
--- /dev/null
+++ b/Help/release/dev/ExternalProject-INSTALL_BYPRODUCTS.rst
@@ -0,0 +1,6 @@
+ExternalProject-INSTALL_BYPRODUCTS
+----------------------------------
+
+* The :module:`ExternalProject` module :command:`ExternalProject_Add` command
+  gained an ``INSTALL_BYPRODUCTS`` option to specify files generated by the
+  "install" step.
diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake
index 141b185..9fecd8f 100644
--- a/Modules/ExternalProject.cmake
+++ b/Modules/ExternalProject.cmake
@@ -637,8 +637,11 @@ External Project Definition
 
       Specifies files that will be generated by the build command but which
       might or might not have their modification time updated by subsequent
-      builds. These ultimately get passed through as ``BYPRODUCTS`` to the
-      build step's own underlying call to :command:`add_custom_command`.
+      builds. This may also be required to explicitly declare dependencies
+      when using the :generator:`Ninja` generator.
+      These ultimately get passed through as ``BYPRODUCTS`` to the
+      build step's own underlying call to :command:`add_custom_command`, which
+      has additional documentation.
 
   **Install Step Options:**
     If the configure step assumed the external project uses CMake as its build
@@ -661,6 +664,17 @@ External Project Definition
       supported). Passing an empty string as the ``<cmd>`` makes the install
       step do nothing.
 
+    ``INSTALL_BYPRODUCTS <file>...``
+      .. versionadded:: 3.26
+
+      Specifies files that will be generated by the install command but which
+      might or might not have their modification time updated by subsequent
+      installs. This may also be required to explicitly declare dependencies
+      when using the :generator:`Ninja` generator.
+      These ultimately get passed through as ``BYPRODUCTS`` to the
+      install step's own underlying call to :command:`add_custom_command`, which
+      has additional documentation.
+
     .. note::
       If the :envvar:`CMAKE_INSTALL_MODE` environment variable is set when the
       main project is built, it will only have an effect if the following
@@ -943,9 +957,12 @@ control needed to implement such step-level capabilities.
     .. versionadded:: 3.2
 
     Files that will be generated by this custom step but which might or might
-    not have their modification time updated by subsequent builds. This list of
+    not have their modification time updated by subsequent builds.
+    This may also be required to explicitly declare dependencies
+    when using the :generator:`Ninja` generator. This list of
     files will ultimately be passed through as the ``BYPRODUCTS`` option to the
-    :command:`add_custom_command` used to implement the custom step internally.
+    :command:`add_custom_command` used to implement the custom step internally,
+    which has additional documentation.
 
   ``ALWAYS <bool>``
     When enabled, this option specifies that the custom step should always be
@@ -3846,6 +3863,11 @@ function(_ep_add_install_command name)
     set(always 0)
   endif()
 
+  get_property(install_byproducts
+    TARGET ${name}
+    PROPERTY _EP_INSTALL_BYPRODUCTS
+  )
+
   set(__cmdQuoted)
   foreach(__item IN LISTS cmd)
     string(APPEND __cmdQuoted " [==[${__item}]==]")
@@ -3854,6 +3876,7 @@ function(_ep_add_install_command name)
     ExternalProject_Add_Step(${name} install
       INDEPENDENT FALSE
       COMMAND ${__cmdQuoted}
+      BYPRODUCTS \${install_byproducts}
       WORKING_DIRECTORY \${binary_dir}
       DEPENDEES build
       ALWAYS \${always}
@@ -4081,6 +4104,7 @@ function(ExternalProject_Add name)
     # Install step options
     #
     INSTALL_COMMAND
+    INSTALL_BYPRODUCTS
     #
     # Test step options
     #
diff --git a/Tests/CustomCommandByproducts/CMakeLists.txt b/Tests/CustomCommandByproducts/CMakeLists.txt
index 08c897c..e391a6f 100644
--- a/Tests/CustomCommandByproducts/CMakeLists.txt
+++ b/Tests/CustomCommandByproducts/CMakeLists.txt
@@ -149,6 +149,29 @@ set_property(TARGET ExternalLibraryWithSubstitution PROPERTY IMPORTED_LOCATION
   ${binary_dir}${cfg}/${CMAKE_STATIC_LIBRARY_PREFIX}ExternalLibrary${CMAKE_STATIC_LIBRARY_SUFFIX})
 add_dependencies(ExternalLibraryWithSubstitution ExtTargetSubst)
 
+# Generate the library file of an imported target as an install byproduct
+# of an external project. The byproduct uses <INSTALL_DIR> that is substituted
+# by the real install path
+if(_isMultiConfig)
+  set(cfg /${CMAKE_CFG_INTDIR})
+else()
+  set(cfg)
+endif()
+include(ExternalProject)
+ExternalProject_Add(ExtTargetInstallSubst
+  SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/External"
+  DOWNLOAD_COMMAND ""
+  INSTALL_COMMAND
+    "${CMAKE_COMMAND}" -E copy_directory "<BINARY_DIR>${cfg}" "<INSTALL_DIR>${cfg}"
+  BUILD_BYPRODUCTS "<BINARY_DIR>${cfg}/${CMAKE_STATIC_LIBRARY_PREFIX}ExternalLibrary${CMAKE_STATIC_LIBRARY_SUFFIX}"
+  INSTALL_BYPRODUCTS "<INSTALL_DIR>${cfg}/${CMAKE_STATIC_LIBRARY_PREFIX}ExternalLibrary${CMAKE_STATIC_LIBRARY_SUFFIX}"
+  )
+ExternalProject_Get_Property(ExtTargetInstallSubst install_dir)
+add_library(ExternalLibraryWithInstallDirSubstitution STATIC IMPORTED)
+set_property(TARGET ExternalLibraryWithInstallDirSubstitution PROPERTY IMPORTED_LOCATION
+  ${install_dir}${cfg}/${CMAKE_STATIC_LIBRARY_PREFIX}ExternalLibrary${CMAKE_STATIC_LIBRARY_SUFFIX})
+add_dependencies(ExternalLibraryWithInstallDirSubstitution ExtTargetInstallSubst)
+
 # Add an executable consuming all the byproducts.
 add_executable(CustomCommandByproducts
   CustomCommandByproducts.c
@@ -169,6 +192,18 @@ add_dependencies(CustomCommandByproducts Producer2)
 
 target_link_libraries(CustomCommandByproducts ExternalLibrary)
 
+add_executable(ExternalLibraryByproducts ExternalLibraryByproducts.c)
+target_link_libraries(ExternalLibraryByproducts ExternalLibrary)
+
+add_executable(ExternalLibraryByproducts_WithSubstitution ExternalLibraryByproducts.c)
+target_link_libraries(ExternalLibraryByproducts_WithSubstitution ExternalLibraryWithSubstitution)
+
+add_executable(ExternalLibraryByproducts_WithInstallDirSubstitution ExternalLibraryByproducts.c)
+target_link_libraries(
+  ExternalLibraryByproducts_WithInstallDirSubstitution
+  ExternalLibraryWithInstallDirSubstitution
+)
+
 if(CMAKE_GENERATOR STREQUAL "Ninja")
   add_custom_target(CheckNinja ALL
     COMMENT "Checking build.ninja"
diff --git a/Tests/CustomCommandByproducts/ExternalLibraryByproducts.c b/Tests/CustomCommandByproducts/ExternalLibraryByproducts.c
new file mode 100644
index 0000000..3588e53
--- /dev/null
+++ b/Tests/CustomCommandByproducts/ExternalLibraryByproducts.c
@@ -0,0 +1,5 @@
+extern int ExternalLibrary(void);
+int main(void)
+{
+  return (ExternalLibrary() + 1);
+}