如果这篇文章对你有帮助，麻烦大家点赞 + 收藏 + 转发三连支持～ 你们的每一份认可，都是我持续输出技术干货的最大动力！后续还会带来更多实操教程，技术解读。记得关注不迷路哦～

也欢迎添加我的联系方式，咱们交个朋友！未来我也会持续分享各类前沿技术干货。

lycium_plusplus 项目全景解读：OpenHarmony 三方库构建的"大管家"

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

前言

做 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 <库名>                               │└─────────────────────────────────────────────────────────────┘              │              ▼┌─────────────────────────────────────────────────────────────┐│                    构建框架层（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 后，设置本机编译标志，跳过交叉编译步骤。

核心逻辑：

# 检测是否为 HarmonyOSif [ "${OS_NAME:0:5}" == "Harmo" ]; then    TARGET_HARMONYOS="true"# 设置本机编译路径    INSTALL_LOCAL_PERFIX=/usr/localfi# 最终还是调用 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 命令行工具

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

• xxx_armeabi-v7a_Compilation_instructions.md
• xxx_arm64_v8a_Compilation_instructions.md
• xxx_x86_64_compilation_instructions.md

template/ — HPKBUILD 模板

位置：lycium/template/

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

完整构建流程示例

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

$ cd lycium && ./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 打包，变成了一条命令的事。