【鸿蒙PC三方库移植适配框架解读系列】第一篇：Lycium C/C++ 三方库适配 — 概述与环境配置

系列导读：本文是 Lycium 适配系列的第一篇，介绍 Lycium 框架的核心概念、适配工作本质，以及如何搭建完整的交叉编译环境。

欢迎加入【开源鸿蒙PC社区】，一起共建鸿蒙化C/C++三方库生态。

前言

项目	说明
macOS环境配置	https://bxming.blog.csdn.net/article/details/159284830
Ubuntu环境配置（或者windows + wsl）	https://bxming.blog.csdn.net /article/details/159284760
lycium框架	https://atomgit.com/OpenHarmonyPCDeveloper/lycium_plusplus.git
应用平台	HarmonyOS PC

系列索引

篇章	标题	内容
第一篇	概述与环境配置	Lycium 概念、构建机要求、OHOS SDK 配置
第二篇	项目结构与适配目录创建	目录结构、community vs thirdparty、创建适配目录
第三篇	HPKBUILD 编写详解	元数据字段、过程函数、三种构建系统写法
第四篇	构建执行与产物获取	构建流程、日志分析、多库递归、HAP 集成
第五篇	流程图与角色职责	完整流程图、各角色职责、协作时序
第六篇	关键注意事项与最佳实践	依赖管理、架构超集、日志调试、外部适配仓
第七篇	快速参考与模板	入门步骤、模板、完整案例、检查清单

1. 什么是 Lycium？

Lycium 是 OpenHarmony 官方提供的 C/C++ 三方库交叉编译框架。

一句话概括 ：Lycium 的角色类似于嵌入式领域的 Buildroot 或 Yocto，但更轻量------它只做一件事：将上游开源的 C/C++ 库，编译成可在 OpenHarmony 设备上运行的二进制文件（.so 动态库 / .a 静态库）。

核心设计思想

Lycium 的设计深受 Arch Linux 的 PKGBUILD 影响：

• 每个库对应一个 HPKBUILD 描述文件（类比 PKGBUILD）
• 元数据是声明式的：库名、版本、架构、依赖等用变量定义
• 构建逻辑是过程式的：prepare、build、package 等阶段用 shell 函数实现
• 框架负责编排 （下载、解压、设置工具链、循环多架构），适配者只负责告诉框架怎么做

典型适配场景

场景	说明
新增一个开源库	将 curl、sqlite、openssl 等 C 库移植到 OH
升级库版本	修改 pkgver，必要时调整 build() 中的 API 变更
修复构建失败	上游代码不兼容 OH 时，通过 patch 打补丁或修改 build() 参数
添加新架构	在 archs 中添加 "arm64-v8a" 等

---

2. 构建环境要求

2.1 构建机（开发主机）

可以选择 Linux（Ubuntu 22.04+） 、 macOS 、Windows + WSL/Linux虚拟机 、以及HarmonyOS PC其一。本篇文章选择使用macOS作为开发主机。

必需工具一览

工具/组件	角色	说明
gcc / clang	本机编译器	构建本机辅助工具，部分 makedepends 命令检测
cmake (≥3.16)	构建系统	CMake 项目的构建工具，Lycium 会使用 OHOS SDK 中定制的 cmake
make	构建系统	Makefile 项目的构建驱动，build_hpk.sh 中默认 make -j$(nproc)
ninja	构建系统	Ninja 项目构建驱动，某些 CMake 项目生成器选择 Ninja
pkg-config	依赖定位	configure/cmake 项目查找已安装库的 .pc 文件
autoconf / autoreconf / automake	构建系统	autotools 项目的构建工具链（生成 configure 脚本）
wget	源码下载	下载上游源码压缩包
sha512sum	完整性校验	校验源码包哈希值（coreutils 自带）
git	源码/适配仓获取	克隆外部适配仓、应用 patch

Ubuntu 一键安装

sudo apt install gcc cmake make ninja-build pkg-config autoconf automake wget

macOS 注意事项

macOS 上需要额外注意：

• 工具链使用 OHOS SDK 中的交叉编译器，不需要 Xcode Clang
• sha512sum 在 macOS 上需通过 brew install coreutils 安装
• pkg-config 通过 brew install pkg-config 安装
• 文件路径、sed 语法与 Linux 有差异，注意 build() 函数中的兼容性

2.2 OpenHarmony SDK（OHOS_SDK）

这是适配工作中最关键的外部依赖。SDK 提供了：

1. 交叉编译器（arm-linux-ohos-clang、aarch64-linux-ohos-clang 等）
2. LLVM 工具链（ld.lld、llvm-ar、llvm-strip、llvm-ranlib、llvm-nm、llvm-objcopy 等）
3. CMake + 交叉编译 toolchain 文件 （ohos.toolchain.cmake）
4. musl libc sysroot（OpenHarmony 系统 C 库头文件和库）
5. HNP 打包工具（hnpcli，用于生成鸿蒙 Native Package）

SDK 目录结构详解

${OHOS_SDK}/
├── native/
│   ├── llvm/bin/
│   │   ├── arm-linux-ohos-clang          # armeabi-v7a C 编译器
│   │   ├── arm-linux-ohos-clang++        # armeabi-v7a C++ 编译器
│   │   ├── aarch64-linux-ohos-clang      # arm64-v8a C 编译器
│   │   ├── aarch64-linux-ohos-clang++    # arm64-v8a C++ 编译器
│   │   ├── x86_64-linux-ohos-clang       # x86_64 C 编译器（模拟器用）
│   │   ├── x86_64-linux-ohos-clang++     # x86_64 C++ 编译器
│   │   ├── ld.lld                        # LLVM 链接器
│   │   ├── llvm-ar                       # 静态库归档工具
│   │   ├── llvm-strip                    # 符号剥离工具
│   │   ├── llvm-ranlib                   # 静态库索引生成
│   │   ├── llvm-nm                       # 符号查看工具
│   │   └── llvm-objcopy / llvm-objdump   # 目标文件操作工具
│   ├── build-tools/cmake/bin/
│   │   └── cmake                         # OHOS 定制的 cmake（内嵌 toolchain 配置）
│   ├── build-tools/cmake/share/
│   │   └── ohos.toolchain.cmake          # CMake 交叉编译 toolchain 文件
│   └── sysroot/                          # OpenHarmony musl libc 系统头文件和库
└── toolchains/
    └── hnpcli                            # HNP 打包工具（生成鸿蒙 Native Package）

各组件作用详解：

组件	路径	作用
交叉编译器	llvm/bin/	将 x86_64 主机上的 C/C++ 代码编译为 ARM/ARM64 可执行文件
LLVM 工具链	llvm/bin/	链接、归档、符号剥离等后处理操作，与编译器保持版本一致
定制 CMake	build-tools/cmake/bin/cmake	内嵌 OHOS toolchain 配置，自动识别 OHOS 目标平台
sysroot	sysroot/	OHOS 的 C 库（musl libc）头文件和系统库，交叉编译时的"目标系统根目录"
hnpcli	toolchains/hnpcli	鸿蒙 Native Package 命令行打包工具，将 .so/.a/.h 打包为 .hnp 格式

注意 ：OHOS_SDK 环境变量需要指向 native/ 目录的父目录 ，而不是 native/ 内部。

环境变量设置

Lycium 通过 lycium/script/envset.sh 中的函数为不同架构自动设置环境变量：

函数	目标架构
setarm32ENV()	armeabi-v7a（32位 ARM）
setarm64ENV()	arm64-v8a（64位 ARM，含 --sysroot）
setx86_64ENV()	x86_64（模拟器）
setHarmonyOSENV()	鸿蒙本机构建（DevBox）

鸿蒙本机构建（DevBox） ：当直接在 OpenHarmony 设备上构建时（而非主机交叉编译），使用 setHarmonyOSENV()。该函数设置 TARGET_HARMONYOS=true，仅构建 arm64-v8a 架构，编译器使用设备本地 clang。对应入口脚本为 build_local.sh：

./build_local.sh <pkgname>

以 arm64-v8a 为例，设置的核心环境变量：

export CC=aarch64-linux-ohos-clang
export CXX=aarch64-linux-ohos-clang++
export AR=llvm-ar
export LD=ld.lld
export STRIP=llvm-strip
export CFLAGS="-DOHOS_NDK -fPIC -D__MUSL__=1 -D__OHOS__ --sysroot=${SYSROOT}"
export CXXFLAGS="${CFLAGS}"
export SYSROOT="${OHOS_SDK}/native/sysroot"

配置 SDK

# 设置环境变量（建议写入 ~/.bashrc 或 ~/.zshrc）
export OHOS_SDK=/home/user/ohos-sdk/linux

# 验证
ls $OHOS_SDK/native/llvm/bin/aarch64-linux-ohos-clang
# 输出：/home/user/ohos-sdk/linux/native/llvm/bin/aarch64-linux-ohos-clang

2.3 目标架构

OpenHarmony 当前主要支持以下 CPU 架构：

架构	archs 值	编译器三元组	说明
32位 ARM	armeabi-v7a	arm-linux-ohos	旧设备/低端设备（IoT）
64位 ARM	arm64-v8a	aarch64-linux-ohos	主流设备（手机、平板、TV）
x86_64	x86_64	x86_64-linux-ohos	模拟器/特定设备

实际适配中的建议：

• 如果没有特殊需求，至少适配 arm64-v8a（当前绝大多数 OH 设备）
• 同时支持 armeabi-v7a 可覆盖更多存量设备
• x86_64 主要用于模拟器调试，按需添加

---

3. 环境验证：快速跑通第一个库

在进入正式的适配流程之前，建议先验证环境是否正确。最简单的验证方式是构建一个 Lycium 官方已经适配好的库（如 cJSON）：

# 1. 确保 OHOS_SDK 已设置
export OHOS_SDK=/path/to/ohos-sdk/linux

# 2. 获取框架代码
git clone https://atomgit.com/OpenHarmonyPCDeveloper/lycium_plusplus.git
cd lycium_plusplus
# 3. 构建一个已验证的库
./build.sh cJSON

如果构建成功，lycium/usr/cJSON/ 下会出现 arm64-v8a/ 等架构目录，包含 include/、lib/ 等产物。

💡 常见环境问题排查：

• OHOS_SDK 未设置 → 在 build.sh 中会报 "not set yet" 错误
• cmake 版本过低 → 使用 SDK 自带的 cmake ($OHOS_SDK/native/build-tools/cmake/bin/cmake)
• 缺少 sha512sum → macOS 上 brew install coreutils，Linux 上 apt install coreutils

---

下篇预告

环境就绪后，下一篇文章将介绍 Lycium 的项目目录结构，以及如何创建库的适配目录、编写必要的文件（README.OpenSource、SHA512SUM、OAT.xml 等）。