OpenHarmony开发中管理275个C/C++三方库的构建难题如何破解？lycium_plusplus框架通过自动依赖解析、批量交叉编译和HNP包生成，让复杂的三方库适配工作变得高效可控。本文将深度解析其架构设计与核心模块，展示从源码到产物的完整构建流程。

做 OpenHarmony 开发时，你大概率会遇到这样的需求：我要用 OpenSSL、zlib、curl 这些经典 C/C++ 库，但它们不是为 OpenHarmony 写的，怎么编译？怎么打包？怎么管理依赖？

一个库还好，手动写个 CMake 也能搞定。但如果你要管理 275 个三方库呢？每个库的构建方式不同、依赖关系不同、支持架构不同——手动管理根本不现实。

lycium_plusplus 就是解决这个问题的。它是 OpenHarmony C/C++ 三方库的构建框架，能自动解析依赖关系、批量交叉编译、生成 HNP 安装包，让 275 个三方库的构建从”不可能完成的任务”变成”一条命令搞定”。

这篇文章就从顶层到底层，把 lycium_plusplus 的架构、核心模块、工作流程讲清楚。

背景：为什么需要这个项目

三方库适配的痛点

在 OpenHarmony 上使用三方库，需要解决这些问题：

lycium_plusplus 的定位

lycium_plusplus 是 lycium 构建框架的增强版，在原始 lycium 的基础上增加了：

• 依赖关系树构建：自动解析依赖，按正确顺序编译
• 多版本构建能力：支持外部适配仓，独立发布
• HNP 产物生成：生成 HarmonyOS 可安装的原生包
• 华为电脑本机编译：在鸿蒙 PC 上直接编译，无需交叉编译
• 外部仓库支持：通过 module.json 管理外部适配仓

项目整体架构

目录结构

lycium_plusplus/

├── README.md # 项目说明

├── LICENSE # 许可证

├── 经验之谈.md # 开发经验分享

│├── lycium/ # 核心构建框架

│ ├── build.sh # 主构建脚本（交叉编译入口）

│ ├── build_local.sh # 本机构建脚本（鸿蒙PC入口）

│ ├── test.sh # 设备端测试脚本

│ ├── script/ # 核心脚本

│ │ ├── build_hpk.sh # 单包构建脚本

│ │ ├── envset.sh # 环境变量设置

│ │ └── load_outer_parts.py # 外部模块下载

│ ├── Buildtools/ # 工具链

│ ├── CItools/ # CI 测试环境工具

│ ├── template/ # HPKBUILD/HPKCHECK 模板

│ ├── docker/ # Docker 构建环境

│ ├── doc/ # 文档

│ ├── output/ # 构建产物输出

│ └── usr/ # 编译安装目录

│├── thirdparty/ # 三方库源码（275个库）

│ ├── sha/ # SHA 加密库

│ ├── openssl/ # OpenSSL

│ ├── zlib/ # zlib 压缩库

│ ├── curl/ # libcurl│ └── … # 更多库

│├── community/ # 社区适配库（132个）

│└── external_deps/ # 外部依赖仓

└── module.json # 外部模块配置

架构分层

┌─────────────────────────────────────────────────────────────┐

│ 用户层 │

│ 开发者执行 ./build.sh &lt；库名&gt； │

└─────────────────────────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│ 构建框架层（lycium/） │

│ │

│ build.sh ─── 主流程控制、依赖解析、多架构循环 │

│ build_hpk.sh ─── 单包构建（prepare→build→package→archive） │

│ envset.sh ─── 架构环境设置（setarm32ENV/setarm64ENV） │

│ load_outer_parts.py ─── 外部仓库下载 │

└─────────────────────────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│ 包定义层（thirdparty/） │

│ │

│ 每个库目录包含： │

│ HPKBUILD ─── 构建定义（元数据+函数） │

│ HPKCHECK ─── 测试定义 │

│ hnp.json ─── HNP 包配置 │

│ *.patch ─── 适配补丁 │

│ README.OpenSource ─── 开源声明 │

└─────────────────────────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│ 工具链层 │

│ │

│ OpenHarmony SDK ─── 交叉编译工具链（clang/cmake/hnpcli） │

│ Buildtools/ ─── 辅助工具 │

│ CItools/ ─── 设备端测试工具 │

└─────────────────────────────────────────────────────────────┘

核心模块详解

1. build.sh — 主构建脚本

位置：lycium/build.sh（476 行）

通俗理解：这是整个框架的”总调度”。你执行 ./build.sh sha，它就负责把 SHA 库从源码编译成 HNP 包，包括自动处理依赖。

核心流程：

./build.sh sha

│

├─

1. preparetoolchain 检查并准备 OpenHarmony SDK 工具链

│

├─

2. checkbuildenv 检查构建环境（gcc/cmake/make 等）

│

├─

3. loaddonelibs 读取已构建完成的库列表

│

├─

4. collectcommunitylibs 收集社区库信息

│

├─

5. load_outer_parts 下载外部适配仓（module.json 中定义的）

│

├─

6. findarglibsdir 查找目标库目录

│

├─

7. prepareshell 准备 Shell 环境

│

├─

8. buildhpk 执行构建（核心！）

│ │

│ │ 对每个架构（arm32/arm64）：

│ │ 对每个库（按依赖顺序）：

│ │ source HPKBUILD

│ │ prepare() → build() → package() → archive()

│ │

│ └─

9. cleanhpkdir 清理临时目录

│

└─ 完成！产物在 output/ 目录

支持的操作系统：

依赖解析：这是 build.sh 最核心的能力。当构建 curl 时，它会：

1. 读取 curl 的 HPKBUILD，发现 depends=(openssl zlib)
2. 检查 openssl 和 zlib 是否已构建
3. 如果没有，先构建 zlib（无依赖），再构建 openssl（依赖 zlib），最后构建 curl
4. 构建顺序自动确定，无需手动指定

2. build_local.sh — 本机构建脚本

位置：lycium/build_local.sh

通俗理解：在华为鸿蒙 PC 上直接编译的入口。和 build.sh 的区别是，它检测到当前系统是 HarmonyOS 后，设置本机编译标志，跳过交叉编译步骤。

核心逻辑：

# 检测是否为 HarmonyOS

if [ “${OS_NAME:0:5}” == “Harmo” ]; then

TARGET_HARMONYOS=”true”

# 设置本机编译路径

INSTALL_LOCAL_PERFIX=/usr/local

fi

# 最终还是调用 build.sh

./build.sh “$@”

使用场景：在华为 MateBook 等鸿蒙 PC 上开发时，可以直接编译，不需要 OpenHarmony SDK 的交叉编译工具链。

3. test.sh — 设备端测试脚本

位置：lycium/test.sh（203 行）

通俗理解：编译好的库需要在真实设备上测试。test.sh 就是把测试程序推送到 OpenHarmony 设备上执行的脚本。

核心流程：

test.sh

│

├─

1. 检查测试环境（cmake/make/ctest/perl）

│

├─

2. 获取 CPU 架构（arm64-v8a / armeabi-v7a）

│

├─

3. 设置动态库加载路径（LD_LIBRARY_PATH）

│

├─

4. 遍历已编译库

│ │

│ └─ 对每个库：

│ source HPKCHECK

│ 执行 openharmonycheck()

│ 记录测试结果

│

└─

5. 输出测试报告（成功/失败统计）

4. script/envset.sh — 环境变量设置

位置：lycium/script/envset.sh

通俗理解：不同架构需要不同的编译器和工具链。envset.sh 提供了一组函数，按架构设置正确的环境变量。

提供的函数：

每个 set 函数设置的关键变量包括：CC、CXX、LD、AR、NM、RANLIB、STRIP、OBJDUMP、HNP_TOOL 等。

5. script/build_hpk.sh — 单包构建脚本

位置：lycium/script/build_hpk.sh

通俗理解：build.sh 负责调度，build_hpk.sh 负责执行单个库的具体构建。它读取库的 HPKBUILD，按顺序调用 prepare() → build() → package() → archive() 函数。

6. script/load_outer_parts.py — 外部模块下载

位置：lycium/script/load_outer_parts.py

通俗理解：从 external_deps/module.json 读取外部适配仓信息，自动 git clone 到 thirdparty 目录。

thirdparty/ — 三方库仓库

规模与分类

thirdparty 目录包含 275 个三方库，是整个项目的”原料仓库”。

每个库的标准目录结构

以 SHA 库为例：

thirdparty/sha/

├── HPKBUILD # 构建定义（必需）

├── HPKCHECK # 测试定义（必需）

├── hnp.json # HNP 包配置（必需）

├── README.OpenSource # 开源声明（必需）

├── sha_ohos.patch # 适配补丁（按需）

├── README_zh.md # 中文文档（推荐）

├── SHA512SUM # 校验和（推荐）

├── OAT.xml # OAT 扫描配置（推荐）

├── .gitignore # Git 忽略规则（推荐）

└── docs/ # 详细文档（推荐）

必需文件：缺少任何一个，构建系统都无法正常工作。

external_deps/ — 外部依赖管理

module.json 的作用

external_deps/module.json 定义了外部适配仓的信息——不在本仓库内维护、但构建时需要的三方库。

当前配置了 22 个外部模块，部分示例：

工作流程：

构建开始

│

├─ 读取 external_deps/module.json

│

├─ 对每个外部模块：

│ git clone <url> -b <branch>

│ 放到 thirdparty/<name>/

│

└─ 继续正常构建流程

为什么需要外部依赖？ 有些库的适配仓由其他团队维护，或者版本更新频繁，不适合放在主仓库里。通过 module.json 引用，构建时自动下载，保持主仓库精简。

CItools/ — CI 测试环境工具

问题背景

OpenHarmony 设备上默认没有 make、cmake、ctest 等构建测试工具。但三方库的测试（HPKCHECK 中的 openharmonycheck()）需要这些工具。

解决方案

CItools 提供了这些工具在 ARM 架构上的预编译版本和编译指导：

CItools/

├── env_build.sh # 一键部署脚本

├── busybox/ # busybox（含 make 等基础命令）

├── cmake/ # CMake

├── make/ # GNU Make

├── perl/ # Perl

└── shell_cmd/ # Shell 命令行工具

每个工具目录下有三种架构的编译指导文档：

1. xxx_armeabi-v7a_Compilation_instructions.md
2. xxx_arm64_v8a_Compilation_instructions.md
3. xxx_x86_64_compilation_instructions.md

template/ — HPKBUILD 模板

位置：lycium/template/

通俗理解：新建三方库适配时的”脚手架”。包含 HPKBUILD、HPKCHECK、SHA512SUM 的模板文件，复制后修改即可。

完整构建流程示例

以构建 SHA 库为例，展示从命令到产物的完整流程：

$ cd lycium &&amp； ./build.sh sha

┌─────────────────────────────────────────────────────────────┐

│

1. 环境准备 │

│ ├─ 检测操作系统（Linux/macOS/HarmonyOS） │

│ ├─ 检查 OpenHarmony SDK 是否安装 │

│ ├─ 检查构建工具（gcc/cmake/make/git/patch） │

│ └─ 加载外部依赖仓（module.json → git clone） │

└─────────────────────────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│

2. 依赖解析 │

│ ├─ 读取 sha/HPKBUILD │

│ ├─ depends=() → 无依赖 │

│ └─ 构建顺序：[sha] │

│ │

│ （如果是 curl，则：depends=(openssl zlib) │

│ → 构建顺序：[zlib, openssl, curl]） │

└─────────────────────────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│

3. 架构循环：armeabi-v7a │

│ ├─ ARCH=armeabi-v7a │

│ ├─ source HPKBUILD │

│ ├─ prepare() → git clone + patch │

│ ├─ build() → cmake + make（arm-linux-ohos-clang） │

│ ├─ package() → make install │

│ └─ archive() → tar.gz + HNP（setarm32ENV → pack） │

└─────────────────────────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│

4. 架构循环：arm64-v8a │

│ ├─ ARCH=arm64-v8a │

│ ├─ source HPKBUILD │

│ ├─ prepare() → 跳过下载（已下载） │

│ ├─ build() → cmake + make（aarch64-linux-ohos-clang）│

│ ├─ package() → make install │

│ └─ archive() → tar.gz + HNP（setarm64ENV → pack） │

└─────────────────────────────────────────────────────────────┘

│

▼

┌─────────────────────────────────────────────────────────────┐

│

5. 产物输出 │

│ output/ │

│ ├── armeabi-v7a/ │

│ │ ├── sha.hnp │

│ │ └── sha_3ee0d88….tar.gz │

│ └── arm64-v8a/ │

│ ├── sha.hnp │

│ └── sha_3ee0d88….tar.gz │

└─────────────────────────────────────────────────────────────┘

两种构建模式对比

项目数据一览

常见问题

Q1：如何构建单个库？

cd lycium

./build.sh sha # 构建 SHA 库

./build.sh openssl # 构建 OpenSSL

Q2：如何构建有依赖的库？

./build.sh curl # 自动先构建 zlib 和 openssl

构建系统会自动解析 HPKBUILD 中的 depends 变量，按依赖顺序构建。

Q3：如何添加新的三方库？

1. 在 thirdparty/ 下创建库目录
2. 复制 lycium/template/ 中的模板文件
3. 修改 HPKBUILD（包名、版本、源码地址、构建函数）
4. 修改 HPKCHECK（测试逻辑）
5. 创建 hnp.json（包配置）
6. 编写适配补丁（如需要）
7. 测试构建：./build.sh <库名>

Q4：如何在设备上测试？

#1. 部署 CItools 到设备

cd lycium/CItools && ./env_build.sh

#2. 执行测试

cd lycium && ./test.sh

Q5：external_deps 中的库和 thirdparty 中的有什么区别？

• thirdparty：主仓库内维护的库，代码直接在本仓库
• external_deps：外部团队维护的库，构建时从 gitcode.com 自动下载

两者在构建流程中没有区别，只是代码来源不同。

Q6：构建失败怎么排查？

1. 查看构建日志：thirdparty/<库名>/<库名>_<版本>_<架构>_lycium_build.log
2. 查看 last_error 文件
3. 手动进入源码目录，逐步执行 prepare/build/package 验证
4. 检查 HPKBUILD 中的变量和函数是否正确

总结

lycium_plusplus 是 OpenHarmony 三方库生态的基础设施，它解决的核心问题是：让 275 个 C/C++ 三方库在 OpenHarmony 上能自动、可重现、可依赖地构建。

核心能力

项目哲学

1. 声明式构建：每个库只需写一个 HPKBUILD 声明”怎么构建”，框架负责”怎么调度”
2. 依赖自动化：开发者只需 ./build.sh curl，框架自动处理 zlib → openssl → curl 的构建顺序
3. 源码与适配分离：原始源码通过 git clone 获取，适配修改通过 patch 文件记录，保持可追溯
4. 多架构统一：同一套 HPKBUILD 定义，框架自动为每个架构执行一遍
5. 可扩展：通过 external_deps 引入外部适配仓，不修改主仓库

一句话总结

lycium_plusplus 把”275 个三方库在 OpenHarmony 上怎么编译”这个看似不可能的问题，通过声明式构建定义 + 自动依赖解析 + 多架构循环 + HNP 打包，变成了一条命令的事。

项目地址：https://atomgit.com/OpenHarmonyPCDeveloper/lycium_plusplus