Lycium++ - OpenHarmony PC C/C++ 增强编译框架

macOS 环境配置

第 1 步：安装 Homebrew

如果还未安装 Homebrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

第 2 步：安装必需工具

# 安装所有必需工具（一键安装）
brew install cmake autoconf automake libtool pkg-config
brew install ninja wget coreutils

# 验证安装
cmake --version
ninja --version
pkg-config --version
sha512sum --version  # 来自 coreutils

第 3 步：下载 OpenHarmony SDK

方式一：通过 DevEco Studio（推荐）

1. 下载并安装 DevEco Studio
2. 打开 DevEco Studio
3. 进入 Tools → SDK Manager
4. 选择 OpenHarmony SDK
5. 勾选 Native 开发套件
6. 点击 Apply 下载

方式二：命令行下载

访问 OpenHarmony SDK 下载页 手动下载。

第 4 步：配置环境变量

在 ~/.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

第 5 步：验证环境

# 验证 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 -> 完成

外部仓库管理

module.json 配置文件

外部仓库信息存放在 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"
        }
    ]
}

配置字段说明

外部 Ports 仓规范

外部代码仓应遵循以下目录结构：

ohos_tree/              # 仓库名
├── HPKBUILD            # 必需：构建配置
├── HPKCHECK            # 可选：测试脚本
├── hnp.json            # 可选：HNP 打包配置
├── README.md           # 推荐：说明文档
├── 0001-ports-for-ohos.patch # 可选：补丁文件
└── SHA512SUM           # 推荐：校验和文件

HPKBUILD 示例

# 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
}

hnp.json 配置

{
    "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"]
    }
}

使用外部仓库

第 1 步：配置 module.json

在 outerrepo/module.json 中添加模块配置。

第 2 步：执行编译

cd lycium
./build.sh tree

第 3 步：自动化流程

构建系统会自动：

1. 检查 outerrepo/tree 是否存在
2. 如不存在，读取 module.json 配置
3. 执行 git clone -b <branch> <url> tree
4. 执行标准的 lycium 编译流程

HNP 打包

什么是 HNP？

HNP (HarmonyOS Native Package) 是 HarmonyOS 的原生包格式，可以直接在 HarmonyOS 系统上安装和使用。

打包流程

1. 在 HPKBUILD 中添加 archive() 函数

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/
}

2. 执行编译

./build.sh tree

3. 获取产物

编译完成后，可以在以下位置获取产物：

二进制产物：

lycium/usr/tree// ├── bin/ # 可执行文件 ├── lib/ # 库文件 ├── include/ # 头文件 └── share/ # 文档等

归档产物：

lycium/output// ├── tree_2.2.1.tar.gz # tar 归档 └── tree_2.2.1.hnp # 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

常见问题

macOS 环境相关

Q1: cp: the -R and -r options may not be specified together

原因：macOS 的 BSD cp 命令参数检查更严格。

解决：已在最新版本中修复。如果仍遇到，请更新到最新代码：

git pull origin main

详见：docs/fix-cp-error.md

Q2: pkg-config 命令未安装

解决：

brew install pkg-config

Q3: ninja 命令未安装

解决：

brew install ninja

Q4: wget 命令未安装

解决：

brew install wget

Q5: sha512sum: command not found

原因：macOS 默认没有 sha512sum 命令。

解决：

brew install coreutils

编译问题

Q6: 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

Q7: 编译时找不到依赖库

现象：

CMake Error: Could not find package "ZLIB"

解决：

# 先编译依赖
./build.sh zlib

# 再编译目标库
./build.sh target-lib

Q8: SHA512 校验失败

解决：

# 删除旧的源码包
rm thirdparty/pkgname/*.tar.gz

# 重新编译（会自动下载）
./build.sh pkgname

外部仓库问题

Q9: Git clone 失败

可能原因：

1. 网络问题
2. 仓库地址错误
3. 分支不存在

解决：

# 手动克隆测试
cd outerrepo
git clone -b <branch> <url> <name>

# 检查分支
cd <name>
git branch -a

Q10: 外部仓库编译失败

排查步骤：

1. 检查 HPKBUILD 语法
2. 查看编译日志
3. 手动进入目录测试

cd outerrepo/pkgname
source HPKBUILD prepare build

贡献指南

如何贡献

我们欢迎所有形式的贡献！

贡献新的库适配

1. Fork 本项目
2. 创建适配仓库（或在本地 thirdparty 目录）
3. 编写 HPKBUILD 和 HPKCHECK
4. 测试编译和运行
5. 提交 Pull Request

报告问题

发现 Bug？请在 Issues 中报告，并包含：

• 操作系统和版本
• OHOS SDK 版本
• 完整的错误日志
• 复现步骤

完善文档

文档改进也是重要的贡献！

代码规范

• Shell 脚本使用 4 空格缩进
• 函数名使用小写加下划线
• 添加必要的注释
• 遵循现有代码风格

测试验证

在 OpenHarmony 设备上测试

1. 准备测试环境

参考 lycium/CItools/README_zh.md 搭建测试环境。

2. 推送代码到设备

# 压缩整个项目
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

3. 执行测试

cd lycium_plusplus/lycium
./test.sh tree

4. 查看测试结果

cat check_result/check_log/tree_*_test.log

参考资源

官方文档

• OpenHarmony 官方文档
• DevEco Studio 使用指南
• Lycium 原始框架

本项目文档

• Lycium 系统完全指南
• 第三方库适配指南
• Ninja 使用指南
• macOS cp 命令问题解决

学习资源

• Shell 脚本编程
• CMake 教程
• OpenHarmony 开发者社区

许可证

本项目采用 Apache License 2.0 许可证。详见 LICENSE 文件。

致谢

感谢以下项目和组织：

• OpenHarmony - 开放原子开源基金会
• Lycium - 原始编译框架
• 所有贡献者和社区成员