Skip to content

Commit f7f02c7

Browse files
alcroitoalcroito
committed
CMake: Add a script to build qdoc and friends from qttools/dev/HEAD
A new QtBuildStaticDocToolsScript.cmake script is added which: - clones qt5.git - initializes required submodules for building doc tools - checks out qttools/dev/HEAD - syncs the dependency SHA1s as specified in qttools' dependencies.yaml file - configures qt5 as a top-level static build - builds qdoc and other tools required for documentation generation - installs them into a custom prefix under a subdirectory of the repo's root build dir. The script is intended to be used as part of qtbase's CI build instructions. See the follow-up coin change for reasons on why we want to do that and how to configure optional ref pinning, instead of using dev branch always. Pick-to: 6.8 Task-number: QTBUG-128730 Change-Id: I836fc2f1b47c07171d2a2bd54a85bc2145212e46 Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
1 parent aab8b77 commit f7f02c7

File tree

2 files changed

+253
-0
lines changed

2 files changed

+253
-0
lines changed

‎cmake/QtBuildHelpers.cmake

+1
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,7 @@ function(qt_internal_get_qt_build_private_files_to_install out_var)
229229
QtBaseTopLevelHelpers.cmake
230230
QtBuild.cmake
231231
QtBuildHelpers.cmake
232+
QtBuildStaticDocToolsScript.cmake
232233
QtCMakePackageVersionFile.cmake.in
233234
QtCompilerFlags.cmake
234235
QtCompilerOptimization.cmake

‎cmake/QtBuildStaticDocToolsScript.cmake

+252
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# Copyright (C) 2024 The Qt Company Ltd.
2+
# SPDX-License-Identifier: BSD-3-Clause
3+
4+
cmake_minimum_required(VERSION 3.16)
5+
6+
# Query the var name from the CMake cache or the environment or use a default value.
7+
function(qt_internal_get_cmake_or_env_or_default out_var var_name_to_check default_value)
8+
if(${var_name_to_check})
9+
set(value "${var_name_to_check}")
10+
elseif(DEFINED ENV{${var_name_to_check}})
11+
set(value "$ENV{${var_name_to_check}}")
12+
else()
13+
set(value "${default_value}")
14+
endif()
15+
set(${out_var} "${value}" PARENT_SCOPE)
16+
endfunction()
17+
18+
# Prepares paths for the cloning of the sources, the build and the installation.
19+
function(qt_internal_prepare_build_paths)
20+
set(current_dir "${CMAKE_CURRENT_BINARY_DIR}")
21+
22+
qt_internal_get_cmake_or_env_or_default(working_dir
23+
QT_CI_DOC_TOOLS_WORKING_DIR "${current_dir}/qdoc_build")
24+
25+
qt_internal_get_cmake_or_env_or_default(qt_src_dir
26+
QT_CI_DOC_TOOLS_SRC_DIR "${working_dir}/qt5")
27+
28+
qt_internal_get_cmake_or_env_or_default(qt_build_dir
29+
QT_CI_DOC_TOOLS_BUILD__DIR "${working_dir}/build")
30+
31+
qt_internal_get_cmake_or_env_or_default(qt_installed_dir
32+
QT_CI_DOC_TOOLS_INSTALL_DIR "${working_dir}/install")
33+
34+
set(QT_DOC_TOOLS_WORKING_DIR "${working_dir}" PARENT_SCOPE)
35+
set(QT_DOC_TOOLS_SRC_DIR "${qt_src_dir}" PARENT_SCOPE)
36+
set(QT_DOC_TOOLS_BUILD_DIR "${qt_build_dir}" PARENT_SCOPE)
37+
set(QT_DOC_TOOLS_INSTALL_DIR "${qt_installed_dir}" PARENT_SCOPE)
38+
endfunction()
39+
40+
# Gets the remote git base URL for qt repositories.
41+
function(qt_internal_get_repo_base_url out_var)
42+
# This Coin CI git daemon IP is set in all CI jobs.
43+
# Prefer using it when available, to avoid general network issues.
44+
# Sample value: QT_COIN_GIT_DAEMON=10.215.0.212:9418
45+
qt_internal_get_cmake_or_env_or_default(coin_git_ip_port QT_COIN_GIT_DAEMON "")
46+
47+
# Allow opting out of using the coin git daemon.
48+
qt_internal_get_cmake_or_env_or_default(skip_coin_git QT_DOC_TOOLS_SKIP_COIN_GIT_DAEMON FALSE)
49+
50+
# Allow override of the default remote.
51+
qt_internal_get_cmake_or_env_or_default(git_remote QT_CI_DOC_TOOLS_GIT_REMOTE "")
52+
53+
if(coin_git_ip_port AND NOT skip_coin_git)
54+
set(value "git://${coin_git_ip_port}/qt-project")
55+
elseif(git_remote)
56+
set(value "${git_remote}")
57+
else()
58+
set(value "https://code.qt.io")
59+
endif()
60+
61+
set(${out_var} "${value}" PARENT_SCOPE)
62+
endfunction()
63+
64+
# Clones qt5.git into the specified src directory.
65+
function(qt_internal_clone_qt5)
66+
file(MAKE_DIRECTORY "${QT_DOC_TOOLS_SRC_DIR}")
67+
68+
qt_internal_get_repo_base_url(remote_url)
69+
execute_process(
70+
COMMAND git clone "${remote_url}/qt/qt5.git" "${QT_DOC_TOOLS_SRC_DIR}"
71+
COMMAND_ECHO STDOUT
72+
WORKING_DIRECTORY "${QT_DOC_TOOLS_WORKING_DIR}"
73+
RESULT_VARIABLE result
74+
ERROR_VARIABLE proc_err
75+
OUTPUT_STRIP_TRAILING_WHITESPACE
76+
)
77+
if(result)
78+
message(WARNING "Cloning qt5.git sources failed. Output: ${result}")
79+
endif()
80+
81+
# Allow pinning the qt5.git sha1 or any other git ref, based on a cmake var or env var.
82+
qt_internal_get_cmake_or_env_or_default(super_repo_ref
83+
QT_CI_DOC_TOOLS_TOP_LEVEL_PIN_GIT_REF "dev")
84+
85+
# Allow using the branch that the Coin CI sets, as an opt-in.
86+
qt_internal_get_cmake_or_env_or_default(use_ci_branch
87+
QT_CI_DOC_TOOLS_USE_CI_TOP_LEVEL_BRANCH "OFF")
88+
qt_internal_get_cmake_or_env_or_default(ci_branch
89+
TESTED_MODULE_BRANCH_COIN "")
90+
91+
if(use_ci_branch AND ci_branch)
92+
set(super_repo_ref "${ci_branch}")
93+
endif()
94+
95+
execute_process(
96+
COMMAND git checkout "${super_repo_ref}"
97+
COMMAND_ECHO STDOUT
98+
WORKING_DIRECTORY "${QT_DOC_TOOLS_SRC_DIR}"
99+
RESULT_VARIABLE result
100+
OUTPUT_STRIP_TRAILING_WHITESPACE
101+
)
102+
if(result)
103+
message(FATAL_ERROR
104+
"Checking out qt5.git '${super_repo_ref}' ref failed. Output: ${result}")
105+
endif()
106+
endfunction()
107+
108+
# Checks out qttools to the dev branch (or other specified ref) and syncs its submodule
109+
# dependencies according to qttools dependencies.yaml file.
110+
function(qt_internal_sync_to_qttools)
111+
execute_process(
112+
COMMAND
113+
git submodule update
114+
--init
115+
--recursive
116+
--progress
117+
--depth 1
118+
qttools
119+
120+
# TODO: Remove these once the sync-to script is taught to automatically clone these.
121+
qtbase
122+
qtshadertools
123+
qtdeclarative
124+
qtsvg
125+
qtimageformats
126+
qtactiveqt
127+
qtlanguageserver
128+
129+
COMMAND_ECHO STDOUT
130+
WORKING_DIRECTORY "${QT_DOC_TOOLS_SRC_DIR}"
131+
RESULT_VARIABLE result
132+
OUTPUT_STRIP_TRAILING_WHITESPACE
133+
)
134+
if(result)
135+
message(FATAL_ERROR "Cloning qttools submodule failed. Output: ${result}")
136+
endif()
137+
138+
# Allow pinning the qttools sha1 or any other git ref, based on a cmake var or env var.
139+
qt_internal_get_cmake_or_env_or_default(qttools_sync_to_ref QT_CI_DOC_TOOLS_PIN_GIT_REF "dev")
140+
141+
execute_process(
142+
COMMAND
143+
${CMAKE_COMMAND}
144+
-DSYNC_TO_MODULE=qttools
145+
"-DSYNC_TO_BRANCH=${qttools_sync_to_ref}"
146+
-DSHOW_PROGRESS=1
147+
-DVERBOSE=1
148+
-P cmake/QtSynchronizeRepo.cmake
149+
--log-level=DEBUG
150+
COMMAND_ECHO STDOUT
151+
WORKING_DIRECTORY "${QT_DOC_TOOLS_SRC_DIR}"
152+
RESULT_VARIABLE result
153+
OUTPUT_STRIP_TRAILING_WHITESPACE
154+
)
155+
if(result)
156+
message(FATAL_ERROR "Syncing qttools submodule dependencies failed: Output: ${result}")
157+
endif()
158+
endfunction()
159+
160+
# Configures a top-level static qt build for the checked out qt5.git sources.
161+
function(qt_internal_configure_qt)
162+
file(MAKE_DIRECTORY "${QT_DOC_TOOLS_BUILD_DIR}")
163+
file(MAKE_DIRECTORY "${QT_DOC_TOOLS_INSTALL_DIR}")
164+
165+
# Get the common CI args, to set the sccache args, etc.
166+
qt_internal_get_cmake_or_env_or_default(ci_common_cmake_args COMMON_CMAKE_ARGS "")
167+
if(ci_common_cmake_args)
168+
separate_arguments(ci_common_cmake_args NATIVE_COMMAND ${ci_common_cmake_args})
169+
endif()
170+
171+
execute_process(
172+
COMMAND
173+
"${QT_DOC_TOOLS_SRC_DIR}/configure"
174+
-release
175+
-static
176+
-prefix "${QT_DOC_TOOLS_INSTALL_DIR}"
177+
# Skip optional dependencies we don't need to build.
178+
-skip qtactiveqt,qtimageformats,qtlanguageserver,qtsvg
179+
--
180+
-DWARNINGS_ARE_ERRORS=OFF
181+
--log-level STATUS
182+
--fresh
183+
-GNinja
184+
${ci_common_cmake_args}
185+
186+
COMMAND_ECHO STDOUT
187+
WORKING_DIRECTORY "${QT_DOC_TOOLS_BUILD_DIR}"
188+
RESULT_VARIABLE result
189+
OUTPUT_STRIP_TRAILING_WHITESPACE
190+
)
191+
if(result)
192+
message(FATAL_ERROR "Configuring top-level qt5.git build failed. Output: ${result}")
193+
endif()
194+
endfunction()
195+
196+
# Builds the main doc tools in a configured qt5.git build.
197+
function(qt_internal_build_tools)
198+
execute_process(
199+
COMMAND
200+
cmake
201+
--build .
202+
--verbose
203+
--parallel
204+
--target
205+
qdoc
206+
qtattributionsscanner
207+
qdbusxml2cpp
208+
qdbuscpp2xml
209+
qvkgen
210+
COMMAND_ECHO STDOUT
211+
WORKING_DIRECTORY "${QT_DOC_TOOLS_BUILD_DIR}"
212+
RESULT_VARIABLE result
213+
OUTPUT_STRIP_TRAILING_WHITESPACE
214+
)
215+
if(result)
216+
message(FATAL_ERROR "Failed to build doc tools. Output: ${result}")
217+
endif()
218+
endfunction()
219+
220+
# Installs the built doc tools.
221+
function(qt_internal_install_tools)
222+
execute_process(
223+
COMMAND
224+
cmake
225+
--build .
226+
--target
227+
# TODO: Replace with ninja install_doc_tools_stripped once it lands.
228+
qttools/src/qdoc/qdoc/install/strip
229+
qttools/src/qtattributionsscanner/install/strip
230+
qtbase/src/tools/qdbusxml2cpp/install/strip
231+
qtbase/src/tools/qdbuscpp2xml/install/strip
232+
qtbase/src/tools/qvkgen/install/strip
233+
COMMAND_ECHO STDOUT
234+
WORKING_DIRECTORY "${QT_DOC_TOOLS_BUILD_DIR}"
235+
RESULT_VARIABLE result
236+
OUTPUT_STRIP_TRAILING_WHITESPACE
237+
)
238+
if(result)
239+
message(FATAL_ERROR "Failed to install doc tools. Output: ${result}")
240+
endif()
241+
endfunction()
242+
243+
function(qt_internal_run_script)
244+
qt_internal_prepare_build_paths()
245+
qt_internal_clone_qt5()
246+
qt_internal_sync_to_qttools()
247+
qt_internal_configure_qt()
248+
qt_internal_build_tools()
249+
qt_internal_install_tools()
250+
endfunction()
251+
252+
qt_internal_run_script()

0 commit comments

Comments
 (0)