鸿蒙三方库适配读懂 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 模板去哪看。

---

标题：AES（tiny-AES-c）OpenHarmony 适配说明

通俗理解：

• AES 是 lycium 里的名字（目录名、pkgname、./build.sh AES）。
• tiny-AES-c 是 GitHub 上的上游项目名。
  括号把两者绑在一起，避免读者以为「AES」是 OpenSSL 那种全家桶，这里只是 tiny-AES-c 的 OHOS 适配包。

---

「简介」在说什么？

原文三段信息可以拆成：

1. 溯源
   上游是 kokke/tiny-AES-c，版本 v1.0.0。读者知道 issue、license、算法说明 要去上游仓库看。

2. 能力边界
   纯 C、默认 AES-128，模式 ECB / CBC / CTR。文档里提醒：AES192/AES256 要在 aes.h 里改宏，本适配 没有替你改 密钥长度——意思是 默认行为与上游一致，别误以为 OHOS 版自动开了 256。

3. 适配做了什么
   上游 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 设置）。$ARCH：armeabi-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 真机或模拟器 上跑。

原文给了两条路：

1. 整目录推送
   把 tiny-AES-c-1.0.0/$ARCH-build（和 HPKBUILD 里 builddir + arm64-v8a-build 这类目录 一致）弄到设备上，且 路径尽量和编译机一致，这样 CTest 配置 不容易乱。

2. 只推测试程序
   至少要把 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、安装路径、打包。
HPKCHECK	CI / 设备脚本：自动跑 ctest、写 log。
docs/HPKBUILD解读.md	想搞懂 为什么 prepare 要重写 CMake、build 参数从哪来。
README.OpenSource	合规：许可证、版本、Owner、URL。

---

总结

• README_zh.md 是 中文入口文档：简介交代上游与适配改动，产物与用法给路径和链接行，依赖说明不拖别的 HPK，编译一条命令，测试强调 必须上 OHOS 设备 及 ctest / tiny_aes_test 两种方式。
• 读的时候记住两个名字：lycium 包名 AES vs 上游 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

## 参考
- 上游链接
- 相关文档

写作原则

1. 简洁明了：每段话控制在 3-5 行
2. 结构清晰：使用标题和列表
3. 示例完整：代码示例可直接运行
4. 版本明确：说明适用的版本范围

---

与其他文档的配合

文档分工矩阵

文档	目标读者	主要内容	更新频率
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` 即可编译

---

国际化考虑

中英文对照

如果需要同时维护中英文 README：

README_zh.md  (中文)
README.md     (英文)

同步策略：

1. 先更新主要语言的文档
2. 再翻译到另一语言
3. 使用相同的结构和章节名

术语对照表

中文	英文
交叉编译	cross-compilation
静态库	static library
动态库	shared library / dynamic library
头文件	header file
链接	link

---

验证与测试

验证 README 内容

# 检查链接是否有效
grep -o '\[.*\](.*)' README_zh.md | while read link; do
    url=$(echo $link | grep -o 'http[^)]*')
    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 最佳实践

• 使用相对路径引用本地文件
• 代码块指定语言以启用语法高亮
• 表格保持简洁，复杂内容用列表
• 适当使用粗体强调关键信息

文档维护工具

• markdownlint：Markdown 语法检查
• markdown-toc：自动生成目录
• doctoc：目录生成工具

---

若你希望 README 正文本身再扩写（例如加「鸿蒙 PC 签名示例」或「HAP 集成链接示例」），可以在 README_zh.md 里加小节，本文解读类文档再跟一节 「扩展阅读」 指向即可。

---

相关文档

• docs 索引与体例说明 · build_sh_AES命令执行流程详解.md · HPKCHECK 文件执行流程详解.md