深入理解鸿蒙PC 三方库构建系统中的HPKCHECK文件

前言

在OpenHarmony生态系统中，开发者经常需要使用各种第三方C/C++库来加速开发进程。为了确保这些库在OpenHarmony平台上能够正常工作，需要对其进行适配、编译和测试。今天我们要聊的HPKCHECK文件，就是这个构建系统中专门用于测试验证的重要组件。

什么是HPKCHECK文件？

HPKCHECK是OpenHarmony三方库构建框架lycium中的一个测试脚本文件。简单来说，它的作用就是在真实的OpenHarmony设备上跑测试，确保编译好的三方库功能正常。

让我们先看一下sha库的HPKCHECK文件示例：

bash 复制代码

# 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>

source HPKBUILD > /dev/null 2>&1
logfile=${LYCIUM_THIRDPARTY_ROOT}/${pkgname}/${pkgname}_${ARCH}_${OHOS_SDK_VER}_test.log

openharmonycheck() {
    cd$builddir/$ARCH-build
    ctest >${logfile} 2>&1
    res=$?
    cd$OLDPWD

    return $res
}

HPKCHECK文件的核心组成部分

1. 源文件导入

bash 复制代码

source HPKBUILD > /dev/null 2>&1

这行代码的作用是导入同目录下的HPKBUILD文件（构建脚本文件）。HPKBUILD文件中包含了库的基本信息，比如：

pkgname: 库名称（sha）
pkgver: 库版本
archs: 支持的CPU架构
builddir: 构建目录

通过导入HPKBUILD，HPKCHECK可以获取这些关键变量，从而知道要测试哪个库、在哪个目录下测试。

2. 日志文件设置

bash 复制代码

logfile=${LYCIUM_THIRDPARTY_ROOT}/${pkgname}/${pkgname}_${ARCH}_${OHOS_SDK_VER}_test.log

这行代码定义了测试日志文件的路径，包含以下信息：

库名称
CPU架构（如arm64-v8a、armeabi-v7a）
OpenHarmony SDK版本

LYCIUM_THIRDPARTY_ROOT路径是在./test.sh下。

OHOS_SDK_VER 是在./test.sh下。

pkgname是在HPKBUILD中。

这样做的好处是便于区分不同架构、不同SDK版本下的测试结果。

执行这个文件的时候，是需要用到

复制代码

./test.sh sha

3. 核心测试函数

bash 复制代码

openharmonycheck() {
    cd $builddir/$ARCH-build
    ctest > ${logfile} 2>&1
    res=$?
    cd $OLDPWD

    return$res
}

这是HPKCHECK文件的核心函数，让我们逐行分析：

第1行：进入构建目录

bash 复制代码

cd $builddir/$ARCH-build

$builddir: 从HPKBUILD导入的源码目录名
$ARCH: 当前编译的CPU架构（如arm64-v8a）
进入到编译产物的目录

第2行：执行测试

bash 复制代码

ctest > ${logfile} 2>&1

ctest: CMake的测试工具，会运行CMakeLists.txt中定义的测试用例，请参考搭建开发环境，以及查看技术博客
> ${logfile}: 将标准输出重定向到日志文件
2>&1: 将标准错误也重定向到标准输出（即也写入日志文件）

第3行：保存测试结果

bash 复制代码

res=$?

$? 是Shell特殊变量，表示上一条命令的退出状态
0表示成功，非0表示失败
将结果保存到变量res中

第4行：返回原目录

bash 复制代码

cd $OLDPWD

$OLDPWD是Shell内置变量，记录上一次的工作目录
这是一个好习惯，避免影响后续操作

第6行：返回测试结果

bash 复制代码

return $res

将测试结果返回给调用者

为什么需要HPKCHECK文件？

你可能会问：为什么不直接在HPKBUILD文件中写测试逻辑呢？

实际上，HPKBUILD文件中确实有一个check()函数：

bash 复制代码

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

但这里有个关键问题：交叉编译环境的限制

交叉编译 vs 真机测试

在lycium构建系统中，大部分三方库都是在开发机（通常是x86_64架构的Linux）上进行交叉编译，生成目标平台（如ARM架构的OpenHarmony设备）的可执行文件。

交叉编译过程中：

✅ 可以编译代码
✅ 可以链接库
❌ 不能运行编译出的程序（因为架构不匹配）

而HPKCHECK的作用就是：

将编译好的库和测试程序部署到真实的OpenHarmony设备上
在设备上运行测试
收集测试结果

这是为什么HPKCHECK文件中要强调"OpenHarmony device"的原因。

完整的测试流程

一个典型的三方库测试流程如下：

复制代码

1. 编译阶段 (HPKBUILD)
   ↓
   ├─ prepare()  准备环境
   ├─ build()    交叉编译
   └─ package()  安装到指定目录

2. 部署阶段
   ↓
   将编译产物推送到OpenHarmony设备

3. 测试阶段 (HPKCHECK)
   ↓
   ├─ openharmonycheck()  在设备上运行测试
   └─ 生成测试日志

4. 结果分析
   ↓
   检查日志，判断测试是否通过

HPKCHECK文件的规范写法

根据模板文件，一个规范的HPKCHECK文件应该包含以下结构：

bash 复制代码

# 导入HPKBUILD文件
source HPKBUILD > /dev/null 2>&1
logfile=${LYCIUM_THIRDPARTY_ROOT}/${pkgname}/${pkgname}_${ARCH}_${OHOS_SDK_VER}_test.log

# 测试前的准备（可选）
checkprepare(){
    return 0
}

# 在OpenHarmony环境执行测试的接口
openharmonycheck() {
    res=0
    cd${builddir}/${ARCH}-build
    ctest >${logfile} 2>&1
    res=$?
    cd$OLDPWD
    return $res
}

可选的checkprepare()函数

如果测试前需要做一些准备工作（比如设置环境变量、创建测试数据等），可以添加checkprepare()函数。

常见测试命令

不同的三方库可能使用不同的测试框架，常见的有：

测试框架	命令	适用场景
CTest	`ctest`	CMake项目
Make test	`make test`	传统Makefile项目
自定义脚本	`./run_tests.sh`	项目自定义测试

如何为新的三方库编写HPKCHECK？

假设你要为一个新的三方库编写HPKCHECK文件，步骤如下：

查看原始项目的测试方式
- 查看项目的README.md
- 查看CMakeLists.txt或Makefile
- 确定项目使用的测试框架

创建HPKCHECK文件

bash 复制代码

# 复制模板
cp lycium/template/HPKCHECK your_library/HPKCHECK

修改测试命令

根据项目实际情况修改openharmonycheck()函数

例如，如果项目使用make test：

bash 复制代码

openharmonycheck() {
    cd $builddir/$ARCH-build
    make test > ${logfile} 2>&1
         res=$?
    cd $OLDPWD
         return$res
}

测试验证
- 在真实的OpenHarmony设备上运行测试
- 检查日志文件内容
- 确保测试结果正确

实际案例：sha库

回到我们的示例文件，sha库是一个SHA哈希算法的实现库。它的HPKCHECK文件非常简洁：

bash 复制代码

openharmonycheck() {
    cd $builddir/$ARCH-build
    ctest > ${logfile} 2>&1
    res=$?
    cd $OLDPWD
    return$res
}

这意味着：

sha库使用CMake构建系统
测试用例通过CTest定义
测试结果会输出到日志文件

日志文件路径示例：

复制代码

${LYCIUM_THIRDPARTY_ROOT}/sha/sha_arm64-v8a_10_test.log

测试地址：https://atomgit.com/oh-tpc/pc_sha

具体代码路径：https://atomgit.com/oh-tpc/pc_sha/blob/main/HPKCHECK

常见问题与解决方案

Q1: 如果三方库没有测试用例怎么办？

A: 如果原始项目没有提供测试用例，可以考虑：

编写简单的测试程序验证基本功能
在HPKCHECK中跳过测试，但要在文档中说明
向上游项目贡献测试用例

Q2: 测试失败如何调试？

查看日志文件内容
检查设备上是否正确安装了所有依赖
确认测试环境配置是否正确
可以在HPKCHECK中添加调试输出

Q3: 为什么有些库不需要HPKCHECK？

纯头文件库（header-only）可能不需要测试
某些库可能只在编译阶段验证
但为了质量保证，建议尽可能添加测试

总结

HPKCHECK文件是OpenHarmony三方库构建系统中不可或缺的一环，它承担着质量把关的重要职责。通过在真实设备上运行测试，确保了三方库在OpenHarmony平台上的可靠性和稳定性。

对于开发者来说，理解HPKCHECK文件的作用和编写方法，有助于：

更好地适配三方库到OpenHarmony平台
提高代码质量和可靠性
为OpenHarmony生态贡献高质量的三方库

记住：编译通过只是第一步，测试通过才是真正的成功！