2022-07-05 13:26:52 +02:00
|
|
|
# Copyright (C) 2022 The Qt Company Ltd.
|
2022-08-19 15:21:34 +02:00
|
|
|
# SPDX-License-Identifier: BSD-3-Clause
|
2022-07-05 13:26:52 +02:00
|
|
|
|
2020-10-23 13:06:51 +02:00
|
|
|
# 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()
|
|
|
|
|
2025-01-22 11:30:38 +01:00
|
|
|
# Adds custom build and install targets to generate documentation for a documentation project
|
|
|
|
# identified by a cmake target and a path to a .qdocconf file.
|
|
|
|
#
|
|
|
|
# Creates custom targets of the form:
|
|
|
|
# - generate_docs_${target}
|
|
|
|
# - prepare_docs_${target}
|
|
|
|
# - html_docs_${target}
|
|
|
|
# - install_html_docs_${target}
|
|
|
|
# - etc.
|
|
|
|
#
|
|
|
|
# The first two arguments to the function should be <target> <path-to-qdocconf>.
|
|
|
|
#
|
|
|
|
# Additional options are:
|
|
|
|
# INDEX_DIRECTORIES - a list of index directories to pass to qdoc.
|
|
|
|
#
|
|
|
|
# DEFINES - extra environment variable assignments of the form ENV_VAR=VALUE, which should be set
|
|
|
|
# during qdoc execution.
|
|
|
|
#
|
2025-01-22 12:06:10 +01:00
|
|
|
# QDOC_EXTRA_ARGS - extra command-line arguments to pass to qdoc in both prepare and generate
|
|
|
|
# phases.
|
|
|
|
#
|
|
|
|
# QDOC_PREPARE_EXTRA_ARGS - extra command-line arguments to pass to qdoc in the prepare phase.
|
|
|
|
#
|
|
|
|
# QDOC_GENERATE_EXTRA_ARGS - extra command-line arguments to pass to qdoc in the generate phase.
|
|
|
|
#
|
2025-01-22 12:11:12 +01:00
|
|
|
# SHOW_INTERNAL - if set, the --showinternal option is passed to qdoc.
|
|
|
|
#
|
2025-01-22 11:30:38 +01:00
|
|
|
# Additional environment variables considered:
|
|
|
|
# QT_INSTALL_DOCS - directory path where the qt docs were expected to be installed, used for
|
|
|
|
# linking to other built docs. If not set, defaults to the qtbase or qt5 build directory, or the
|
|
|
|
# install directory extracted from the BuildInternals package.
|
2025-01-22 12:06:10 +01:00
|
|
|
#
|
|
|
|
# QT_QDOC_EXTRA_ARGS, QT_QDOC_PREPARE_EXTRA_ARGS, QT_QDOC_GENERATE_EXTRA_ARGS - same as the options
|
|
|
|
# but can be set as either environment or cmake variables.
|
2025-01-22 12:11:12 +01:00
|
|
|
#
|
|
|
|
# QT_QDOC_SHOW_INTERNAL - same as the option but can be set as either an environment or
|
|
|
|
# cmake variable.
|
2020-09-22 10:02:27 +02:00
|
|
|
function(qt_internal_add_docs)
|
2024-10-16 11:13:43 +02:00
|
|
|
if(NOT QT_BUILD_DOCS)
|
|
|
|
return()
|
|
|
|
endif()
|
|
|
|
|
2020-08-13 17:37:47 +02:00
|
|
|
if(${ARGC} EQUAL 1)
|
|
|
|
# Function called from old generated CMakeLists.txt that was missing the target parameter
|
2025-01-22 11:30:38 +01:00
|
|
|
if(QT_FEATURE_developer_build)
|
|
|
|
message(AUTHOR_WARNING
|
|
|
|
"qt_internal_add_docs called with old signature. Skipping doc generation.")
|
|
|
|
endif()
|
2020-08-13 17:37:47 +02:00
|
|
|
return()
|
|
|
|
endif()
|
2025-01-22 11:30:38 +01:00
|
|
|
|
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
Pick-to: 6.7
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
2024-01-12 11:48:29 +01:00
|
|
|
if(NOT ${ARGC} GREATER_EQUAL 2)
|
2025-01-22 11:30:38 +01:00
|
|
|
message(FATAL_ERROR
|
|
|
|
"qt_internal_add_docs called with a wrong number of arguments. "
|
|
|
|
"The call should be qt_internal_add_docs\(<target> <path-to-qdocconf> [other-options])"
|
|
|
|
)
|
2020-08-13 17:37:47 +02:00
|
|
|
endif()
|
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
Pick-to: 6.7
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
2024-01-12 11:48:29 +01:00
|
|
|
|
2020-08-13 17:37:47 +02:00
|
|
|
set(target ${ARGV0})
|
2025-01-22 11:30:38 +01:00
|
|
|
set(qdoc_conf_path ${ARGV1})
|
|
|
|
|
2025-01-22 12:11:12 +01:00
|
|
|
set(opt_args
|
|
|
|
SHOW_INTERNAL
|
2025-03-28 09:00:01 +01:00
|
|
|
SKIP_JAVADOC
|
2025-01-22 12:11:12 +01:00
|
|
|
)
|
2025-01-22 11:30:38 +01:00
|
|
|
set(single_args "")
|
|
|
|
set(multi_args
|
|
|
|
INDEX_DIRECTORIES
|
|
|
|
DEFINES
|
2025-01-22 12:06:10 +01:00
|
|
|
QDOC_EXTRA_ARGS
|
|
|
|
QDOC_PREPARE_EXTRA_ARGS
|
|
|
|
QDOC_GENERATE_EXTRA_ARGS
|
2025-01-22 11:30:38 +01:00
|
|
|
)
|
|
|
|
cmake_parse_arguments(PARSE_ARGV 2 arg "${opt_args}" "${single_args}" "${multi_args}")
|
|
|
|
_qt_internal_validate_all_args_are_parsed(arg)
|
|
|
|
|
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
Pick-to: 6.7
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
2024-01-12 11:48:29 +01:00
|
|
|
set(qdoc_extra_args "")
|
2025-01-22 11:30:38 +01:00
|
|
|
|
|
|
|
# The INDEX_DIRECTORIES key should enable passing a list of index
|
|
|
|
# directories as extra command-line arguments to qdoc, in prepare and
|
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
Pick-to: 6.7
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
2024-01-12 11:48:29 +01:00
|
|
|
# generate phases.
|
2025-01-22 11:30:38 +01:00
|
|
|
if(arg_INDEX_DIRECTORIES)
|
|
|
|
foreach(index_directory ${arg_INDEX_DIRECTORIES})
|
|
|
|
list(APPEND qdoc_extra_args "--indexdir" ${index_directory})
|
|
|
|
endforeach()
|
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
Pick-to: 6.7
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
2024-01-12 11:48:29 +01:00
|
|
|
endif()
|
|
|
|
|
2025-01-22 12:11:12 +01:00
|
|
|
set(show_internal_env FALSE)
|
|
|
|
if(DEFINED ENV{QT_QDOC_SHOW_INTERNAL})
|
|
|
|
set(show_internal_env $ENV{QT_QDOC_SHOW_INTERNAL})
|
|
|
|
endif()
|
|
|
|
if(arg_SHOW_INTERNAL OR QT_QDOC_SHOW_INTERNAL OR show_internal_env)
|
|
|
|
list(APPEND qdoc_extra_args "--showinternal")
|
|
|
|
endif()
|
|
|
|
|
2025-01-22 12:06:10 +01:00
|
|
|
if(arg_QDOC_EXTRA_ARGS)
|
|
|
|
list(APPEND qdoc_extra_args ${arg_QDOC_EXTRA_ARGS})
|
|
|
|
endif()
|
|
|
|
|
|
|
|
if(QT_QDOC_EXTRA_ARGS)
|
|
|
|
list(APPEND qdoc_extra_args ${QT_QDOC_EXTRA_ARGS})
|
|
|
|
endif()
|
|
|
|
|
|
|
|
if(DEFINED ENV{QT_QDOC_EXTRA_ARGS})
|
|
|
|
list(APPEND qdoc_extra_args $ENV{QT_QDOC_EXTRA_ARGS})
|
|
|
|
endif()
|
|
|
|
|
2022-10-05 02:01:05 +02:00
|
|
|
# If a target is not built (which can happen for tools when crosscompiling), we shouldn't try
|
2020-08-13 17:37:47 +02:00
|
|
|
# to generate docs.
|
|
|
|
if(NOT TARGET "${target}")
|
|
|
|
return()
|
|
|
|
endif()
|
|
|
|
|
2021-04-28 09:23:59 +02:00
|
|
|
set(tool_dependencies_enabled TRUE)
|
|
|
|
if(NOT "${QT_HOST_PATH}" STREQUAL "")
|
|
|
|
set(tool_dependencies_enabled FALSE)
|
2025-03-17 18:55:27 +01:00
|
|
|
qt_internal_get_host_info_var_prefix(host_info_var_prefix)
|
|
|
|
set(doc_tools_bin "${QT_HOST_PATH}/${${host_info_var_prefix}_BINDIR}")
|
|
|
|
set(doc_tools_libexec "${QT_HOST_PATH}/${${host_info_var_prefix}_LIBEXECDIR}")
|
2024-09-06 13:54:24 +02:00
|
|
|
elseif(NOT "${QT_OPTIONAL_TOOLS_PATH}" STREQUAL "")
|
|
|
|
set(tool_dependencies_enabled FALSE)
|
|
|
|
set(doc_tools_bin "${QT_OPTIONAL_TOOLS_PATH}/${INSTALL_BINDIR}")
|
|
|
|
set(doc_tools_libexec "${QT_OPTIONAL_TOOLS_PATH}/${INSTALL_LIBEXECDIR}")
|
2021-04-28 09:23:59 +02:00
|
|
|
elseif(QT_SUPERBUILD)
|
2021-06-01 14:55:52 +02:00
|
|
|
set(doc_tools_bin "${QtBase_BINARY_DIR}/${INSTALL_BINDIR}")
|
|
|
|
set(doc_tools_libexec "${QtBase_BINARY_DIR}/${INSTALL_LIBEXECDIR}")
|
2020-08-13 17:37:47 +02:00
|
|
|
else()
|
2021-06-01 14:55:52 +02:00
|
|
|
set(doc_tools_bin "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_BINDIR}")
|
2025-01-22 11:30:38 +01:00
|
|
|
set(doc_tools_libexec
|
|
|
|
"${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_LIBEXECDIR}")
|
2020-08-13 17:37:47 +02:00
|
|
|
endif()
|
|
|
|
|
2024-09-06 13:54:24 +02:00
|
|
|
if(CMAKE_HOST_WIN32)
|
|
|
|
set(executable_suffix ".exe")
|
|
|
|
else()
|
|
|
|
set(executable_suffix "")
|
|
|
|
endif()
|
|
|
|
|
|
|
|
set(qdoc_bin "${doc_tools_bin}/qdoc${executable_suffix}")
|
|
|
|
set(qtattributionsscanner_bin "${doc_tools_libexec}/qtattributionsscanner${executable_suffix}")
|
|
|
|
set(qhelpgenerator_bin "${doc_tools_libexec}/qhelpgenerator${executable_suffix}")
|
2020-08-26 10:18:42 +02:00
|
|
|
|
2020-08-13 17:37:47 +02:00
|
|
|
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()
|
2020-10-23 11:18:33 +02:00
|
|
|
set(doc_output_dir "${target_bin_dir}/.doc")
|
2020-08-13 17:37:47 +02:00
|
|
|
|
|
|
|
# Generate include dir list
|
2020-10-23 11:18:33 +02:00
|
|
|
set(target_include_dirs_file "${doc_output_dir}/$<CONFIG>/includes.txt")
|
2020-08-13 17:37:47 +02:00
|
|
|
|
2020-11-25 11:50:30 +01:00
|
|
|
|
|
|
|
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")
|
2020-08-13 17:37:47 +02:00
|
|
|
file(GENERATE
|
|
|
|
OUTPUT ${target_include_dirs_file}
|
2020-11-27 12:41:21 +11:00
|
|
|
CONTENT "$<$<BOOL:${include_paths_property}>:-I$<JOIN:${include_paths_property},\n-I>>"
|
2020-08-13 17:37:47 +02:00
|
|
|
)
|
|
|
|
set(include_path_args "@${target_include_dirs_file}")
|
|
|
|
else()
|
|
|
|
set(include_path_args "")
|
|
|
|
endif()
|
|
|
|
|
2025-01-22 11:30:38 +01:00
|
|
|
get_filename_component(doc_target "${qdoc_conf_path}" NAME_WLE)
|
2020-08-13 17:37:47 +02:00
|
|
|
if (QT_WILL_INSTALL)
|
|
|
|
set(qdoc_output_dir "${CMAKE_BINARY_DIR}/${INSTALL_DOCDIR}/${doc_target}")
|
2021-01-08 12:44:54 +01:00
|
|
|
set(qdoc_qch_output_dir "${CMAKE_BINARY_DIR}/${INSTALL_DOCDIR}")
|
2020-08-13 17:37:47 +02:00
|
|
|
set(index_dir "${CMAKE_BINARY_DIR}/${INSTALL_DOCDIR}")
|
|
|
|
else()
|
2025-01-22 11:30:38 +01:00
|
|
|
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}")
|
2020-08-13 17:37:47 +02:00
|
|
|
endif()
|
|
|
|
|
|
|
|
# qtattributionsscanner
|
|
|
|
add_custom_target(qattributionsscanner_${target}
|
|
|
|
COMMAND ${qtattributionsscanner_bin}
|
|
|
|
${PROJECT_SOURCE_DIR}
|
2022-06-20 16:09:30 +02:00
|
|
|
--basedir "${PROJECT_SOURCE_DIR}/.."
|
2020-08-26 11:36:56 +02:00
|
|
|
--filter "QDocModule=${doc_target}"
|
2020-08-13 17:37:47 +02:00
|
|
|
-o "${target_bin_dir}/codeattributions.qdoc"
|
2025-03-11 16:41:47 +01:00
|
|
|
COMMENT "Scanning attributions for ${target}..."
|
2020-08-13 17:37:47 +02:00
|
|
|
)
|
|
|
|
|
|
|
|
# prepare docs target
|
|
|
|
set(prepare_qdoc_args
|
|
|
|
-outputdir "${qdoc_output_dir}"
|
2025-01-22 11:30:38 +01:00
|
|
|
"${target_source_dir}/${qdoc_conf_path}"
|
2020-08-13 17:37:47 +02:00
|
|
|
-prepare
|
|
|
|
-indexdir "${index_dir}"
|
|
|
|
-no-link-errors
|
|
|
|
"${include_path_args}"
|
|
|
|
)
|
2021-09-29 16:56:27 +02:00
|
|
|
if(NOT QT_BUILD_ONLINE_DOCS)
|
|
|
|
list(PREPEND prepare_qdoc_args
|
|
|
|
-installdir "${QT_INSTALL_DIR}/${INSTALL_DOCDIR}"
|
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
Pick-to: 6.7
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
2024-01-12 11:48:29 +01:00
|
|
|
${qdoc_extra_args}
|
2021-09-29 16:56:27 +02:00
|
|
|
)
|
|
|
|
endif()
|
2020-08-13 17:37:47 +02:00
|
|
|
|
2025-01-22 12:06:10 +01:00
|
|
|
if(arg_QDOC_PREPARE_EXTRA_ARGS)
|
|
|
|
list(APPEND prepare_qdoc_args ${arg_QDOC_PREPARE_EXTRA_ARGS})
|
|
|
|
endif()
|
|
|
|
|
|
|
|
if(QT_QDOC_PREPARE_EXTRA_ARGS)
|
|
|
|
list(APPEND prepare_qdoc_args ${QT_QDOC_PREPARE_EXTRA_ARGS})
|
|
|
|
endif()
|
|
|
|
|
|
|
|
if(DEFINED ENV{QT_QDOC_PREPARE_EXTRA_ARGS})
|
|
|
|
list(APPEND prepare_qdoc_args $ENV{QT_QDOC_PREPARE_EXTRA_ARGS})
|
|
|
|
endif()
|
|
|
|
|
2024-01-23 13:43:12 +01:00
|
|
|
if(DEFINED ENV{QT_INSTALL_DOCS})
|
2024-09-19 14:30:37 +02:00
|
|
|
if(NOT EXISTS "$ENV{QT_INSTALL_DOCS}")
|
|
|
|
message(FATAL_ERROR
|
|
|
|
"Environment variable QT_INSTALL_DOCS points to a directory which does not exist:\n"
|
|
|
|
"$ENV{QT_INSTALL_DOCS}")
|
|
|
|
endif()
|
2024-01-23 13:43:12 +01:00
|
|
|
set(qt_install_docs_env "$ENV{QT_INSTALL_DOCS}")
|
|
|
|
elseif(QT_SUPERBUILD OR "${PROJECT_NAME}" STREQUAL "QtBase")
|
2020-10-22 21:46:56 +02:00
|
|
|
set(qt_install_docs_env "${QtBase_BINARY_DIR}/${INSTALL_DOCDIR}")
|
2020-08-13 17:37:47 +02:00
|
|
|
else()
|
2025-01-22 11:30:38 +01:00
|
|
|
set(qt_install_docs_env
|
|
|
|
"${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_DOCDIR}")
|
2020-08-13 17:37:47 +02:00
|
|
|
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}"
|
|
|
|
)
|
2024-10-31 15:45:03 +01:00
|
|
|
if(arg_DEFINES)
|
|
|
|
foreach(define ${arg_DEFINES})
|
|
|
|
list(APPEND qdoc_env_args "${define}")
|
|
|
|
endforeach()
|
|
|
|
endif()
|
2020-08-13 17:37:47 +02:00
|
|
|
|
|
|
|
add_custom_target(prepare_docs_${target}
|
|
|
|
COMMAND ${CMAKE_COMMAND} -E env ${qdoc_env_args}
|
|
|
|
${qdoc_bin}
|
|
|
|
${prepare_qdoc_args}
|
2025-03-11 16:41:47 +01:00
|
|
|
COMMENT "Running qdoc for ${target}..."
|
2020-08-13 17:37:47 +02:00
|
|
|
)
|
|
|
|
|
|
|
|
add_dependencies(prepare_docs_${target} qattributionsscanner_${target})
|
2022-10-05 16:32:31 +02:00
|
|
|
if(NOT TARGET sync_all_public_headers)
|
|
|
|
add_custom_target(sync_all_public_headers)
|
2022-08-15 18:29:41 +02:00
|
|
|
endif()
|
2022-10-05 16:32:31 +02:00
|
|
|
add_dependencies(prepare_docs_${target} sync_all_public_headers)
|
2020-08-13 17:37:47 +02:00
|
|
|
|
|
|
|
# generate docs target
|
2021-10-25 11:03:13 +02:00
|
|
|
set(generate_qdoc_args
|
2020-08-13 17:37:47 +02:00
|
|
|
-outputdir "${qdoc_output_dir}"
|
2025-01-22 11:30:38 +01:00
|
|
|
"${target_source_dir}/${qdoc_conf_path}"
|
2020-08-13 17:37:47 +02:00
|
|
|
-generate
|
|
|
|
-indexdir "${index_dir}"
|
|
|
|
"${include_path_args}"
|
|
|
|
)
|
2021-09-29 16:56:27 +02:00
|
|
|
if(NOT QT_BUILD_ONLINE_DOCS)
|
|
|
|
list(PREPEND generate_qdoc_args
|
|
|
|
-installdir "${QT_INSTALL_DIR}/${INSTALL_DOCDIR}"
|
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
Pick-to: 6.7
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
2024-01-12 11:48:29 +01:00
|
|
|
${qdoc_extra_args}
|
2021-09-29 16:56:27 +02:00
|
|
|
)
|
|
|
|
endif()
|
2020-08-13 17:37:47 +02:00
|
|
|
|
2025-01-22 12:06:10 +01:00
|
|
|
if(arg_QDOC_GENERATE_EXTRA_ARGS)
|
|
|
|
list(APPEND generate_qdoc_args ${arg_QDOC_GENERATE_EXTRA_ARGS})
|
|
|
|
endif()
|
|
|
|
|
|
|
|
if(QT_QDOC_GENERATE_EXTRA_ARGS)
|
|
|
|
list(APPEND generate_qdoc_args ${QT_QDOC_GENERATE_EXTRA_ARGS})
|
|
|
|
endif()
|
|
|
|
|
|
|
|
if(DEFINED ENV{QT_QDOC_GENERATE_EXTRA_ARGS})
|
|
|
|
list(APPEND generate_qdoc_args $ENV{QT_QDOC_GENERATE_EXTRA_ARGS})
|
|
|
|
endif()
|
|
|
|
|
2020-10-27 10:35:07 +01:00
|
|
|
foreach(target_prefix generate_top_level_docs generate_repo_docs generate_docs)
|
2021-04-28 09:23:59 +02:00
|
|
|
set(depends_arg "")
|
|
|
|
if(tool_dependencies_enabled)
|
|
|
|
set(depends_arg DEPENDS ${qdoc_bin})
|
|
|
|
endif()
|
2020-10-27 10:35:07 +01:00
|
|
|
add_custom_target(${target_prefix}_${target}
|
2021-04-28 09:23:59 +02:00
|
|
|
${depends_arg}
|
2025-03-12 13:16:14 +01:00
|
|
|
COMMAND ${CMAKE_COMMAND} -E env ${qdoc_env_args} ${qdoc_bin} ${generate_qdoc_args}
|
|
|
|
COMMENT "Generating documentation for ${target}..."
|
|
|
|
)
|
2020-10-27 10:35:07 +01:00
|
|
|
endforeach()
|
2020-08-13 17:37:47 +02:00
|
|
|
|
|
|
|
add_dependencies(generate_docs_${target} prepare_docs_${target})
|
2020-10-27 10:35:07 +01:00
|
|
|
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})
|
2020-08-13 17:37:47 +02:00
|
|
|
|
2020-10-21 11:20:04 +02:00
|
|
|
# html docs target
|
|
|
|
add_custom_target(html_docs_${target})
|
2020-08-13 17:37:47 +02:00
|
|
|
add_dependencies(html_docs_${target} generate_docs_${target})
|
|
|
|
|
|
|
|
# generate .qch
|
|
|
|
set(qch_file_name ${doc_target}.qch)
|
2021-01-08 12:44:54 +01:00
|
|
|
set(qch_file_path ${qdoc_qch_output_dir}/${qch_file_name})
|
2020-08-13 17:37:47 +02:00
|
|
|
|
2020-10-27 10:35:07 +01:00
|
|
|
foreach(target_prefix qch_top_level_docs qch_repo_docs qch_docs)
|
2021-04-28 09:23:59 +02:00
|
|
|
set(depends_arg "")
|
|
|
|
if(tool_dependencies_enabled)
|
|
|
|
set(depends_arg DEPENDS ${qhelpgenerator_bin})
|
|
|
|
endif()
|
2020-10-27 10:35:07 +01:00
|
|
|
add_custom_target(${target_prefix}_${target}
|
2021-04-28 09:23:59 +02:00
|
|
|
${depends_arg}
|
2020-10-27 10:35:07 +01:00
|
|
|
COMMAND ${qhelpgenerator_bin}
|
|
|
|
"${qdoc_output_dir}/${doc_target}.qhp"
|
|
|
|
-o "${qch_file_path}"
|
2025-03-11 16:41:47 +01:00
|
|
|
COMMENT "Building QtHelp files for ${target}..."
|
2020-10-27 10:35:07 +01:00
|
|
|
)
|
|
|
|
endforeach()
|
2020-08-13 17:37:47 +02:00
|
|
|
add_dependencies(qch_docs_${target} generate_docs_${target})
|
2020-10-27 10:35:07 +01:00
|
|
|
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})
|
2020-08-13 17:37:47 +02:00
|
|
|
|
|
|
|
if (QT_WILL_INSTALL)
|
2020-02-09 18:09:38 +01:00
|
|
|
install(DIRECTORY "${qdoc_output_dir}/"
|
2025-03-28 09:00:01 +01:00
|
|
|
DESTINATION "${INSTALL_DOCDIR}/${doc_target}"
|
|
|
|
COMPONENT _install_html_docs_${target}
|
|
|
|
EXCLUDE_FROM_ALL
|
2020-02-09 18:09:38 +01:00
|
|
|
)
|
|
|
|
|
2020-08-13 17:37:47 +02:00
|
|
|
add_custom_target(install_html_docs_${target}
|
2020-02-09 18:09:38 +01:00
|
|
|
COMMAND ${CMAKE_COMMAND}
|
|
|
|
--install "${CMAKE_BINARY_DIR}"
|
|
|
|
--component _install_html_docs_${target}
|
2020-08-13 17:37:47 +02:00
|
|
|
COMMENT "Installing html docs for target ${target}"
|
|
|
|
)
|
|
|
|
|
2020-02-09 18:09:38 +01:00
|
|
|
install(FILES "${qch_file_path}"
|
2025-03-28 09:00:01 +01:00
|
|
|
DESTINATION "${INSTALL_DOCDIR}"
|
|
|
|
COMPONENT _install_qch_docs_${target}
|
|
|
|
EXCLUDE_FROM_ALL
|
2020-02-09 18:09:38 +01:00
|
|
|
)
|
|
|
|
|
2020-08-13 17:37:47 +02:00
|
|
|
add_custom_target(install_qch_docs_${target}
|
2020-02-09 18:09:38 +01:00
|
|
|
COMMAND ${CMAKE_COMMAND}
|
|
|
|
--install "${CMAKE_BINARY_DIR}"
|
|
|
|
--component _install_qch_docs_${target}
|
2020-08-13 17:37:47 +02:00
|
|
|
COMMENT "Installing qch docs for target ${target}"
|
2020-02-09 18:09:38 +01:00
|
|
|
)
|
|
|
|
|
2020-08-13 17:37:47 +02:00
|
|
|
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})
|
2020-10-27 10:35:07 +01:00
|
|
|
add_dependencies(${qt_docs_generate_target_name} generate_repo_docs_${target})
|
|
|
|
add_dependencies(${qt_docs_qch_target_name} qch_repo_docs_${target})
|
2020-11-05 10:32:30 +01:00
|
|
|
add_dependencies(${qt_docs_install_html_target_name} install_html_docs_${target})
|
|
|
|
add_dependencies(${qt_docs_install_qch_target_name} install_qch_docs_${target})
|
2020-10-23 13:06:51 +02:00
|
|
|
|
|
|
|
# Make sure that the necessary tools are built when running,
|
|
|
|
# for example 'cmake --build . --target generate_docs'.
|
2021-04-28 09:23:59 +02:00
|
|
|
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()
|
2025-03-28 09:00:01 +01:00
|
|
|
|
|
|
|
_qt_internal_forward_function_args(
|
|
|
|
FORWARD_PREFIX arg
|
|
|
|
FORWARD_OUT_VAR add_java_documentation_args
|
|
|
|
FORWARD_OPTIONS
|
|
|
|
SKIP_JAVADOC
|
|
|
|
)
|
|
|
|
qt_internal_add_java_documentation(${target} ${add_java_documentation_args}
|
|
|
|
OUTPUT_DIR "${qdoc_output_dir}"
|
|
|
|
)
|
|
|
|
endfunction()
|
|
|
|
|
|
|
|
function(qt_internal_add_java_documentation target)
|
|
|
|
if(NOT ANDROID AND NOT QT_BUILD_HOST_JAVA_DOCS)
|
|
|
|
return()
|
|
|
|
endif()
|
|
|
|
|
|
|
|
set(no_value_options
|
|
|
|
SKIP_JAVADOC
|
|
|
|
)
|
|
|
|
set(single_value_options
|
|
|
|
OUTPUT_DIR
|
|
|
|
)
|
|
|
|
set(multi_value_options "")
|
|
|
|
cmake_parse_arguments(PARSE_ARGV 1 arg
|
|
|
|
"${no_value_options}" "${single_value_options}" "${multi_value_options}"
|
|
|
|
)
|
|
|
|
_qt_internal_validate_all_args_are_parsed(arg)
|
|
|
|
|
|
|
|
# Use a default output directory based on the project name.
|
|
|
|
if(NOT DEFINED arg_OUTPUT_DIR)
|
|
|
|
if (QT_WILL_INSTALL)
|
|
|
|
set(arg_OUTPUT_DIR "${CMAKE_BINARY_DIR}/${INSTALL_DOCDIR}")
|
|
|
|
else()
|
|
|
|
set(arg_OUTPUT_DIR "${QT_BUILD_INTERNALS_RELOCATABLE_INSTALL_PREFIX}/${INSTALL_DOCDIR}")
|
|
|
|
endif()
|
|
|
|
string(APPEND arg_OUTPUT_DIR "/${PROJECT_NAME}")
|
|
|
|
endif()
|
|
|
|
|
|
|
|
qt_internal_collect_jar_sources(sources)
|
|
|
|
|
|
|
|
# Bail out if we haven't found relevant sources.
|
|
|
|
if(sources STREQUAL "")
|
|
|
|
return()
|
|
|
|
endif()
|
|
|
|
|
|
|
|
if(NOT TARGET docs_android)
|
|
|
|
add_custom_target(docs_android)
|
|
|
|
add_custom_target(install_docs_android)
|
|
|
|
add_dependencies(install_docs_android docs_android)
|
|
|
|
|
|
|
|
add_custom_target(android_source_jars)
|
|
|
|
add_custom_target(install_android_source_jars)
|
|
|
|
add_dependencies(install_android_source_jars android_source_jars)
|
|
|
|
endif()
|
|
|
|
|
|
|
|
if(NOT ANDROID)
|
|
|
|
qt_internal_set_up_build_host_java_docs()
|
|
|
|
endif()
|
|
|
|
|
|
|
|
if(NOT arg_SKIP_JAVADOC)
|
|
|
|
qt_internal_add_javadoc_target(
|
|
|
|
MODULE ${target}
|
|
|
|
SOURCES ${sources}
|
|
|
|
OUTPUT_DIR "${arg_OUTPUT_DIR}"
|
|
|
|
)
|
|
|
|
endif()
|
|
|
|
|
|
|
|
qt_internal_create_source_jar(SOURCES ${sources} MODULE ${target})
|
2020-08-13 17:37:47 +02:00
|
|
|
endfunction()
|