HPKBUILD 是 OpenHarmony 三方库构建系统的核心脚本，如同 PKGBUILD 之于 Arch Linux。它仅用百余行代码，便精准定义了从源码获取、编译、安装到打包的完整自动化流程。本文将以 SHA 库为例，逐行拆解其作为“总指挥”的设计逻辑与关键函数，助你掌握为任意库编写 HPKBUILD 的能力。

如果你用过 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=sha

pkgver=3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb

pkgrel=0

pkgdesc=””

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=false

downloadpackage=false

builddir=$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$builddir

if [ $? -ne 0 ]

then

return -1

fi

cd$builddir

git reset –hard $pkgver

if [ $? -ne 0 ]

then

cd$OLDPWD

return -2

fi

patch -p1 < ../sha_ohos.patch

cd$OLDPWD

download_and_patch_flag=false

fi

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 $builddir

if [ $? -ne 0 ]

then

return -1

fi

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

步骤 2：git reset –hard

cd $builddir

git reset –hard $pkgver

if [ $? -ne 0 ]

then

cd $OLDPWD

return -2

fi

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

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

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

步骤 3：应用补丁

patch -p1 < ../sha_ohos.patch

cd $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 $OLDPWD

return $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 $OLDPWD

return $ret

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

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

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

# 设置架构相关的环境变量

if [ “$ARCH” == “armeabi-v7a” ]; then

setarm32ENV

elif [ “$ARCH” == “arm64-v8a” ]; then

setarm64ENV

fi

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

# 清理环境变量

if [ “$ARCH” == “armeabi-v7a” ]; then

unsetarm32ENV

elif [ “$ARCH” == “arm64-v8a” ]; then

unsetarm64ENV

fi

}

通俗理解：打包阶段——把安装产物压缩成 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

setarm32ENV

elif [ “$ARCH” == “arm64-v8a” ]; then

setarm64ENV

fi

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

• 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

unsetarm32ENV

elif [ “$ARCH” == “arm64-v8a” ]; then

unsetarm64ENV

fi

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

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

package() {

cd $builddir

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

cd $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 数组：

# 只构建 ARM64

archs=(“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=0

pkgdesc=”包描述”

url=”上游仓库主页”

archs=(“armeabi-v7a””arm64-v8a”)

license=(“许可证”)

depends=() # 运行时依赖

makedepends=() # 构建时依赖

# === 源码配置 ===

source=”源码地址”

autounpack=false

downloadpackage=false

builddir=$pkgname-${pkgver}

download_and_patch_flag=true

# === 函数定义 ===

prepare() {

if [ “$download_and_patch_flag” == true ]; then

git clone$source$builddir || return -1

cd$builddir

git reset –hard $pkgver || { cd$OLDPWD; return -2; }

patch -p1 < ../补丁文件.patch

cd$OLDPWD

download_and_patch_flag=false

fi

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$OLDPWD

return$ret

}

package() {

cd$builddir

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

cd$OLDPWD

}

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

if [ “$ARCH” == “armeabi-v7a” ]; then

setarm32ENV

elif [ “$ARCH” == “arm64-v8a” ]; then

setarm64ENV

fi

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

if [ “$ARCH” == “armeabi-v7a” ]; then

unsetarm32ENV

elif [ “$ARCH” == “arm64-v8a” ]; then

unsetarm64ENV

fi

}

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 包的全过程。