【鸿蒙 PC三方库构建系统】SHA 库 鸿蒙PC 适配详解
📋 目录
欢迎大家加入开源鸿蒙PC社区
项目地址：https://atomgit.com/oh-tpc/pc_sha
核心文件介绍
SHA 库的 鸿蒙PC 适配包含以下核心文件，每个文件都有特定的作用和重要性：
1. HPKBUILD - 构建配置文件 ⭐⭐⭐⭐⭐
重要性: ⭐⭐⭐⭐⭐ (最核心的文件)
作用: 定义包的元数据、构建过程和打包逻辑
关键配置:
bash
# 包的基本信息
pkgname=sha # 包名
pkgver=3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb # 版本号（commit hash）
archs=("armeabi-v7a" "arm64-v8a") # 支持的架构
# 源码配置
source="https://github.com/BrianGladman/sha.git"
autounpack=false # 不自动解压（使用 git clone）
downloadpackage=false # 不下载压缩包
# 构建函数
prepare() # 准备阶段：下载源码、应用补丁
build() # 构建阶段：编译代码
archive() # 打包阶段：生成 HNP 包
package() # 安装阶段：安装到目标目录核心功能:
- 源码获取: 通过 git clone 获取指定版本的源码
- 补丁应用: 自动应用 OpenHarmony 适配补丁
- 多架构构建: 支持 armeabi-v7a 和 arm64-v8a 两种架构
- 产物打包: 生成 HNP 包和 tar.gz 压缩包
关键改进:
bash
# 添加环境配置加载
source envset.sh
# archive 函数中添加环境变量设置
if [ "$ARCH" == "armeabi-v7a" ]; then
setarm32ENV # 设置 ARM32 环境
elif [ "$ARCH" == "arm64-v8a" ]; then
setarm64ENV # 设置 ARM64 环境
fi
${HNP_TOOL} pack -i ... # 打包 HNP2. HPKCHECK - 测试配置文件 ⭐⭐⭐⭐
重要性: ⭐⭐⭐⭐ (质量保证)
作用: 定义测试逻辑和测试执行方式
关键配置:
bash
source HPKBUILD > /dev/null 2>&1 # 加载 HPKBUILD 配置
# 测试函数
openharmonycheck() {
cd $builddir/$ARCH-build
ctest > ${logfile} 2>&1 # 执行 CMake 测试
res=$?
cd $OLDPWD
return $res
}测试内容:
- SHA-1 算法正确性测试
- SHA-256 算法正确性测试
- SHA-512 算法正确性测试
- HMAC 功能测试
- 密钥派生功能测试
3. hnp.json - HNP 包配置文件 ⭐⭐⭐⭐⭐
重要性: ⭐⭐⭐⭐⭐ (部署关键)
作用: 定义 HNP 包的元数据和安装配置
配置内容:
json
{
"type": "hnp-config", // 配置类型
"name": "sha", // 包名
"version": "1.1.0", // HNP 版本号
"install": {} // 安装配置（可选）
}重要性说明:
- HNP (Harmony Native Package) 是 OpenHarmony 的原生包格式
- 这个文件是打包工具识别包的必要条件
- 版本号用于包管理和版本控制
- 可以包含安装后的配置信息
4. README_zh.md - 中文文档 ⭐⭐⭐⭐
重要性: ⭐⭐⭐⭐ (用户指南)
作用: 提供完整的使用文档和 API 说明
文档结构:
markdown
# SHA 加密库说明文档
## 功能简介
## 支持的算法
## API 接口
## 使用示例
## 构建说明
## 测试验证
## 常见问题
## 安全建议文档亮点:
- ✅ 完整的 API 接口文档
- ✅ 3 个实用的代码示例
- ✅ 详细的构建步骤
- ✅ 测试验证方法
- ✅ 常见问题解答
- ✅ 安全使用建议
5. README.OpenSource - 开源声明 ⭐⭐⭐
重要性: ⭐⭐⭐ (合规性)
作用: 声明开源软件的许可证和版权信息
格式: JSON 数组
json
[
{
"Name": "sha",
"License": "",
"License File": "",
"Version Number": "3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb",
"Owner": "jianguo@nutpi.net",
"Upstream URL": "https://github.com/BrianGladman/sha",
"Description": "sha is an algorithm that calculates a fixed length string..."
}
]用途:
- 开源合规性检查
- 许可证管理
- 依赖关系追踪
- 审计和合规报告
SHA 适配架构
整体架构图
┌─────────────────────────────────────────────────────────────┐
│ OpenHarmony 适配层 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ HPKBUILD │ │ HPKCHECK │ │ hnp.json │ │
│ │ 构建配置 │ │ 测试配置 │ │ 包配置 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Lycium 构建系统 │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │build.sh │ │envset.sh │ │build_hpk │ │ │
│ │ │主构建脚本│ │环境设置 │ │构建执行 │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 补丁适配层 │ │
│ │ sha_ohos.patch │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ CMakeLists.txt 修改 │ │ │
│ │ │ - 静态链接配置 │ │ │
│ │ │ - OpenHarmony 特定配置 │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 原始 SHA 库 │ │
│ │ BrianGladman/sha (v3ee0d88) │ │
│ │ - sha1.c / sha1.h │ │
│ │ - sha2.c / sha2.h │ │
│ │ - hmac.c / hmac.h │ │
│ │ - pwd2key.c / pwd2key.h │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘关键文件详解
HPKBUILD 详细解析
1. 元数据部分
bash
pkgname=sha # 包名称
pkgver=3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb # Git commit hash
pkgrel=0 # 包释放版本
pkgdesc="" # 包描述
url="https://github.com/BrianGladman/sha" # 上游地址
archs=("armeabi-v7a" "arm64-v8a") # 支持架构
license=("the sha license") # 许可证
depends=() # 运行依赖
makedepends=() # 构建依赖2. 源码配置
bash
source="https://github.com/BrianGladman/sha.git"
autounpack=false # 不自动解压
downloadpackage=false # 不下载压缩包
builddir=$pkgname-${pkgver} # 构建目录
download_and_patch_flag=true # 下载和补丁标志3. prepare() 函数 - 准备阶段
bash
prepare() {
if [ "$download_and_patch_flag" == true ]; then
# 1. 克隆源码
git clone $source $builddir
# 2. 切换到指定版本
cd $builddir
git reset --hard $pkgver
# 3. 应用 OpenHarmony 补丁
patch -p1 < ../sha_ohos.patch
# 4. 标记已完成
download_and_patch_flag=false
fi
# 5. 创建构建目录
mkdir -p $builddir/$ARCH-build
}关键点:
- 使用 git clone 而不是下载压缩包
- 精确控制源码版本（通过 commit hash）
- 自动应用适配补丁
- 为每个架构创建独立的构建目录
4. build() 函数 - 构建阶段
bash
build() {
cd $builddir
# 使用 OpenHarmony SDK 的 CMake
${OHOS_SDK}/native/build-tools/cmake/bin/cmake "$@" \
-B$ARCH-build -S./ > $buildlog 2>&1
# 编译（使用 make 或 ninja）
$MAKE VERBOSE=1 -C $ARCH-build >> $buildlog 2>&1
ret=$?
cd $OLDPWD
return $ret
}关键点:
- 使用 OpenHarmony SDK 提供的工具链
- 支持多架构并行构建
- 构建日志记录到
$buildlog - 返回编译结果状态码
5. archive() 函数 - 打包阶段 ⭐
bash
archive() {
# 1. 创建输出目录
mkdir -p ${LYCIUM_ROOT}/output/$ARCH
# 2. 打包 tar.gz
pushd $LYCIUM_ROOT/usr/$pkgname/$ARCH
tar -zvcf ${LYCIUM_ROOT}/output/$ARCH/${pkgname}_${pkgver}.tar.gz *
popd
# 3. 复制 HNP 配置文件
cp hnp.json $LYCIUM_ROOT/usr/$pkgname/$ARCH
# 4. 设置架构相关环境变量 ⭐ 关键修复
if [ "$ARCH" == "armeabi-v7a" ]; then
setarm32ENV # ARM32 环境
elif [ "$ARCH" == "arm64-v8a" ]; then
setarm64ENV # ARM64 环境
fi
# 5. 打包 HNP
${HNP_TOOL} pack -i ${LYCIUM_ROOT}/usr/$pkgname/$ARCH \
-o ${LYCIUM_ROOT}/output/$ARCH/
# 6. 清理环境变量
if [ "$ARCH" == "armeabi-v7a" ]; then
unsetarm32ENV
elif [ "$ARCH" == "arm64-v8a" ]; then
unsetarm64ENV
fi
}关键修复点:
- ✅ 添加了架构特定的环境变量设置
- ✅ 解决了 HNP_TOOL 找不到的问题
- ✅ 确保每个架构使用正确的工具链
6. package() 函数 - 安装阶段
bash
package() {
cd $builddir
# 执行 make install
$MAKE VERBOSE=1 -C $ARCH-build install >> $buildlog 2>&1
cd $OLDPWD
}sha_ohos.patch 详细解析
这是最重要的适配补丁文件，包含以下关键修改：
1. CMakeLists.txt 新增
注意 ：原始 BrianGladman/sha 仓库没有 CMakeLists.txt 文件。补丁中的时间戳
1969-12-31（Unix 纪元）表明原始文件不存在，补丁是新增文件而非修改文件。
补丁新增的 CMakeLists.txt 中，工具程序采用静态链接策略：
cmake
add_executable(hmac hmac_test.c)
target_link_libraries(hmac PRIVATE sha_static) # 静态链接静态链接的目标:
hmac→sha_staticpwd2key→sha_staticsha_test→sha_staticsha256sum→sha_static
选择静态链接的原因:
- 避免动态链接库找不到的问题
- 简化部署，无需管理库路径
- 适合独立运行的工具程序
2. 新增 CMake 配置
cmake
# 添加 OpenHarmony 特定配置
if(OHOS)
target_compile_options(sha_test PRIVATE -Wno-format-security)
endif()适配流程
完整的适配流程图
┌─────────────────────────────────────────────────────────────┐
│ 适配流程开始 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 1. 分析原始库 │
│ - 检查依赖关系 │
│ - 评估移植难度 │
│ - 确定适配策略 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. 创建 HPKBUILD │
│ - 定义包元数据 │
│ - 配置源码下载 │
│ - 编写构建函数 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. 创建补丁文件 │
│ - 分析需要修改的内容 │
│ - 编写 CMakeLists.txt 修改 │
│ - 处理平台特定问题 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 4. 配置测试 │
│ - 编写 HPKCHECK │
│ - 定义测试用例 │
│ - 验证功能正确性 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 5. 创建配置文件 │
│ - hnp.json │
│ - README 文档 │
│ - 开源声明 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 6. 构建测试 │
│ - 执行 ./build.sh sha │
│ - 检查构建产物 │
│ - 验证多架构支持 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 7. 设备测试 │
│ - 部署到 OpenHarmony 设备 │
│ - 运行测试程序 │
│ - 验证功能完整性 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 8. 问题修复 │
│ - 修复动态链接问题 │
│ - 优化构建配置 │
│ - 完善文档说明 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 适配流程完成 │
└─────────────────────────────────────────────────────────────┘技术要点
1. 静态链接 vs 动态链接
| 特性 | 动态链接 | 静态链接（采用） |
|---|---|---|
| 文件大小 | 小 | 大 |
| 内存占用 | 低 | 高 |
| 部署复杂度 | 高 | 低 |
| 运行时依赖 | 需要库文件 | 无 |
| 更新便利性 | 高 | 低 |
| 适用场景 | 系统库 | 工具程序 |
选择理由:
- SHA 库体积小，静态链接增加的体积可忽略
- 简化部署，无需管理库路径
- 避免版本冲突问题
- 适合独立运行的工具
2. 多架构支持
bash
archs=("armeabi-v7a" "arm64-v8a")实现方式:
- 为每个架构独立构建
- 使用架构特定的工具链
- 生成架构特定的产物
- 统一的构建流程
环境变量设置:
bash
# ARM32 环境
setarm32ENV() {
export CC=${OHOS_SDK}/native/llvm/bin/arm-linux-ohos-clang
export CXX=${OHOS_SDK}/native/llvm/bin/arm-linux-ohos-clang++
export HNP_TOOL=${OHOS_SDK}/toolchains/hnpcli
# ...
}
# ARM64 环境
setarm64ENV() {
export CC=${OHOS_SDK}/native/llvm/bin/aarch64-linux-ohos-clang
export CXX=${OHOS_SDK}/native/llvm/bin/aarch64-linux-ohos-clang++
export HNP_TOOL=${OHOS_SDK}/toolchains/hnpcli
# ...
}3. 补丁管理
补丁格式:
diff
--- a/original_file.txt
+++ b/modified_file.txt
@@ -line_start,count +line_start,count @@
context_line
-removed_line
+added_line
context_line补丁应用:
bash
patch -p1 < ../sha_ohos.patch优势:
- 保持原始代码完整性
- 便于版本升级
- 清晰的修改记录
- 易于代码审查
4. 构建产物管理
output/
├── armeabi-v7a/
│ ├── sha.hnp # HNP 包
│ └── sha_*.tar.gz # 压缩包
└── arm64-v8a/
├── sha.hnp
└── sha_*.tar.gz
usr/sha/
├── armeabi-v7a/
│ ├── bin/ # 可执行文件
│ ├── include/ # 头文件
│ └── lib/ # 库文件
└── arm64-v8a/
├── bin/
├── include/
└── lib/常见问题
Q1: 为什么使用 commit hash 作为版本号？
A: 使用 commit hash 的优势：
- 精确标识源码版本
- 便于追溯和调试
- 避免版本号冲突
- 符合开源项目管理习惯
Q2: 补丁文件的作用是什么？
A: 补丁文件的作用：
- 修改原始代码以适配 OpenHarmony
- 保持原始代码不变
- 便于版本升级和合并
- 清晰记录所有修改
Q3: HNP 包和 tar.gz 包有什么区别？
A:
| 包类型 | 用途 | 格式 | 工具 |
|---|---|---|---|
| HNP | OpenHarmony 原生包 | 专有格式 | hnpcli |
| tar.gz | 通用压缩包 | 标准格式 | tar |
Q4: 如何验证构建是否成功？
A: 验证步骤：
- 检查构建日志是否无错误
- 检查产物文件是否生成
- 在设备上运行测试程序
- 验证功能正确性
Q5: 如何添加新的架构支持？
A: 步骤：
- 在 HPKBUILD 中添加新架构
- 在 envset.sh 中添加环境设置函数
- 测试新架构的构建和运行
总结
SHA 库的 鸿蒙PC 适配是一个完整的工程实践，包含以下关键要素：
核心文件
- HPKBUILD - 构建配置的核心
- HPKCHECK - 质量保证的关键
- hnp.json - 部署配置的必需
- README_zh.md - 用户使用的指南
- README.OpenSource - 合规性的声明
技术要点
- ✅ 静态链接简化部署
- ✅ 多架构支持
- ✅ 补丁管理
- ✅ 完整的测试验证
- ✅ 详细的文档说明
适配成果
- 🎯 成功适配 OpenHarmony 平台
- 🎯 支持 ARM64 和 ARM 架构
- 🎯 提供完整的测试工具
- 🎯 编写详细的文档
- 🎯 解决动态链接问题
这个适配案例为其他开源库的 鸿蒙PC 移植提供了很好的参考模板。