系列导读：本文是 Lycium 适配系列的第五篇，通过一张完整的流程图展示适配者、Lycium 框架和 OHOS SDK 三者之间的交互关系，并总结各环节的角色职责。
欢迎加入【开源鸿蒙PC社区】，一起共建鸿蒙化C/C++三方库生态。
前言
| 项目 | 说明 |
|---|---|
| macOS环境配置 | https://bxming.blog.csdn.net/article/details/159284830 |
| Ubuntu环境配置（或者windows + wsl） | https://bxming.blog.csdn.net /article/details/159284760 |
| lycium框架 | https://atomgit.com/OpenHarmonyPCDeveloper/lycium_plusplus.git |
| 应用平台 | HarmonyOS PC |
系列索引
| 篇章 | 标题 | 内容 |
|---|---|---|
| 第一篇 | 概述与环境配置 | Lycium 概念、构建机要求、OHOS SDK 配置 |
| 第二篇 | 项目结构与适配目录创建 | 目录结构、community vs thirdparty、创建适配目录 |
| 第三篇 | HPKBUILD 编写详解 | 元数据字段、过程函数、三种构建系统写法 |
| 第四篇 | 构建执行与产物获取 | 构建流程、日志分析、多库递归、HAP 集成 |
| 第五篇 | 流程图与角色职责 | 完整流程图、各角色职责、协作时序 |
| 第六篇 | 关键注意事项与最佳实践 | 依赖管理、架构超集、日志调试、外部适配仓 |
| 第七篇 | 快速参考与模板 | 入门步骤、模板、完整案例、检查清单 |
1. 完整流程图
流程图解读
这张图清晰地展示了三个角色在适配流程中的交互：
| 角色 | 列 | 主要工作 |
|---|---|---|
| 开发者 | 环境搭建 → 创建 HPKBUILD → 执行构建 → 获取产物 | 输出"做什么"（HPKBUILD 中的构建逻辑） |
| Lycium 框架 | 加载环境 → 解析依赖 → 调度构建 → 循环多架构 | 负责"怎么做"（编排整个构建流程） |
| OHOS SDK | 提供编译器、toolchain、sysroot | 提供"用什么做"（交叉编译能力） |
2. 各环节角色职责总结
适配者（库维护者）
适配者是整个流程的核心驱动者，负责：
| 序号 | 职责 | 说明 |
|---|---|---|
| ① | 搭建编译环境 | 安装基础工具 + 下载配置 OHOS SDK |
| ② | 创建适配目录、编写 HPKBUILD | 核心工作：定义元数据 + prepare/build/package 三核心函数 |
| ③ | 编写开源合规文件 | README.OpenSource、OAT.xml |
| ④ | 生成 SHA512SUM 校验值 | 下载源码包后用 sha512sum 生成 |
| ⑤ | 编写 OH 补丁 | 对上游代码做适配修改 |
| ⑥ | 调试构建失败 | 分析日志、迭代 HPKBUILD |
| ⑦ | 编写 HAP 集成文档 | docs/hap_integrate.md |
| ⑧ | HNP 打包配置 | hnp.json 配置 |
Lycium 框架（build.sh + build_hpk.sh）
框架是自动化编排引擎，负责：
| 序号 | 职责 | 说明 |
|---|---|---|
| ① | 加载交叉编译环境 | envset.sh 根据不同架构设置编译器路径、CFLAGS 等 |
| ② | 依赖拓扑解析与递归调度 | 读取 depends[]，自动排序和递归构建 |
| ③ | 多架构循环执行构建 | 为 archs[] 中每个架构依次执行完整流程 |
| ④ | 自动注入构建参数 | $buildargs（toolchain file、搜索路径、安装前缀）和 $pkgconfigpath |
| ⑤ | 调用 HPKBUILD 各阶段函数 | 按顺序调用 prepare → build → package → archive → check |
| ⑥ | 源码管理 | 下载、校验（SHA512SUM）、解压 |
| ⑦ | 构建日志记录 | 每个架构独立日志文件 |
| ⑧ | 产物管理 | 安装目录组织、归档打包、构建记录 CSV |
OHOS SDK
SDK 是基础设施提供者，负责：
| 序号 | 职责 | 说明 |
|---|---|---|
| ① | 交叉编译器 | arm-linux-ohos-clang、aarch64-linux-ohos-clang 等 |
| ② | LLVM 工具链 | ld.lld、llvm-ar、llvm-strip、llvm-ranlib、llvm-nm、llvm-objcopy 等 |
| ③ | CMake + Toolchain | OHOS 定制的 cmake + ohos.toolchain.cmake |
| ④ | musl libc sysroot | OpenHarmony 系统的 C 运行时库 |
| ⑤ | HNP 打包工具 | hnpcli |
HPKBUILD 的角色定位
HPKBUILD 是整个适配流程中的适配契约：
HPKBUILD 以声明式 + 过程式的形式告知框架：
① 元数据：库名、版本、架构、依赖、源码地址
② 构建逻辑：prepare/build/package 等函数的具体实现关键原则 ：框架只提供编排和工具链，不介入具体构建逻辑。具体的编译参数、安装方式等全部由 HPKBUILD 决定。
应用开发者
应用开发者是最终消费者，职责相对简单：
| 序号 | 职责 | 说明 |
|---|---|---|
| ① | 获取产物 | 从 usr/<pkgname>/<arch>/ 或 output/ 获取已构建好的库文件 |
| ② | 集成到 HAP | 将 .so / .a / .h 文件复制到 HAP 工程目录 |
| ③ | 配置链接 | 在 HAP 工程的 CMakeLists.txt 中配置 target_link_libraries |
| ④ | 验证集成 | 参考 docs/hap_integrate.md 验证集成正确性 |
3. 角色协作时序
4. 多依赖链示例时序
当目标库有多个依赖时，框架会自动按拓扑排序依次构建。以 libcurl（依赖 openssl、zlib、nghttp2）为例：
关键提示：适配者只需编写目标库的 HPKBUILD，依赖库由框架自动解决。如果某个依赖也已适配，直接复用；如果未适配，框架会报错提示需要优先构建依赖。
5. 适配全流程速查表
| 阶段 | 输入 | 输出 | 负责方 |
|---|---|---|---|
| 0. 环境准备 | 空 | 构建工具 + OHOS SDK | 适配者 |
| 1. 创建适配目录 | 下载的源码包 | thirdparty/<pkgname>/ 目录结构 | 适配者 |
| 2. 编写 HPKBUILD | 库的构建文档 | HPKBUILD（元数据 + 函数） | 适配者 |
| 3. 构建执行 | HPKBUILD | usr/<pkgname>/ 下的产物 |
Lycium 框架 |
| 4. 产物获取 | 安装目录中的 .so/.a/.h | 归档包 / HNP 包 | 适配者 / 框架 |
| 5. HAP 集成 | 库产物 | 可运行的 HAP 应用 | 应用开发者 |
下篇预告
了解了整体流程和角色职责后，下一篇将总结适配过程中的关键注意事项和最佳实践，包括依赖管理、架构超集规则、SHA512SUM 校验、日志调试技巧、外部适配仓等内容。