1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
qtbase/cmake/QtDocsHelpers.cmake
Venugopal Shivashankar a375e52aa3 CMake: Accept additional arguments for qt_internal_add_docs 
The current implementation of the API accepts only two
arguments, {target} and {qdocconf}. It passes a few
environment variables to build targets, providing info.
about the Qt version being used. QT_INSTALL_DOCS is one
of these environment variables, and it is the install
path for all the Qt module/addon documentation sets.
QT_INSTALL_DOCS is also the path where the global QDoc
configuration files are available.

If a project uses the qt_internal_add_docs to create
the build targets for the documentation, and the Qt
version used to configure the project is a pkg installed
using the qt-online-installer, the QT_INSTALL_DOCS path
is always wrong. Such projects should either maintain a
CMake setup for documentation or configure and
build Qt from source with the correct QT_INSTALL_DOCS
path, which is then passed to qdoc.

This change enables passing additional indexdir
and other arguments to QDoc, which is useful. For example,
if QDoc cannot find all the cross-module link targets,
you could either pass extra indexdir argument to resolve
the links or turn off the link errors.

For example, if your qdocconf has the following depends
entry to enble linking to other modules:

    depends += qtcore qtmultimedia

And the documentation for these modules are not part
of the Qt installation used to build the projects, you
could pass additional index dirs to enable cross-module
linking.

    qt_internal_add_docs{target_name qdocconf
                         INDEX_DIRECTORIES /absolute/path/Qt6/Docs /one/more/Qt6/Docs /another/Qt6/Docs)

Change-Id: Ieac271ddf92990d722602487c41af7f18546d096
Done-with: Topi Reinio <topi.reinio@qt.io>
Task-number: QTBUG-121457
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
(cherry picked from commit c024af0d12e35891e19752c1f7cd6fb3371d09b0)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
2024-01-24 19:01:41 +00:00

283 lines
11 KiB
CMake
Raw Blame History

# Copyright (C) 2022 The Qt Company Ltd.
# SPDX-License-Identifier: BSD-3-Clause
# 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
return()
endif()
set(error_msg "qt_add_docs called with wrong number of arguments. ")
list(APPEND error_msg
"Should be qt_add_docs\(target_name qdocconf "
"\[INDEX_DIRECTORIES EXTRA_INDEX_DIRS_LIST_TO_ENABLE_QDOC_RESOLVE_LINKS\]\)")
if(NOT ${ARGC} GREATER_EQUAL 2)
message(FATAL_ERROR ${error_msg})
return()
endif()
set(target ${ARGV0})
set(doc_project ${ARGV1})
set(qdoc_extra_args "")
# Check if there are more than 2 arguments and pass them
# as extra --indexdir arguments to qdoc in prepare and
# generate phases.
if (${ARGC} GREATER 2)
# The INDEX_DIRECTORIES key should enable passing a list of index
# directories as extra command-line arguments to qdoc.
set(qdocExtraArgs INDEX_DIRECTORIES)
cmake_parse_arguments(PARSE_ARGV 2 arg "" "" "${qdocExtraArgs}")
if(arg_UNPARSED_ARGUMENTS)
message(FATAL_ERROR ${error_msg})
return()
endif()
if(arg_INDEX_DIRECTORIES)
foreach(index_directory ${arg_INDEX_DIRECTORIES})
list(APPEND qdoc_extra_args "--indexdir" ${index_directory})
endforeach()
endif()
endif()
# If a target is not built (which can happen for tools when crosscompiling), we shouldn't try
# to generate docs.
if(NOT TARGET "${target}")
return()
endif()
set(tool_dependencies_enabled TRUE)
if(NOT "${QT_HOST_PATH}" STREQUAL "")
set(tool_dependencies_enabled FALSE)
set(doc_tools_bin "${QT_HOST_PATH}/${QT${PROJECT_VERSION_MAJOR}_HOST_INFO_BINDIR}")
set(doc_tools_libexec "${QT_HOST_PATH}/${QT${PROJECT_VERSION_MAJOR}_HOST_INFO_LIBEXECDIR}")
elseif(QT_SUPERBUILD)
set(doc_tools_bin "${QtBase_BINARY_DIR}/${INSTALL_BINDIR}")
set(doc_tools_libexec "${QtBase_BINARY_DIR}/${INSTALL_LIBEXECDIR}")
else()
set(doc_tools_bin "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_BINDIR}")
set(doc_tools_libexec "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_LIBEXECDIR}")
endif()
set(qdoc_bin "${doc_tools_bin}/qdoc${CMAKE_EXECUTABLE_SUFFIX}")
set(qtattributionsscanner_bin "${doc_tools_libexec}/qtattributionsscanner${CMAKE_EXECUTABLE_SUFFIX}")
set(qhelpgenerator_bin "${doc_tools_libexec}/qhelpgenerator${CMAKE_EXECUTABLE_SUFFIX}")
get_target_property(target_type ${target} TYPE)
if (NOT target_type STREQUAL "INTERFACE_LIBRARY")
get_target_property(target_bin_dir ${target} BINARY_DIR)
get_target_property(target_source_dir ${target} SOURCE_DIR)
else()
set(target_bin_dir ${CMAKE_CURRENT_BINARY_DIR})
set(target_source_dir ${CMAKE_CURRENT_SOURCE_DIR})
endif()
set(doc_output_dir "${target_bin_dir}/.doc")
# Generate include dir list
set(target_include_dirs_file "${doc_output_dir}/$<CONFIG>/includes.txt")
set(prop_prefix "")
if(target_type STREQUAL "INTERFACE_LIBRARY")
set(prop_prefix "INTERFACE_")
endif()
set(include_path_prop "${prop_prefix}INCLUDE_DIRECTORIES")
set(include_paths_property "$<TARGET_PROPERTY:${target},${include_path_prop}>")
if (NOT target_type STREQUAL "UTILITY")
file(GENERATE
OUTPUT ${target_include_dirs_file}
CONTENT "$<$<BOOL:${include_paths_property}>:-I$<JOIN:${include_paths_property},\n-I>>"
)
set(include_path_args "@${target_include_dirs_file}")
else()
set(include_path_args "")
endif()
get_filename_component(doc_target "${doc_project}" NAME_WLE)
if (QT_WILL_INSTALL)
set(qdoc_output_dir "${CMAKE_BINARY_DIR}/${INSTALL_DOCDIR}/${doc_target}")
set(qdoc_qch_output_dir "${CMAKE_BINARY_DIR}/${INSTALL_DOCDIR}")
set(index_dir "${CMAKE_BINARY_DIR}/${INSTALL_DOCDIR}")
else()
set(qdoc_output_dir "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_DOCDIR}/${doc_target}")
set(qdoc_qch_output_dir "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_DOCDIR}")
set(index_dir "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_DOCDIR}")
endif()
# qtattributionsscanner
add_custom_target(qattributionsscanner_${target}
COMMAND ${qtattributionsscanner_bin}
${PROJECT_SOURCE_DIR}
--basedir "${PROJECT_SOURCE_DIR}/.."
--filter "QDocModule=${doc_target}"
-o "${target_bin_dir}/codeattributions.qdoc"
)
# prepare docs target
set(prepare_qdoc_args
-outputdir "${qdoc_output_dir}"
"${target_source_dir}/${doc_project}"
-prepare
-indexdir "${index_dir}"
-no-link-errors
"${include_path_args}"
)
if(NOT QT_BUILD_ONLINE_DOCS)
list(PREPEND prepare_qdoc_args
-installdir "${QT_INSTALL_DIR}/${INSTALL_DOCDIR}"
${qdoc_extra_args}
)
endif()
if(DEFINED ENV{QT_INSTALL_DOCS})
set(qt_install_docs_env "$ENV{QT_INSTALL_DOCS}")
elseif(QT_SUPERBUILD OR "${PROJECT_NAME}" STREQUAL "QtBase")
set(qt_install_docs_env "${QtBase_BINARY_DIR}/${INSTALL_DOCDIR}")
else()
set(qt_install_docs_env "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_DOCDIR}")
endif()
set(qdoc_env_args
"QT_INSTALL_DOCS=\"${qt_install_docs_env}\""
"QT_VERSION=${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}"
"QT_VER=${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}"
"QT_VERSION_TAG=${PROJECT_VERSION_MAJOR}${PROJECT_VERSION_MINOR}${PROJECT_VERSION_PATCH}"
"BUILDDIR=${target_bin_dir}"
)
add_custom_target(prepare_docs_${target}
COMMAND ${CMAKE_COMMAND} -E env ${qdoc_env_args}
${qdoc_bin}
${prepare_qdoc_args}
)
add_dependencies(prepare_docs_${target} qattributionsscanner_${target})
if(NOT TARGET sync_all_public_headers)
add_custom_target(sync_all_public_headers)
endif()
add_dependencies(prepare_docs_${target} sync_all_public_headers)
# generate docs target
set(generate_qdoc_args
-outputdir "${qdoc_output_dir}"
"${target_source_dir}/${doc_project}"
-generate
-indexdir "${index_dir}"
"${include_path_args}"
)
if(NOT QT_BUILD_ONLINE_DOCS)
list(PREPEND generate_qdoc_args
-installdir "${QT_INSTALL_DIR}/${INSTALL_DOCDIR}"
${qdoc_extra_args}
)
endif()
foreach(target_prefix generate_top_level_docs generate_repo_docs generate_docs)
set(depends_arg "")
if(tool_dependencies_enabled)
set(depends_arg DEPENDS ${qdoc_bin})
endif()
add_custom_target(${target_prefix}_${target}
${depends_arg}
COMMAND ${CMAKE_COMMAND} -E env ${qdoc_env_args} ${qdoc_bin} ${generate_qdoc_args})
endforeach()
add_dependencies(generate_docs_${target} prepare_docs_${target})
add_dependencies(generate_repo_docs_${target} ${qt_docs_prepare_target_name})
add_dependencies(generate_top_level_docs_${target} prepare_docs)
add_dependencies(generate_docs generate_top_level_docs_${target})
# html docs target
add_custom_target(html_docs_${target})
add_dependencies(html_docs_${target} generate_docs_${target})
# generate .qch
set(qch_file_name ${doc_target}.qch)
set(qch_file_path ${qdoc_qch_output_dir}/${qch_file_name})
foreach(target_prefix qch_top_level_docs qch_repo_docs qch_docs)
set(depends_arg "")
if(tool_dependencies_enabled)
set(depends_arg DEPENDS ${qhelpgenerator_bin})
endif()
add_custom_target(${target_prefix}_${target}
${depends_arg}
COMMAND ${qhelpgenerator_bin}
"${qdoc_output_dir}/${doc_target}.qhp"
-o "${qch_file_path}"
)
endforeach()
add_dependencies(qch_docs_${target} generate_docs_${target})
add_dependencies(qch_repo_docs_${target} ${qt_docs_generate_target_name})
add_dependencies(qch_top_level_docs_${target} generate_docs)
add_dependencies(qch_docs qch_top_level_docs_${target})
if (QT_WILL_INSTALL)
install(DIRECTORY "${qdoc_output_dir}/"
DESTINATION "${INSTALL_DOCDIR}/${doc_target}"
COMPONENT _install_html_docs_${target}
EXCLUDE_FROM_ALL
)
add_custom_target(install_html_docs_${target}
COMMAND ${CMAKE_COMMAND}
--install "${CMAKE_BINARY_DIR}"
--component _install_html_docs_${target}
COMMENT "Installing html docs for target ${target}"
)
install(FILES "${qch_file_path}"
DESTINATION "${INSTALL_DOCDIR}"
COMPONENT _install_qch_docs_${target}
EXCLUDE_FROM_ALL
)
add_custom_target(install_qch_docs_${target}
COMMAND ${CMAKE_COMMAND}
--install "${CMAKE_BINARY_DIR}"
--component _install_qch_docs_${target}
COMMENT "Installing qch docs for target ${target}"
)
else()
# Don't need to do anything when not installing
add_custom_target(install_html_docs_${target})
add_custom_target(install_qch_docs_${target})
endif()
add_custom_target(install_docs_${target})
add_dependencies(install_docs_${target} install_html_docs_${target} install_qch_docs_${target})
add_custom_target(docs_${target})
add_dependencies(docs_${target} html_docs_${target})
add_dependencies(docs_${target} qch_docs_${target})
add_dependencies(${qt_docs_prepare_target_name} prepare_docs_${target})
add_dependencies(${qt_docs_generate_target_name} generate_repo_docs_${target})
add_dependencies(${qt_docs_qch_target_name} qch_repo_docs_${target})
add_dependencies(${qt_docs_install_html_target_name} install_html_docs_${target})
add_dependencies(${qt_docs_install_qch_target_name} install_qch_docs_${target})
# Make sure that the necessary tools are built when running,
# for example 'cmake --build . --target generate_docs'.
if(tool_dependencies_enabled)
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)
endif()
endfunction()
Reference in New Issue View Git Blame Copy Permalink