CMake: Let doc targets depend on doc tools in top-level build

For top-level builds it's desirable to have "ninja generate_docs" build
all tools needed to generate the documentation.

This is problematic since the doc-generating targets are created before
the doc tool targets. Thus, we must defer the dependency connection if
the doc tool target is not yet available.

This patch adds the functions qt_internal_defer_dependency and
qt_internal_add_deferred_dependencies.

Change-Id: Ica940b80882e67cb0e0943e95541f7f4d1885948
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>

cmake/QtBaseGlobalTargets.cmake

@@ -158,6 +158,7 @@ qt_copy_or_install(FILES
                    cmake/QtCompilerFlags.cmake
                    cmake/QtCompilerOptimization.cmake
                    cmake/QtConfigDependencies.cmake.in
+                   cmake/QtDeferredDependenciesHelpers.cmake
                    cmake/QtDbusHelpers.cmake
                    cmake/QtDocsHelpers.cmake
                    cmake/QtExecutableHelpers.cmake

cmake/QtBuild.cmake

@@ -458,6 +458,7 @@ include(QtAppHelpers)
 include(QtAutogenHelpers)
 include(QtCMakeHelpers)
 include(QtCompatibilityHelpers)
+include(QtDeferredDependenciesHelpers)
 include(QtDbusHelpers)
 include(QtDocsHelpers)
 include(QtExecutableHelpers)

cmake/QtDeferredDependenciesHelpers.cmake

@@ -0,0 +1,28 @@
+# Defers the connection 'dependent' -> 'dependency'
+#
+# The actual connection can be made by calling qt_internal_add_deferred_dependencies.
+#
+function(qt_internal_defer_dependency dependent dependency)
+    set_property(GLOBAL APPEND PROPERTY QT_DEFERRED_DEPENDENCIES ${doc_target} ${tool_target})
+endfunction()
+
+# Adds dependencies between targets that have been deferred by calling qt_internal_defer_dependency.
+#
+# This function checks whether the connection can be made (the dependency target exists).
+# If the connection cannot be made, the deferred connection is left in the global property.
+# Potentially, some later call to qt_internal_add_deferred_dependencies will add it.
+#
+function(qt_internal_add_deferred_dependencies)
+    unset(unknown_deps)
+    get_property(deferred_deps GLOBAL PROPERTY QT_DEFERRED_DEPENDENCIES)
+    while(deferred_deps)
+        list(POP_FRONT deferred_deps dependent)
+        list(POP_FRONT deferred_deps dependency)
+        if (TARGET ${dependency})
+            add_dependencies(${dependent} ${dependency})
+        else()
+            list(APPEND unknown_deps ${dependent} ${dependency})
+        endif()
+    endwhile()
+    set_property(GLOBAL PROPERTY QT_DEFERRED_DEPENDENCIES ${unknown_deps})
+endfunction()

cmake/QtDocsHelpers.cmake

@@ -1,3 +1,18 @@
+# This function adds a dependency between a doc-generating target like 'generate_docs_Gui'
+# and the necessary tool target like 'qdoc'.
+#
+# If the target is not yet existing, save the dependency connection in a global property.
+# The dependency is then added near the end of the top-level build after all subdirectories have
+# been handled.
+function(qt_internal_add_doc_tool_dependency doc_target tool_name)
+    qt_get_tool_target_name(tool_target ${tool_name})
+    if(TARGET ${tool_target})
+        add_dependencies(${doc_target} ${tool_target})
+    else()
+        qt_internal_defer_dependency(${doc_target} ${tool_target})
+    endif()
+endfunction()
+
 function(qt_internal_add_docs)
     if(${ARGC} EQUAL 1)
         # Function called from old generated CMakeLists.txt that was missing the target parameter
@@ -193,4 +208,10 @@ function(qt_internal_add_docs)
     add_dependencies(${qt_docs_install_html_target_name} install_html_docs_${target})
     add_dependencies(${qt_docs_install_qch_target_name} install_qch_docs_${target})
     add_dependencies(${qt_docs_install_target_name} install_docs_${target})
+
+    # Make sure that the necessary tools are built when running,
+    # for example 'cmake --build . --target generate_docs'.
+    qt_internal_add_doc_tool_dependency(qattributionsscanner_${target} qtattributionsscanner)
+    qt_internal_add_doc_tool_dependency(prepare_docs_${target} qdoc)
+    qt_internal_add_doc_tool_dependency(qch_docs_${target} qhelpgenerator)
 endfunction()