Lycium++ 是 OpenHarmony PC C/C++ 编译框架的增强版本，提供自动化构建和依赖管理功能。支持多版本共存、外部仓库管理及 HNP 打包。文档涵盖环境准备（macOS/Linux）、原生与增强型构建方式、外部仓库配置规范、HNP 打包流程及常见问题排查。旨在简化 OpenHarmony 原生库在 PC 端的编译与集成工作。
Lycium++ 是基于 OpenHarmony PC C/C++ 编译框架 Lycium 的增强版本，提供更强大的自动化构建能力和依赖管理功能。
| 特性 | Lycium（原生） | Lycium++（增强） |
|---|
| 依赖自动构建 | ❌ | ✅ 一键构建依赖树 |
| 多版本支持 | ❌ | ✅ 支持多版本共存 |
| 外部仓库 | ❌ | ✅ 独立仓库管理 |
| HNP 打包 | ❌ | ✅ 原生支持 |
| macOS 支持 | ⚠️ 部分 | ✅ 完全支持 |
| 项目 | 要求 |
|---|---|
| 操作系统 | macOS 12+, Linux (Ubuntu 18.04+), HarmonyOS |
| 磁盘空间 | 至少 10GB 可用空间 |
| 内存 | 建议 8GB 以上 |
| 网络 | 需要访问外网下载源码 |
所有平台通用：
# 基础编译工具 gcc g++ cmake make
# 自动化工具 autoconf automake libtool pkg-config
# 辅助工具 git wget curl tar unzip patch
# 构建工具 ninja
如果还未安装 Homebrew：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装所有必需工具（一键安装）
brew install cmake autoconf automake libtool pkg-config
brew install ninja wget coreutils
# 验证安装
cmake --version
ninja --version
pkg-config --version
sha512sum --version # 来自 coreutils
方式一：通过 DevEco Studio（推荐）
Tools → SDK ManagerOpenHarmony SDKNative 开发套件Apply 下载方式二：命令行下载
访问 OpenHarmony SDK 下载页 手动下载。
在 ~/.zshrc 或 ~/.bash_profile 中添加：
# OpenHarmony SDK 路径（根据实际安装路径修改）
export OHOS_SDK="/Users/$(whoami)/Library/OpenHarmony/Sdk/20"
# 添加 CMake 到 PATH（可选，方便使用）
export PATH="$OHOS_SDK/native/build-tools/cmake/bin:$PATH"
# 设置 HNP 工具路径（如果需要打包 HNP）
export HNP_TOOL="/path/to/hnp-tool" # 根据实际路径修改
使配置生效：
source ~/.zshrc
# 验证 SDK 路径
echo $OHOS_SDK
ls $OHOS_SDK/native/llvm/bin/clang
# 验证编译器
$OHOS_SDK/native/llvm/bin/clang --version
# 验证 CMake
$OHOS_SDK/native/build-tools/cmake/bin/cmake --version
预期输出：
LLVM version 15.0.4 ... cmake version 3.16.5
git clone https://gitcode.com/your-repo/lycium_plusplus.git
cd lycium_plusplus
编译一个简单的库来验证环境：
cd lycium
./build.sh zlib
如果成功，会看到类似输出：
Build OS Darwin OHOS_SDK=/Users/username/Library/OpenHarmony/Sdk/20 CLANG_VERSION=15.0.4 Start building zlib 1.3.1! Compileing OpenHarmony arm64-v8a zlib 1.3.1 libs... ... Build zlib 1.3.1 end! ALL JOBS DONE!!!
ls -lh usr/zlib/arm64-v8a/
应该看到：
include/ # 头文件 lib/ # 库文件 share/ # 文档
原生方式使用 lycium 框架编译 community 和 thirdparty 目录中已存在的三方库。
cd lycium
./build.sh zlib
./build.sh zlib openssl curl
./build.sh
# 实时查看
tail -f lycium_build_intl.log
# 查看完整日志
cat lycium_build_intl.log
增强型方式支持外部独立仓库参与构建，实现更灵活的版本管理。
lycium_plusplus/
├── lycium/ # 主构建系统
│ ├── build.sh # 构建脚本
│ ├── community/ # 社区库（软链接）
│ ├── thirdparty/ # 第三方库（软链接）
│ └── usr/ # 编译产物
├── community/ # 社区库实际目录
├── thirdparty/ # 第三方库实际目录
└── outerrepo/ # 外部仓库
├── module.json # 外部仓库配置
└── tree/ # 动态下载的外部仓库
不存在 -> 是 -> ./build.sh tree -> 检查 outerrepo/tree -> 读取 module.json -> Git Clone 仓库 -> 切换到指定分支 -> 准备编译环境 -> 执行 HPKBUILD -> 编译产物 -> 有 archive? -> 生成 HNP -> 完成
外部仓库信息存放在 outerrepo/module.json 中。
{
"modules": [
{
"name": "tree",
"version": "2.2.1",
"branch": "ohos_2.2.1",
"type": "git",
"url": "https://gitcode.com/OpenHarmonyPCDeveloper/ohos_tree.git"
},
{
"name": "another-lib",
"version": "1.0.0",
"branch": "main",
"type": "git",
"url": "https://github.com/user/another-lib-ohos.git"
}
]
}
| 字段 | 说明 | 必需 | 示例 |
|---|---|---|---|
name | 模块名称，必须与 HPKBUILD 中的 pkgname 一致 | ✅ | tree |
version | 原生库版本号 | ✅ | 2.2.1 |
branch | 适配仓库的分支名 | ✅ | ohos_2.2.1 |
type | 源码获取方式 | ✅ | git |
url | 代码仓库地址 | ✅ | https://... |
外部代码仓应遵循以下目录结构：
ohos_tree/ # 仓库名
├── HPKBUILD # 必需：构建配置
├── HPKCHECK # 可选：测试脚本
├── hnp.json # 可选：HNP 打包配置
├── README.md # 推荐：说明文档
├── 0001-ports-for-ohos.patch # 可选：补丁文件
└── SHA512SUM # 推荐：校验和文件
# Contributor: Your Name <[email protected]>
# Maintainer: Your Name <[email protected]>
pkgname=tree
pkgver=2.2.1
pkgrel=0
pkgdesc="A directory listing program displaying a depth indented list of files"
url="http://mama.indstate.edu/users/ice/tree/"
archs=("armeabi-v7a" "arm64-v8a")
license=("GPL")
depends=()
makedepends=("make" "patch")
source="https://github.com/Old-Man-Programmer/tree/archive/refs/tags/${pkgver}.tar.gz"
downloadpackage=true
autounpack=true
buildtools="make"
builddir="tree-${pkgver}"
packagename="${pkgver}.tar.gz"
prepare() {
cd $builddir
# 应用补丁
patch -p1 < ../0001-ports-for-ohos.patch
cd ${OLDPWD}
}
build() {
cd $builddir
# 设置编译器
export CC="${OHOS_SDK}/native/llvm/bin/aarch64-linux-ohos-clang"
export CFLAGS="-target aarch64-linux-ohos --sysroot=${SYSROOT}"
# 编译
make -j8
ret=$?
cd $OLDPWD
return $ret
}
package() {
cd $builddir
# 安装
install -Dm755 tree "$LYCIUM_ROOT/usr/$pkgname/$ARCH/bin/tree"
install -Dm644 doc/tree.1 "$LYCIUM_ROOT/usr/$pkgname/$ARCH/share/man/man1/tree.1"
cd $OLDPWD
}
# 归档阶段（可选，用于生成 HNP）
archive() {
mkdir -p ${LYCIUM_ROOT}/output/$ARCH
# 打包 tar.gz
pushd $LYCIUM_ROOT/usr/$pkgname/$ARCH
tar -czf ${LYCIUM_ROOT}/output/$ARCH/${pkgname}_${pkgver}.tar.gz *
popd
# 复制 HNP 配置
cp hnp.json $LYCIUM_ROOT/usr/$pkgname/$ARCH/
# 生成 HNP 包
${HNP_TOOL} pack -i ${LYCIUM_ROOT}/usr/$pkgname/$ARCH \
-o ${LYCIUM_ROOT}/output/$ARCH/
}
check() {
echo "The test must be on an OpenHarmony device!"
}
cleanbuild() {
rm -rf ${PWD}/$builddir
}
{
"type": "hnp-config",
"name": "tree",
"version": "2.2.1",
"description": "A directory listing program",
"license": "GPL",
"install": {
"bin": ["bin/tree"],
"man": ["share/man/man1/tree.1"]
}
}
在 outerrepo/module.json 中添加模块配置。
cd lycium
./build.sh tree
构建系统会自动：
outerrepo/tree 是否存在module.json 配置git clone -b <branch> <url> treeHNP (HarmonyOS Native Package) 是 HarmonyOS 的原生包格式，可以直接在 HarmonyOS 系统上安装和使用。
archive() {
# 创建输出目录
mkdir -p ${LYCIUM_ROOT}/output/$ARCH
# 打包二进制文件
pushd $LYCIUM_ROOT/usr/$pkgname/$ARCH
tar -czf ${LYCIUM_ROOT}/output/$ARCH/${pkgname}_${pkgver}.tar.gz *
popd
# 复制 HNP 配置
cp hnp.json $LYCIUM_ROOT/usr/$pkgname/$ARCH/
# 生成 HNP 包
${HNP_TOOL} pack \
-i ${LYCIUM_ROOT}/usr/$pkgname/$ARCH \
-o ${LYCIUM_ROOT}/output/$ARCH/
}
./build.sh tree
编译完成后，可以在以下位置获取产物：
二进制产物：
lycium/usr/tree// ├── bin/ # 可执行文件 ├── lib/ # 库文件 ├── include/ # 头文件 └── share/ # 文档等
归档产物：
lycium/output// ├── tree_2.2.1.tar.gz # tar 归档 └── tree_2.2.1.hnp # HNP 包
在 HarmonyOS 设备上：
# 使用 hnp 工具安装
hnp install tree_2.2.1.hnp
# 或使用 hdc 推送后安装
hdc file send tree_2.2.1.hnp /data/local/tmp/
hdc shell hnp install /data/local/tmp/tree_2.2.1.hnp
cp: the -R and -r options may not be specified together原因：macOS 的 BSD cp 命令参数检查更严格。
解决：已在最新版本中修复。如果仍遇到，请更新到最新代码：
git pull origin main
pkg-config 命令未安装解决：
brew install pkg-config
ninja 命令未安装解决：
brew install ninja
wget 命令未安装解决：
brew install wget
sha512sum: command not found原因：macOS 默认没有 sha512sum 命令。
解决：
brew install coreutils
OHOS_SDK 未设置解决：
# 设置环境变量
export OHOS_SDK="/Users/$(whoami)/Library/OpenHarmony/Sdk/20"
# 或添加到 ~/.zshrc
echo 'export OHOS_SDK="/Users/$(whoami)/Library/OpenHarmony/Sdk/20"' >> ~/.zshrc
source ~/.zshrc
现象：
CMake Error: Could not find package "ZLIB"
解决：
# 先编译依赖
./build.sh zlib
# 再编译目标库
./build.sh target-lib
解决：
# 删除旧的源码包
rm thirdparty/pkgname/*.tar.gz
# 重新编译（会自动下载）
./build.sh pkgname
可能原因：
解决：
# 手动克隆测试
cd outerrepo
git clone -b <branch> <url> <name>
# 检查分支
cd <name>
git branch -a
排查步骤：
cd outerrepo/pkgname
source HPKBUILD prepare build
我们欢迎所有形式的贡献！
发现 Bug？请在 Issues 中报告，并包含：
文档改进也是重要的贡献！
参考 lycium/CItools/README_zh.md 搭建测试环境。
# 压缩整个项目
tar -czf lycium_plusplus.tar.gz lycium_plusplus/
# 推送到设备
hdc file send lycium_plusplus.tar.gz /data/local/tmp/
# 连接设备
hdc shell
cd /data/local/tmp
tar -xzf lycium_plusplus.tar.gz
cd lycium_plusplus/lycium
./test.sh tree
cat check_result/check_log/tree_*_test.log
本项目采用 Apache License 2.0 许可证。详见 LICENSE 文件。
感谢以下项目和组织：
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online
将JSON字符串修饰为友好的可读格式。 在线工具，JSON美化和格式化在线工具，online