ExternalProject: Replace placeholder tokens in BYPRODUCTS

This allows the developer to specify the byproducts relative to the
binary directory without the need to set the binary directory location
explicitly.

Help/release/dev/ExternalProject-byproducts-tokens.rst

@@ -0,0 +1,5 @@
+ExternalProject-byproducts-tokens
+---------------------------------
+
+* The :module:`ExternalProject` module learned to replace tokens
+  like ``<BINARY_DIR>`` in the ``BYPRODUCTS`` of each step.

Modules/ExternalProject.cmake

@@ -251,8 +251,8 @@ Create custom targets to build projects in external trees
   ``LOG 1``
     Wrap step in script to log output
 
-  The command line, comment, and working directory of every standard and
-  custom step is processed to replace tokens ``<SOURCE_DIR>``,
+  The command line, comment, working directory, and byproducts of every
+  standard and custom step are processed to replace tokens ``<SOURCE_DIR>``,
   ``<BINARY_DIR>``, ``<INSTALL_DIR>``, and ``<TMP_DIR>`` with
   corresponding property values.
 
@@ -1443,7 +1443,7 @@ function(ExternalProject_Add_Step name step)
   endif()
 
   # Replace location tags.
-  _ep_replace_location_tags(${name} comment command work_dir)
+  _ep_replace_location_tags(${name} comment command work_dir byproducts)
 
   # Custom comment?
   get_property(comment_set TARGET ${name} PROPERTY _EP_${step}_COMMENT SET)

Tests/CustomCommandByproducts/CMakeLists.txt

@@ -102,6 +102,27 @@ add_library(ExternalLibrary STATIC IMPORTED)
 set_property(TARGET ExternalLibrary PROPERTY IMPORTED_LOCATION ${ExternalLibrary_LIBRARY})
 add_dependencies(ExternalLibrary ExternalTarget)
 
+# Generate the library file of an imported target as a byproduct
+# of an external project. The byproduct uses <BINARY_DIR> that is substituted
+# by the real binary path
+if(CMAKE_CONFIGURATION_TYPES)
+  set(cfg /${CMAKE_CFG_INTDIR})
+else()
+  set(cfg)
+endif()
+include(ExternalProject)
+ExternalProject_Add(ExtTargetSubst
+  SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/External"
+  DOWNLOAD_COMMAND ""
+  INSTALL_COMMAND ""
+  BUILD_BYPRODUCTS "<BINARY_DIR>${cfg}/${CMAKE_STATIC_LIBRARY_PREFIX}ExternalLibrary${CMAKE_STATIC_LIBRARY_SUFFIX}"
+  )
+ExternalProject_Get_Property(ExtTargetSubst binary_dir)
+add_library(ExternalLibraryWithSubstitution STATIC IMPORTED)
+set_property(TARGET ExternalLibraryWithSubstitution PROPERTY IMPORTED_LOCATION
+  ${binary_dir}${cfg}/${CMAKE_STATIC_LIBRARY_PREFIX}ExternalLibrary${CMAKE_STATIC_LIBRARY_SUFFIX})
+add_dependencies(ExternalLibraryWithSubstitution ExtTargetSubst)
+
 # Add an executable consuming all the byproducts.
 add_executable(CustomCommandByproducts
   CustomCommandByproducts.c