欢迎加入开源鸿蒙PC社区 https://harmonypc.csdn.net/欢迎在PC社区平台申请新建项目https://atomgit.com/OpenHarmonyPCDeveloper本文记录 Zstandardzstd1.5.6 在 HarmonyOS PCAArch64上的适配、Conan 制品交付与消费者验证全过程。文中的测试数字均来自实际执行日志宿主回归、交叉编译与 CI 门禁分层表述不把未验证的结论写成全量通过。本文适配成果已合入开源鸿蒙 PC 仓库build_in_harmonyos / archives/z/zstd/1.5.6 包含 Conan 配方、test_package 消费者测试与一键复测脚本 run_upstream_tests.sh。适配 MR 评审与合入记录【积分赛】fix(zstd): 1.5.6 修复 conandata.yml 源码 sha256 哈希值错误 #3578一、先看结论项目结果上游项目Zstandardzstd上游源码版本v1.5.6官方源码地址https://github.com/facebook/zstd源码 SHA-2568c29e06cf42aacc1eafc4077ae2ec6c6fcb96a626157e0593d5e82a34fd403c1目标平台HarmonyOS PC / AArch64OHOS_ARCHarm64-v8a适配路径路径 A基础适配Conan 配方交付上游测试2731 项实测2730 通过通过率 99.96%新增测试test_packagedlopen libzstd.so 校验ZSTD_versionNumber符号导出CI 门禁conan create/ test_package / L0 结构完整性 / L1 测试执行验证 全部通过交付状态已合入 mainCI 双通道CI REL全绿一句话总结zstd 1.5.6 以 Conan 配方交付上游 2731 项测试在宿主侧实测 99.96% 通过唯一失败项为 root 环境问题非库缺陷并新增 1 项鸿蒙特有消费者测试验证共享库可被dlopen加载。二、为什么是 Zstandardfan-in 35 的压缩机底座Zstandard 由 Yann ColletxxHash、LZ4 作者与 Meta 开源BSD-3 许可2016 年发布。它的设计目标是把压缩比和压缩速度从二选一变成一把可调的滑尺1~22 级压缩等级从实时场景每秒数百 MB到极致压缩逼近 LZMA 的比率一个参数自由权衡对比 gzip官方基准下中等级别的压缩速度可达 gzip 的数倍压缩比同时更优对比 LZMA/xz压缩比略逊但速度快一个数量级解压普遍在 GB/s 量级工程友好流式 API、上下文复用单线程多流并发、字典训练小文件场景压缩比大幅提升。开源鸿蒙 PC 社区公布本批星光库时给出的依赖统计中zstd 的 fan-in被依赖数为 35——它是生态中被下游引用最多的基础库之一。这不是偶然看看各领域对它的采用领域代表项目Linux 内核内核镜像压缩、zram、squashfs、btrfs、f2fs5.6 原生支持文件系统/存储Btrfs、ZFS/OpenZFS数据库RocksDB、MySQL InnoDB 页压缩、PostgreSQL TOASTPG14、ClickHouse、MongoDB包管理Arch pacman、Fedora RPM、Debian dpkg、conda、Nix网络/传输Chrome/Firefox 的Content-Encoding: zstd、OpenSSH、rsync归档格式tar --zstd、zip方法 20从内核到浏览器从数据库到包管理器zstd 已经是事实上的新一代压缩选型。对一个 PC 操作系统生态来说它是数据库、归档工具、传输组件绕不开的压缩机底座。三、它在鸿蒙 PC 生态里的位置本次适配可以理解为下面这条链路zstd 上游源码github.com/facebook/zstd - Conan 配方conandata.yml conanfile.py test_package - OHOS NDK ohos.toolchain.cmake 交叉编译arm64-v8a - binary-sign-tool 共享库自签 - ohpcd 制品仓发布 - 下游库/应用通过 Conan 消费 libzstd.so - HarmonyOS PC 上动态加载运行高 fan-in 意味着适配一次、受益一片任何依赖 zstd 的数据库类、归档类、传输类三方库都可以直接站在这个制品上做交叉编译而不用各自面对一遍 musl libc 和工具链差异。四、适配难点拆解4.1 musl libcGNU 扩展不能想当然HarmonyOS 用户态使用 musl libc与 glibc 的差异是所有三方库适配的第一道坎。zstd 的场景比较典型先核查事实再打补丁。上游同类库常踩的坑是 GNU 扩展qsort_rmusl 不提供。我们对 1.5.6 全树grep qsort_r结果无命中——zstd 仅使用标准 C90 的qsort()/mergesort()不存在此依赖。配方中保留的_patch_gnu_qsort_r()沿用自已发布的 1.5.7 配方在 1.5.6 上未命中模式走else分支仅打 warning是防御性 no-op不影响构建与功能。平台宏不是万能药。项目规范 R8最高优先级明确源码和 patches/ 补丁不得引入平台条件编译宏要求通过 POSIX 接口适配。评审中也指出即使确需兼容也建议改为 CMakecheck_c_source_compiles做能力检测、用target_compile_definitions传递功能宏而不是硬编码__OHOS__这类平台名。这条经验对任何库都适用判断能力而不是判断平台。4.2 交叉编译下的测试策略宿主回归 设备消费者双层验证OHOS 目标是 arm64CI 宿主是 x86_64交叉编译出的测试二进制无法在宿主执行——这是所有 C/C 库适配都要回答的问题你的 99% 通过率是怎么跑出来的我们的答案分两层宿主侧原生回归在 Ubuntu 24.04x86_64上以ZSTD_BUILD_TESTSON原生构建完整跑上游tests/套件。这一层的有效性有依据zstd 1.5.6 仅使用标准 C90 排序接口、不依赖平台特有符号宿主原生测试可完整覆盖库逻辑。设备侧消费者测试新增test_package在设备上通过dlopen加载libzstd.so、dlsym校验ZSTD_versionNumber符号存在并被实际调用验证交叉编译产物在真机可加载、符号可消费。同时给test()加上cross_building保护交叉编译场景只验编译链接避免在宿主上执行 arm64 二进制导致exec format error。这两层合起来才构成库逻辑正确和制品可用的完整证据链。4.3 共享库签名从编译通过到能被加载编译出的.so在 OHOS 上还不能直接用——平台要求共享库经过签名。配方的_sign_shared_libs()完成两步llvm-objcopy 移除 .codesign 段 - binary-sign-tool 对 libzstd.so 自签这一步不处理dlopen就会在加载阶段失败。它是构建成功与制品可消费之间最容易被忽略的一环。4.4 制品可复现性URL、哈希与镜像配方固定官方源 github.comR39 规则CI 自动改写镜像 fallback。本次源码 SHA-256 实测为8c29e06c...403c1与 gh-proxy、kkgithub 多镜像返回的哈希一致——多镜像哈希比对是排除下载被污染质疑的关键动作。五、CI 失败排查实录一个 sha256 引发的全链路阻塞这次适配的直接导火索是 CI 失败source()下载源码后哈希校验不通过构建在第一步就挂掉。排查路径定位conandata.yml中记录的 sha2560f6096...是一个无效哈希值验证本地实际下载源码计算哈希再与 CI 多镜像源gh-proxy、kkgithub返回的哈希比对三者一致修复将正确值8c29e06c...同步写入conandata.yml与manifest.yamlCI 恢复全绿。经验哈希类失败先本地对源再怀疑代码。无效哈希会让所有构建门禁在第一步全灭表象是CI 全挂根因却只是一行配置。六、测试与验证6.1 上游测试实测明细宿主侧测试套件运行命令用例数通过失败通过率make checkplayTests.sh shortest./playTests.sh41410100%fuzzer./fuzzer -v -i5005005000100%zstreamtest./zstreamtest -v -T20s9859850100%zstreamtestnewapi./zstreamtest --newapi -t1 -T20s115911590100%cli-tests./cli-tests/run.py4140197.6%fullbench./fullbench -i1/-i1 -P0220100%invalidDictionaries./invalidDictionaries110100%legacy./legacy110100%poolTests./poolTests110100%合计—27312730199.96%官方make check退出码 0PASS。唯一失败项cli-tests/file-stat/compress-file-to-dir-without-write-perm.sh。该用例chmod 000 out后期望 zstd 因无写权限而失败本次以 root 运行root 绕过 Unix 写权限校验导致 zstd 写入成功用例期望失败未成立。属宿主 root 环境问题非库缺陷OHOS 应用以非 root 运行该用例在非 root 环境通过。剔除该环境项后库功能用例通过率 2730/2730 100%。6.2 新增消费者测试项目说明新增文件test_package/test.c验证内容dlopen加载 libzstd.sodlsym校验ZSTD_versionNumber符号存在并被实际调用执行方式由 CI 在设备侧自动执行MANIFEST.yml声明以 hnp 环境的 bash 运行./test_probe结果1/1 通过6.3 HarmonyOS PC 真机实测HiShell在 HarmonyOS PC 真机上实测上游测试套件测试二进制经 OHOS NDK arm64 交叉编译、binary-sign-tool 自签后在真机 HiShell 执行。测试真机结果./zstd -Vv1.5.6 版本横幅正常./fuzzer -v -i500All fuzzer tests completed500/500./zstreamtest -v -T20sOK./zstreamtest --newapi -t1 -T20sOK20 秒窗口完成 781 项宿主机同命令为 1159 项限时模式完成数随设备性能浮动./fullbench -i1全部 API 基准通过compress 540.4 MB/s / decompress 1750.8 MB/s七、复现指南上游测试已封装为一键脚本下载 sha256 校验 构建 跑测archives/z/zstd/1.5.6/run_upstream_tests.shConan 交叉构建入口profile 以仓库ci/conan/profiles为准conan create archives/z/zstd/1.5.6 \ -pr:hci/conan/profiles/ohos-aarch64 \ -pr:bci/conan/profiles/ohos-aarch64 \ --buildmissing构建通过后 CI 会依次执行 L0 结构完整性门禁、L1 测试执行验证门禁、制品签名与上传。八、边界说明哪些结论成立哪些还在路上严谨的适配报告必须划清已验证与未覆盖的边界已验证宿主侧x86_64上游全量测试回归2731 项99.96%交叉编译OHOS arm64-v8a构建、链接与制品签名CI 设备侧 test_packagelibzstd.so 可dlopen加载、核心符号可消费CI 双通道CI REL门禁全绿。HarmonyOS PC 真机HiShell实测fuzzer / zstreamtest / fullbench 全部通过未覆盖上游全量测试套件在真机 arm64 上的原生运行交叉编译测试二进制需设备侧 shell 支持属后续可扩展项依赖 zstd 的下游库的真机端到端验证随各下游库自身的适配交付。九、踩坑清单哈希类 CI 失败先本地对源无效 sha256 会让source()第一步全灭先下载实测哈希、多镜像比对再怀疑别的平台宏不是适配的正解R8 禁止平台条件编译宏check_c_source_compiles能力检测优于__OHOS__平台名判断打补丁前先核查上游源码全树grep qsort_r无命中才敢下结论防御性补丁必须有安全的 no-op 出口root 环境会伪造失败chmod 000对 root 无效环境问题不等于库缺陷报告里要把口径写清楚交叉编译的测试必须分层宿主回归证明库逻辑消费者测试证明制品可用test_package记得加cross_building保护。结语zstd 的适配本质是一次基础库交付的完整实践上游 2731 项测试守住库逻辑musl 兼容核查守住平台正确性签名与消费者测试守住制品可用性。对 fan-in 高达 35 的压缩机底座来说这一次适配的收益会随下游生态持续放大——数据库、包管理、归档与传输类三方库都可以直接站在这个制品上继续往前走。同库 1.5.7 配方中的成熟做法qsort_r 防御性补丁、签名流程已在本次 1.5.6 适配中复用后续版本的适配成本只会越来越低。欢迎加入开源鸿蒙PC社区 https://harmonypc.csdn.net/欢迎在PC社区平台申请新建项目https://atomgit.com/OpenHarmonyPCDevelopernceDiagram.html
