当前位置： 首页 > news >正文

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

news 2026/7/27 10:42:38

鸿蒙三方库适配读懂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、安装路径、打包。
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 ## 参考 - 上游链接 - 相关文档

写作原则

  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|whilereadlink;dourl=$(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
http://www.cnnetsun.cn/news/1858532.html

相关文章：

  • 终极指南：3步彻底解决Windows C盘爆红问题，这个开源工具真的免费！
  • Kubernetes Operator 框架入门
  • 55项核心技术重构炉石体验：HsMod开源插件深度解析
  • 抖音直播间数据监控：5分钟搭建实时弹幕采集系统
  • 深求·墨鉴（DeepSeek-OCR-2）效果实测：复杂表单结构还原度98%展示
  • StructBERT文本相似度模型Web服务开发：从零搭建RESTful API
  • 高效管理Flash内容：CefFlashBrowser深度应用解析
  • 新手必看！PyTorch通用开发镜像保姆级教程：从零到一快速上手
  • Qwen2.5-7B-Instruct效果展示：vLLM推理加速实测，Chainlit界面流畅对话
  • Intv_ai_mk11 与卷积神经网络结合：探索多模态对话理解新范式
  • .NET+AI | Agent Skills | Inline Skill 如此轻快，带你体验 Agent Skills 的魅力
  • Z-Image-Turbo新手教程：无需代码，用Gradio界面轻松玩转AI绘画
  • 终极指南：如何轻松解密网易云NCM音乐文件实现全设备播放
  • CYBER-VISION零号协议Win11系统优化与定制指南
  • AI写教材全流程揭秘，低查重工具带你开启高效编写之旅！
  • Pixel Language Portal保姆级教程：从Docker拉取到16-bit HUD状态栏调试的完整流程
  • 51单片机入门实战：独立按键控制数码管0~9循环显示（附Proteus仿真文件）
  • DamoFD-0.5G与传统算法在低光照人脸检测中的对比研究
  • QT开发加速：Qwen2.5-32B-Instruct界面生成器
  • intv_ai_mk11效果惊艳展示：高质量代码生成+精准概念解释+多轮追问实录
  • Java的Atomic类：无锁编程的CAS操作原理
  • GVHMR：基于重力-视图坐标与RoPE Transformer的长序列人体运动恢复解析
  • Hunyuan 1.8B如何快速上手？ModelScope下载部署保姆级教程
  • ORA-12445报错：无法更改列隐藏属性，Oracle故障修复与远程处理，网友推荐解决方案
  • 从零开始打造你的AI军团——OpenClaw Skills保姆级入门指南
  • 基于 Vue + TS + Ant Design Vue 实现精细化菜单按钮权限授权组件险
  • Pixel Aurora Engine 系统清理优化：释放 C 盘空间并保持引擎高效运行
  • RTMPose模型在RK3588上的性能优化实战：从ONNX到RKNN的完整调优过程
  • FPGA入门200例(25)：无源蜂鸣器驱动原理：通过分频器演奏一首《孤勇者》
  • GLM-4-9B-Chat-1M实操手册：Chainlit中嵌入代码执行结果、图表与交互式组件