【鸿蒙 PC三方库构建系统】【测试验证】HPKCHECK文件详解

欢迎大家加入开源鸿蒙PC社区

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

前言

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

什么是HPKCHECK文件？

HPKCHECK是OpenHarmony三方库构建框架lycium中的一个测试脚本文件。简单来说，它的作用就是在真实的OpenHarmony设备上跑测试，确保编译好的三方库功能正常。
lycium 项目链接如下：https://atomgit.com/OpenHarmonyPCDeveloper/lycium_plusplus

以 sha 库为例，让我们先看一下HPKCHECK文件示例：
测试地址：https://atomgit.com/oh-tpc/pc_sha
具体代码路径：https://atomgit.com/oh-tpc/pc_sha/blob/main/HPKCHECK

# 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文件的核心组成部分

测试流程如下：HPKCHECK文件是包含在test.sh中被调用，需要执行以下命令，来触发测试：

./test.sh sha

1. 源文件导入

source HPKBUILD > /dev/null 2>&1

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

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

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

2. 日志文件设置

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

这行代码定义了测试日志的路径及文件名，路径名称为LYCIUM_THIRDPARTY_ROOT/${pkgname}。

• LYCIUM_THIRDPARTY_ROOT 是三方库构建根路径，是在启动测试脚本./test.sh中定义的环境变量

文件名为pkgname}_${ARCH}_${OHOS_SDK_VER}_test.log，包含以下信息：

• pkgname: 库名称,是在HPKBUILD中定义的变量
• ARCH: CPU架构（如arm64-v8a、armeabi-v7a），是在HPKBUILD中定义的变量
• OHOS_SDK_VER: OpenHarmony SDK版本，是在启动测试脚本./test.sh中定义的环境变量

注：arm64-v8a arm64位架构。armeabi-v7a arm32位架构。

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

3. 核心测试函数

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

    return$res
}

这是HPKCHECK文件的核心函数，让我们逐行分析：
第1行：进入构建目录

cd $builddir/$ARCH-build

执行命令，进入到编译产物的目录

• $builddir: 构建路径，是在HPKBUILD中定义的变量
• $ARCH-build: 构建产物目录，是在HPKBUILD中定义的变量$ARCH-build
• $ARCH: 当前编译的CPU架构（如arm64-v8a），是在HPKBUILD中定义的变量

第2行：执行测试

ctest > ${logfile} 2>&1

• ctest: CMake的测试工具，会运行CMakeLists.txt中定义的测试用例，cmake配套测试工具
• > ${logfile}: 将标准输出重定向到日志文件，
• 2>&1: 将标准错误也重定向到标准输出（即也写入日志文件）

第3行：保存测试结果

res=$?

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

第4行：返回原目录

cd $OLDPWD

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

第6行：返回测试结果

return $res

• 将测试结果返回给调用者

为什么需要HPKCHECK文件？

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

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

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

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

交叉编译 vs 真机测试

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

交叉编译过程中：

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

而HPKCHECK的作用就是：

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

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

完整的测试流程

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

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

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

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

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

HPKCHECK文件的规范写法

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

# 导入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文件，步骤如下：

1. 查看原始项目的测试方式

   • 查看项目的README.md
   • 查看CMakeLists.txt或Makefile
   • 确定项目使用的测试框架

2. 创建HPKCHECK文件

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

3. 修改测试命令

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

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

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

4. 测试验证

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

实际案例：sha库

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

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

常见问题与解决方案

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

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

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

Q2: 测试失败如何调试？

A:

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

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

A:

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

总结

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

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

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

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