From 4bcfff2df3889a60b64e46d2431229cc6871c981 Mon Sep 17 00:00:00 2001 From: Alois Klink Date: Thu, 3 Nov 2022 15:27:09 +0000 Subject: ExternalProject: Clarify `BYPRODUCTS` docs Clarify that the `BUILD_BYPRODUCTS` and `BYPRODUCTS` options in ExternalProject may also be required when using the Ninja generator (as that's one of the primary reasons why you'd want to use those options). I've also mentioned that `add_custom_command` has additional documentation on what `BYPRODUCTS` does. --- Modules/ExternalProject.cmake | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake index 141b185..4af0952 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 @@ -943,9 +946,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 `` When enabled, this option specifies that the custom step should always be -- cgit v0.12 From 6d6baffb85ab4e02848fa7a3752f967d6ecb9518 Mon Sep 17 00:00:00 2001 From: Alois Klink Date: Thu, 3 Nov 2022 22:44:53 +0000 Subject: Tests: Fix ExternalLibraryWithSubstitution test The ExternalLibraryWithSubstitution test should test whether BUILD_BYPRODUCTS supports and other ExternalProject placeholder tokens. However, it's not hooked up correctly, and therefore isn't properly tested. This commit links it to an executable, to confirm whether it's possible to use the BUILD_BYPRODUCT in the Ninja generator. Fixes: commit 86032ae0eb (ExternalProject: Replace placeholder tokens in BYPRODUCTS, 2015-03-06) --- Tests/CustomCommandByproducts/CMakeLists.txt | 6 ++++++ Tests/CustomCommandByproducts/ExternalLibraryByproducts.c | 5 +++++ 2 files changed, 11 insertions(+) create mode 100644 Tests/CustomCommandByproducts/ExternalLibraryByproducts.c diff --git a/Tests/CustomCommandByproducts/CMakeLists.txt b/Tests/CustomCommandByproducts/CMakeLists.txt index 08c897c..638e165 100644 --- a/Tests/CustomCommandByproducts/CMakeLists.txt +++ b/Tests/CustomCommandByproducts/CMakeLists.txt @@ -169,6 +169,12 @@ 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) + 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); +} -- cgit v0.12 From 8c6b2928f4b71f87ba6ef6ccfaa7ba1c767f3097 Mon Sep 17 00:00:00 2001 From: Alois Klink Date: Thu, 3 Nov 2022 15:40:30 +0000 Subject: ExternalProject: Add `INSTALL_BYPRODUCTS` option Add an `INSTALL_BYPRODUCTS` option to `ExternalProject_Add` that can be used to declare that files are `BYPRODUCTS` of the ExternalProject install step. This is often required by the Ninja generator to explicitly declare dependencies. Previously, many users used `BUILD_BYPRODUCTS`, even if their files were created by the install step, not the build step. This commit essentially just copies the code for `BUILD_BYPRODUCTS`. Fixes: #24120 Fixes: #23056 --- Auxiliary/vim/syntax/cmake.vim | 1 + .../dev/ExternalProject-INSTALL_BYPRODUCTS.rst | 6 +++++ Modules/ExternalProject.cmake | 18 ++++++++++++++ Tests/CustomCommandByproducts/CMakeLists.txt | 29 ++++++++++++++++++++++ 4 files changed, 54 insertions(+) create mode 100644 Help/release/dev/ExternalProject-INSTALL_BYPRODUCTS.rst 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 4af0952..9fecd8f 100644 --- a/Modules/ExternalProject.cmake +++ b/Modules/ExternalProject.cmake @@ -664,6 +664,17 @@ External Project Definition supported). Passing an empty string as the ```` makes the install step do nothing. + ``INSTALL_BYPRODUCTS ...`` + .. 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 @@ -3852,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}]==]") @@ -3860,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} @@ -4087,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 638e165..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 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 "${cfg}" "${cfg}" + BUILD_BYPRODUCTS "${cfg}/${CMAKE_STATIC_LIBRARY_PREFIX}ExternalLibrary${CMAKE_STATIC_LIBRARY_SUFFIX}" + INSTALL_BYPRODUCTS "${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 @@ -175,6 +198,12 @@ 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" -- cgit v0.12