HPKBUILD 深度解读：SHA 库构建的"总指挥"

前言

如果你用过 Arch Linux，一定知道 PKGBUILD——一个脚本文件定义了包的名字、版本、怎么下载源码、怎么编译、怎么打包。Lycium 构建系统的 HPKBUILD 就是这个思路的 OpenHarmony 版本。

HPKBUILD 是整个三方库适配的总指挥。它告诉构建系统：这个包叫什么、从哪下载源码、支持哪些 CPU 架构、怎么准备源码、怎么编译、怎么安装、怎么打包。所有构建流程的决策都集中在这一个文件里。

SHA 库的 HPKBUILD 只有 106 行，但每一行都有明确的作用。这篇文章就从头到尾拆解一遍，让你看完之后能自己写一个 HPKBUILD。

项目地址：https://atomgit.com/oh-tpc/pc_sha

背景：HPKBUILD 在构建系统中的角色

Lycium 构建系统简介

Lycium 是 OpenHarmony 的三方库构建系统，负责把开源库从源码编译成可在 OpenHarmony 设备上安装的 HNP 包。它的核心工作流程是：

源码获取 → 补丁应用 → 编译构建 → 安装产物 → 打包发布

HPKBUILD 就是定义这个流程的脚本。Lycium 的主构建脚本（build.sh）读取 HPKBUILD，按顺序调用里面的函数，完成从源码到包的全过程。

HPKBUILD 的函数生命周期

┌─────────────┐│  prepare()  │  准备：下载源码、应用补丁、创建构建目录└──────┬──────┘       │       ▼┌─────────────┐│   build()   │  编译：运行 CMake 配置和 make 编译└──────┬──────┘       │       ▼┌─────────────┐│  package()  │  安装：把编译产物安装到目标目录└──────┬──────┘       │       ▼┌─────────────┐│  archive()  │  打包：生成 tar.gz 和 HNP 包└──────┬──────┘       │       ▼┌─────────────┐│   check()   │  测试：验证功能正确性（需在设备上执行）└─────────────┘

这五个函数就是 HPKBUILD 的骨架，每个函数负责构建流程的一个阶段。

完整文件结构总览

HPKBUILD├── 版权声明（第 1-15 行）├── 环境加载（第 17 行）├── 包元数据（第 19-27 行）├── 源码配置（第 29-35 行）├── prepare()  函数（第 37-57 行）├── build()    函数（第 59-66 行）├── archive()  函数（第 67-89 行）├── package()  函数（第 91-95 行）├── check()    函数（第 97-100 行）└── cleanbuild() 函数（第 103-105 行）

下面逐段拆解。

第一段：版权声明（第 1-15 行）

# Copyright (c) 2023 Huawei Device Co., Ltd.# Licensed under the Apache License, Version 2.0 (the "License");# you may not use this file except in compliance with the License.# You may obtain a copy of the License at##     http://www.apache.org/licenses/LICENSE-2.0## Unless required by applicable law or agreed to in writing, software# distributed under the License is distributed on an "AS IS" BASIS,# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.# See the License for the specific language governing permissions and# limitations under the License.# Contributor: huangminzhong <huangminzhong2@huawei.com># Maintainer:  huangminzhong <huangminzhong2@huawei.com>

通俗理解：这是文件的"身份证"——谁写的、什么许可证、谁负责维护。

Apache 2.0 是 OpenHarmony 项目统一使用的许可证，要求保留版权声明和许可证文本。

第二段：环境加载（第 17 行）

source envset.sh

通俗理解：加载"工具箱"——envset.sh 里定义了各种架构的环境设置函数。

这一行看似简单，但它是解决 HNP 打包问题的关键。envset.sh 提供了以下函数：

这些函数在 archive() 阶段被调用，确保 HNP 打包工具能找到正确的工具链。如果缺少这一行，打包时会报 pack: command not found 错误。

第三段：包元数据（第 19-27 行）

pkgname=shapkgver=3ee0d88fc4f629b2e084f1b4cbf22cd3597542fbpkgrel=0pkgdesc=""url="https://github.com/BrianGladman/sha"archs=("armeabi-v7a""arm64-v8a")license=("the sha license")depends=()makedepends=()

通俗理解：这是包的"名片"——名字、版本、主页、支持什么架构、依赖什么。

逐变量解读

pkgname=sha

包名。整个构建系统用这个名字来标识包——目录叫 sha/，产物叫 sha.hnp，日志叫 sha_xxx.log。

pkgver=3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb

版本号。这里用的是 Git commit hash 而不是 1.0.0 这样的语义化版本，因为上游仓库没有发布正式版本号。

为什么用 commit hash？

• 精确：唯一标识源码的某一确切状态
• 可追溯：git show 3ee0d88 就能看到具体提交内容
• 可重现：确保每次构建基于完全相同的源码

pkgrel=0

包释放版本。同一个 pkgver 的第几次打包。比如修复了打包脚本但源码没变，就把 pkgrel 从 0 改成 1。当前为 0，表示首次打包。

pkgdesc=""

包描述。当前为空，建议补充为类似 "SHA hash algorithm library for OpenHarmony" 的描述。

url="https://github.com/BrianGladman/sha"

上游仓库主页。供人浏览用，和 source 变量（用于 git clone）略有不同。

archs=("armeabi-v7a" "arm64-v8a")

支持的 CPU 架构列表。

构建系统会为每个架构分别执行一遍完整的构建流程，生成架构特定的产物。

license=("the sha license")

许可证声明。这里用的是自定义字符串，建议改为标准 SPDX 标识符如 "BSD-2-Clause"。

depends=() 和 makedepends=()

运行时依赖和构建时依赖。SHA 库是纯算法库，不依赖任何其他库，所以都是空数组。

第四段：源码配置（第 29-35 行）

source="https://github.com/BrianGladman/sha.git"autounpack=falsedownloadpackage=falsebuilddir=$pkgname-${pkgver}download_and_patch_flag=true

通俗理解：告诉构建系统"从哪拿源码"和"怎么拿"。

逐变量解读

source="https://github.com/BrianGladman/sha.git"

源码地址。注意末尾有 .git，表示用 git clone 获取，而不是下载压缩包。

autounpack=false

不自动解压。因为用的是 git clone，不需要解压步骤。

downloadpackage=false

不下载压缩包。和 autounpack 配合使用，明确告诉构建系统"我们用 Git 管理源码"。

builddir=$pkgname-${pkgver}

构建目录名。展开后是 sha-3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb。源码就放在这个目录里。

download_and_patch_flag=true

下载和补丁标志。true 表示还没下载过，prepare() 函数会执行下载和补丁操作。下载完成后设为 false，避免重复下载。

第五段：prepare() 函数（第 37-57 行）

prepare() {if [ "$download_and_patch_flag" == true ]then        git clone$source$builddirif [ $? -ne 0 ]thenreturn -1ficd$builddir        git reset --hard $pkgverif [ $? -ne 0 ]thencd$OLDPWDreturn -2fi        patch -p1 < ../sha_ohos.patchcd$OLDPWD        download_and_patch_flag=falsefi    mkdir -p $builddir/$ARCH-build}

通俗理解：准备阶段——下载源码、锁定版本、打补丁、创建构建目录。

执行流程图

prepare() 开始    │    ├─ download_and_patch_flag == true ?    │   │    │   ├─ 是 → 执行下载和补丁    │   │   │    │   │   ├─ 1. git clone 源码    │   │   │      失败 → return -1    │   │   │    │   │   ├─ 2. git reset --hard 锁定版本    │   │   │      失败 → return -2    │   │   │    │   │   ├─ 3. patch -p1 应用 OpenHarmony 补丁    │   │   │    │   │   └─ 4. 设 download_and_patch_flag=false    │   │    │   └─ 否 → 跳过（已经下载过了）    │    └─ mkdir -p 创建架构构建目录

逐步解读

步骤 1：git clone

git clone$source$builddirif [ $? -ne 0 ]thenreturn -1fi

从 GitHub 克隆源码到构建目录。$? 是上一条命令的退出码，0 表示成功，非 0 表示失败。失败时返回 -1，构建系统会中止并报告"源码下载失败"。

步骤 2：git reset --hard

cd$builddirgit reset --hard $pkgverif [ $? -ne 0 ]thencd$OLDPWDreturn -2fi

把源码切换到指定版本。git reset --hard 会把工作目录重置到某个 commit 的状态，丢弃所有其他修改。这确保了无论仓库当前在什么状态，构建时用的都是同一个版本。

失败时先 cd $OLDPWD 回到原目录，再返回 -2。$OLDPWD 是 Bash 的内置变量，保存上一次的目录路径。

为什么不用 git checkout？reset --hard 更彻底——它不仅切换版本，还清理工作区，确保没有残留文件干扰构建。

步骤 3：应用补丁

patch -p1 < ../sha_ohos.patchcd$OLDPWD

把 OpenHarmony 适配补丁应用到源码上。-p1 表示去掉路径的第一层（sha/），因为我们在源码目录内执行 patch。

步骤 4：标记完成

download_and_patch_flag=false

标记"已下载"，下次调用 prepare() 时不会重复下载。这在多架构构建时很重要——ARM32 和 ARM64 共享同一份源码，只需下载一次。

步骤 5：创建构建目录

mkdir -p $builddir/$ARCH-build

为当前架构创建独立的构建目录，比如 sha-3ee0d88.../arm64-v8a-build。-p 参数表示如果父目录不存在就自动创建，如果目录已存在也不报错。

为什么每个架构要单独的构建目录？ 因为不同架构的编译选项、工具链、产物都不同，混在一起会冲突。

第六段：build() 函数（第 59-66 行）

build() {cd$builddir${OHOS_SDK}/native/build-tools/cmake/bin/cmake "$@" -B$ARCH-build -S./ > $buildlog 2>&1$MAKE VERBOSE=1 -C $ARCH-build >> $buildlog 2>&1    ret=$?cd$OLDPWDreturn$ret}

通俗理解：编译阶段——用 OpenHarmony SDK 的 CMake 配置项目，然后 make 编译。

逐步解读

CMake 配置

${OHOS_SDK}/native/build-tools/cmake/bin/cmake "$@" -B$ARCH-build -S./ > $buildlog 2>&1

为什么用 SDK 自带的 CMake？ OpenHarmony SDK 的 CMake 预配置了交叉编译的工具链路径和系统根目录，能正确找到 OpenHarmony 的编译器和系统头文件。系统自带的 CMake 不知道这些信息。

Make 编译

$MAKE VERBOSE=1 -C $ARCH-build >> $buildlog 2>&1

返回结果

ret=$?cd$OLDPWDreturn$ret

捕获编译退出码，回到原目录，返回编译结果。0 表示成功，非 0 表示有编译错误。

第七段：archive() 函数（第 67-89 行）

archive() {    mkdir -p ${LYCIUM_ROOT}/output/$ARCHpushd$LYCIUM_ROOT/usr/$pkgname/$ARCH        tar -zvcf ${LYCIUM_ROOT}/output/$ARCH/${pkgname}_${pkgver}.tar.gz *popd    cp hnp.json $LYCIUM_ROOT/usr/$pkgname/$ARCH# 设置架构相关的环境变量if [ "$ARCH" == "armeabi-v7a" ]; then        setarm32ENVelif [ "$ARCH" == "arm64-v8a" ]; then        setarm64ENVfi${HNP_TOOL} pack -i ${LYCIUM_ROOT}/usr/$pkgname/$ARCH -o ${LYCIUM_ROOT}/output/$ARCH/# 清理环境变量if [ "$ARCH" == "armeabi-v7a" ]; then        unsetarm32ENVelif [ "$ARCH" == "arm64-v8a" ]; then        unsetarm64ENVfi}

通俗理解：打包阶段——把安装产物压缩成 tar.gz，再打包成 HNP 格式。

这是 HPKBUILD 中最复杂的函数，也是曾经出过 bug 的地方。逐步拆解：

步骤 1：创建输出目录

mkdir -p ${LYCIUM_ROOT}/output/$ARCH

创建最终产物的输出目录，如 output/arm64-v8a/。

步骤 2：打包 tar.gz

pushd$LYCIUM_ROOT/usr/$pkgname/$ARCH    tar -zvcf ${LYCIUM_ROOT}/output/$ARCH/${pkgname}_${pkgver}.tar.gz *popd

进入安装目录，把所有文件打包成 sha_3ee0d88....tar.gz。pushd/popd 是 Bash 的目录栈操作，相当于"临时 cd 进去，干完活自动 cd 回来"。

步骤 3：复制 hnp.json

cp hnp.json $LYCIUM_ROOT/usr/$pkgname/$ARCH

把 hnp.json 复制到安装目录。HNP 打包工具需要读取这个文件来识别包的元数据。

步骤 4：设置架构环境变量

if [ "$ARCH" == "armeabi-v7a" ]; then    setarm32ENVelif [ "$ARCH" == "arm64-v8a" ]; then    setarm64ENVfi

这是关键修复点！ 根据当前架构设置对应的环境变量，包括：

• CC：C 编译器路径（如 arm-linux-ohos-clang）
• CXX：C++ 编译器路径
• HNP_TOOL：HNP 打包工具路径

为什么需要这一步？ 因为 hnpcli（HNP 打包工具）需要知道当前架构的工具链信息。如果不设置环境变量，${HNP_TOOL} pack 会找不到 pack 命令，报错 pack: command not found。

步骤 5：打包 HNP

${HNP_TOOL} pack -i ${LYCIUM_ROOT}/usr/$pkgname/$ARCH -o ${LYCIUM_ROOT}/output/$ARCH/

执行后生成 sha.hnp 文件。

步骤 6：清理环境变量

if [ "$ARCH" == "armeabi-v7a" ]; then    unsetarm32ENVelif [ "$ARCH" == "arm64-v8a" ]; then    unsetarm64ENVfi

打包完成后，清理之前设置的环境变量。为什么需要清理？ 因为构建系统会连续为多个架构执行构建——先 ARM32 再 ARM64。如果不清理，ARM32 的环境变量会污染 ARM64 的构建，导致用错误的编译器。

第八段：package() 函数（第 91-95 行）

package() {cd$builddir$MAKE VERBOSE=1 -C $ARCH-build install >> $buildlog 2>&1cd$OLDPWD}

通俗理解：安装阶段——执行 make install，把编译产物安装到标准目录结构。

CMake 的 install() 指令（在 CMakeLists.txt 中定义）决定了文件安装到哪：

最终安装到 ${LYCIUM_ROOT}/usr/sha/$ARCH/ 目录下。

第九段：check() 函数（第 97-100 行）

check() {echo"The test must be on an OpenHarmony device!"# ctest}

通俗理解：测试阶段——但当前只是打印提示信息，没有实际执行测试。

ctest 被注释掉了，因为 SHA 库的测试需要在真实的 OpenHarmony 设备上运行。在开发机上交叉编译出的可执行文件无法直接运行。

实际的测试逻辑在 HPKCHECK 文件中定义，通过 openharmonycheck() 函数在设备上执行。

第十段：cleanbuild() 函数（第 103-105 行）

cleanbuild(){    rm -rf ${PWD}/$builddir#${PWD}/$packagename}

通俗理解：清理构建目录，删除源码和构建产物。

rm -rf 会递归强制删除整个构建目录，包括源码、编译产物、构建日志等。下次构建时会重新 git clone 下载源码。

变量依赖关系图

HPKBUILD 中定义的变量之间有依赖关系，理解这些关系有助于整体把握：

pkgname ─────┬──→ builddir ($pkgname-${pkgver})             │pkgver ──────┤             │source ──────┼──→ prepare() 中的 git clone             │archs ───────┼──→ 决定循环次数（每个架构执行一遍）             │ARCH ────────┼──→ 由构建系统设置，决定当前构建的架构             │      ├→ $builddir/$ARCH-build  (构建目录)             │      ├→ ${LYCIUM_ROOT}/usr/$pkgname/$ARCH  (安装目录)             │      └→ ${LYCIUM_ROOT}/output/$ARCH  (输出目录)             │OHOS_SDK ────┼──→ build() 中的 CMake 路径             │LYCIUM_ROOT ─┼──→ archive() 中的输出路径             │HNP_TOOL ────┴──→ archive() 中的打包命令

多架构构建的完整流程

HPKBUILD 最精妙的设计是支持多架构构建。构建系统会为 archs 中的每个架构分别执行一遍完整流程：

┌─────────────────────────────────────────────────────────┐│  架构 1: armeabi-v7a                                     ││                                                          ││  ARCH=armeabi-v7a                                        ││  prepare()  → 下载源码（仅首次）、创建 arm32 构建目录    ││  build()    → 用 arm-linux-ohos-clang 编译              ││  package()  → 安装到 usr/sha/armeabi-v7a/               ││  archive()  → setarm32ENV → 打包 → unsetarm32ENV        │└─────────────────────────────────────────────────────────┘                        │                        ▼┌─────────────────────────────────────────────────────────┐│  架构 2: arm64-v8a                                       ││                                                          ││  ARCH=arm64-v8a                                          ││  prepare()  → 跳过下载（已下载）、创建 arm64 构建目录    ││  build()    → 用 aarch64-linux-ohos-clang 编译          ││  package()  → 安装到 usr/sha/arm64-v8a/                 ││  archive()  → setarm64ENV → 打包 → unsetarm64ENV        │└─────────────────────────────────────────────────────────┘

关键设计：

• 源码只下载一次：download_and_patch_flag 确保不会重复 clone
• 构建目录隔离：每个架构有独立的 $ARCH-build 目录
• 环境变量隔离：setarmXXENV / unsetarmXXENV 确保架构间不污染

常见问题

Q1：为什么用 git clone 而不是下载压缩包？

SHA 库的上游仓库没有发布正式的 release 压缩包，只有 Git 仓库。用 git clone + git reset --hard 可以精确获取任意 commit 的源码，而压缩包通常只对应 release 版本。

Q2：prepare() 中的错误码 -1 和 -2 有什么区别？

• return -1：git clone 失败（网络问题、仓库不存在等）
• return -2：git reset 失败（commit hash 不存在等）

不同的错误码便于构建系统区分问题类型，给出更有针对性的错误提示。

Q3：为什么 build() 中用 $MAKE 而不是直接写 make？

$MAKE 是由构建系统设置的变量，可能是 make -j8（并行编译）或 ninja（更快的构建工具）。用变量而不是硬编码，让构建系统有灵活选择的余地。

Q4：archive() 中为什么要先 setarmXXENV 再 unsetarmXXENV？

setarmXXENV 设置了 HNP_TOOL 等环境变量，${HNP_TOOL} pack 才能正常执行。执行完后必须 unsetarmXXENV 清理，否则下一个架构的构建会被上一个架构的环境变量污染。

Q5：check() 为什么是空的？

SHA 库的测试程序是编译出的 ARM 可执行文件，无法在 x86 开发机上直接运行。测试需要在 OpenHarmony 设备上执行，由 HPKCHECK 文件定义。

Q6：如何只构建一个架构？

修改 archs 数组：

# 只构建 ARM64archs=("arm64-v8a")

或者通过构建系统的命令行参数指定架构（如果支持的话）。

写一个 HPKBUILD 的模板

理解了 SHA 库的 HPKBUILD，你可以用以下模板为其他库编写 HPKBUILD：

# Copyright (c) 2023 Huawei Device Co., Ltd.# Licensed under the Apache License, Version 2.0 (the "License");# ...（版权声明）# Contributor: 你的名字 <你的邮箱># Maintainer:  你的名字 <你的邮箱>source envset.sh# === 包元数据 ===pkgname=库名pkgver=版本号pkgrel=0pkgdesc="包描述"url="上游仓库主页"archs=("armeabi-v7a""arm64-v8a")license=("许可证")depends=()        # 运行时依赖makedepends=()    # 构建时依赖# === 源码配置 ===source="源码地址"autounpack=falsedownloadpackage=falsebuilddir=$pkgname-${pkgver}download_and_patch_flag=true# === 函数定义 ===prepare() {if [ "$download_and_patch_flag" == true ]; then        git clone$source$builddir || return -1cd$builddir        git reset --hard $pkgver || { cd$OLDPWD; return -2; }        patch -p1 < ../补丁文件.patchcd$OLDPWD        download_and_patch_flag=falsefi    mkdir -p $builddir/$ARCH-build}build() {cd$builddir${OHOS_SDK}/native/build-tools/cmake/bin/cmake "$@" -B$ARCH-build -S./ > $buildlog 2>&1$MAKE VERBOSE=1 -C $ARCH-build >> $buildlog 2>&1    ret=$?cd$OLDPWDreturn$ret}package() {cd$builddir$MAKE VERBOSE=1 -C $ARCH-build install >> $buildlog 2>&1cd$OLDPWD}archive() {    mkdir -p ${LYCIUM_ROOT}/output/$ARCHpushd$LYCIUM_ROOT/usr/$pkgname/$ARCH        tar -zvcf ${LYCIUM_ROOT}/output/$ARCH/${pkgname}_${pkgver}.tar.gz *popd    cp hnp.json $LYCIUM_ROOT/usr/$pkgname/$ARCHif [ "$ARCH" == "armeabi-v7a" ]; then        setarm32ENVelif [ "$ARCH" == "arm64-v8a" ]; then        setarm64ENVfi${HNP_TOOL} pack -i ${LYCIUM_ROOT}/usr/$pkgname/$ARCH -o ${LYCIUM_ROOT}/output/$ARCH/if [ "$ARCH" == "armeabi-v7a" ]; then        unsetarm32ENVelif [ "$ARCH" == "arm64-v8a" ]; then        unsetarm64ENVfi}check() {echo"The test must be on an OpenHarmony device!"}cleanbuild() {    rm -rf ${PWD}/$builddir}

总结

HPKBUILD 是 SHA 库构建的"总指挥"，106 行代码定义了从源码到 HNP 包的完整流程。

核心结构

关键设计决策

1. Git 管理源码：git clone + git reset --hard 精确控制版本
2. 多架构隔离：独立构建目录 + 环境变量设置/清理
3. SDK 工具链：使用 OpenHarmony SDK 自带的 CMake 和编译器
4. HNP 打包：setarmXXENV → hnpcli pack → unsetarmXXENV 确保打包成功
5. 源码只下载一次：download_and_patch_flag 避免多架构重复下载

一句话总结

HPKBUILD 把"从哪拿源码、怎么编译、装到哪、怎么打包"这四个问题的答案，用 Bash 脚本的形式写在一个文件里，让构建系统按图索骥，自动完成从源码到 HNP 包的全过程。