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

📖 本文适合谁？

• 第一次在 macOS 上搭建鸿蒙 PC 相关 C/C++ 三方库交叉编译 环境的新手

读完本文后，你将能够：

• ✅ 通过 DevEco Studio 下载并定位 OHOS SDK（API 20）
• ✅ 正确配置 OHOS_SDK / HNP_SDK（或 HNP_TOOL） 等环境变量
• ✅ 克隆 lycium++ 并用示例库 bzip2 完成一次完整构建（含可选 HNP/tar）

---

🎯 工具与版本一览

工具名称	版本 / 地址	说明
🛠️ DevEco Studio	与 OpenHarmony API 20 配套版本	安装指南见 Windows 11 安装 DevEco Studio 完整指南（macOS 步骤类似）
📦 ohos-sdk	6.0 Release 及以上；本文使用 API 20	在 DevEco 设置中勾选 API Version 20 下载
🔧 lycium++	仓库 lycium_plusplus	克隆源示例：git clone https://gitcode.com/OpenHarmonyPCDeveloper/lycium_plusplus
💻 鸿蒙 PC	6.0 Release 及以上	与 SDK 大版本保持一致即可

---

📱 本文档验证环境（当前设备 / 成文环境）

下表便于你对照「自己的电脑是否接近」，路径请按本机用户名修改。

项目	版本或取值
🖥️ 操作系统	macOS（Darwin 25.2.0）
🧩 芯片架构	Apple Silicon（arm64）（Intel Mac 亦可按官方工具链说明使用）
🎨 DevEco Studio	支持 OpenHarmony SDK API 20 的版本（以安装后 About 显示为准）
📂 OHOS SDK 路径（示例）	/Users/ming/OpenHarmony/Sdk/20/（native 所在 SDK 根）
🔗 HNP 工具链路径（示例）	/Users/ming/OpenHarmony/Sdk/20/toolchains（与 HNP_SDK / hnpcli 配置一致）
📦 OpenHarmony SDK	API 20（对应 6.0 系）
🧪 验证用三方库	bzip2，构建成功提示含 Build bzip2 1_0_6 end! ALL JOBS DONE!!!

---

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

步骤	内容	对应章节
1️⃣	安装 DevEco Studio，下载 OHOS SDK（API 20）	下载 OHOS SDK
2️⃣	配置 OHOS_SDK、HNP_SDK	配置环境变量
3️⃣	克隆 lycium++，了解目录与 HPKBUILD	lycium 交叉编译框架
4️⃣	用 bzip2 构建验证，按需处理 shebang、HNP	以三方库 bzip2 验证环境

💡 Shell 说明：下文默认使用 zsh（~/.zshrc）。若你使用 bash，请改为 ~/.bash_profile 或 ~/.bashrc。

---

⬇️ 下载 OHOS SDK

1. 启动 DevEco Studio
2. 左侧点击 Customize → Configure… 打开设置
3. 进入 OpenHarmony SDK
4. 勾选 API Version 20，点击 Apply / OK 开始下载

📌 新手提示
下载完成后，请记住 SDK 在本机的实际路径（常见为 ~/OpenHarmony/Sdk/20/，以 DevEco 显示为准），下一步环境变量必须与此一致。

---

⚙️ 配置环境变量

将 SDK 根目录 与 toolchains（含 HNP 相关工具）写入 ~/.zshrc：

vim ~/.zshrc

# 在文件末尾添加（路径改成你的本机 SDK 路径）
export OHOS_SDK=/Users/ming/OpenHarmony/Sdk/20/
export HNP_SDK=/Users/ming/OpenHarmony/Sdk/20/toolchains

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

📌 若 lycium 脚本要求 HNP_TOOL 指向 hnpcli 可执行文件，请在 toolchains 目录下找到实际路径后增加一行，例如：
export HNP_TOOL=/Users/ming/OpenHarmony/Sdk/20/toolchains/hnpcli
（以你本机目录为准。）

---

🏗️ lycium 交叉编译框架

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

✨ 核心功能

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

📥 克隆 lycium++ 工程

在 /Users/ming/AtomGitRepo/ohpkg（或你喜欢的目录）执行：

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/macOS 上为 OpenHarmony 交叉编译
• 💻 本机编译模式：在鸿蒙 PC（DevBox）上本机编译

---

✅ 以三方库 bzip2 验证环境

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

1️⃣ 进入 lycium 目录并构建

• 三方库适配文件在：/Users/ming/AtomGitRepo/ohpkg/lycium_plusplus/thirdparty/bzip2
• 在终端执行：

cd /Users/ming/AtomGitRepo/ohpkg/lycium_plusplus/lycium/
./build.sh bzip2

---

❓ 常见问题 1：bad interpreter: /bin/env: no such file or directory

现象：执行 ./build.sh 时提示 zsh: ./build.sh: bad interpreter: /bin/env: no such file or directory（macOS 上通常没有 /bin/env）。

处理：将 lycium/build.sh 首行 从 #!/bin/env bash 改为 #!/bin/bash，保存后重新执行：

./build.sh bzip2

---

🎉 构建成功标志

出现 Build bzip2 1_0_6 end! ALL JOBS DONE!!! 表示构建成功。
检查目录：/Users/ming/AtomGitRepo/ohpkg/lycium_plusplus/lycium/usr/bzip2 下是否包含 armeabi-v7a、arm64-v8a、x86_64 等架构产物。

---

📦 可选：生成 tar 包与 HNP

若需要在各架构目录外方便分发 HNP 与 tar，可在
/Users/ming/AtomGitRepo/ohpkg/lycium_plusplus/thirdparty/bzip2 的 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/
}

并在同一 thirdparty/bzip2 目录下新增 hnp.json：

{
    "type":"hnp-config",
    "name":"bzip2",
    "version":"1_0_6",
    "install":{}
}

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

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

---

🎓 小结

检查项	说明
✅	DevEco 已下载 API 20 SDK，路径与 OHOS_SDK 一致
✅	已配置 HNP_SDK / HNP_TOOL（若需打 HNP 包）
✅	build.sh 首行在 macOS 上为 #!/bin/bash
✅	./build.sh bzip2 出现 ALL JOBS DONE，且 lycium/usr/bzip2 下有多架构产物

至此，macOS 上鸿蒙 PC 三方库交叉编译开发环境 搭建与验证完成。后续可在 thirdparty 中参考 bzip2 编写自己的 HPKBUILD。🚀