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

欢迎大家加入开源鸿蒙PC社区

项目地址：https://atomgit.com/oh-tpc/pc_sha

前言

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

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

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

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

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

三方库适配的痛点

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

问题 具体内容
交叉编译 开发机是 x86，目标设备是 ARM，需要用 OpenHarmony SDK 的工具链
多架构支持 同一个库要编译 ARM32 和 ARM64 两个版本
依赖管理 curl 依赖 openssl，openssl 依赖 zlib，构建顺序怎么确定？
产物打包 编译出的 .so/.a/.h 要打包成 OpenHarmony 的 HNP 格式
版本管理 上游库更新了，怎么同步？commit hash 还是 tag？
规模问题 275 个库，手动管理不现实

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/ 目录

支持的操作系统：

系统 支持方式
Linux 交叉编译（主要方式）
macOS (Darwin) 交叉编译
HarmonyOS 本机编译（无需交叉编译）
Windows (Cygwin) 交叉编译

依赖解析：这是 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 提供了一组函数，按架构设置正确的环境变量。

提供的函数：

函数 设置内容 对应架构
setarm32ENV() CC=arm-linux-ohos-clang 等 armeabi-v7a
setarm64ENV() CC=aarch64-linux-ohos-clang 等 arm64-v8a
setx86_64ENV() x86_64 编译环境 x86_64
setHarmonyOSENV() 本机 clang/clang++ HarmonyOS
unsetarm32ENV() 清理 ARM32 环境 —
unsetarm64ENV() 清理 ARM64 环境 —
unsetx86_64ENV() 清理 x86_64 环境 —
unsetHarmonyOSENV() 清理 HarmonyOS 环境 —

每个 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 个三方库，是整个项目的"原料仓库"。

类别 代表库 数量
加密/安全 openssl, wolfssl, GmSSL, tink ~20
压缩 zlib, zstd, lz4, bzip2, xz ~10
图像/视频 FFmpeg, libjpeg-turbo, libpng, opencv ~15
数据库 sqlite, postgresql, sqlcipher ~8
网络 curl, libev, libevent, pjsip ~10
数据格式 libxml2, rapidjson, yaml-cpp, protobuf ~15
数学/科学 openblas, eigen, fftw, gsl ~10
其他 boost, icu, re2, onnxruntime ~187

每个库的标准目录结构

以 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 个外部模块，部分示例：

模块名 版本 来源
openssl 3.6 atomgit.com
zlib_static 6.0.0.1 atomgit.com
curl 8.11.1 atomgit.com
bash 5.3 atomgit.com
gmp 6.3.0 atomgit.com
gdb 16.3 atomgit.com

工作流程：

构建开始
    │
    ├─ 读取 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                           │
└─────────────────────────────────────────────────────────────┘

两种构建模式对比

特性 原生模式（build.sh） 增强模式（build_local.sh）
运行环境 Linux/macOS HarmonyOS PC
编译方式 交叉编译 本机编译
工具链 OpenHarmony SDK Clang 系统 Clang
产物架构 ARM32 + ARM64 本机架构
适用场景 CI/CD、服务器构建 本地开发调试

项目数据一览

指标 数量
三方库总数 275
社区适配库 132
外部依赖模块 22
支持架构 3（armeabi-v7a, arm64-v8a, x86_64）
支持操作系统 4（Linux, macOS, HarmonyOS, Cygwin）
核心脚本 5（build.sh, build_local.sh, test.sh, build_hpk.sh, envset.sh）

常见问题

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 上能自动、可重现、可依赖地构建。

核心能力

能力 实现方式
交叉编译 OpenHarmony SDK 工具链 + envset.sh 架构环境
依赖解析 读取 HPKBUILD 的 depends，自动排序
多架构支持 循环执行 armeabi-v7a / arm64-v8a
产物打包 hnpcli 生成 HNP 包 + tar.gz
外部依赖 module.json + load_outer_parts.py
本机编译 build_local.sh + HarmonyOS 检测
设备测试 test.sh + CItools

项目哲学

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

一句话总结

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

# 华为 # harmonyos
Logo
开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

#鸿蒙三方库生态深度分析：现状、缺口与移植指南

鸿蒙三方库生态现状与移植指南 摘要 鸿蒙操作系统（HarmonyOS）的OHPM生态相比主流包管理系统（如npm、Maven、PyPI）仍存在显著差距，但这也为开发者提供了巨大机会。本文分析了鸿蒙三方库生态现状：当前覆盖较完善的领域包括网络通信、状态管理和日期处理，但图表可视化、地图SDK和AI/ML库等领域存在严重短缺。 文章详细介绍了将开源库移植到鸿蒙的实用方法，包括四步移植流程和常见API替

avatar 开源鸿蒙跨平台开发者社区
cover

Flutter | 商城项目鸿蒙（OpenHarmony）适配实战

avatar 开源鸿蒙跨平台开发者社区
cover

APP开发技术选型：Flutter vs React Native vs 原生，2026年最新对比与实战指南

avatar 开源鸿蒙跨平台开发者社区