Merge pull request #116

kilo52 · web-flow · commit e7fb2727eb37 · 2025-10-29T20:53:23.000+01:00
Add Dependency Build Instruction File Handling
diff --git a/share/c/cmake/DependencyUtil.cmake b/share/c/cmake/DependencyUtil.cmake
@@ -26,23 +26,29 @@ include(FetchContent)
 # either Git repositories or source archive files. It is a thin wrapper
 # around the FetchContent machinery provided by CMake. By using this function,
 # a dependency becomes available to the underlying project in a
-# declarative way. There are three steps involved in processing a dependency:
+# declarative way. There are four steps involved in processing a dependency:
 # First, the specified dependency is passed to the CMake FetchContent_Declare()
 # function. The caller does not need to take care of the different arguments
 # as used by FetchContent_Declare(), as they are handled entirely by
 # this function. Secondly, an additional configuration file is potentially
 # included by this function. The purpose of such a file is to configure the
 # dependency to be made available to the underlying project. The configuration
-# file can contain arbitrary CMake code. Lastly, the dependency is made
+# file can contain arbitrary CMake code. Thirdly, the dependency is made
 # available by means of the CMake FetchContent_MakeAvailable() function.
+# This steps makes the declared targets of the dependency available to
+# the underlying project. Lastly, an additional build file is potentially
+# included by this function. This is similar to the configuration step, but
+# it allows a project to potentially manipulate the dependency target and its
+# build directly.
 #
-# The configuration file for a dependency is an ordinary CMake file, i.e. it
-# must contain syntactically valid CMake code. Each dependency configuration
-# file is included by this function. It can be used to set variables or do any
-# other kind of processing in order to properly configure the dependency to
-# be used by the underlying project. If no concrete config file is
-# specified by the DEPENDENCY_CONFIG_FILE argument, then this function will
-# look for a dependency config file in the "cmake" directory relative
+# The configuration and build files for a dependency are ordinary CMake files,
+# i.e. it must contain syntactically valid CMake code. Each dependency
+# configuration and build file included by this function if found.
+# The configuration file can be used to set variables or do any other kind of
+# processing in order to properly configure the dependency to be used by the
+# underlying project. If no concrete config file is specified by
+# the DEPENDENCY_CONFIG_FILE argument, then this function will look for a
+# dependency config file in the "cmake" directory relative
 # to CMAKE_CURRENT_SOURCE_DIR. The corresponding config file must be
 # named "Config${DEPENDENCY_NAME}.cmake", where ${DEPENDENCY_NAME} is the
 # value of the mandatory dependency name argument. Please note that the
@@ -51,6 +57,9 @@ include(FetchContent)
 # concrete dependency is named "mydep", then the conventional config file
 # has to be named "ConfigMydep.cmake". The inclusion of any dependency config
 # file can be disabled by using the DEPENDENCY_NO_CONFIG option.
+# The same convention applies to the build file, with a varying file prefix
+# of "Build*" instead of "Config*". For example, a conventional build file
+# might be named "BuildMydep.cmake".
 #
 # Every dependency has a scope. A dependency is only used if its scope
 # is active. The following scopes are available: "ANY", "RELEASE", "TEST"
@@ -134,6 +143,11 @@ include(FetchContent)
 #       to configure the dependency. This argument can optionally be used to
 #       specify a file which deviates from the convention.
 #
+#   DEPENDENCY_BUILD_FILE:
+#       The relative path to the file containing CMake instructions to be used
+#       to build the dependency. This argument can optionally be used to
+#       specify a file which deviates from the convention.
+#
 #   [options]
 #
 #   DEPENDENCY_QUIET:
@@ -181,6 +195,7 @@ function(dependency)
         DEPENDENCY_SCOPE
         DEPENDENCY_FILE_HASH
         DEPENDENCY_CONFIG_FILE
+        DEPENDENCY_BUILD_FILE
     )
     set(multiValueArgs "")
 
@@ -283,6 +298,46 @@ function(dependency)
         set(DEP_ARGS_DEPENDENCY_RESOURCE "${_DEP_BASE_URL}/${_DEP_SRC_RES}")
     endif()
 
+    # Set default conventional config and build files
+    string(
+        TOLOWER
+        ${DEP_ARGS_DEPENDENCY_NAME}
+        DEPENDENCY_NAME_LOWER
+    )
+    string(
+        SUBSTRING
+        ${DEPENDENCY_NAME_LOWER} 1 -1
+        DEPENDENCY_NAME_LOWER
+    )
+    string(
+        SUBSTRING
+        ${DEP_ARGS_DEPENDENCY_NAME} 0 1
+        DEPENDENCY_NAME_FIRST
+    )
+    string(
+        TOUPPER
+        ${DEPENDENCY_NAME_FIRST}
+        DEPENDENCY_NAME_FIRST
+    )
+    set(DEPENDENCY_DEFAULT_CONFIG_FILE "cmake/Config")
+    string(APPEND DEPENDENCY_DEFAULT_CONFIG_FILE ${DEPENDENCY_NAME_FIRST})
+    string(APPEND DEPENDENCY_DEFAULT_CONFIG_FILE ${DEPENDENCY_NAME_LOWER})
+    string(APPEND DEPENDENCY_DEFAULT_CONFIG_FILE ".cmake")
+    string(
+        PREPEND
+        DEPENDENCY_DEFAULT_CONFIG_FILE
+        "${CMAKE_CURRENT_SOURCE_DIR}" "/"
+    )
+    set(DEPENDENCY_DEFAULT_BUILD_FILE "cmake/Build")
+    string(APPEND DEPENDENCY_DEFAULT_BUILD_FILE ${DEPENDENCY_NAME_FIRST})
+    string(APPEND DEPENDENCY_DEFAULT_BUILD_FILE ${DEPENDENCY_NAME_LOWER})
+    string(APPEND DEPENDENCY_DEFAULT_BUILD_FILE ".cmake")
+    string(
+        PREPEND
+        DEPENDENCY_DEFAULT_BUILD_FILE
+        "${CMAKE_CURRENT_SOURCE_DIR}" "/"
+    )
+
     set(OPT_DEP_CACHE_SRC_PATH "")
     set(OPT_DEP_GIT_SHALLOW "GIT_SHALLOW")
     set(DEP_USE_GIT_SHALLOW ON)
@@ -397,41 +452,34 @@ function(dependency)
             endif()
         else()
             # Use the conventional file
-            string(
-                TOLOWER
-                ${DEP_ARGS_DEPENDENCY_NAME}
-                DEPENDENCY_NAME_LOWER
-            )
-            string(
-                SUBSTRING
-                ${DEPENDENCY_NAME_LOWER} 1 -1
-                DEPENDENCY_NAME_LOWER
-            )
-            string(
-                SUBSTRING
-                ${DEP_ARGS_DEPENDENCY_NAME} 0 1
-                DEPENDENCY_NAME_FIRST
-            )
-            string(
-                TOUPPER
-                ${DEPENDENCY_NAME_FIRST}
-                DEPENDENCY_NAME_FIRST
-            )
-            set(DEPENDENCY_CONFIG_FILE "cmake/Config")
-            string(APPEND DEPENDENCY_CONFIG_FILE ${DEPENDENCY_NAME_FIRST})
-            string(APPEND DEPENDENCY_CONFIG_FILE ${DEPENDENCY_NAME_LOWER})
-            string(APPEND DEPENDENCY_CONFIG_FILE ".cmake")
-            string(
-                PREPEND
-                DEPENDENCY_CONFIG_FILE
-                "${CMAKE_CURRENT_SOURCE_DIR}" "/"
-            )
-            if(EXISTS "${DEPENDENCY_CONFIG_FILE}")
-                include("${DEPENDENCY_CONFIG_FILE}")
+            if(EXISTS "${DEPENDENCY_DEFAULT_CONFIG_FILE}")
+                include("${DEPENDENCY_DEFAULT_CONFIG_FILE}")
             endif()
         endif()
     endif()
 
     FetchContent_MakeAvailable(${DEP_ARGS_DEPENDENCY_NAME})
 
+    # Check if a build file needs to be included
+    if(DEFINED DEP_ARGS_DEPENDENCY_BUILD_FILE)
+        set(
+            DEPENDENCY_BUILD_FILE
+            "${CMAKE_CURRENT_SOURCE_DIR}/${DEP_ARGS_DEPENDENCY_BUILD_FILE}"
+        )
+        if(EXISTS "${DEPENDENCY_BUILD_FILE}")
+            include("${DEPENDENCY_BUILD_FILE}")
+        else()
+            message(
+                WARNING
+                "The specified build file for "
+                "dependency ${DEP_ARGS_DEPENDENCY_NAME} "
+                "was not found: '${DEPENDENCY_BUILD_FILE}'"
+            )
+        endif()
+    else()
+        # Use the conventional file
+        if(EXISTS "${DEPENDENCY_DEFAULT_BUILD_FILE}")
+            include("${DEPENDENCY_DEFAULT_BUILD_FILE}")
+        endif()
+    endif()
 endfunction()
diff --git a/share/cpp/cmake/DependencyUtil.cmake b/share/cpp/cmake/DependencyUtil.cmake
@@ -26,23 +26,29 @@ include(FetchContent)
 # either Git repositories or source archive files. It is a thin wrapper
 # around the FetchContent machinery provided by CMake. By using this function,
 # a dependency becomes available to the underlying project in a
-# declarative way. There are three steps involved in processing a dependency:
+# declarative way. There are four steps involved in processing a dependency:
 # First, the specified dependency is passed to the CMake FetchContent_Declare()
 # function. The caller does not need to take care of the different arguments
 # as used by FetchContent_Declare(), as they are handled entirely by
 # this function. Secondly, an additional configuration file is potentially
 # included by this function. The purpose of such a file is to configure the
 # dependency to be made available to the underlying project. The configuration
-# file can contain arbitrary CMake code. Lastly, the dependency is made
+# file can contain arbitrary CMake code. Thirdly, the dependency is made
 # available by means of the CMake FetchContent_MakeAvailable() function.
+# This steps makes the declared targets of the dependency available to
+# the underlying project. Lastly, an additional build file is potentially
+# included by this function. This is similar to the configuration step, but
+# it allows a project to potentially manipulate the dependency target and its
+# build directly.
 #
-# The configuration file for a dependency is an ordinary CMake file, i.e. it
-# must contain syntactically valid CMake code. Each dependency configuration
-# file is included by this function. It can be used to set variables or do any
-# other kind of processing in order to properly configure the dependency to
-# be used by the underlying project. If no concrete config file is
-# specified by the DEPENDENCY_CONFIG_FILE argument, then this function will
-# look for a dependency config file in the "cmake" directory relative
+# The configuration and build files for a dependency are ordinary CMake files,
+# i.e. it must contain syntactically valid CMake code. Each dependency
+# configuration and build file included by this function if found.
+# The configuration file can be used to set variables or do any other kind of
+# processing in order to properly configure the dependency to be used by the
+# underlying project. If no concrete config file is specified by
+# the DEPENDENCY_CONFIG_FILE argument, then this function will look for a
+# dependency config file in the "cmake" directory relative
 # to CMAKE_CURRENT_SOURCE_DIR. The corresponding config file must be
 # named "Config${DEPENDENCY_NAME}.cmake", where ${DEPENDENCY_NAME} is the
 # value of the mandatory dependency name argument. Please note that the
@@ -51,6 +57,9 @@ include(FetchContent)
 # concrete dependency is named "mydep", then the conventional config file
 # has to be named "ConfigMydep.cmake". The inclusion of any dependency config
 # file can be disabled by using the DEPENDENCY_NO_CONFIG option.
+# The same convention applies to the build file, with a varying file prefix
+# of "Build*" instead of "Config*". For example, a conventional build file
+# might be named "BuildMydep.cmake".
 #
 # Every dependency has a scope. A dependency is only used if its scope
 # is active. The following scopes are available: "ANY", "RELEASE", "TEST"
@@ -134,6 +143,11 @@ include(FetchContent)
 #       to configure the dependency. This argument can optionally be used to
 #       specify a file which deviates from the convention.
 #
+#   DEPENDENCY_BUILD_FILE:
+#       The relative path to the file containing CMake instructions to be used
+#       to build the dependency. This argument can optionally be used to
+#       specify a file which deviates from the convention.
+#
 #   [options]
 #
 #   DEPENDENCY_QUIET:
@@ -181,6 +195,7 @@ function(dependency)
         DEPENDENCY_SCOPE
         DEPENDENCY_FILE_HASH
         DEPENDENCY_CONFIG_FILE
+        DEPENDENCY_BUILD_FILE
     )
     set(multiValueArgs "")
 
@@ -283,6 +298,46 @@ function(dependency)
         set(DEP_ARGS_DEPENDENCY_RESOURCE "${_DEP_BASE_URL}/${_DEP_SRC_RES}")
     endif()
 
+    # Set default conventional config and build files
+    string(
+        TOLOWER
+        ${DEP_ARGS_DEPENDENCY_NAME}
+        DEPENDENCY_NAME_LOWER
+    )
+    string(
+        SUBSTRING
+        ${DEPENDENCY_NAME_LOWER} 1 -1
+        DEPENDENCY_NAME_LOWER
+    )
+    string(
+        SUBSTRING
+        ${DEP_ARGS_DEPENDENCY_NAME} 0 1
+        DEPENDENCY_NAME_FIRST
+    )
+    string(
+        TOUPPER
+        ${DEPENDENCY_NAME_FIRST}
+        DEPENDENCY_NAME_FIRST
+    )
+    set(DEPENDENCY_DEFAULT_CONFIG_FILE "cmake/Config")
+    string(APPEND DEPENDENCY_DEFAULT_CONFIG_FILE ${DEPENDENCY_NAME_FIRST})
+    string(APPEND DEPENDENCY_DEFAULT_CONFIG_FILE ${DEPENDENCY_NAME_LOWER})
+    string(APPEND DEPENDENCY_DEFAULT_CONFIG_FILE ".cmake")
+    string(
+        PREPEND
+        DEPENDENCY_DEFAULT_CONFIG_FILE
+        "${CMAKE_CURRENT_SOURCE_DIR}" "/"
+    )
+    set(DEPENDENCY_DEFAULT_BUILD_FILE "cmake/Build")
+    string(APPEND DEPENDENCY_DEFAULT_BUILD_FILE ${DEPENDENCY_NAME_FIRST})
+    string(APPEND DEPENDENCY_DEFAULT_BUILD_FILE ${DEPENDENCY_NAME_LOWER})
+    string(APPEND DEPENDENCY_DEFAULT_BUILD_FILE ".cmake")
+    string(
+        PREPEND
+        DEPENDENCY_DEFAULT_BUILD_FILE
+        "${CMAKE_CURRENT_SOURCE_DIR}" "/"
+    )
+
     set(OPT_DEP_CACHE_SRC_PATH "")
     set(OPT_DEP_GIT_SHALLOW "GIT_SHALLOW")
     set(DEP_USE_GIT_SHALLOW ON)
@@ -397,41 +452,34 @@ function(dependency)
             endif()
         else()
             # Use the conventional file
-            string(
-                TOLOWER
-                ${DEP_ARGS_DEPENDENCY_NAME}
-                DEPENDENCY_NAME_LOWER
-            )
-            string(
-                SUBSTRING
-                ${DEPENDENCY_NAME_LOWER} 1 -1
-                DEPENDENCY_NAME_LOWER
-            )
-            string(
-                SUBSTRING
-                ${DEP_ARGS_DEPENDENCY_NAME} 0 1
-                DEPENDENCY_NAME_FIRST
-            )
-            string(
-                TOUPPER
-                ${DEPENDENCY_NAME_FIRST}
-                DEPENDENCY_NAME_FIRST
-            )
-            set(DEPENDENCY_CONFIG_FILE "cmake/Config")
-            string(APPEND DEPENDENCY_CONFIG_FILE ${DEPENDENCY_NAME_FIRST})
-            string(APPEND DEPENDENCY_CONFIG_FILE ${DEPENDENCY_NAME_LOWER})
-            string(APPEND DEPENDENCY_CONFIG_FILE ".cmake")
-            string(
-                PREPEND
-                DEPENDENCY_CONFIG_FILE
-                "${CMAKE_CURRENT_SOURCE_DIR}" "/"
-            )
-            if(EXISTS "${DEPENDENCY_CONFIG_FILE}")
-                include("${DEPENDENCY_CONFIG_FILE}")
+            if(EXISTS "${DEPENDENCY_DEFAULT_CONFIG_FILE}")
+                include("${DEPENDENCY_DEFAULT_CONFIG_FILE}")
             endif()
         endif()
     endif()
 
     FetchContent_MakeAvailable(${DEP_ARGS_DEPENDENCY_NAME})
 
+    # Check if a build file needs to be included
+    if(DEFINED DEP_ARGS_DEPENDENCY_BUILD_FILE)
+        set(
+            DEPENDENCY_BUILD_FILE
+            "${CMAKE_CURRENT_SOURCE_DIR}/${DEP_ARGS_DEPENDENCY_BUILD_FILE}"
+        )
+        if(EXISTS "${DEPENDENCY_BUILD_FILE}")
+            include("${DEPENDENCY_BUILD_FILE}")
+        else()
+            message(
+                WARNING
+                "The specified build file for "
+                "dependency ${DEP_ARGS_DEPENDENCY_NAME} "
+                "was not found: '${DEPENDENCY_BUILD_FILE}'"
+            )
+        endif()
+    else()
+        # Use the conventional file
+        if(EXISTS "${DEPENDENCY_DEFAULT_BUILD_FILE}")
+            include("${DEPENDENCY_DEFAULT_BUILD_FILE}")
+        endif()
+    endif()
 endfunction()
