鸿蒙三方库适配读懂 `README_zh.md`：中文适配说明里每段在说什么？

鸿蒙三方库适配读懂README_zh.md中文适配说明里每段在说什么欢迎大家加入开源鸿蒙跨平台开发者社区前言在 OpenHarmony / lycium 三方库目录里README_zh.md通常承担「给中文读者看的说明书」用自然语言说明这是什么库、编出来在哪、怎么编、怎么测不必像HPKBUILD那样写成 Shell 脚本。本仓库的thirdparty/AES/README_zh.md对应包名AES、上游 tiny-AES-c。下面按原文章节顺序把每段话的用途、背后的约定、和别的文件怎么对照讲清楚方便新人5 分钟建立全局印象需要细节时再翻HPKBUILD或docs/HPKBUILD解读.md。整体结构一览对应原文标题原文章节主要回答的问题简介谁家的库、叫什么、能干什么、和上游差在哪、适配时改了什么。产物与用法编完文件在哪、应用怎么链接、头文件和宏要注意什么。依赖说明还要不要别的库、构建机要装什么。编译一条命令怎么触发构建。测试为什么在设备上测、进哪个目录、ctest 还是直接跑二进制。参考上游链接、lycium 模板去哪看。标题AEStiny-AES-cOpenHarmony 适配说明通俗理解AES是lycium 里的名字目录名、pkgname、./build.sh AES。tiny-AES-c是GitHub 上的上游项目名。括号把两者绑在一起避免读者以为「AES」是 OpenSSL 那种全家桶这里只是tiny-AES-c 的 OHOS 适配包。「简介」在说什么原文三段信息可以拆成溯源上游是kokke/tiny-AES-c版本v1.0.0。读者知道issue、license、算法说明要去上游仓库看。能力边界纯 C、默认AES-128模式ECB / CBC / CTR。文档里提醒AES192/AES256要在aes.h里改宏本适配没有替你改密钥长度——意思是默认行为与上游一致别误以为 OHOS 版自动开了 256。适配做了什么上游CMake 的 include 路径错了也没配好安装和测试。所以我们在HPKBUILD的prepare()里重写 CMake得到静态库libtiny-aes.a、tiny_aes_test并挂上CTest和HPKCHECK里ctest对应。和HPKBUILD的关系简介是结论HPKBUILD是实现。读不懂简介里的某句时去docs/HPKBUILD解读.md找同名概念即可。「产物与用法」在说什么那张路径表$LYCIUM_ROOT一般指你本机lycium工程根目录由lycium/build.sh设置。$ARCHarmeabi-v7a或arm64-v8a。原文「类型」实际文件用途静态库lib/libtiny-aes.a链接进你的 native 模块。头文件include/aes.h#include与 API 声明。测试程序bin/tiny_aes_test设备上跑自测可选拷贝。路径模式usr/AES/ARCH/...是 lycium约定俗成的安装树和HPKBUILD的package()一致。链接示例那几行-I/-L/-ltiny-aes编译器找头文件、链接器找libtiny-aes.a-l名字是tiny-aes对应libtiny-aes.a。把$LYCIUM_ROOT和$ARCH换成你本机真实路径即可。关于ECB/CBC/CTR上游aes.h里可以用宏开关模式。你的工程若要用某种模式需在包含aes.h之前或编译参数-D里定义与上游文档一致。README 里点出test.c在包含头文件前把三个都设为 1是告诉你官方自测默认全开你写业务代码时可以只开需要的。「依赖说明」在说什么构建依赖没有「还要先编另一个 HPK 库」这种事但要OHOS SDK、cmake、make等——具体以lycium 仓库环境说明为准。运行时依赖静态库链进去后不依赖再带一份libtiny-aes.so除非你自己又做了动态库版本本 README 描述的是当前 HPK 产物。注意若未来depends里加了别的包README_zh.md的依赖节要同步改否则文档会骗人。「编译」在说什么就一条在lycium根目录执行./build.sh AES。通俗理解lycium根目录放build.sh的那一层不是thirdparty/AES。AES必须和thirdparty下文件夹名、HPKBUILD的pkgname一致。若只编部分库且带依赖社区有时写./build.sh dep1 AES本库无 depends只写AES即可。「测试」在说什么核心就一句交叉编出来的二进制不能在 Mac/Windows 上直接双击跑要在OpenHarmony 真机或模拟器上跑。原文给了两条路整目录推送把tiny-AES-c-1.0.0/$ARCH-build和HPKBUILD里builddirarm64-v8a-build这类目录一致弄到设备上且路径尽量和编译机一致这样CTest 配置不容易乱。只推测试程序至少要把tiny_aes_test及其依赖静态链上则相对简单能在设备上跑起来。ctest与HPKCHECK相同思路设备上若装了lycium-citools可把PATH配上cmake等文中/usr/CIusr/bin为示例。./tiny_aes_test直接跑上游自测退出码 0 表示全过。「无需 chmod x」OpenHarmony 侧常见约定与 Linux 桌面习惯略有不同若你环境仍报权限再按现场策略处理。「参考」在说什么上游仓库算法、issue、Unlicense全文等。lycium 模板官方HPKBUILD/HPKCHECK空模板适合对比「最小长什么样」。若要开源合规清单应看同目录README.OpenSource解读见docs/README_OpenSource解读.md。和仓库里其它文档怎么分工文件更适合谁、干什么README_zh.md使用者 / 集成方快速知道产物路径、编译命令、上哪测。HPKBUILD维护适配的人改下载地址、CMake、安装路径、打包。HPKCHECKCI / 设备脚本自动跑 ctest、写 log。docs/HPKBUILD解读.md想搞懂为什么prepare要重写 CMake、build参数从哪来。README.OpenSource合规许可证、版本、Owner、URL。总结README_zh.md是中文入口文档简介交代上游与适配改动产物与用法给路径和链接行依赖说明不拖别的 HPK编译一条命令测试强调必须上 OHOS 设备及ctest / tiny_aes_test两种方式。读的时候记住两个名字lycium 包名AESvs上游tiny-AES-c记住一条路径规律$LYCIUM_ROOT/usr/AES/$ARCH/{lib,include,bin}。维护时改pkgver/ 目录结构 / 测试方式要同时改README_zh.md、HPKBUILD、HPKCHECK、README.OpenSource避免文档与脚本脱节。若你希望README 正文本身再扩写例如加「鸿蒙 PC 签名示例」或「HAP 集成链接示例」可以在README_zh.md里加小节本文解读类文档再跟一节「扩展阅读」指向即可。实战案例如何编写高质量的 README_zh.md案例一新增功能说明假设你为 AES 库添加了新的加密模式需要在 README 中说明## 新增功能 ### GCM 模式支持 本适配在 tiny-AES-c 基础上新增了 GCM (Galois/Counter Mode) 支持 \\\c #include aes.h // 使用 GCM 模式加密 AES_GCM_encrypt(plaintext, len, key, iv, ciphertext, tag); \\\ **注意** GCM 模式需要额外的 16 字节空间存储认证标签。案例二添加性能数据## 性能测试 在 OpenHarmony 设备上的性能测试结果 | 架构 | 加密速度 (MB/s) | 解密速度 (MB/s) | | ---- | --------------- | --------------- | | arm64-v8a | 120 | 118 | | armeabi-v7a | 85 | 83 | 测试环境 - 设备OpenHarmony 4.0 - 数据块大小4KB - 模式AES-128-CBC案例三添加故障排查## 常见问题 ### Q: 链接时找不到 libtiny-aes.a **A:** 检查以下几点 1. 确认已执行 ./build.sh AES 2. 检查库文件路径ls $LYCIUM_ROOT/usr/AES/arm64-v8a/lib/ 3. 确认链接参数-L$LYCIUM_ROOT/usr/AES/arm64-v8a/lib -ltiny-aes ### Q: 运行测试时提示权限不足 **A:** OpenHarmony 设备上可能需要 \\\bash chmod x tiny_aes_test ./tiny_aes_test \\\README_zh.md 结构最佳实践推荐结构# 库名上游名OpenHarmony 适配说明 ## 简介 - 上游来源 - 功能说明 - 适配改动 ## 产物与用法 - 文件路径表 - 链接示例 - API 使用示例 ## 依赖说明 - 构建依赖 - 运行时依赖 ## 编译 - 构建命令 - 环境要求 ## 测试 - 测试方法 - 测试环境 ## 示例代码可选 - 基础示例 - 高级示例 ## 性能数据可选 - 基准测试结果 ## 常见问题可选 - FAQ ## 参考 - 上游链接 - 相关文档写作原则简洁明了每段话控制在 3-5 行结构清晰使用标题和列表示例完整代码示例可直接运行版本明确说明适用的版本范围与其他文档的配合文档分工矩阵文档目标读者主要内容更新频率README_zh.md使用者快速上手版本更新时HPKBUILD维护者构建逻辑构建改动时HPKCHECK测试人员测试逻辑测试改动时docs/*.md深入学习者详细解读按需更新更新同步检查清单当修改README_zh.md时检查是否需要同步更新HPKBUILD中的版本号README.OpenSource中的版本号hnp.json中的版本号文档中的路径引用示例代码的正确性常见错误与修正错误一路径不一致错误示例产物位于/usr/AES/arm64-v8a/lib/问题使用了绝对路径不同机器上路径不同。修正产物位于$LYCIUM_ROOT/usr/AES/$ARCH/lib/错误二版本号遗漏错误示例基于 tiny-AES-c 开发问题未说明具体版本。修正基于 tiny-AES-c v1.0.0 开发错误三缺少环境说明错误示例执行 ./build.sh AES 即可编译问题未说明前置条件。修正前置条件 - 已安装 OpenHarmony SDK - 已设置 OHOS_SDK 环境变量 执行 ./build.sh AES 即可编译国际化考虑中英文对照如果需要同时维护中英文 READMEREADME_zh.md (中文) README.md (英文)同步策略先更新主要语言的文档再翻译到另一语言使用相同的结构和章节名术语对照表中文英文交叉编译cross-compilation静态库static library动态库shared library / dynamic library头文件header file链接link验证与测试验证 README 内容# 检查链接是否有效grep-o\[.*\](.*)README_zh.md|whilereadlink;dourl$(echo$link|grep-ohttp[^)]*) if [ -n $url ]; then curl -sI $url | head -1 fi done # 检查代码块语法 grep README_zh.md | wc -l # 应为偶数 # 检查标题层级 grep ^# README_zh.md测试示例代码# 提取并测试 README 中的示例代码# 1. 手动复制示例代码# 2. 在测试环境中运行# 3. 验证输出是否符合描述扩展阅读Markdown 最佳实践使用相对路径引用本地文件代码块指定语言以启用语法高亮表格保持简洁复杂内容用列表适当使用粗体强调关键信息文档维护工具markdownlintMarkdown 语法检查markdown-toc自动生成目录doctoc目录生成工具若你希望README 正文本身再扩写例如加「鸿蒙 PC 签名示例」或「HAP 集成链接示例」可以在README_zh.md里加小节本文解读类文档再跟一节「扩展阅读」指向即可。相关文档docs 索引与体例说明 · build_sh_AES命令执行流程详解.md · HPKCHECK 文件执行流程详解.md