开源鸿蒙终端工具Termony构建HNP包指导手册Mac版

❓ 什么是 HNP？

HNP（OpenHarmony Native Package）是 OpenHarmony 的原生包格式，用于打包原生程序和库。HNP 包本质上是一个 ZIP 文件，包含可执行文件、共享库、配置文件和元数据。

🏗️ 构建 HNP 包

✅ 前置条件

在构建 HNP 包之前，请确保：

✅ 已完成环境配置（Homebrew、开发工具等）
✅ DevEco Studio 已安装（用于提供 OpenHarmony SDK）
✅ 环境变量已正确设置

🛠️ 构建步骤

步骤 1：检查环境变量

确保 TOOL_HOME 和 OHOS_SDK_HOME 已设置：

bash 复制代码

# 检查 TOOL_HOME（如果未设置，脚本会自动设置）
echo $TOOL_HOME
# 应该显示：/Applications/DevEco-Studio.app/Contents

# 检查 OHOS_SDK_HOME（如果未设置，脚本会自动设置）
echo $OHOS_SDK_HOME
# 应该显示：/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony

步骤 2：执行构建脚本

bash 复制代码

# 进入项目根目录
cd /path/to/Termony

# 执行构建脚本
OHOS_ARCH=aarch64 OHOS_ABI=arm64-v8a ./create-hnp.sh

🔍 构建过程详解

执行 ./create-hnp.sh 后，脚本会执行以下步骤：

1. 环境准备

bash 复制代码

# 设置区域设置（确保字符处理使用 C 语言标准）
export LC_CTYPE=C

# 设置工具目录路径
export TOOL_HOME=/Applications/DevEco-Studio.app/Contents

# 设置 OpenHarmony SDK 路径
export OHOS_SDK_HOME=$TOOL_HOME/sdk/default/openharmony

2. 调用 Makefile 构建

脚本会调用 make -C build-hnp，执行主 Makefile 的构建流程：

复制代码

make -C build-hnp
  ↓
all 目标
  ↓
copy 目标
  ↓
base.hnp 目标
  ↓
构建所有包（根据 PKGS 变量）
  ↓
创建 sysroot 目录结构

3. 构建各个包

Makefile 会根据 PKGS 变量中的包列表，逐个构建每个包：

进入每个包的目录（如 bash/、gcc/、vim/ 等）
执行包的 Makefile
将编译好的文件安装到 sysroot/ 目录
创建 .stamp 文件标记构建完成

4. 优化包大小

构建完成后，Makefile 会删除不必要的文档文件：

bash 复制代码

# 删除手册页（减小包体积）
rm -rfv sysroot/share/man

# 删除文档文件
rm -rfv sysroot/share/doc

# 删除信息文件
rm -rfv sysroot/share/info

5. 添加剪贴板工具

将项目提供的剪贴板工具复制到 sysroot：

bash 复制代码

# 复制剪贴板复制工具
cp utils/pbcopy sysroot/bin

# 复制剪贴板粘贴工具
cp utils/pbpaste sysroot/bin

6. 配置 GCC 运行时库

为了让 GCC 编译的程序能在 OpenHarmony 上运行，需要配置运行时库：

bash 复制代码

# 创建 GCC 运行时库目录
mkdir -p sysroot/aarch64-unknown-linux-musl/lib

# 复制 C 运行时启动文件
cp $OHOS_SDK_HOME/native/sysroot/usr/lib/aarch64-linux-ohos/crt1.o ...
cp $OHOS_SDK_HOME/native/sysroot/usr/lib/aarch64-linux-ohos/crti.o ...
cp $OHOS_SDK_HOME/native/sysroot/usr/lib/aarch64-linux-ohos/crtn.o ...

# 复制 C++ 运行时启动文件
cp $OHOS_SDK_HOME/native/llvm/lib/clang/15.0.4/lib/aarch64-linux-ohos/clang_rt.crtbegin.o ...
cp $OHOS_SDK_HOME/native/llvm/lib/clang/15.0.4/lib/aarch64-linux-ohos/clang_rt.crtend.o ...

# 复制 GCC 运行时库（使用 Clang 的 builtins）
cp $OHOS_SDK_HOME/native/llvm/lib/clang/15.0.4/lib/aarch64-linux-ohos/libclang_rt.builtins.a .../libgcc.a
cp $OHOS_SDK_HOME/native/llvm/lib/clang/15.0.4/lib/aarch64-linux-ohos/libclang_rt.builtins.a .../libgcc_s.a

# 复制异常处理库（空库）
cp utils/empty.a .../libgcc_eh.a

7. 打包成 HNP 格式

bash 复制代码

# 复制 HNP 配置文件
cp hnp.json sysroot

# 删除旧的 HNP 包
rm -f base.hnp

# 使用 zip 命令打包整个 sysroot 目录
zip -r base.hnp sysroot

8. 复制到应用目录

bash 复制代码

# 删除旧的 HNP 包
rm -f ../entry/hnp/arm64-v8a/*.hnp

# 复制到应用目录
cp base.hnp ../entry/hnp/arm64-v8a

# 同时创建 base-public.hnp（用于公开包）
cp base.hnp ../entry/hnp/arm64-v8a/base-public.hnp

📦 构建输出

成功标志：

构建成功后，你会看到：

HNP 包文件：

bash 复制代码

ls -lh build-hnp/base.hnp
# 输出：-rw-r--r--  1 user  staff   807K Nov 15 12:30 build-hnp/base.hnp

应用目录中的 HNP 包：

bash 复制代码

ls -lh entry/hnp/arm64-v8a/*.hnp
# 输出：
# -rw-r--r--  1 user  staff   807K Nov 15 12:30 entry/hnp/arm64-v8a/base.hnp
# -rw-r--r--  1 user  staff   807K Nov 15 12:30 entry/hnp/arm64-v8a/base-public.hnp

HNP 包内容：

bash 复制代码

unzip -l build-hnp/base.hnp
# 输出：
# Archive:  build-hnp/base.hnp
#   Length      Date    Time    Name
# ---------  ---------- -----   ----
#         0  11-15-2025 12:27   sysroot/
#         0  11-15-2025 12:27   sysroot/bin/
#   1059232  11-15-2025 12:27   sysroot/bin/tree
#       152  11-15-2025 12:30   sysroot/bin/pbcopy
#       318  11-15-2025 12:30   sysroot/bin/pbpaste
#        80  11-15-2025 12:30   sysroot/hnp.json
#         0  11-15-2025 12:27   sysroot/aarch64-unknown-linux-musl/lib/
#       ... (GCC 运行时库文件)

⏱️ 构建时间

单个包（如 tree）：几秒到几分钟
所有包（54 个）：30-60 分钟（取决于硬件和网络）
增量构建：只构建修改的包，几秒到几分钟

🧯 常见问题

问题 1：找不到 DevEco Studio

错误信息：

复制代码

make: *** No rule to make target '...'.  Stop.

解决方案：

确保 DevEco Studio 已安装在 /Applications/DevEco-Studio.app
或者修改 create-hnp.sh 中的 TOOL_HOME 路径

问题 2：SDK 路径不存在

错误信息：

复制代码

cp: /Applications/.../sdk/default/openharmony/...: No such file or directory

解决方案：

确保 DevEco Studio 已正确安装
打开 DevEco Studio，下载并安装 OpenHarmony SDK
检查 SDK 路径是否正确

问题 3：构建某个包失败

解决方案：

bash 复制代码

# 查看构建日志
tail -100 hnp-build.log

# 重新构建失败的包
cd build-hnp
make rebuild-<package-name>

# 或者清理后重新构建
make clean
make

问题 4：磁盘空间不足

解决方案：

bash 复制代码

# 清理构建产物
cd build-hnp
make clean

# 检查磁盘空间
df -h

🚀 构建优化建议

并行构建：

bash 复制代码

# 使用多核并行构建（加快构建速度）
make -C build-hnp -j$(sysctl -n hw.ncpu)

增量构建：
- 只修改需要的包，避免全量重建
- 使用 make rebuild-<package> 重新构建特定包

测试构建：

bash 复制代码

# 只构建一个包进行测试（修改 build-hnp/Makefile 中的 PKGS）
# 例如：PKGS=tree

🧪 验证构建结果

方法 1：检查文件

bash 复制代码

# 检查 HNP 包是否存在
ls -lh build-hnp/base.hnp

# 检查包内容
unzip -l build-hnp/base.hnp | head -20

# 检查应用目录
ls -lh entry/hnp/arm64-v8a/*.hnp

方法 2：检查包结构

bash 复制代码

# 解压并查看包结构
cd /tmp
unzip -q /path/to/Termony/build-hnp/base.hnp
tree sysroot -L 2

方法 3：验证可执行文件

bash 复制代码

# 解压 HNP 包
cd /tmp
unzip -q /path/to/Termony/build-hnp/base.hnp

# 检查可执行文件（需要 OpenHarmony 设备或模拟器）
file sysroot/bin/tree