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

发布日期：2026-04-29 01:12    点击次数：133

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

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

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

lycium_plusplus就是解决这个问题的。它是OpenHarmonyC/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───开源声明│

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

│

▼

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

│工具链层│

││

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

│Buildtools/───辅助工具│

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

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

核心模块详解

1.build.sh—主构建脚本

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

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

核心流程：

./build.shsha

│

├─

1.preparetoolchain检查并准备OpenHarmonySDK工具链

│

├─

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

│

├─

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

│

├─

4.collectcommunitylibs收集社区库信息

│

├─

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

│

├─

6.findarglibsdir查找目标库目录

│

├─

7.prepareshell准备Shell环境

│

├─

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

││

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

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

││sourceHPKBUILD

││prepare→build→package→archive

││

│└─

9.cleanhpkdir清理临时目录

│

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

支持的操作系统：

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

读取curl的HPKBUILD，发现depends=(opensslzlib)

检查openssl和zlib是否已构建

如果没有，先构建zlib（无依赖），再构建openssl（依赖zlib），最后构建curl

构建顺序自动确定，无需手动指定

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上开发时，可以直接编译，不需要OpenHarmonySDK的交叉编译工具链。

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.遍历已编译库

││

│└─对每个库：

│sourceHPKCHECK

│执行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读取外部适配仓信息，自动gitclone到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

│

├─对每个外部模块：

│gitclone-b

│放到thirdparty//

│

└─继续正常构建流程

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

CItools/—CI测试环境工具

问题背景

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

解决方案

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

CItools/

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

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

├──cmake/#CMake

├──make/#GNUMake

├──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库为例，展示从命令到产物的完整流程：

$cdlycium&；./build.shsha

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

│

1.环境准备│

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

│├─检查OpenHarmonySDK是否安装│

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

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

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

│

▼

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

│

2.依赖解析│

│├─读取sha/HPKBUILD│

│├─depends=→无依赖│

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

││

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

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

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

│

▼

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

│

3.架构循环：armeabi-v7a│

│├─ARCH=armeabi-v7a│

│├─sourceHPKBUILD│

│├─prepare→gitclone+patch│

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

│├─package→makeinstall│

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

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

│

▼

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

│

4.架构循环：arm64-v8a│

│├─ARCH=arm64-v8a│

│├─sourceHPKBUILD│

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

│├─package→makeinstall│

│└─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：如何构建单个库？

cdlycium

./build.shsha#构建SHA库

./build.shopenssl#构建OpenSSL

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

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

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

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

在thirdparty/下创建库目录

复制lycium/template/中的模板文件

修改HPKBUILD（包名、版本、源码地址、构建函数）

修改HPKCHECK（测试逻辑）

创建hnp.json（包配置）

编写适配补丁（如需要）

测试构建：./build.sh

Q4：如何在设备上测试？

#1.部署CItools到设备

cdlycium/CItools&./env_build.sh

#2.执行测试

cdlycium&./test.sh

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

thirdparty：主仓库内维护的库，代码直接在本仓库

external_deps：外部团队维护的库，构建时从gitcode.com自动下载

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

Q6：构建失败怎么排查？

查看构建日志：thirdparty//___lycium_build.log

查看last_error文件

手动进入源码目录，逐步执行prepare/build/package验证

检查HPKBUILD中的变量和函数是否正确

总结

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

核心能力

项目哲学

声明式构建：每个库只需写一个HPKBUILD声明”怎么构建”，框架负责”怎么调度”

依赖自动化：开发者只需./build.shcurl，框架自动处理zlib→openssl→curl的构建顺序

源码与适配分离：原始源码通过gitclone获取，适配修改通过patch文件记录，保持可追溯

多架构统一：同一套HPKBUILD定义，框架自动为每个架构执行一遍

可扩展：通过external_deps引入外部适配仓，不修改主仓库

一句话总结

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