❓ 什么是 HNP？

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

🏗️ 构建 HNP 包

✅ 前置条件

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

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

🛠️ 构建步骤

步骤 1：检查环境变量

确保 TOOL_HOME 和 OHOS_SDK_HOME 已设置：

# 检查 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：执行构建脚本

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

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

🔍 构建过程详解

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

1. 环境准备

# 设置区域设置（确保字符处理使用 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 会删除不必要的文档文件：

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

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

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

5. 添加剪贴板工具

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

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

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

6. 配置 GCC 运行时库

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

# 创建 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 格式

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

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

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

8. 复制到应用目录

# 删除旧的 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

📦 构建输出

成功标志：

构建成功后，你会看到：

1. HNP 包文件：

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

2. 应用目录中的 HNP 包：

   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
   

3. HNP 包内容：

   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：构建某个包失败

解决方案：

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

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

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

问题 4：磁盘空间不足

解决方案：

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

# 检查磁盘空间
df -h

🚀 构建优化建议

1. 并行构建：

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

2. 增量构建：

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

3. 测试构建：

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

🧪 验证构建结果

方法 1：检查文件

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

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

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

方法 2：检查包结构

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

方法 3：验证可执行文件

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

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

---