在 Ubuntu 中搭建鸿蒙 PC 三方库交叉编译构建开发环境

📖 本文适合谁？

• • 第一次在 Ubuntu 上搭建鸿蒙 PC 相关 C/C++ 三方库交叉编译 环境的新手
• • 需要按步骤完成：系统依赖 → OHOS SDK → 环境变量 → lycium++ → 用 cups 验证环境可行性 的开发者

读完本文后，你将能够：

• • ✅ 在 Ubuntu 上安装交叉编译所需基础工具
• • ✅ 下载、解压并正确配置 OHOS SDK 与 HNP 工具链
• • ✅ 克隆 lycium++ 并完成一次示例库（cups）的构建与产物打包

🎯 环境一览（开始前请对照）

💡 关于 Ubuntu
Ubuntu 是常用的 Linux 发行版，社区资料多、易上手。本文示例将工作目录统一放在 /home/ohpkg，你也可以改成自己的路径，但后文 OHOS_SDK 等变量需一并修改。

🗺️ 整体步骤（建议按顺序做）

🛠️ 基本工具准备

lycium 支持多种构建方式的三方库。为保证能正常编译，请先安装常用构建工具：

sudo apt-get install gcc g++; sudo apt-get install cmake; sudo apt-get install make; sudo apt-get install pkg-config; sudo apt-get install autoconf; sudo apt-get install autoreconf; sudo apt-get install automake; sudo apt-get install git git-lfs

📌 新手提示
若提示权限不足，请在 apt-get 前加 sudo。

⬇️ 下载 OHOS SDK

方式 A：本机有图形界面

1. 1. 浏览器打开 OpenHarmony 镜像站点说明^[8] ，在目录中点击**「源码获取」--> 「从镜像站点获取」**。
2. 2. 找到 「标准系统 Public SDK 包（Windows/Linux）」 一行，点击 站点 链接下载 ohos-sdk

方式 B：仅 SSH 远程 Ubuntu

1. 1. 在你日常用的电脑浏览器打开同上镜像说明页 ，在目录中点击**「源码获取」--> 「从镜像站点获取」**。
2. 2. 对 「标准系统 Public SDK 包（Windows/Linux）」 的 站点 链接 右键 → 复制链接
3. 3. 在 Ubuntu 终端执行 wget 下载（例如通过 VS Code Remote SSH 连上 Ubuntu 后，在集成终端操作）

示例：固定目录并下载

为方便管理，下文默认将所有内容放在 /home/ohpkg（可自定义，记得同步改环境变量）。

📋 说明
执行下面命令创建目录并下载 SDK 压缩包（链接以镜像站当前版本为准，若 404 请回到镜像页复制最新地址）。

cd /home
mkdir ohpkg
cd ohpkg
wget https://repo.huaweicloud.com/openharmony/os/6.0-Release/ohos-sdk-windows_linux-public.tar.gz

📂 解压 OHOS SDK

1. 1. 进入目录并确认压缩包已下载：

cd /home/ohpkg
ls

1. 2. 解压（文件名以你实际下载的为准，下图为示例）：

tar -zxf version-Master_Version-OpenHarmony_6.1.0.31_sp1-20260318_020533-ohos-sdk-full_6.1-Release_img.tar.gz
tree -L 2

1. 3. 交叉编译主要使用 native 工具链，通常还需解压 linux 目录下的 native-linux-x64-*.zip（版本号以你包内实际文件名为准）：

cd /home/ohpkg/linux
unzip -q native-linux-x64-6.0.0.47-Beta1.zip
tree -L 2

⚙️ 配置环境变量

lycium 做 C/C++ 三方库交叉编译时，OHOS_SDK 应指向 native 的父目录（即包含 native 的那一层，示例中为 linux 目录）。

vim ~/.bashrc

# 在文件末尾添加（路径改成你的实际解压目录）
export OHOS_SDK=/home/ohpkg/linux

# 保存退出后执行
source ~/.bashrc

🏗️ lycium 交叉编译框架

lycium 帮助开发者用 Shell 配置三方库的编译方式与参数，快速产出可在 OpenHarmony 上验证的二进制/库文件。

✨ 核心功能

• • 🔗 依赖关系管理：构建依赖树，支持一键构建
• • 📦 多版本构建：支持 HPKBUILD 多版本，代码仓可独立发布
• • 🎯 HNP 产物：可生成 HarmonyOS 使用的 HNP 构建产物
• • 💻 本机编译：支持在华为鸿蒙 PC（DevBox）上本机构建
• • 📄 开源声明聚合：计划支持聚合开源声明生成 HTML（进行中）🚧

📥 克隆 lycium++ 工程

在 /home（或你喜欢的目录）执行：

git clone https://gitcode.com/OpenHarmonyPCDeveloper/lycium_plusplus.git

📁 目录结构速查

lycium_plusplus/
├── LICENSE                          # 📜 项目许可证
├── README.md                        # 📖 项目说明文档
├── openharmony_tpc_c_cplusplus_LICENSE  # 📜 OpenHarmony TPC 许可证
├── community/                       # 👥 社区主导的构建库（隐式依赖）
├── external_deps/                   # 🔌 外部适配仓
│   ├── module.json                  # ⚙️ 外部依赖配置文件
│   ├── muslc_gext/                  # 🔧 muslc 扩展库
│   └── tree/                        # 🌳 tree 工具的适配
├── thirdparty/                      # 📚 三方库目录（显式构建）
└── lycium/                          # 🏗️ lycium 编译框架核心
    ├── build.sh                     # 🚀 主构建脚本
    ├── build_local.sh               # 💻 本机构建脚本
    ├── script/                      # 📜 构建脚本集合
    │   ├── build_hpk.sh             # 📦 HPK 构建脚本
    │   ├── envset.sh                # 🔧 环境变量设置脚本
    │   └── load_outer_parts.py      # 📥 外部依赖加载脚本
    ├── template/                    # 📋 HPKBUILD 模板
    ├── output/                      # 📤 编译产物输出目录
    └── usr/                         # 📁 安装目录

📌 说明：上面树形结构中 lycium/ 下子项的缩进已按常见层级整理，便于新手对照本地目录。

📋 构建系统详解

HPKBUILD 文件格式

HPKBUILD 是核心配置，描述三方库如何下载、编译、安装：

pkgname=NAME              # 📦 库名
pkgver=VERSION           # 🏷️ 库版本
pkgrel=0                 # 🔢 发布号
pkgdesc=""# 📄 库描述
url=""# 🔗 官网链接
archs=("armeabi-v7a""arm64-v8a")  # 💻 CPU 架构
license=()               # ⚖️ 许可证
depends=()               # 🔗 依赖库的目录名
makedepends=()           # 🛠️ 构建依赖工具
source=""# 📥 源码下载链接

downloadpackage=true# 📥 是否自动下载压缩包
autounpack=true# 📦 是否自动解压
buildtools=              # 🔨 编译方法（cmake/configure/make）

构建流程（函数阶段）

• • ⚙️ prepare：准备环境、创建编译目录
• • 🔨 build：执行编译
• • 📦 package：安装产物
• • 📤 archive：归档（可选）
• • ✅ check：测试（可选）
• • 🧹 cleanbuild：清理构建目录

构建模式

• • 🔀 交叉编译模式：在 Linux 上为 OpenHarmony 交叉编译
• • 💻 本机编译模式：在鸿蒙 PC（DevBox）上本机编译

✅ 以三方库 cups 验证环境

下面用仓库里已有的 cups 适配做一次完整验证。

1️⃣ 进入 lycium 目录并构建

• • 三方库适配文件在：/home/lycium_plusplus/thirdparty/cups
• • 在终端执行：

cd /home/lycium_plusplus/lycium/
./build.sh cups

❓ 常见问题 1：ninja 未安装

现象：提示 ninja 命令未安装。

处理：

sudo apt install ninja-build

然后重新执行：

./build.sh cups

❓ 常见问题 2：arm64-v8a 构建失败（CPP 被设成 C++ 编译器）

现象：armeabi-v7a 成功，arm64-v8a 失败。
原因：在 envset.sh 的 setarm64ENV() 中若设置了 export CPP=${CXX}，会把 C 预处理器错误指到 aarch64-linux-ohos-clang++，应改为正确的 C 预处理器配置（按你当前框架版本修复该函数后）再构建。

修复后重新执行：

./build.sh cups

🎉 构建成功标志

出现 Build cups 2.3.6 end! ALL JOBS DONE!!! 表示构建成功。
检查目录：/home/lycium_plusplus/lycium/usr/cups 下是否包含 armeabi-v7a、arm64-v8a 等架构产物。

📦 可选：生成 tar 包与 HNP

若需要在 arm64-v8a/bin 等目录外方便分发 HNP 与 tar，可在 /home/lycium_plusplus/thirdparty/cups 的 HPKBUILD 中增加 archive 函数，例如：

archive() {
mkdir -p ${LYCIUM_ROOT}/output/$ARCH
pushd$LYCIUM_ROOT/usr/$pkgname/$ARCH
        tar -zvcf ${LYCIUM_ROOT}/output/$ARCH/${pkgname}_${pkgver}.tar.gz *
popd
cp hnp.json $LYCIUM_ROOT/usr/$pkgname/$ARCH
${HNP_TOOL} pack -i ${LYCIUM_ROOT}/usr/$pkgname/$ARCH -o ${LYCIUM_ROOT}/output/$ARCH/
}

再次在 lycium 目录执行 ./build.sh cups。若出现 pack: command not found，说明未配置 hnpcli，需要解压工具链并设置 HNP_TOOL：

cd /home/ohpkg/linux
unzip -q toolchains-linux-x64-6.0.0.47-Beta1.zip
vim ~/.bashrc

# 在最后一行添加（路径按实际解压位置修改）
export HNP_TOOL=/home/ohpkg/linux/toolchains/hnpcli

source ~/.bashrc

然后重新执行 ./build.sh cups。

最终在 /home/lycium_plusplus/lycium/output 下各架构目录中可看到对应的 hnp 与 tar 包。

🎓 小结

至此，Ubuntu 上鸿蒙 PC 三方库交叉编译开发环境 搭建完成。后续可在 thirdparty 中参考 cups 编写自己的 HPKBUILD 进行适配。🚀

引用链接

[1] lycium_plusplus 仓库:https://atomgit.com/OpenHarmonyPCDeveloper/lycium_plusplus
[2]OpenHarmony 镜像站点说明:https://atomgit.com/openharmony/docs/blob/master/zh-cn/release-notes/OpenHarmony-v6.0-release.md