通过开源鸿蒙终端工具Termony完成LZ4 命令行工具构建过程深度解读

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

📖 LZ4 简介

LZ4 是一个极速的无损压缩算法，专注于压缩和解压速度。它提供了非常高的压缩和解压速度，同时保持合理的压缩比。LZ4 广泛应用于需要快速压缩的场景，如实时数据传输、日志压缩、数据库备份等。

🎯 LZ4 的作用与重要性

LZ4 是一个高性能压缩工具，提供了：

• 极速压缩：提供非常高的压缩和解压速度，适合实时场景
• 合理压缩比：在保持高速的同时，提供合理的压缩比
• 低资源占用：压缩和解压过程占用内存和 CPU 资源较少
• 跨平台支持：支持多种操作系统和架构
• 库和工具：提供 C 库和命令行工具，便于集成和使用

🔧 LZ4 核心特性

1. 命令行工具

• lz4 - 主压缩/解压工具
• lz4cat - 解压并输出到标准输出（类似 zcat）
• unlz4 - 解压工具（lz4 -d 的别名）

2. 压缩模式

• 快速模式：默认模式，平衡速度和压缩比
• 高压缩模式：-9 选项，更高的压缩比但速度较慢
• 超快速模式：-1 选项，最快速度但压缩比较低

3. 库文件

• liblz4.so - 共享库，提供压缩/解压 API
• 头文件：lz4.h、lz4hc.h、lz4frame.h 等
• pkg-config：liblz4.pc 用于依赖发现

🚀 构建入口与环境

• 📝 执行命令：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 变量定义需要构建的包列表（包含 lz4）
  • 通过 check-pkgs 机制自动检测 PKGS 变化并触发重新构建
  • 自动合并 external-hnp 目录下的外部 HNP 包
  • base.hnp 依赖所有包的 .stamp 和外部 HNP 包
  • 总目标 all: copy，打包 base.hnp 并拷贝到 entry/hnp/$(OHOS_ABI)

⚙️ LZ4 包的构建配置

• 📁 包目录：build-hnp/lz4/Makefile
  • 继承通用规则：include ../utils/Makefrag
  • 源地址：SOURCE_URL = https://github.com/lz4/lz4/releases/download/v1.10.0/lz4-1.10.0.tar.gz
  • 版本：1.10.0
  • 构建系统：CMake
• ⚙️ CMake 配置参数：
  • -DCMAKE_INSTALL_PREFIX=$(PREFIX) 安装前缀（默认 PREFIX=/data/app/base.org/base_1.0）
  • -DCMAKE_SYSTEM_NAME=Linux 系统名称
  • -DCMAKE_SYSTEM_PROCESSOR=$(OHOS_ARCH) 目标架构
  • -DBUILD_SHARED_LIBS=ON 构建共享库
  • -DBUILD_STATIC_LIBS=OFF 不构建静态库
  • -DCMAKE_BUILD_TYPE=RelWithDebInfo 构建类型
• 🔨 构建流程：
  1. 下载源码包
  2. 解包并进入源码目录
  3. 使用 CMake 配置构建系统
  4. 编译库和命令行工具
  5. 安装到临时前缀后复制至 ../sysroot
  6. 执行 ELF strip 减小体积
• 🔧 通用工具链与路径：build-hnp/utils/Makefrag
  • CC/CXX/LD/AR/RANLIB/... 均指向 OHOS SDK 的 LLVM 工具链
  • 通过 PKG_CONFIG_LIBDIR 指向 sysroot 下 .pc 目录，确保依赖发现
  • 下载支持多镜像回退：wget → curl，主镜像失败时自动尝试备用镜像

📋 关键日志与过程节点

• 📥 下载与解包：
  • 从 GitHub Releases 下载 lz4-1.10.0.tar.gz
  • 完成解包并进入 temp/lz4-1.10.0 目录
  • 包含 programs/（命令行工具）和 lib/（库）源码
  • 下载规则支持多镜像回退：wget → curl，自动尝试备用镜像
• ⚙️ CMake 配置阶段：
  • 使用 CMake 配置构建系统
  • 检测 Clang 编译器和编译标志（-Wall、-Wextra 等）
  • 配置共享库构建，禁用静态库
• 🔨 编译与安装：
  • 同时构建 liblz4.so 和 CLI 可执行文件 lz4
  • 创建符号链接：lz4cat -> lz4、unlz4 -> lz4
  • 安装库文件、头文件、pkg-config 文件
  • 执行 ELF strip 减小体积
  • 在打包前移除 man 目录以缩减体积
• 📦 打包：
  • 合并外部 HNP 包（如果存在）
  • 顶层执行 zip -r base.hnp sysroot 并拷贝到 entry/hnp/arm64-v8a/
  • 所有 LZ4 工具和库文件已成功打包到 base.hnp

✅ 产物验证

📦 检查打包文件

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

🔍 检查命令行工具

1# 检查 LZ4 工具
2ls -lh build-hnp/sysroot/bin/lz4*
3file build-hnp/sysroot/bin/lz4
4
5# 验证工具是否存在
6test -f build-hnp/sysroot/bin/lz4 && echo "lz4: OK" || echo "lz4: MISSING"
7test -L build-hnp/sysroot/bin/lz4cat && echo "lz4cat: OK" || echo "lz4cat: MISSING"
8test -L build-hnp/sysroot/bin/unlz4 && echo "unlz4: OK" || echo "unlz4: MISSING"
9

✅ 构建验证结果：

• ✅ LZ4 主程序已成功安装：lz4 (228K)
• ✅ 符号链接已正确创建：lz4cat -> lz4、unlz4 -> lz4

📚 检查库文件

1# 检查 LZ4 库
2ls -lh build-hnp/sysroot/lib/liblz4*
3file build-hnp/sysroot/lib/liblz4.so.1.10.0
4
5# 检查 pkg-config 文件
6ls -lh build-hnp/sysroot/lib/pkgconfig/liblz4.pc
7

✅ 构建验证结果：

• ✅ LZ4 库已成功安装：liblz4.so.1.10.0 (159K)
• ✅ 符号链接已正确创建：liblz4.so -> liblz4.so.1、liblz4.so.1 -> liblz4.so.1.10.0

📝 检查头文件

1# 检查头文件
2ls -lh build-hnp/sysroot/include/lz4*
3
4# 检查主要头文件
5test -f build-hnp/sysroot/include/lz4.h && echo "lz4.h: OK" || echo "lz4.h: MISSING"
6test -f build-hnp/sysroot/include/lz4hc.h && echo "lz4hc.h: OK" || echo "lz4hc.h: MISSING"
7test -f build-hnp/sysroot/include/lz4frame.h && echo "lz4frame.h: OK" || echo "lz4frame.h: MISSING"
8

💻 终端中执行的示例命令

🔧 LZ4 基本使用

1. 压缩文件

1# 基本压缩
2lz4 file.txt
3
4# 压缩并指定输出文件名
5lz4 file.txt compressed.lz4
6
7# 压缩并保留原文件
8lz4 -k file.txt
9
10# 高压缩比模式（-9）
11lz4 -9 file.txt compressed.lz4
12
13# 超快速模式（-1）
14lz4 -1 file.txt compressed.lz4
15
16# 压缩并显示详细信息
17lz4 -v file.txt compressed.lz4
18
19# 压缩并显示进度
20lz4 --progress file.txt compressed.lz4
21

2. 解压文件

1# 基本解压
2lz4 -d compressed.lz4
3
4# 解压并指定输出文件名
5lz4 -d compressed.lz4 output.txt
6
7# 解压并保留原文件
8lz4 -d -k compressed.lz4
9
10# 使用 unlz4 命令（等同于 lz4 -d）
11unlz4 compressed.lz4
12
13# 解压并显示详细信息
14lz4 -d -v compressed.lz4
15
16# 强制覆盖已存在的文件
17lz4 -d -f compressed.lz4
18

3. 查看压缩文件信息

1# 测试压缩文件完整性
2lz4 -t compressed.lz4
3
4# 显示压缩文件信息
5lz4 -l compressed.lz4
6
7# 显示详细统计信息
8lz4 -l -v compressed.lz4
9

4. 流式压缩/解压

1# 压缩标准输入到标准输出
2echo "Hello, LZ4!" | lz4 > compressed.lz4
3
4# 解压标准输入到标准输出
5cat compressed.lz4 | lz4 -d
6
7# 使用 lz4cat 解压并输出（类似 zcat）
8lz4cat compressed.lz4
9
10# 管道压缩
11cat file.txt | lz4 > compressed.lz4
12
13# 管道解压
14cat compressed.lz4 | lz4 -d > output.txt
15

5. 批量压缩/解压

1# 压缩多个文件
2lz4 file1.txt file2.txt file3.txt
3
4# 递归压缩目录（需要配合其他工具）
5find . -type f -name "*.txt" -exec lz4 {} {}.lz4 \;
6
7# 批量解压
8for file in *.lz4; do lz4 -d "$file"; done
9

6. 压缩级别和性能

1# 级别 1（最快，压缩比最低）
2lz4 -1 file.txt
3
4# 级别 3（默认，平衡速度和压缩比）
5lz4 file.txt
6
7# 级别 9（最慢，压缩比最高）
8lz4 -9 file.txt
9
10# 级别 12（最高压缩比）
11lz4 -12 file.txt
12

7. 实际应用示例

1# 压缩日志文件
2lz4 -k access.log
3
4# 压缩数据库备份
5lz4 -9 database_backup.sql
6
7# 压缩大文件并显示进度
8lz4 --progress large_file.dat
9
10# 解压并直接查看内容
11lz4cat log.lz4 | head -20
12
13# 压缩并传输
14tar czf - directory/ | lz4 > archive.tar.gz.lz4
15
16# 解压并提取
17lz4 -d archive.tar.gz.lz4 | tar xzf -
18

8. 性能测试

1# 创建测试文件
2dd if=/dev/zero of=test.dat bs=1M count=100
3
4# 测试压缩速度
5time lz4 test.dat test.lz4
6
7# 测试解压速度
8time lz4 -d test.lz4 test_out.dat
9
10# 比较压缩比
11ls -lh test.dat test.lz4
12

🧪 功能验证脚本

1#!/bin/bash
2# LZ4 工具验证脚本
3
4LZ4_BIN="build-hnp/sysroot/bin"
5
6echo "=== LZ4 工具验证 ==="
7
8# 检查主程序
9if [ -f "$LZ4_BIN/lz4" ]; then
10    echo "✓ lz4: 存在"
11    file "$LZ4_BIN/lz4"
12    echo "文件大小: $(ls -lh "$LZ4_BIN/lz4" | awk '{print $5}')"
13else
14    echo "✗ lz4: 缺失"
15fi
16
17echo ""
18
19# 检查符号链接
20for tool in lz4cat unlz4; do
21    if [ -L "$LZ4_BIN/$tool" ]; then
22        echo "✓ $tool: 存在（符号链接 -> $(readlink "$LZ4_BIN/$tool")）"
23    else
24        echo "✗ $tool: 缺失"
25    fi
26done
27
28echo ""
29echo "=== 库文件验证 ==="
30if [ -f "build-hnp/sysroot/lib/liblz4.so.1.10.0" ]; then
31    echo "✓ liblz4.so.1.10.0: 存在"
32    ls -lh build-hnp/sysroot/lib/liblz4.so*
33else
34    echo "✗ liblz4.so.1.10.0: 缺失"
35fi
36
37echo ""
38echo "=== 测试压缩/解压（如果可执行）==="
39echo "注意：这些是交叉编译的二进制文件，需要在目标设备上运行"
40

🐛 常见问题与解决方案

❌ 问题 1：CMake 工具链问题

• 🔍 症状：CMake 配置失败，找不到编译器或工具链
• 🔎 原因：CMake 未正确检测到交叉编译工具链
• ✅ 解决方法：
  • 确保 OHOS_SDK_HOME 环境变量正确设置
  • 确保 CMake 能够找到交叉编译器
  • 检查 CMAKE_SYSTEM_NAME 和 CMAKE_SYSTEM_PROCESSOR 设置
  • 位置：build-hnp/lz4/Makefile:7

❌ 问题 2：共享库构建失败

• 🔍 症状：编译时出现共享库链接错误
• 🔎 原因：缺少共享库依赖或链接选项不正确
• ✅ 解决方法：
  • 确保 BUILD_SHARED_LIBS=ON 设置正确
  • 检查交叉工具链是否支持共享库
  • 确保所有依赖库都已正确构建
  • 位置：build-hnp/lz4/Makefile:7

❌ 问题 3：文档体积过大

• 🔍 症状：HNP 包体积较大，包含不必要的文档
• 🔎 原因：man 手册页等文档文件占用空间
• ✅ 解决方法：
  • 在打包前移除 man 目录以缩减体积
  • 如需保留文档，可调整顶层裁剪步骤
  • 位置：顶层 Makefile 的打包规则

❌ 问题 4：符号链接未创建

• 🔍 症状：lz4cat 或 unlz4 符号链接不存在
• 🔎 原因：安装过程中符号链接创建失败
• ✅ 解决方法：
  • 检查安装过程是否正常完成
  • 手动创建符号链接：ln -s lz4 lz4cat、ln -s lz4 unlz4
  • 位置：build-hnp/lz4/Makefile（CMake 自动创建）

🔄 重建与扩展

• 🔧 重建单包：

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

• 🧹 清理：

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

• 📦 扩展：LZ4 是压缩栈的重要组成部分，与 zlib、zstd、xz 等共同构建，提升上层工具兼容性
• 🔄 自动重建机制：
  • 修改 PKGS 后，check-pkgs 会自动检测变化并触发重新构建
  • 新增外部 HNP 包到 external-hnp 目录后，会自动合并到 base.hnp

💡 实践建议

• 🔧 压缩级别选择：根据实际需求选择合适的压缩级别，平衡速度和压缩比
• 🛡️ 性能优化：LZ4 专注于速度，适合实时压缩场景；如需更高压缩比，可考虑 zstd
• 📦 库集成：使用 liblz4.so 和头文件在应用程序中集成 LZ4 压缩功能
• 🔗 压缩栈配合：与 zlib、zstd、xz 共同构建，配合 libarchive 提供归档/解压的统一接口

📝 结论与建议

• ✅ 本次已在 aarch64 环境下完成 LZ4 1.10.0 的交叉编译与打包，所有工具和库文件已安装到 sysroot 并纳入 HNP 包。
• 💡 为保证构建稳定：
  • 固定可靠的上游镜像，避免下载阶段随机失败（已实现自动回退机制）
  • 对大型包启用构建缓存（可在 Makefrag 中开启 USE_CCACHE）
  • 使用 CMake 构建系统，确保跨平台兼容性
  • 移除不必要的文档以减小包体积
  • 利用 check-pkgs 机制自动检测包列表变化，无需手动清理

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

《通过开源鸿蒙终端工具Termony完成LZ4 命令行工具构建过程深度解读》 是转载文章，点击查看原文。