鸿蒙Lycium 交叉编译框架完全指南

不爱吃糖的程序媛2025-12-19 8:32

Lycium 交叉编译框架完全指南

目录

系统概述

什么是 Lycium？

Lycium 是一款协助开发者通过 Shell 脚本语言实现 C/C++ 第三方库快速交叉编译，并在 OpenHarmony 系统上快速验证的编译框架工具。

核心特性

特性 说明
🚀 全自动化 从下载、校验、解压、编译到安装全程自动化
📦 智能依赖管理 自动解析和处理库之间的依赖关系
🔧 多构建系统支持 支持 CMake、Configure、Make 等多种构建方式
✅ 完整性校验 使用 SHA512 确保源码完整性
🧪 集成测试框架 在真实设备上验证移植效果
🎯 多架构支持 支持 armeabi-v7a、arm64-v8a 等多种架构
🔄 跨平台编译 支持在 Linux、macOS、HarmonyOS 上交叉编译
📝 标准化流程 统一的配置文件格式，降低学习成本

系统架构

复制代码 
lycium_plusplus/
├── lycium/                     # Lycium 构建系统核心
│   ├── build.sh               # 主构建脚本（入口）
│   ├── test.sh                # 主测试脚本
│   ├── script/                # 构建辅助脚本
│   │   ├── build_hpk.sh      # 单包构建逻辑
│   │   ├── envset.sh         # 环境变量设置
│   │   └── load_outer_parts.py  # 外部仓库加载
│   ├── template/              # 配置文件模板
│   │   ├── HPKBUILD          # 构建配置模板
│   │   ├── HPKCHECK          # 测试配置模板
│   │   ├── README.md         # 模板使用说明
│   │   └── SHA512SUM         # 校验和模板
│   ├── Buildtools/            # 编译工具链
│   │   ├── README.md         # 环境配置指南
│   │   └── toolchain.tar.gz  # 工具链补丁
│   ├── CItools/               # CI/CD 环境工具
│   ├── doc/                   # 详细文档
│   ├── community/             # 社区贡献的库链接
│   └── usr/                   # 编译产物安装目录
├── thirdparty/                # 第三方库适配目录
├── community/                 # 社区库实际存储目录
├── outerrepo/                 # 外部仓库配置
└── docs/                      # 项目文档

工作流程

用户 build.sh build_hpk.sh 源码 OHOS SDK usr目录 ./build.sh pkgname 检查环境 解析依赖 调用 build_hpk.sh 下载源码 SHA512 校验 解压源码 prepare() 准备 使用工具链编译 build() 编译 package() 打包 安装到 usr/pkgname 编译完成 用户 build.sh build_hpk.sh 源码 OHOS SDK usr目录

快速开始

5 分钟上手

第 1 步：环境准备
bash 复制代码 
# 设置 OpenHarmony SDK 路径
export OHOS_SDK=/path/to/OH_SDK/ohos-sdk/linux

# 验证 SDK
ls $OHOS_SDK/native/llvm/bin/clang
第 2 步：编译第一个库
bash 复制代码 
cd lycium
./build.sh zlib
第 3 步：查看产物
bash 复制代码 
ls -lh usr/zlib/arm64-v8a/
# include/ - 头文件
# lib/     - 库文件
# share/   - 文档等

三方库适配流程

复制代码 
创建目录 → 编写HPKBUILD → 测试编译 → 编写HPKCHECK → 在设备测试 → 提交代码

环境配置

系统要求

项目 要求
操作系统 Linux、macOS、HarmonyOS
Shell Bash 4.0+
磁盘空间 建议 10GB+
内存 建议 8GB+

必需工具清单

Linux/macOS 环境
bash 复制代码 
# 编译工具
gcc g++ cmake make

# 自动化工具
autoconf autoreconf automake libtool

# 辅助工具
pkg-config patch unzip tar git

# 构建加速工具
ninja curl wget

# 校验工具
sha512sum  # Linux 自带，macOS 需安装 coreutils
macOS 特殊说明
bash 复制代码 
# 安装 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

OpenHarmony SDK 配置

下载 SDK

  1. 方式一：通过 DevEco Studio

    • 打开 DevEco Studio
    • Tools → SDK Manager
    • 选择 OpenHarmony SDK
    • 下载 Native 开发套件

  2. 方式二：命令行下载

    bash 复制代码 
    # 访问官方网站下载
# https://developer.harmonyos.com/cn/develop/deveco-studio
配置环境变量

Linux/HarmonyOS:

bash 复制代码 
# 添加到 ~/.bashrc 或 ~/.bash_profile
export OHOS_SDK=/home/user/OH_SDK/ohos-sdk/linux
export PATH=$OHOS_SDK/native/build-tools/cmake/bin:$PATH

# 使配置生效
source ~/.bashrc

macOS:

bash 复制代码 
# 添加到 ~/.zshrc 或 ~/.bash_profile
export OHOS_SDK=/Users/user/Library/OpenHarmony/Sdk/20
export PATH=$OHOS_SDK/native/build-tools/cmake/bin:$PATH

# 使配置生效
source ~/.zshrc
验证安装
bash 复制代码 
# 检查 SDK 路径
echo $OHOS_SDK

# 检查编译器
$OHOS_SDK/native/llvm/bin/clang --version

# 检查 CMake
$OHOS_SDK/native/build-tools/cmake/bin/cmake --version

工具链补丁（macOS/非 Linux）

在非 HarmonyOS 环境下，需要安装额外的工具链文件：

bash 复制代码 
cd lycium
./build.sh <any-package>  # 首次运行会自动安装工具链

工具链文件包括：

  • aarch64-linux-ohos-clang
  • aarch64-linux-ohos-clang++
  • arm-linux-ohos-clang
  • arm-linux-ohos-clang++

构建系统详解

build.sh 主构建脚本

基本用法
bash 复制代码 
# 编译所有库
./build.sh

# 编译单个库
./build.sh zlib

# 编译多个库
./build.sh zlib openssl curl

# 编译指定架构
# 在 HPKBUILD 中通过 archs=() 配置
执行流程
复制代码 
1. preparetoolchain()    - 准备工具链
2. checkbuildenv()       - 检查编译环境
3. readdonelibs()        - 读取编译记录
4. findarglibsdir()      - 搜集待编译库
5. prepareshell()        - 准备构建脚本
6. buildhpk()            - 执行编译
7. cleanhpkdir()         - 清理环境
依赖解析机制

构建系统会自动解析依赖关系：

bash 复制代码 
# 示例：curl 依赖 openssl 和 zlib
./build.sh curl

# 系统会自动：
# 1. 检查 openssl 和 zlib 是否已编译
# 2. 如果未编译，先编译依赖
# 3. 最后编译 curl
编译状态管理
bash 复制代码 
# 编译记录文件
usr/hpk_build.csv

# 格式：架构,库名,版本
arm64-v8a,zlib,1.3.1
armeabi-v7a,zlib,1.3.1

build_hpk.sh 单包构建

这是实际执行构建的核心脚本，自动处理：

1. 下载阶段
bash 复制代码 
download() {
    if [ -s ${PWD}/$2 ]; then
        echo "文件已存在"
    else
        wget "$1" -O ${PWD}/$2
    fi
}

支持的下载方式：

  • HTTP/HTTPS 直接下载
  • Git clone（需在 prepare() 中手动处理）
2. 校验阶段
bash 复制代码 
checksum() {
    sha512sum -c ${PWD}/SHA512SUM
}

如果校验失败，构建会中止。

3. 解压阶段
bash 复制代码 
unpack() {
    # 支持的格式
    *.tar.gz  *.tgz      # gzip 压缩
    *.tar.xz             # xz 压缩
    *.tar.bz2            # bzip2 压缩
    *.zip                # zip 压缩
}
4. 依赖处理
bash 复制代码 
builddepends() {
    # 检查所有依赖是否已编译
    # 返回 101 表示依赖未满足
    # 返回 0 表示可以继续编译
}
5. 构建参数生成

CMake 项目：

bash 复制代码 
cmakedependpath() {
    buildargs="-DCMAKE_BUILD_TYPE=Release"
    buildargs="$buildargs -DCMAKE_TOOLCHAIN_FILE=$OHOS_SDK/native/build/cmake/ohos.toolchain.cmake"
    buildargs="$buildargs -DCMAKE_INSTALL_PREFIX=$LYCIUM_ROOT/usr/$pkgname/$ARCH"
    buildargs="$buildargs -DCMAKE_FIND_ROOT_PATH=\"/path/to/deps\""
}

Configure 项目：

bash 复制代码 
configuredependpath() {
    buildargs="--prefix=$LYCIUM_ROOT/usr/$pkgname/$ARCH/"
    # 设置 PKG_CONFIG_PATH
}
6. 编译执行
bash 复制代码 
builpackage() {
    for arch in ${archs[@]}; do
        prepare              # 准备环境
        build $buildargs     # 执行编译
        package              # 安装打包
        archive              # 归档（可选）
        check                # 检查（可选）
    done
}

环境变量参考

全局变量
变量名 说明 示例值
LYCIUM_ROOT Lycium 根目录 /path/to/lycium
LYCIUM_BUILD_OS 构建系统类型 Darwi/Linux/HarmonyOS
LYCIUM_BUILD_CHECK 是否执行检查 true/false
LYCIUM_DEPEND_PKGNAMES 依赖包临时文件 /tmp/user-lycium_deps-xxx
OHOS_SDK OpenHarmony SDK 路径 /path/to/SDK
SYSROOT 系统根目录 $OHOS_SDK/native/sysroot
CLANG_VERSION Clang 版本 15.0.4
HPKBUILD 内变量
变量名 说明 来源
pkgname 当前库名 HPKBUILD
pkgver 当前版本 HPKBUILD
ARCH 当前架构 遍历 archs
builddir 源码目录 HPKBUILD
depends 依赖列表 HPKBUILD

测试框架详解

test.sh 主测试脚本

测试脚本运行在 OpenHarmony 设备上，用于验证编译产物的功能。

执行环境
bash 复制代码 
# 必须在 OpenHarmony 设备上运行
# 通过 hdc shell 连接到设备

hdc shell
cd /data/local/tmp/lycium_plusplus/lycium
./test.sh
测试流程
复制代码 
1. checktestenv()              - 检查测试环境
2. getcpuarchitecture()        - 获取设备架构
3. setloaddynamiclibrarypath() - 设置动态库路径
4. findbuilddir()              - 搜索已编译的库
5. checkhpk()                  - 执行测试
6. 生成测试报告
测试环境要求

在 OpenHarmony 设备上必须安装：

bash 复制代码 
# 必需工具
cmake    # CMake 构建工具
make     # Make 构建工具
ctest    # CTest 测试框架
perl     # Perl 解释器（部分测试需要）

安装方法参考：lycium CItools

测试结果

测试完成后会生成：

复制代码 
lycium/check_result/
├── check_log/                    # 所有测试日志
│   ├── zlib_arm64-v8a_OH4.0_test.log
│   └── openssl_arm64-v8a_OH4.0_test.log
├── check_fault/                  # 失败测试详情
│   └── failed_lib/
│       └── fault.log
└── manual_confirm/               # 需要手动确认的输出
    └── lib_name/
        └── output_file.wav
测试报告
bash 复制代码 
################################################
CHECK REPORT :
TEST TOTAL LIBS : 15
TEST FAILED : 2
FAILED TEST ARE:
libpng
opencv
################################################

HPKCHECK 配置文件

基本结构
bash 复制代码 
# 导入 HPKBUILD 配置
source HPKBUILD > /dev/null 2>&1

# 日志文件路径
logfile=${LYCIUM_THIRDPARTY_ROOT}/${pkgname}/${pkgname}_${ARCH}_${OHOS_SDK_VER}_test.log

# 测试前准备（可选）
checkprepare() {
    # 编译测试程序
    # 准备测试数据
    return 0
}

# 执行测试
openharmonycheck() {
    res=0
    cd ${builddir}/${ARCH}-build
    
    # 运行测试
    ctest > ${logfile} 2>&1
    res=$?
    
    cd $OLDPWD
    return $res
}
高级测试示例
bash 复制代码 
source HPKBUILD > /dev/null 2>&1

logfile=${LYCIUM_THIRDPARTY_ROOT}/${pkgname}/${pkgname}_${ARCH}_${OHOS_SDK_VER}_test.log
faultlog=${LYCIUM_FAULT_PATH}/${pkgname}/fault.log

checkprepare() {
    echo "=== Preparing ${pkgname} test ===" | tee -a ${logfile}
    
    # 创建测试目录
    mkdir -p ${LYCIUM_THIRDPARTY_ROOT}/${pkgname}
    mkdir -p ${LYCIUM_FAULT_PATH}/${pkgname}
    
    # 设置动态库路径
    export LD_LIBRARY_PATH=${LYCIUM_ROOT}/usr/${pkgname}/${ARCH}/lib:$LD_LIBRARY_PATH
    
    return 0
}

openharmonycheck() {
    res=0
    
    echo "=== Testing ${pkgname} ${pkgver} ===" | tee -a ${logfile}
    echo "Architecture: ${ARCH}" | tee -a ${logfile}
    echo "SDK Version: ${OHOS_SDK_VER}" | tee -a ${logfile}
    
    cd ${builddir}/${ARCH}-build
    
    # 方式1：使用 CTest
    if [ -f CTestTestfile.cmake ]; then
        ctest --output-on-failure --verbose >> ${logfile} 2>&1
        res=$?
    
    # 方式2：运行自定义测试
    elif [ -f ./test/${pkgname}_test ]; then
        ./test/${pkgname}_test >> ${logfile} 2>&1
        res=$?
    
    # 方式3：运行示例程序
    elif [ -d ./examples ]; then
        for example in ./examples/*; do
            if [ -x "$example" ]; then
                echo "Running $example" | tee -a ${logfile}
                $example >> ${logfile} 2>&1
                if [ $? -ne 0 ]; then
                    res=1
                    echo "FAILED: $example" | tee -a ${faultlog}
                fi
            fi
        done
    else
        echo "No test found, skipping..." | tee -a ${logfile}
    fi
    
    cd $OLDPWD
    
    # 报告测试结果
    if [ $res -eq 0 ]; then
        echo "✅ Test PASSED" | tee -a ${logfile}
    else
        echo "❌ Test FAILED" | tee -a ${logfile} ${faultlog}
    fi
    
    return $res
}
测试环境变量
变量名 说明 用途
LYCIUM_ROOT Lycium 根目录 查找已编译的库
LYCIUM_THIRDPARTY_ROOT thirdparty 目录 源码和构建目录
LYCIUM_FAULT_PATH 错误日志目录 存储失败测试的详细信息
LYCIUM__MANUAL_CONFIRM_PATH 手动确认目录 存储需人工验证的输出文件
ARCH CPU 架构 当前设备架构
OHOS_SDK_VER SDK 版本 OpenHarmony 版本

北向应用集成

什么是北向应用？

北向应用是指运行在 OpenHarmony 系统上的应用程序，使用 ArkTS/JS 开发界面，通过 NAPI 调用 C/C++ 代码。

集成方式

方式一：源码集成

在应用项目中直接包含第三方库源码并编译。

优点：

  • ✅ 代码完全可控
  • ✅ 便于调试
  • ✅ 可以修改源码

缺点：

  • ❌ 增加项目复杂度
  • ❌ 编译时间长
方式二：二进制集成（推荐）

使用 Lycium 预编译的二进制文件。

优点：

  • ✅ 编译快速
  • ✅ 项目简洁
  • ✅ 易于维护

缺点：

  • ❌ 需要提前编译
  • ❌ 调试相对困难

二进制集成详细步骤

第 1 步：使用 Lycium 编译库
bash 复制代码 
cd lycium
./build.sh zlib
第 2 步：创建应用目录结构

在 DevEco Studio 项目中创建 thirdparty 目录：

复制代码 
MyApp/
└── entry/
    └── src/
        └── main/
            ├── cpp/
            │   ├── thirdparty/           # 第三方库
            │   │   └── zlib/
            │   │       ├── arm64-v8a/    # ARM 64位
            │   │       │   ├── include/  # 头文件
            │   │       │   └── lib/      # 库文件
            │   │       └── armeabi-v7a/  # ARM 32位
            │   │           ├── include/
            │   │           └── lib/
            │   ├── CMakeLists.txt
            │   └── hello.cpp
            └── ets/
第 3 步：复制编译产物
bash 复制代码 
# 复制头文件和库文件
cp -r lycium/usr/zlib/arm64-v8a MyApp/entry/src/main/cpp/thirdparty/zlib/
cp -r lycium/usr/zlib/armeabi-v7a MyApp/entry/src/main/cpp/thirdparty/zlib/
第 4 步：复制动态库到 libs 目录（仅动态库）

如果是动态库（.so 文件），还需要复制到 libs 目录：

bash 复制代码 
# 创建 libs 目录
mkdir -p MyApp/entry/libs/arm64-v8a
mkdir -p MyApp/entry/libs/armeabi-v7a

# 复制 so 文件（注意：复制 soname 对应的文件）
# 查看 soname
$OHOS_SDK/native/llvm/bin/llvm-readelf -d lycium/usr/zlib/arm64-v8a/lib/libz.so

# 复制正确的文件
cp lycium/usr/zlib/arm64-v8a/lib/libz.so.1.3.1 MyApp/entry/libs/arm64-v8a/
cp lycium/usr/zlib/armeabi-v7a/lib/libz.so.1.3.1 MyApp/entry/libs/armeabi-v7a/

⚠️ 重要提示：必须复制 soname 指定的文件，而不是软链接！

第 5 步：配置 CMakeLists.txt
cmake 复制代码 
cmake_minimum_required(VERSION 3.4.1)
project(MyApp)

# 设置第三方库路径
set(THIRDPARTY_DIR ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty)

# 配置头文件路径
target_include_directories(entry PRIVATE
    ${THIRDPARTY_DIR}/zlib/${OHOS_ARCH}/include
)

# 链接库文件
# 静态库
target_link_libraries(entry PRIVATE
    ${THIRDPARTY_DIR}/zlib/${OHOS_ARCH}/lib/libz.a
)

# 或动态库
target_link_libraries(entry PRIVATE
    ${THIRDPARTY_DIR}/zlib/${OHOS_ARCH}/lib/libz.so
)
第 6 步：在 C++ 代码中使用
cpp 复制代码 
// hello.cpp
#include <napi/native_api.h>
#include <zlib.h>  // 使用第三方库

static napi_value Compress(napi_env env, napi_callback_info info) {
    // 使用 zlib 的功能
    z_stream stream;
    stream.zalloc = Z_NULL;
    stream.zfree = Z_NULL;
    
    int ret = deflateInit(&stream, Z_DEFAULT_COMPRESSION);
    if (ret == Z_OK) {
        // 压缩操作
        deflateEnd(&stream);
    }
    
    // 返回结果到 ArkTS
    napi_value result;
    napi_create_int32(env, ret, &result);
    return result;
}

EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports) {
    napi_property_descriptor desc[] = {
        {"compress", nullptr, Compress, nullptr, nullptr, nullptr, napi_default, nullptr}
    };
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}
EXTERN_C_END

static napi_module demoModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "entry",
    .nm_priv = ((void*)0),
    .reserved = { 0 },
};

extern "C" __attribute__((constructor)) void RegisterEntryModule(void) {
    napi_module_register(&demoModule);
}
第 7 步：在 ArkTS 中调用
typescript 复制代码 
// index.ets
import testNapi from 'libentry.so'

@Entry
@Component
struct Index {
  @State message: string = 'Hello World'

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
        Button('Compress')
          .onClick(() => {
            let result = testNapi.compress()
            this.message = `Result: ${result}`
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

常见问题

问题 1：找不到 so 文件
复制代码 
Error: dlopen failed: library "libz.so.1" not found

原因：

  • so 文件没有复制到 entry/libs/${OHOS_ARCH}/
  • 复制的是软链接而不是实际文件

解决：

bash 复制代码 
# 查看 soname
llvm-readelf -d libz.so | grep SONAME

# 复制对应的文件
cp libz.so.1.3.1 entry/libs/arm64-v8a/
问题 2：编译时找不到头文件
复制代码 
fatal error: 'zlib.h' file not found

解决 ：

检查 CMakeLists.txt 中的 target_include_directories 配置。

问题 3：链接错误
复制代码 
undefined reference to `deflate'

解决 ：

检查 target_link_libraries 是否正确配置了库文件路径。

高级功能

移植原则

核心原则：移植过程不可以改源码！

  • ❌ 不允许 patch .c/.cpp 文件
  • ❌ 不允许 patch 构建脚本
  • ✅ 如果必须 patch，需要充分的理由并经过评审
  • ✅ 不接受业务相关的 patch

外部仓库管理

对于不方便直接放在 thirdparty 目录的库，可以使用外部仓库功能。

配置 module.json
json 复制代码 
{
  "modules": [
    {
      "name": "tree",
      "version": "2.2.1",
      "git": {
        "url": "https://gitcode.com/OpenHarmonyPCDeveloper/ohos_tree.git",
        "branch": "ohos_2.2.1"
      }
    }
  ]
}
使用外部仓库
bash 复制代码 
# 构建系统会自动：
# 1. 检查 outerrepo/tree 是否存在
# 2. 如果不存在，根据 module.json 克隆仓库
# 3. 切换到指定分支
# 4. 执行构建

./build.sh tree

多版本支持（TODO）

未来版本将支持同一库的多个版本：

bash 复制代码 
# 期望的功能
./build.sh openssl@1.1.1
./build.sh openssl@3.0.0

# 依赖也可以指定版本
depends=("zlib>=1.2.11" "openssl@1.1.1")

并行编译

bash 复制代码 
# 在 build.sh 中配置
export MAKE="make -j8"     # Make 使用 8 线程
export Ninja="ninja -j8"   # Ninja 使用 8 线程

编译日志

每个库的编译会生成日志文件：

bash 复制代码 
# 构建日志
thirdparty/zlib/zlib-1.3.1-arm64-v8a-lycium_build.log

# 公共日志
thirdparty/zlib/zlib-public-lycium_build.log

# 主构建日志
lycium/lycium_build_intl.log

问题排查

编译问题

问题 1：环境检查失败
bash 复制代码 
gcc 命令未安装, 请先安装 gcc 命令

解决：

bash 复制代码 
# Ubuntu/Debian
sudo apt-get install build-essential

# CentOS/RHEL
sudo yum groupinstall "Development Tools"

# macOS
xcode-select --install
brew install gcc
问题 2：SDK 路径错误
bash 复制代码 
OHOS_SDK 未设置, 请先下载安装ohos SDK

解决：

bash 复制代码 
# 检查 SDK 目录结构
ls $OHOS_SDK/native/llvm/bin

# 如果路径错误，重新设置
export OHOS_SDK=/correct/path/to/sdk
问题 3：依赖未满足
bash 复制代码 
zlib not ready. wait openssl

原因：依赖库未编译

解决：

bash 复制代码 
# 先编译依赖
./build.sh openssl

# 再编译目标库
./build.sh zlib
问题 4：SHA512 校验失败
bash 复制代码 
SHA512SUM 校验失败, 请确认 SHA512SUM 无误后, 重新编译

解决：

bash 复制代码 
# 重新下载源码
rm packagename.tar.gz

# 重新生成校验和
wget <source-url>
sha512sum packagename.tar.gz > SHA512SUM

# 或者删除 SHA512SUM 文件（不推荐）
rm SHA512SUM
问题 5：交叉编译失败
bash 复制代码 
configure: error: cannot run C compiled programs

解决 ：

确保使用了正确的工具链文件：

bash 复制代码 
# CMake 项目
-DCMAKE_TOOLCHAIN_FILE=$OHOS_SDK/native/build/cmake/ohos.toolchain.cmake

# Configure 项目
--host=aarch64-linux-ohos

测试问题

问题 1：测试环境不完整
bash 复制代码 
cmake command not found, please follow the CITools instruction

解决 ：

参考 CItools 文档安装测试环境。

问题 2：动态库找不到
bash 复制代码 
error while loading shared libraries: libz.so: cannot open shared object file

解决：

bash 复制代码 
# 测试脚本应该会自动设置，如果没有：
export LD_LIBRARY_PATH=$LYCIUM_ROOT/usr/zlib/$ARCH/lib:$LD_LIBRARY_PATH
问题 3：测试权限不足
bash 复制代码 
mount: permission denied

解决：

bash 复制代码 
# 需要 root 权限
hdc shell mount -o remount,rw /

最佳实践

1. 目录命名规范

bash 复制代码 
# 库目录名应该与 pkgname 一致
thirdparty/zlib/        # ✅ 正确
thirdparty/ZLIB/        # ❌ 错误
thirdparty/zlib-1.3.1/  # ❌ 不要包含版本号

2. 版本号管理

bash 复制代码 
# HPKBUILD 中
pkgname=zlib
pkgver=1.3.1          # 精确版本号
pkgrel=0              # 适配版本，每次修改 HPKBUILD 时递增

# builddir 通常是
builddir="$pkgname-$pkgver"   # zlib-1.3.1

3. 补丁文件管理

bash 复制代码 
# 补丁文件命名
0001-fix-cross-compile.patch   # 按顺序编号
0002-disable-tests.patch

# 补丁开头应该包含说明
# --- 0001-fix-cross-compile.patch ---
# 修复交叉编译时的路径问题
# 影响文件：CMakeLists.txt
# 原因：原始脚本假设本地编译
# ---

4. 依赖声明

bash 复制代码 
# 运行时依赖
depends=("zlib" "openssl")

# 构建时依赖
makedepends=("cmake" "pkg-config")

# 注意：
# 1. depends 中的库必须先编译
# 2. makedepends 中的工具必须系统已安装
# 3. 依赖库的 archs 必须是当前库 archs 的超集

5. 编译选项

bash 复制代码 
# 推荐的 CMake 选项
-DCMAKE_BUILD_TYPE=Release        # 使用 Release 模式
-DBUILD_SHARED_LIBS=ON           # 优先生成动态库
-DBUILD_TESTING=OFF              # 编译时关闭测试
-DCMAKE_SKIP_RPATH=ON            # 跳过 RPATH

6. 测试编写

bash 复制代码 
# checkprepare 中设置环境
checkprepare() {
    export LD_LIBRARY_PATH=...
    mkdir -p test_dirs
    return 0
}

# openharmonycheck 中执行测试
openharmonycheck() {
    # 1. 尽量使用原生测试框架（ctest）
    # 2. 记录详细日志
    # 3. 返回正确的退出码
    return $res
}

7. 文档编写

每个库目录下应该包含 README.md：

markdown 复制代码 
# 库名称

## 版本信息
- 原始版本：x.y.z
- 适配版本：0
- 支持架构：armeabi-v7a, arm64-v8a

## 依赖
- zlib >= 1.2.11
- openssl = 1.1.1

## 编译
\`\`\`bash
cd lycium
./build.sh pkgname
\`\`\`

## 使用
\`\`\`cmake
find_package(PkgName REQUIRED)
target_link_libraries(your_target PkgName::PkgName)
\`\`\`

## 已知问题
- 无

## 测试状态
- ✅ arm64-v8a: 全部通过
- ✅ armeabi-v7a: 全部通过

8. 代码审查清单

提交前检查：

  • HPKBUILD 中所有必填字段已填写
  • pkgname 与目录名一致
  • archs 根据实际测试填写
  • depends 正确列出所有依赖
  • SHA512SUM 文件存在且正确
  • 补丁文件有详细说明
  • 在目标架构上测试通过
  • HPKCHECK 测试脚本完整
  • README.md 文档完整
  • 无业务相关的 patch

常见问题 FAQ

Q1：为什么叫 Lycium？

A：Lycium（枸杞）是一种植物，寓意项目像枸杞一样"滋补"OpenHarmony 生态，为其提供丰富的第三方库支持。

Q2：可以在 Windows 上使用吗？

A：不建议。Lycium 是基于 Bash 脚本的，虽然可以通过 WSL 或 Cygwin 运行，但推荐使用 Linux 或 macOS。

Q3：如何贡献新的库？

A：

  1. Fork 项目
  2. 在 thirdparty 目录创建新库目录
  3. 编写 HPKBUILD 和 HPKCHECK
  4. 测试通过后提交 Pull Request

Q4：支持哪些 OpenHarmony 版本？

A：理论上支持所有 4.0+ 版本，具体取决于使用的 SDK 版本。

Q5：编译产物可以商用吗？

A：取决于第三方库的开源协议，请查看每个库的 license 字段。

Q6：如何调试编译问题？

A：

bash 复制代码 
# 查看详细日志
tail -f thirdparty/pkgname/pkgname-*-lycium_build.log

# 手动进入构建目录
cd thirdparty/pkgname/pkgname-x.y.z
# 手动执行编译命令

Q7：可以编译静态库吗？

A：可以，在 build() 函数中设置：

bash 复制代码 
-DBUILD_SHARED_LIBS=OFF

Q8：如何加速编译？

A：

  1. 使用 ccache
  2. 增加并行任务数：export MAKE="make -j16"
  3. 使用 SSD 硬盘
  4. 使用 Ninja 代替 Make

Q9：测试失败怎么办？

A：

  1. 查看测试日志：lycium/check_result/check_fault/
  2. 检查依赖库是否正确安装
  3. 确认设备架构与编译架构一致
  4. 联系库的维护者

Q10：如何更新库的版本？

A：

  1. 修改 HPKBUILD 中的 pkgver
  2. 更新 source URL
  3. 重新生成 SHA512SUM
  4. 测试编译和运行
  5. 提交更新

附录

A. 工具链文件路径

工具 路径
CMake ${OHOS_SDK}/native/build-tools/cmake/bin/cmake
Clang (ARM64) ${OHOS_SDK}/native/llvm/bin/aarch64-linux-ohos-clang
Clang++ (ARM64) ${OHOS_SDK}/native/llvm/bin/aarch64-linux-ohos-clang++
Clang (ARM32) ${OHOS_SDK}/native/llvm/bin/arm-linux-ohos-clang
Clang++ (ARM32) ${OHOS_SDK}/native/llvm/bin/arm-linux-ohos-clang++
llvm-readelf ${OHOS_SDK}/native/llvm/bin/llvm-readelf

B. 架构标识

标识 说明 GCC Target
armeabi-v7a ARM 32位 ARMv7-A arm-linux-ohos
arm64-v8a ARM 64位 ARMv8-A aarch64-linux-ohos
x86 Intel 32位 i686-linux-ohos
x86_64 Intel 64位 x86_64-linux-ohos

C. 退出码说明

退出码 说明
0 成功
1 一般错误
2 文件格式错误
101 依赖未满足

D. 参考资源

相关推荐
人间打气筒（Ada）3 小时前
[鸿蒙2025领航者闯关]星盾护航支付安全：鸿蒙6.0在金融APP中的实战闯关记
安全·金融·harmonyos·#鸿蒙2025领航者闯关#·#鸿蒙6实战#·#开发者年度总结#
hh.h.3 小时前
灰度发布与A/B测试：Flutter+鸿蒙的分布式全量发布方案
分布式·flutter·harmonyos
路人与大师4 小时前
PaddleOCR VL 华为NPU 910B 环境配置完成报告
华为
讯方洋哥4 小时前
HarmonyOS实战开发调试
harmonyos
yenggd4 小时前
华为sr-mpls TE配置案例
网络·华为
yenggd4 小时前
华为+sr-mpls BE简单配置案例
运维·网络·华为
柒儿吖12 小时前
m4宏处理器在鸿蒙PC上的应用指南
华为·harmonyos
讯方洋哥14 小时前
初探HarmonyOS应用
华为·harmonyos
C雨后彩虹14 小时前
任务总执行时长
java·数据结构·算法·华为·面试
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03Linux下V2Ray安装配置指南04在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）05BongoCat - 跨平台键盘猫动画工具06安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）07【AutoGLM部署】本地私有化部署AI手机Agent08Neo4j（一） - Neo4j安装教程（Windows）09Open-AutoGLM Windows 安装部署教程10Cursor 又偷偷更新，这个功能太实用：Visual Editor for Cursor Browser