本文记录使用命令 OHOS_ARCH=aarch64 OHOS_ABI=arm64-v8a sh ./create-hnp.sh 构建 XxHash 0.8.3 的完整过程，包括环境、构建链路、关键日志、常见问题与解决方案、产物验证与重建方法，便于复现与运维。

欢迎加入开源鸿蒙PC社区：https://harmonypc.csdn.net/

📖 XxHash 简介

XxHash 是一个极速的非加密哈希算法，由 Yann Collet 开发。它提供了多种哈希算法变体（XXH32、XXH64、XXH3），具有极高的性能和良好的哈希质量，广泛应用于数据校验、去重、缓存等场景。

🎯 XxHash 的作用与重要性

XxHash 是高性能哈希计算的核心工具，提供了：

  • 极速哈希：比传统哈希算法（如 MD5、SHA1）快数倍
  • 多种算法：支持 XXH32、XXH64、XXH3（64-bit 和 128-bit）
  • 数据校验：快速计算文件或数据的哈希值
  • 去重检测：高效检测重复数据
  • 缓存键生成：快速生成缓存键
  • 流式处理：支持流式哈希计算

🔧 XxHash 核心特性

1. 哈希算法变体
  • XXH32：32 位哈希值，适合小数据
  • XXH64：64 位哈希值，平衡性能和碰撞率
  • XXH3 64-bit：最新的 64 位算法，性能最优
  • XXH3 128-bit：128 位哈希值，更高的安全性
2. 性能特点
  • 极速计算：比 MD5 快 10-20 倍
  • 低延迟：适合实时应用
  • 低 CPU 占用：高效的算法实现
  • SIMD 优化：支持 SIMD 指令加速
3. 应用场景
  • 文件校验：快速验证文件完整性
  • 数据去重：检测重复数据
  • 缓存键生成：生成缓存键
  • 布隆过滤器：用于布隆过滤器
  • 数据分片：数据分片和负载均衡
4. 命令行工具
  • xxhsum：类似 md5sum 的哈希计算工具
  • 多种格式：支持多种输出格式
  • 批量处理：支持批量文件处理
  • 校验模式：支持校验模式
5. 编程接口
  • C API：提供 C 语言接口
  • 流式 API：支持流式哈希计算
  • 多线程安全：线程安全的实现
  • 跨平台：支持多种平台和架构

🚀 构建入口与环境

  • 📝 执行命令：OHOS_ARCH=aarch64 OHOS_ABI=arm64-v8a sh ./create-hnp.sh
  • 🔧 入口脚本：create-hnp.sh
    • 检查必需的环境变量 OHOS_ARCH 和 OHOS_ABI
    • 导出 LC_CTYPE、TOOL_HOME、OHOS_SDK_HOME
    • 执行 make -C build-hnp
  • 📦 顶层构建：build-hnp/Makefile
    • PKGS 变量定义需要构建的包列表（包含 xxhash）
    • 通过 check-pkgs 机制自动检测 PKGS 变化并触发重新构建
    • 自动合并 external-hnp 目录下的外部 HNP 包
    • base.hnp 依赖所有包的 .stamp 和外部 HNP 包
    • 总目标 all: copy，打包 base.hnp 并拷贝到 entry/hnp/$(OHOS_ABI)

⚙️ XxHash 包的构建配置

  • 📁 包目录：build-hnp/xxhash/Makefile
    • 继承通用规则：include ../utils/Makefrag
    • 源地址：https://github.com/Cyan4973/xxHash/archive/refs/tags/v0.8.3.tar.gz
    • 版本：0.8.3
  • ⚙️ CMake 配置参数：
    • CMAKE_LISTS_PATH = ../cmake_unofficial - 使用非官方 CMake 脚本
    • -DCMAKE_INSTALL_PREFIX=$(PREFIX) - 安装前缀（/data/app/base.org/base_1.0）
    • -DCMAKE_SYSTEM_NAME=Linux - 目标系统
    • -DCMAKE_SYSTEM_PROCESSOR=$(OHOS_ARCH) - 目标架构
    • -DBUILD_SHARED_LIBS=ON - 构建共享库
    • -DCMAKE_BUILD_TYPE=RelWithDebInfo - 保留符号便于定位问题
  • 🔨 构建流程：
    1. 下载源码包（支持多镜像回退）
    2. 解包并进入 temp/xxHash-0.8.3 目录
    3. 使用 cmake_unofficial 目录中的 CMake 脚本配置
    4. 运行 cmake 配置构建系统
    5. 使用 make -j $(nproc) 并行编译
    6. 使用 make install 安装
    7. 执行 ELF strip 减小体积
    8. 复制到 ../sysroot
  • 🔧 通用工具链与路径：build-hnp/utils/Makefrag
    • CC/CXX/LD/AR/RANLIB/... 均指向 OHOS SDK 的 LLVM 工具链
    • 下载支持多镜像回退：wget → curl，主镜像失败时自动尝试备用镜像

📋 关键日志与过程节点

  • 📥 下载与解包：
    • 从 GitHub Releases 下载 v0.8.3.tar.gz
    • 完成解包并进入 temp/xxHash-0.8.3 目录
    • 下载规则支持多镜像回退：wget → curl 兜底
  • ⚙️ 配置阶段：
    • 使用 cmake_unofficial 目录中的 CMake 脚本
    • 运行 cmake 配置构建系统
    • 配置成功，启用共享库构建
    • 生成 Makefile 和构建配置
  • 🔨 编译与安装：
    • 使用 make -j $(nproc) 并行编译
    • 成功编译生成 libxxhash.so.0.8.3 和 xxhsum 二进制
    • 使用 make install 安装到临时前缀
    • 执行 llvm-strip 剥离共享库和二进制符号
    • 复制到 ../sysroot
  • 📦 打包：
    • 完成 base.hnp 重打包，拷贝产物到 entry/hnp/arm64-v8a/
    • XxHash 库和工具已成功打包到 base.hnp 中

✅ 产物验证

📦 检查打包文件

ls build-hnp/base.hnp  # 应存在
ls entry/hnp/arm64-v8a/*.hnp  # 应包含 base.hnp 与 base-public.hnp

🔍 检查二进制和库文件

# 检查 xxhsum 二进制
ls -lh build-hnp/sysroot/bin/xxhsum
file build-hnp/sysroot/bin/xxhsum

# 检查库文件
ls -lh build-hnp/sysroot/lib/libxxhash.so*
file build-hnp/sysroot/lib/libxxhash.so.0.8.3

# 检查头文件
ls -lh build-hnp/sysroot/include/xxhash.h

# 检查 pkg-config 文件
ls -lh build-hnp/sysroot/lib/pkgconfig/libxxhash.pc
cat build-hnp/sysroot/lib/pkgconfig/libxxhash.pc

✅ 构建验证结果：

  • ✅ XxHash 命令行工具已成功安装：
    • xxhsum (38K) - 主程序二进制
  • ✅ XxHash 库已安装：
    • libxxhash.so.0.8.3 (34K) - 主库文件
    • libxxhash.so.0 - 版本符号链接
    • libxxhash.so - 通用符号链接
  • ✅ 文件类型：ELF 64-bit LSB pie executable/shared object, ARM aarch64
  • ✅ 动态链接：interpreter /lib/ld-musl-aarch64.so.1
  • ✅ 已剥离符号：stripped
  • ✅ 头文件已安装：xxhash.h
  • ✅ pkg-config 文件已安装：libxxhash.pc (432 bytes)
  • ✅ 已打包到 base.hnp 中

💻 终端中执行的示例命令

🔢 XxHash 基本使用

1. 计算文件哈希值
# 计算文件哈希值（默认 XXH64）
xxhsum file.txt

# 计算文件哈希值（XXH32）
xxhsum -H0 file.txt

# 计算文件哈希值（XXH64）
xxhsum -H1 file.txt

# 计算文件哈希值（XXH3 128-bit）
xxhsum -H2 file.txt

# 计算文件哈希值（XXH3 64-bit）
xxhsum -H3 file.txt

# 计算多个文件
xxhsum file1.txt file2.txt file3.txt

# 计算目录中所有文件
xxhsum *.txt

image-20251124143600565

2. 输出格式
# 默认格式（类似 md5sum）
xxhsum file.txt

# BSD 格式
xxhsum -b file.txt

# 只显示哈希值
xxhsum -q file.txt

# 显示进度
xxhsum --progress file.txt

# 显示详细信息
xxhsum -v file.txt

# 显示版本信息
xxhsum -V

image-20251124143756025

3. 校验模式
# 从文件读取哈希值并校验
xxhsum -c checksums.xxh

# 校验并显示详细信息
xxhsum -cv checksums.xxh

# 校验并静默模式
xxhsum -cq checksums.xxh

# 校验并显示进度
xxhsum -c --progress checksums.xxh

# 创建校验文件
xxhsum file1.txt file2.txt > checksums.xxh

# 校验校验文件
xxhsum -c checksums.xxh
4. 标准输入处理
# 从标准输入读取
echo "hello" | xxhsum

# 从标准输入读取（指定算法）
echo "hello" | xxhsum -H3

# 从管道读取
cat file.txt | xxhsum

# 从标准输入读取（显示文件名）
echo "hello" | xxhsum -

# 从标准输入读取（静默模式）
echo "hello" | xxhsum -q
5. 批量处理
# 批量计算哈希值
xxhsum *.txt

# 批量计算并保存到文件
xxhsum *.txt > all_hashes.xxh

# 批量校验
xxhsum -c all_hashes.xxh

# 递归计算目录
find . -type f -exec xxhsum {} \;

# 递归计算并保存
find . -type f -exec xxhsum {} \; > recursive_hashes.xxh

🔢 XxHash 高级用法

6. 不同哈希算法对比
# 对比不同算法的哈希值
xxhsum -H0 file.txt  # XXH32
xxhsum -H1 file.txt  # XXH64
xxhsum -H3 file.txt  # XXH3 64-bit
xxhsum -H4 file.txt  # XXH3 128-bit

# 同时计算多种算法
for algo in 0 1 3 4; do
    echo "Algorithm H$algo:"
    xxhsum -H$algo file.txt
done
7. 性能测试
# 计算大文件哈希值（显示时间）
time xxhsum large_file.bin

# 对比不同算法的性能
time xxhsum -H0 large_file.bin
time xxhsum -H1 large_file.bin
time xxhsum -H3 large_file.bin
time xxhsum -H4 large_file.bin

# 计算并显示速度
xxhsum --progress large_file.bin
8. 实际应用示例
# 创建文件哈希清单
xxhsum *.txt > file_hashes.xxh

# 校验文件完整性
xxhsum -c file_hashes.xxh

# 查找重复文件
xxhsum *.txt | sort | uniq -d -w 16

# 计算目录哈希值
find . -type f -exec xxhsum {} \; | xxhsum

# 快速校验下载文件
xxhsum downloaded_file.tar.gz
xxhsum -c downloaded_file.tar.gz.xxh

# 生成文件指纹
xxhsum -H3 file.txt > file.fingerprint

# 校验文件指纹
xxhsum -H3 -c file.fingerprint file.txt

# 批量校验文件
xxhsum -c checksums.xxh 2>&1 | grep -v "OK"

# 计算并保存哈希值
xxhsum file.txt | tee file.txt.xxh

# 校验并显示失败的文件
xxhsum -c checksums.xxh 2>&1 | grep FAILED

# 计算文件哈希值（静默模式）
xxhsum -q file.txt

# 计算文件哈希值（只显示哈希值）
xxhsum -q file.txt | cut -d' ' -f1

# 计算文件哈希值（只显示文件名）
xxhsum file.txt | cut -d' ' -f2

# 计算文件哈希值（自定义格式）
xxhsum file.txt | awk '{print $1 "  " $2}'

# 批量计算并排序
xxhsum *.txt | sort -k2

# 查找特定哈希值的文件
xxhsum *.txt | grep "abc123def456"

# 计算文件哈希值并追加到文件
xxhsum file.txt >> all_hashes.xxh

# 校验并统计结果
xxhsum -c checksums.xxh 2>&1 | tail -1
9. 与其他工具结合
# 与 find 结合
find . -name "*.txt" -exec xxhsum {} \;

# 与 grep 结合
xxhsum *.txt | grep "pattern"

# 与 sort 结合
xxhsum *.txt | sort -k2

# 与 awk 结合
xxhsum *.txt | awk '{print $1, $2}'

# 与 xargs 结合
find . -type f | xargs xxhsum

# 与 parallel 结合（如果可用）
find . -type f | parallel xxhsum
10. 编程接口示例（C 语言）
// 使用 XxHash 库的示例代码
#include <xxhash.h>
#include <stdio.h>

int main() {
    // XXH32 哈希
    XXH32_hash_t hash32 = XXH32("hello", 5, 0);
    printf("XXH32: %08x\n", hash32);
    
    // XXH64 哈希
    XXH64_hash_t hash64 = XXH64("hello", 5, 0);
    printf("XXH64: %016llx\n", hash64);
    
    // XXH3 64-bit 哈希
    XXH64_hash_t hash3_64 = XXH3_64bits("hello", 5);
    printf("XXH3 64-bit: %016llx\n", hash3_64);
    
    // XXH3 128-bit 哈希
    XXH128_hash_t hash3_128 = XXH3_128bits("hello", 5);
    printf("XXH3 128-bit: %016llx%016llx\n", 
           hash3_128.high64, hash3_128.low64);
    
    return 0;
}

// 编译命令
// gcc -o test_xxhash test_xxhash.c -lxxhash

🧪 功能验证脚本

#!/bin/bash
# XxHash 工具验证脚本

XXHASH_BIN="build-hnp/sysroot/bin"
XXHASH_LIB="build-hnp/sysroot/lib"
XXHASH_INCLUDE="build-hnp/sysroot/include"

echo "=== XxHash 工具验证 ==="

# 检查 xxhsum 二进制
if [ -f "$XXHASH_BIN/xxhsum" ]; then
    echo "✓ xxhsum: 存在"
    file "$XXHASH_BIN/xxhsum"
    echo "文件大小: $(ls -lh "$XXHASH_BIN/xxhsum" | awk '{print $5}')"
    echo "架构信息: $(file "$XXHASH_BIN/xxhsum" | grep -o "ARM aarch64")"
else
    echo "✗ xxhsum: 缺失"
fi

# 检查库文件
echo ""
echo "=== 库文件验证 ==="
if [ -f "$XXHASH_LIB/libxxhash.so.0.8.3" ]; then
    echo "✓ libxxhash.so.0.8.3: 存在"
    file "$XXHASH_LIB/libxxhash.so.0.8.3"
    echo "文件大小: $(ls -lh "$XXHASH_LIB/libxxhash.so.0.8.3" | awk '{print $5}')"
else
    echo "✗ libxxhash.so.0.8.3: 缺失"
fi

# 检查符号链接
for link in libxxhash.so libxxhash.so.0; do
    if [ -L "$XXHASH_LIB/$link" ]; then
        echo "✓ $link: 符号链接 -> $(readlink "$XXHASH_LIB/$link")"
    else
        echo "✗ $link: 缺失"
    fi
done

# 检查头文件
echo ""
echo "=== 头文件验证 ==="
if [ -f "$XXHASH_INCLUDE/xxhash.h" ]; then
    echo "✓ xxhash.h: 存在"
    echo "文件大小: $(ls -lh "$XXHASH_INCLUDE/xxhash.h" | awk '{print $5}')"
else
    echo "✗ xxhash.h: 缺失"
fi

# 检查 pkg-config 文件
echo ""
echo "=== pkg-config 验证 ==="
if [ -f "build-hnp/sysroot/lib/pkgconfig/libxxhash.pc" ]; then
    echo "✓ libxxhash.pc: 存在"
    cat build-hnp/sysroot/lib/pkgconfig/libxxhash.pc
else
    echo "✗ libxxhash.pc: 缺失"
fi

# 测试基本功能（在目标设备上）
echo ""
echo "=== 功能测试（需要在目标设备上运行）==="
echo "测试计算哈希值:"
echo "  echo 'hello' | $XXHASH_BIN/xxhsum"
echo ""
echo "测试不同算法:"
echo "  echo 'hello' | $XXHASH_BIN/xxhsum -H0  # XXH32"
echo "  echo 'hello' | $XXHASH_BIN/xxhsum -H1  # XXH64"
echo "  echo 'hello' | $XXHASH_BIN/xxhsum -H3  # XXH3 64-bit"
echo "  echo 'hello' | $XXHASH_BIN/xxhsum -H4  # XXH3 128-bit"

🐛 常见问题与处理

❌ 问题 1：CLI 未生成

  • 🔍 症状：构建完成但 xxhsum 二进制不存在
  • 🔎 原因：CMake 配置或安装阶段未包含 CLI 工具
  • ✅ 解决方法：
    • 确认使用 cmake_unofficial 目录中的 CMake 脚本
    • 检查 CMake 配置是否启用了 CLI 构建
    • 如果缺失，可以尝试使用上游 make -C cli 方式手工补装
    • 位置：build-hnp/xxhash/Makefile:6

❌ 问题 2：GitHub Releases 不可达

  • 🔍 症状：下载失败，无法获取源码包
  • 🔎 原因：网络问题或 GitHub 访问受限
  • ✅ 解决方法：
    • 手动下载源码包放置到 build-hnp/xxhash/download/v0.8.3.tar.gz
    • 通用下载逻辑支持备用镜像与重试（wget → curl）
    • 位置：build-hnp/utils/Makefrag:61-69

❌ 问题 3：架构不支持

  • 🔍 症状：Unsupported OHOS_ARCH=
  • 🔎 原因：传入的架构不在支持列表中
  • ✅ 解决方法：
    • 确保传入支持架构（aarch64 或 x86_64）
    • 位置：build-hnp/Makefile:1-45

❌ 问题 4：链接失败

  • 🔍 症状：链接错误，无法创建可执行文件或共享库
  • 🔎 原因：交叉工具链或 sysroot 路径不正确
  • ✅ 解决方法：
    • 检查交叉工具链与 sysroot 路径是否正确
    • 确保通过 create-hnp.sh 触发构建以获得完整环境变量
    • 位置：create-hnp.sh、build-hnp/utils/Makefrag

❌ 问题 5：CMake 配置失败

  • 🔍 症状：CMake 配置阶段失败
  • 🔎 原因：CMake 脚本路径或参数不正确
  • ✅ 解决方法：
    • 确认 CMAKE_LISTS_PATH 指向正确的 CMake 脚本目录
    • 检查 CMake 参数是否正确
    • 位置：build-hnp/xxhash/Makefile:6-7

❌ 问题 6：pkg-config 文件缺失

  • 🔍 症状：需要 pkg-config 文件但未生成
  • 🔎 原因：CMake 安装阶段未生成 pkg-config 文件
  • ✅ 解决方法：
    • 当前构建已包含 pkg-config 文件（libxxhash.pc）
    • 如果缺失，可以手动创建或使用头文件和库路径
    • 位置：build-hnp/sysroot/lib/pkgconfig/libxxhash.pc

❌ 问题 7：性能问题

  • 🔍 症状：哈希计算速度不如预期
  • 🔎 原因：未启用 SIMD 优化或编译选项不当
  • ✅ 解决方法：
    • XxHash 会自动检测并使用 SIMD 指令
    • 确保使用 -DCMAKE_BUILD_TYPE=RelWithDebInfo 或 Release 构建类型
    • 这是运行时问题，不是构建问题

🔄 重建与扩展

  • 🔧 重建单包：

    make -C build-hnp rebuild-xxhash  # 触发子包重新编译并刷新 .stamp

  • 🧹 清理：

    make -C build-hnp clean  # 清理 sysroot、所有 .stamp 和 PKGS_MARKER

  • 📦 扩展：XxHash 是高性能哈希计算的基础工具

  • 🔄 自动重建机制：

    • 修改 PKGS 后，check-pkgs 会自动检测变化并触发重新构建
    • 新增外部 HNP 包到 external-hnp 目录后，会自动合并到 base.hnp

💡 实践建议

  • 🔧 构建配置：使用 cmake_unofficial 脚本确保 CLI 工具正确构建
  • 🚀 算法选择：根据需求选择合适的哈希算法（XXH32/XXH64/XXH3）
  • 📦 性能优化：XxHash 会自动使用 SIMD 优化，无需额外配置
  • 🔗 编程接口：通过链接 libxxhash.so 使用编程接口
  • 🌐 文件校验：使用 xxhsum -c 进行批量文件校验

📝 结论与建议

  • ✅ 本次已在 aarch64 环境下完成 XxHash 0.8.3 的交叉编译与打包，xxhsum 工具和库已安装到 sysroot 并纳入 HNP 包。
  • 💡 为保证构建稳定：
    • 使用 cmake_unofficial 脚本确保 CLI 工具正确构建
    • 启用共享库构建以支持动态链接
    • 使用 RelWithDebInfo 构建类型保留符号便于调试
    • 确保通过 create-hnp.sh 触发构建以获得完整环境变量
    • 利用 check-pkgs 机制自动检测包列表变化，无需手动清理
    • XxHash 为高性能哈希计算提供了强大的工具和库支持
    • 常见陷阱包括 CLI 未生成、CMake 配置失败、链接失败；当前已通过 CMake 脚本和配置参数处理
    • CMake 非官方脚本对 XxHash 的库与 CLI 构建做了良好封装，交叉参数清晰可维护
    • 产物完整，上层可直接使用 xxhsum 进行校验，也可链接 libxxhash 实现高性能哈希计算

📚 以上为 XxHash 构建的深度解读与实践记录。

# 哈希算法
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

cover

前端成功转鸿蒙开发者真实案例，教大家如何开发鸿蒙APP-- 卡片实践

avatar 人工智能6S服务平台
cover

前端成功转鸿蒙开发者真实案例，教大家如何开发鸿蒙APP--ArkTS 卡片事件处理

avatar 人工智能6S服务平台
cover

从入门小白到精通，玩转 React Native 鸿蒙跨平台开发：FlatList 高性能列表组件

avatar 人工智能6S服务平台