不改一行上游代码:doxygen 移植鸿蒙 PC 的构建、踩坑与验证
欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/
欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
适配开源地址(Atomgit):https://atomgit.com/OpenHarmonyPCDeveloper/ohos_doxygen-opensource
目录
| 项目 | 说明 |
|---|---|
| 适配软件 | doxygen |
| 开源协议 | GPL-2.0 |
| 源码版本 | Release_1_18_0(1.18.0) |
| 目标平台 | 鸿蒙 PC |
| 交叉目标 | aarch64-linux-ohos、x86_64-linux-ohos |
| 构建宿主 | Linux x86_64 |
| 工具链 | zig-patch 0.16.0(clang 21.1.0 前端)+ CMake 4.4.5 + Ninja 1.13.2 |
| 上游改动 | 源码零修改,全部适配在 CMake toolchain 文件与编译选项里 |
| 产物 | out/aarch64/doxygen(23.83 MB)、out/x86_64/doxygen(24.78 MB),均已 strip |
| 验证方式 | 静态检查、对照实验、压力测试 |
| 上游地址 | https://github.com/doxygen/doxygen/tree/Release_1_18_0 |
| 适配仓库 | https://atomgit.com/OpenHarmonyPCDeveloper/ohos_doxygen-opensource |
doxygen 简介
doxygen 是一个从源码注释生成文档的工具。它读入带注释的源码,生成 HTML、LaTeX、RTF、man、XML、DocBook 等格式的文档,并在文档之间自动建立类继承、成员引用、调用关系等交叉链接。
doxygen 支持的语言很多:C、C++、C#、Objective-C、Python、Fortran、VHDL、Lex、SQL、XML、D 等。
本次适配的目标与产物
本次适配基于 doxygen 1.18.0,构建环境为 Linux x86_64。适配过程中上游 doxygen 源码树保持零修改。
移植路线:仅改动构建工具链层
doxygen 是一个纯 C++ 项目,构建系统是 CMake,词法与语法分析器由 flex 与 bison 在构建时生成。上游没有对鸿蒙进行适配。CMake 4.x 自带 Platform/OHOS.cmake,只要给出合适的编译器与编译选项,整套构建可以直接跑通。
| 层次 | 上游预期 | 鸿蒙侧的处理方式 |
|---|---|---|
| 构建系统 | CMake + Ninja | -DCMAKE_SYSTEM_NAME=OHOS,由 Platform/OHOS.cmake 完成交叉编译设置 |
| C/C++ 编译 | 环境 cc / c++ | zig-patch 的 zig cc1 / zig c++,目标三元组 aarch64-linux-ohos / x86_64-linux-ohos |
| 归档与索引 | ar / ranlib | zig ar / zig ranlib,用 shell 包装脚本转接 |
| C 标准库 | glibc | zig 自带的 OHOS musl 移植,动态链接到设备上的 libc.so |
| C++ 标准库 | libstdc++ 或 libc++_shared | zig 的 libc++ 静态内联,产物只依赖 libc.so |
| 词法 / 语法分析器生成 | 宿主 flex ≥ 2.5.37、bison ≥ 2.7 | 使用宿主工具生成 .cpp,生成物随平台无关 |
| 动态加载器 | 由工具链决定 | /lib/ld-musl-{aarch64,x86_64}.so.1,与 OHOS NDK 官方行为一致 |
build.sh 按以下步骤完成一次构建:
- 检查
cmake、ninja、doxygen-Release_1_18_0/与toolchain/zig-ohos/是否就位; - 用对应的 toolchain 文件执行
cmake -B build-ohos -S doxygen-Release_1_18_0 -G Ninja -DCMAKE_BUILD_TYPE=Release; - 执行
cmake --build build-ohos -j$(nproc) --target doxygen; - 把
build-ohos/bin/doxygen复制到out/<arch>/doxygen,调用toolchain/strip.sh移除符号; - 打印
file结果与NEEDED项做一次快速核查。
在 12 核机器上,从空的构建目录到 strip 完成的产物约需 3 分钟。
准备工具链
宿主依赖
doxygen 的构建需要 CMake 与 Ninja,还需要 flex 与 bison 生成分析器。用系统包管理器安装即可:
# Arch Linux
sudo pacman -Syu --noconfirm cmake ninja flex bison python git curl xz
# Ubuntu 24
sudo apt update && sudo apt install -y cmake ninja-build flex bison python3 git curl xz-utils
本次实测的版本:
cmake version 4.4.5
ninja 1.13.2
flex 2.6.4
bison (GNU Bison) 3.8.2
Python 3.14.8
strip 由 toolchain/strip.sh 完成,它按顺序查找 llvm-objcopy、objcopy,找到任一个就执行 --strip-all。宿主 binutils 或 LLVM 任一存在即可。
zig-patch
编译器使用zig for openharmony,版本 0.16.0。fetch-sources.sh 会下载到 downloads/zig-ohos.tar.xz 并解压到 toolchain/zig-ohos/,离线环境可以预先放好文件。
两个输入包都用 SHA-256 锁定,下载后自动校验,校验失败直接报错退出:
[1/3] doxygen Release_1_18_0 ...
SHA-256 OK: doxygen-Release_1_18_0.tar.gz
[2/3] zig-patch (openharmony-zig) 0.16.0 ...
SHA-256 OK: zig-ohos.tar.xz
[3/3] 解压 ...
toolchain/wrapper/zig-cc 仅用于封装对 zig 的调用,把 CMake 传来的参数原样交给 zig:
#!/bin/sh
exec "$(dirname "$(readlink -f "$0")")/../zig-ohos/zig" cc -target aarch64-linux-ohos "$@"
zig-c++、zig-ar、zig-ranlib 同理,toolchain/wrapper-x86_64/ 下是三元组换成 x86_64-linux-ohos 的一套。
HarmonyOS SDK 的作用
本次构建不需要 HarmonyOS SDK 参与编译。
适配中遇到的问题
zig 的链接器处理 --dependency-file 时直接崩溃
现象。 链接阶段连接器产生 SIGSEGV(退出码 139),且标准错误没有任何输出:
[269/270] Linking CXX executable bin/doxygen
FAILED: [code=139] bin/doxygen
原因。 CMake 3.27 起为 Ninja/Make 生成器引入了「由链接器生成链接依赖文件」的特性。CMake 判定当前链接器支持这个能力(CMAKE_CXX_LINKER_DEPFILE_SUPPORTED 为真),于是往链接命令里加了 -Xlinker --dependency-file=CMakeFiles/doxygen.dir/link.d。zig 0.16.0 内嵌的 ld.lld 不支持该选项,直接崩溃。
处理。 在 toolchain 文件里关掉该特性,让 CMake 回退到传统的重链接策略:
set(CMAKE_LINK_DEPENDS_USE_LINKER OFF)
验证。 修改后链接阶段链接器不再崩溃。
影响。 修改头文件引起的重链接判定改由 CMake 自己维护,构建时间略长,产物没有任何变化。
zig 在优化编译时注入 -Werror=date-time
现象。 一个目标编译失败:
doxygen-Release_1_18_0/src/pre.l:3644:19: error: expansion of date or time macro is not reproducible [-Werror,-Wdate-time]
3644 | resultExpr += __DATE__;
| ^
doxygen-Release_1_18_0/src/pre.l:3650:19: error: expansion of date or time macro is not reproducible [-Werror,-Wdate-time]
3650 | resultExpr += __TIME__;
原因。 doxygen 内置了一个 C 预处理器(src/pre.l)。它的任务之一就是把用户源码里的 __DATE__、__TIME__ 展开成日期时间字符串,这里出现这两个宏属于功能本身。zig 以可重现构建为目标,在 -O1 及更高优化级别自动往编译命令里加 -Werror=date-time,于是把这个功能判成错误。
处理。 把该诊断的级别降回警告:
set(CMAKE_C_FLAGS_INIT "-Wno-error=date-time")
set(CMAKE_CXX_FLAGS_INIT "-Wno-error=date-time")
验证。 去掉这个选项重新编译 src/pre.l 生成的 pre.cpp,错误复现;加上之后整个构建通过,并且只多出一条警告,不改变任何代码生成结果。
zig cc 默认带 -g,Release 产物膨胀到 201 MB
现象。 -O3 -DNDEBUG 之下未 strip 的 doxygen 有 211011464 字节(201 MiB),其中绝大部分是调试信息段。
原因。 zig cc 即使没有被要求也会默认开启调试信息。CMake 的 Release 配置里没有 -g,因此这个行为完全来自工具链的默认值。
处理。 在 Release 配置里显式关掉:
set(CMAKE_C_FLAGS_RELEASE_INIT "-O3 -DNDEBUG -g0")
set(CMAKE_CXX_FLAGS_RELEASE_INIT "-O3 -DNDEBUG -g0")
验证。 同一个单文件用例编译两次,带 -g0 的目标文件里没有任何 .debug_* 段,不带的里面有 6 个:
$ ./verify/repro.sh g0
=== zig cc 默认开启调试信息
不带 -g0:6 个调试信息段,3152 字节
带 -g0:0 个调试信息段,1520 字节
doxygen 本体在加 -g0 后未 strip 为 37506192 字节,llvm-objcopy --strip-all 之后 23826752 字节。
zig 的 objcopy --strip-all 未实现
现象。 想用 zig 自带的 objcopy 完成 strip,执行后报错:
$ zig objcopy --strip-all out/aarch64/doxygen out/aarch64/doxygen.stripped
error: unimplemented
处理。 toolchain/strip.sh 按顺序查找 llvm-objcopy 与 objcopy:
for CAND in llvm-objcopy objcopy; do
if command -v "$CAND" >/dev/null 2>&1; then
"$CAND" --strip-all "$BIN"
exit 0
fi
done
验证。 strip 后 file 输出带 stripped 标记,.debug_* 段数量为 0。
产物的静态核查
交叉编译产物能否在鸿蒙上运行,先做静态核查。
| 核查项 | aarch64 产物 | x86_64 产物 |
|---|---|---|
file 输出 | ELF 64-bit LSB pie executable, ARM aarch64, stripped | ELF 64-bit LSB pie executable, x86-64, stripped |
| interpreter | /lib/ld-musl-aarch64.so.1 | /lib/ld-musl-x86_64.so.1 |
| NEEDED | 仅 libc.so | 仅 libc.so |
| RUNPATH / RPATH | 无 | 无 |
| ELF 标志 | BIND_NOW、NOW PIE | 同 |
| GNU_STACK | RW(不可执行) | 同 |
首个 LOAD 段的 p_align | 0x10000(64 KB) | 0x1000(4 KB) |
| 动态未定义符号总数 | 196 | 196 |
其中 SDK sysroot libc.a 不存在的 | 0 | 0 |
| 产物大小 | 23826752 字节 | 24784064 字节 |
功能验证:与宿主基线对照
判断移植是否成功,靠逐项比较。做法是在宿主上额外构建一份 x86_64-linux-gnu 产物作为参照,两个平台跑同一批命令与同一批输入,比对标准输出、标准错误、退出码与生成的文件。
验证环境
鸿蒙设备的运行环境用 qemu-user 配合 Alpine musl 1.2.5 的 rootfs 模拟。运行环境使用 Alpine minirootfs 3.22.2。验证脚本统一从 verify/common.sh 取路径,默认值如下:
Q=downloads/qemu-aarch64
R=downloads/alpine-root
$Q -L $R out/aarch64/doxygen --version
1.18.0
x86_64 目标把 ARCH 换成 x86_64,对应的 qemu-x86_64 与 downloads/alpine-x64-root 随之生效,同一条命令同样输出 1.18.0。本节的全部结果由模拟环境产生,真机上的操作步骤见后面「在鸿蒙 PC 与设备上验证」一节。
宿主基线由同一份源码构建,不加任何交叉编译设置:
cmake -B build-host -S doxygen-Release_1_18_0 -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build-host -j"$(nproc)" --target doxygen
比对时的归一化处理有三类,都属于环境差异:
- 帮助文本与提示信息里回显的可执行文件路径,统一替换成
DOXYGEN; - HTML 页脚与日志里的
Generated on <时间戳>,统一替换成TS; - 搜索索引脚本里内嵌的输入目录绝对路径,统一替换成
ROOT。
CLI 20 个模式
每个模式在独立目录里各跑一次,比对标准输出、标准错误与退出码,并对生成的文件做逐字节比较。脚本是 verify/cli-alignment.sh:
$ ./verify/cli-alignment.sh
CLI: PASS=20 FAIL=0
=== 生成文件逐字节比对
SAME: g/Doxyfile(3052 行, 137390 字节)
...
| 序号 | 模式 | 比对内容 | 结果 |
|---|---|---|---|
| 1 | --version | 版本字符串 | PASS |
| 2 | -V | 版本与编译特性(含 sqlite3 3.51.3) | PASS |
| 3 | -v | 精简版本字符串 | PASS |
| 4 | -h | 52 行帮助文本 | PASS |
| 5 | -? | 同上,两者的输出一并比对 | PASS |
| 6 | -g | 默认模板 Doxyfile,3052 行 | PASS |
| 7 | -s -g | 无注释模板,426 行 | PASS |
| 8 | -g custom.txt | 自定义文件名的模板 | PASS |
| 9 | -l | DoxygenLayout.xml,269 行 | PASS |
| 10 | -l - | 布局模板写到标准输出 | PASS |
| 11 | -w rtf | RTF 样式表,103 行 | PASS |
| 12 | -w html | 页头 81 行、页脚 18 行、样式表 2607 行 | PASS |
| 13 | -w latex | 页头 290 行、页脚 50 行、样式 899 行 | PASS |
| 14 | -e rtf | RTF 扩展名清单,48 行 | PASS |
| 15 | -x | 与默认配置的差异展开 | PASS |
| 16 | -x_noenv | 不替换环境变量的展开 | PASS |
| 17 | -f emoji | emoji 映射表,1917 行 | PASS |
| 18 | -d nosuchtag | 非法调试标签:完整的参数清单与标签枚举 | PASS |
| 19 | -Z | 非法选项:error: Unknown option "-Z" | PASS |
| 20 | nosuch.cfg | 配置文件不存在:error: configuration file nosuch.cfg not found! | PASS |
20 个模式全部通过。生成的文件逐个逐字节比对,13 个文件全部一致。
-g 生成的默认配置与仓库里的基线文件 baseline/default-Doxyfile.txt 完全一致,311 个配置项一个不少;-h 的帮助文本与 baseline/help-output.txt 一致,共 52 行。两项由 verify/baseline-compare.sh 检查:
$ ./verify/baseline-compare.sh
=== 默认 Doxyfile
一致:3052 行,311 个配置项
=== 帮助文本
一致:52 行
补充的几项在 verify/extras.sh 里:
| 项目 | 内容 | 结果 |
|---|---|---|
-u 更新旧配置 | 构造删掉 4 行、修改 1 行的旧配置,与默认模板合并后重新写出 | 更新后的 3052 行文件一致,提示文本与退出码一致 |
-x 配置展开 | 对同一份旧配置输出差异项 | 标题行加 4 行差异项一致 |
| 标准输入 | doxygen - 从标准输入读配置 | 两条警告与退出码一致 |
-d preprocessor | 在测试项目上输出预处理诊断,498 行 | 一致 |
-d commentscan | 注释扫描诊断,1298 行 | 一致 |
-d extcmd | 外部命令诊断,137 行 | 一致 |
完整文档生成
测试项目是一个自包含的 C++/C 混合演示库,覆盖类、继承、模板类、enum class、命名空间、C 文件、中文注释与 Markdown 主页。两个平台各生成一次,比对全部产物:
$ ./verify/doc-generation.sh
=== 文件集合
集合一致:143 个文件
=== 逐文件比对
逐文件: SAME=143 DIFF=0
143 个文件包括 HTML 页面、search/ 下的索引脚本、PNG 图形与 PHP 脚本。HAVE_DOT=NO、GENERATE_LATEX=NO,因此不涉及外部程序。中文内容正常呈现在生成结果中:
$ grep -o "注册成功" html/classsensor_1_1SensorService.html
注册成功
$ grep -o "实机验证测试项目" html/index.html
实机验证测试项目
$ grep -o "含中文注释路径" html/sensor__service_8cpp.html
含中文注释路径
SERVER_BASED_SEARCH=YES 打开时会额外生成 search/search.idx 与 4 个 PHP 脚本。这一项在 aarch64 与 x86_64 两个鸿蒙目标之间逐字节一致;与宿主 glibc 产物相比,search.idx 有 552 字节不同:
$ ./verify/server-search.sh
=== aarch64 与 x86_64
集合一致:79 个文件
逐文件: SAME=79 DIFF=0
$ ./verify/server-search.sh --vs-host
=== aarch64 与宿主基线
集合一致:79 个文件
DIFF: ./search/search.idx
逐文件: SAME=78 DIFF=1
把两个索引文件按格式解开逐项对比(verify/search-index-diff.py),词表完全相同,309 个词条一个不差,差异只在 67 个词条内部的 URL 配对次序,且每个词条的配对集合完全相同:
$ python3 verify/search-index-diff.py verify-out/server-search/a/html/search/search.idx \
verify-out/server-search/h/html/search/search.idx
词条数: 309 309
词表相同: True
URL 列表次序不同的词条数: 67
其中配对集合相同的: 67
词: accept
侧一: [(274647, 3), (278663, 2)]
侧二: [(278663, 2), (274647, 3)]
这一项的来源是 SearchIndex::IndexWord 用 std::unordered_map<int,URLInfo> 保存 URL 列表(doxygen-Release_1_18_0/src/searchindex.h),写入时按容器遍历顺序输出,而 libc++ 与 libstdc++ 的遍历次序不同。用 verify/umap-order.cpp 直接对比两个标准库实现即可看到差异,且与优化级别无关:
$ ./verify/repro.sh umap
=== unordered_map 的遍历次序
libc++(zig) : 遍历顺序: 9 25 3 41 30 18 7 12
libstdc++(宿主): 遍历顺序: 18 9 3 41 7 30 25 12
同一工具链构建的两个目标之间没有这个差异。
编码转换
doxygen 内部统一使用 UTF-8,读入其它编码的源码时通过 iconv 转换。用一个 GBK 编码的 C 文件验证,脚本是 verify/gbk-encoding.sh:
$ file src/gbk_demo.c
src/gbk_demo.c: ISO-8859 text
配置 INPUT_ENCODING=GBK 之后,中文文件简要、函数说明与参数说明都正确出现在 HTML 里:
温度采样工具
采样并返回摄氏度
原始采样值
29 个产物文件与宿主产物逐个一致(含 search/ 子目录)。musl 内置的 iconv 覆盖 GBK、GB18030、Big5,与 OHOS musl 的字符集集合相同。
压力测试
用 doxygen 解析它自己的源码树(src/ 与 vhdlparser/,334 个文件、约 31.8 万行),脚本是 verify/stress-test.sh:
| 指标 | aarch64(qemu) | 宿主 x86_64 |
|---|---|---|
| 退出码 | 0 | 0 |
| 耗时 | 83.4 秒 | 6.7 秒 |
| HTML 页面数 | 2039 | 2039 |
html/ 下条目数 | 3391 | 3391 |
| 产物体积 | 123 MB | 123 MB |
| 全部产物文件数 | 3631 | 3631 |
| 逐文件比对 | 3631 个全部一致 | — |
qemu 用户态模拟带来的减速约 12 倍,属于模拟开销,设备上直接运行不受影响。3631 个文件里包括 2039 个 HTML 页面、搜索索引、PNG 图形与样式文件,全部逐字节一致:
$ ./verify/stress-test.sh
=== 运行
a: 退出码 0,耗时 83391 ms,HTML 页面 2039 个,条目 3391 个
h: 退出码 0,耗时 6715 ms,HTML 页面 2039 个,条目 3391 个
=== 产物比对
集合一致:3631 个文件
逐文件: SAME=3631 DIFF=0
两个目标之间的一致性
把 -fsigned-char 统一加进两个 toolchain 文件之后,aarch64 与 x86_64 的产物在同一份输入上生成完全相同的文档:
$ ARCH=x86_64 ./verify/doc-generation.sh
逐文件: SAME=143 DIFF=0
功能划分
状态依据适配仓库里的核查记录与上面的验证结果填写。
T0 基础
| 功能 | 状态 | 备注 |
|---|---|---|
| 程序启动与运行环境 | 支持 | 仅依赖 libc.so,无需额外部署运行库 |
| 命令行参数与入口 | 支持 | 20 个模式与宿主逐字节一致 |
| 配置读写 | 支持 | 311 个配置项,默认模板 3052 行,-g / -s -g / -u / -x 均一致 |
| 退出码与错误处理 | 支持 | 成功 0,配置或参数错误 1,报错文本一致 |
T1 核心
| 功能 | 状态 | 备注 |
|---|---|---|
| 源码解析与实体建模 | 支持 | 文件、命名空间、类、结构体、模板、函数、变量、宏,自动生成继承与引用关系;内置 C 预处理器可用 |
| 多语言源码解析 | 支持 | Python、Fortran、VHDL、Lex、SQL、XML、C#、Objective-C、D 的分析器都编在同一可执行文件内 |
| HTML 文档生成与交叉引用 | 支持 | 文件页、类页、命名空间页、成员页,源码浏览带语法高亮;类继承图由内置生成器绘制(PNG 加 image map,不需要 dot) |
| 文档注释命令与 Markdown | 支持 | \brief / \param / \return 等命令、Markdown 语法、USE_MDFILE_AS_MAINPAGE 主页均可用,中文注释正常呈现 |
| 客户端搜索 | 支持 | 由生成的 search/*.js 提供索引与实时搜索 |
| 服务端搜索索引 | 支持 | SERVER_BASED_SEARCH=YES 时生成 search.idx 与 PHP 脚本,两个目标之间一致 |
| 字符编码转换 | 支持 | INPUT_ENCODING=GBK 经 musl 内置 iconv 正确转换,覆盖 GBK、GB18030、Big5 |
| 中文界面 | 支持 | OUTPUT_LANGUAGE=Chinese 可用 |
T2 其它与边界
| 功能 | 状态 | 备注 |
|---|---|---|
| Graphviz 扩展图 | 支持(需要外部程序) | 类层次、包含依赖、调用关系、协作图由外部 dot 绘制;产物不含 Graphviz,HAVE_DOT=YES 时需要设备侧提供 |
| LaTeX 输出与 PDF 编译 | 支持(需要外部程序) | -w latex 的 13 项样式产物一致;把 .tex 编译成 PDF 需要设备侧安装 LaTeX 发行版 |
| RTF / man / XML / DocBook 输出 | 支持 | |
| 外部过滤器与外部命令 | 支持(需要外部程序) | FILTER_PATTERNS、INPUT_FILTER 经 /bin/sh -c 调用,设备需提供可用的 /bin/sh |
| 第三方帮助格式与跨项目引用 | 支持 | |
| Windows HTML Help(CHM) | 未支持 | GENERATE_HTMLHELP=YES 需要 Windows 的 HTML Help Workshop,鸿蒙上没有该程序 |
| 标准输入读配置 | 支持 | doxygen - 可用 |
在鸿蒙 PC 与设备上验证
设备测试包里准备了自检脚本,覆盖版本输出、完整文档生成与关键内容检查。
推送与签名
鸿蒙 PC 要求可执行文件在运行前签名2。把测试包推到设备后解压:
hdc file send doxygen-ohos-1.18.0-aarch64-device-test.tar.gz /data/local/tmp/
hdc shell "cd /data/local/tmp && mkdir -p doxtest && tar xzf doxygen-ohos-1.18.0-aarch64-device-test.tar.gz -C doxtest"
在设备终端里完成签名并赋予执行权限:
cd /data/local/tmp/doxtest
binary-sign-tool sign -inFile doxygen -outFile doxygen_signed -selfSign "1"
mv doxygen_signed doxygen
chmod 755 ./doxygen
一键自检
sh run.sh ./doxygen
脚本按四步执行,最后打印结论:
=== [1/4] version ===
1.18.0
=== [2/4] generate docs ===
exit=0
=== [3/4] verify output ===
=== [4/4] summary ===
html files: 71
html pages: 39
type lookup cache used 49/65536 hits=48 misses=54
symbol lookup cache used 88/65536 hits=459 misses=88
finished...
DEVICE TEST PASSED

自检的内容:
| 步骤 | 检查项 |
|---|---|
| 版本 | --version 输出 1.18.0 |
| 文档生成 | doxygen Doxyfile 生成到 html/,退出码 0 |
| 页面存在 | index.html、classsensor_1_1SensorService.html、classsensor_1_1ThresholdFilter.html、legacy__util_8c.html |
| 内容正确 | 枚举 AlarmLevel 出现在命名空间页,中文类成员注释、中文文件简要、README 主页标题都出现在对应页面 |
| 统计 | 输出 html/ 下的文件数量与日志最后三行 |
同一套脚本在 qemu 加 Alpine musl 的环境里跑过一遍,结果是 DEVICE TEST PASSED:html/ 下 71 个顶层条目、39 个 HTML 页面,与宿主的产物一致。测试项目使用 HAVE_DOT=NO、GENERATE_LATEX=NO,不依赖设备上的外部程序。
常见问题(FAQ)
Q1:产物拷到设备上执行报权限错误。
鸿蒙 PC 要求可执行文件先签名。用 binary-sign-tool sign -selfSign "1" 做一次调试签名,再执行 chmod 755。
Q2:链接阶段进程收到 SIGSEGV,没有任何报错输出。
CMake 3.27 及更高版本会给链接器传 --dependency-file,zig 内嵌的 ld.lld 处理该选项时崩溃。确认 toolchain 文件里有 set(CMAKE_LINK_DEPENDS_USE_LINKER OFF),并且构建目录是重新配置过的(旧目录会沿用缓存的生成规则)。
Q3:编译时报 expansion of date or time macro is not reproducible。
zig 在 -O1 及以上优化级别注入 -Werror=date-time,而 doxygen 的 src/pre.l 需要展开 __DATE__ / __TIME__。确认 toolchain 文件里有 -Wno-error=date-time。
Q4:生成的 search/*.js 与其它平台次序不同。
aarch64 的 char 默认无符号,doxygen 的 dstrcmp 兜底比较会得到相反的结果。确认 toolchain 文件里有 -fsigned-char。
Q5:设备上没有 dot,生成文档时报错或警告。
把 HAVE_DOT 设为 NO,内置的类继承图仍然会生成。需要使用扩展图时在设备侧安装 Graphviz 并保证 dot 在 PATH 中。
Q6:FILTER_PATTERNS 或 INPUT_FILTER 不生效。
doxygen 通过 /bin/sh -c 调用过滤程序。设备上缺少可用的 /bin/sh 时,改为提供预生成的输入文件,或用 INCLUDE_PATH 处理头文件搜索。
后续
后续拟继续推进的方向:
- zig 的
--dependency-file崩溃:向 zig-patch 上游反馈;该选项被正确处理之后可以去掉 toolchain 里的规避设置,恢复由链接器生成的依赖文件。 char符号性依赖:doxygen 的dstricmp直接对char做减法,平台默认值会影响输出次序。适配层已用-fsigned-char统一行为,上游若把比较改成显式的unsigned char,这一项就不再需要工具链介入。- 设备侧外部程序:Graphviz 与 LaTeX 需要自行提供。
参考资料:
- doxygen 上游仓库:https://github.com/doxygen/doxygen/tree/Release_1_18_0
- zig-patch 发行版:https://github.com/openharmony-zig/zig-patch/releases/tag/0.16.0
- CMake 的
CMAKE_LINK_DEPENDS_USE_LINKER变量说明:https://cmake.org/cmake/help/latest/variable/CMAKE_LINK_DEPENDS_USE_LINKER.html - HarmonyOS SDK 命令行工具下载:https://developer.huawei.com/consumer/cn/download/command-line-tools-for-hmos
- 适配仓库:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_doxygen-opensource
更多推荐


所有评论(0)