读懂 `hnp.json`：鸿蒙PC 三方库打包时的这张「小配置」

读懂hnp.json鸿蒙PC 三方库打包时的这张「小配置」欢迎大家加入鸿蒙PC开发者社区前言在lycium适配 OpenHarmony / 鸿蒙三方库时有些仓库根目录会放一个hnp.json。它只有几行看起来像普通 JSON作用却和打包、分发有关告诉工具链常见是hnpcli——这是一份 HNP 相关配置里面写着组件叫什么、版本多少以及可选的安装规则。本文以本仓库thirdparty/AES/hnp.json为例逐个字段说明含义并说明它和HPKBUILD里archive()是怎么配合的。读完你可以自己判断要不要维护这个文件、升级版本时要改哪里。hnp.json在本仓库里长什么样当前内容如下便于对照与仓库文件一致{type:hnp-config,name:tiny-AES-c,version:1.0.0,install:{}}下面按字段解释最后再说明install为什么是空对象。每个字段代表什么字段通俗含义本仓库示例说明type配置文件的类型标识hnp-config固定含义这是 HNP 打包用的配置文件。工具如hnpcli读到这个值就知道要按「HNP 配置」来解析而不是别的 JSON。不要改成随意字符串否则工具可能不认。name组件 / 包的显示名称tiny-AES-c一般与上游库名一致方便在产物、清单里识别「这是哪套库」。注意lycium 的pkgname是AES目录名而这里name更偏向产品/上游名称两者可以不同各司其职。version组件版本号1.0.0建议与HPKBUILD里的pkgver、上游tag如v1.0.0保持一致。升级源码版本时记得同步改这里避免「包里写的是 1.0.0实际已是别的版本」这类混乱。install安装规则拷贝路径、权限等{}空对象表示不在 JSON 里写复杂安装映射而是依赖package()已经放好的目录结构本库为lib/、include/、bin/。若平台或hnpcli要求声明额外规则可在此按官方文档扩展本库当前保持默认即可。一句话type说「这是什么配置文件」name/version说「是谁、哪一版」install说「怎么装」——本库用空对象表示走默认目录布局。它和HPKBUILD的archive()是什么关系构建流程里package()会把libtiny-aes.a、aes.h、tiny_aes_test放进$LYCIUM_ROOT/usr/AES/$ARCH/下的标准子目录。之后若定义了archive()本仓库已定义会做几件事与理解hnp.json相关的部分若thirdparty/AES/hnp.json存在会先复制到usr/AES/$ARCH/根目录与lib、include同级再打压缩包或供hnpcli pack使用。hnpcli通常从$HNP_TOOL或$OHOS_SDK/toolchains/hnpcli查找若本机没有可执行文件脚本会跳过 pack只记日志不强制失败。因此hnp.json不是给 C 编译器看的而是给打包 / 分发链路用的没有跑archive()或没有hnpcli时你仍然可以正常交叉编译和安装到usr/...只是不会生成 HNP 侧产物。维护时容易忽略的点version与pkgver/hnp.json/ 文档建议一起改避免版本漂移。hnp.json必须与HPKBUILD同目录复制到安装目录时应用${PWD}/hnp.json避免相对路径写错例如误用../hnp.json。若团队完全不使用 HNP 打包可以保留最小hnp.json以备将来接入或在流程上明确「不执行archive()」以项目规范为准。总结hnp.json是HNP 场景下的轻量配置核心是type固定为 hnp-config、name组件名、version版本、install安装规则本库为空表示默认。它与lycium 的archive()、hnpcli pack配合服务于产物打包与分发不参与编译aes.c本身。日常升级上游或发版时优先核对version是否与HPKBUILD一致再根据平台文档决定是否扩展install。如需结合鸿蒙PC tiny-AES-c三方库适配实践.md里的「6.1 hnp.json」小节可与本文对照阅读实践文档偏流程步骤本文偏字段语义与维护。实战案例如何修改 hnp.json场景一升级上游版本假设上游 tiny-AES-c 发布了 v1.1.0你需要更新适配{type:hnp-config,name:tiny-AES-c,version:1.1.0,// 从 1.0.0 改为 1.1.0install:{}}同步修改清单HPKBUILD中的pkgver1.1.0README.OpenSource中的Version NumberSHA512SUM文件用新 tarball 重新计算相关文档中的版本号引用场景二添加安装规则如果需要在 HNP 包中包含额外的配置文件或示例{type:hnp-config,name:tiny-AES-c,version:1.0.0,install:{include:[aes.h,aes_config.h],lib:[libtiny-aes.a],bin:[tiny_aes_test],extra:{examples:share/tiny-AES-c/examples}}}注意添加install规则后需要验证hnpcli pack是否能正确处理。场景三多组件打包如果一个仓库包含多个独立组件如 AES DES{type:hnp-config,name:tiny-AES-c,version:1.0.0,components:{aes:{name:tiny-aes,files:[libtiny-aes.a,aes.h]},des:{name:tiny-des,files:[libtiny-des.a,des.h]}},install:{}}常见问题与解决方案Q1: hnp.json 缺失会怎样A:如果thirdparty/AES/hnp.json不存在构建阶段build()和package()正常执行产物安装到usr/AES/$ARCH/打包阶段archive()中复制hnp.json会失败但脚本会跳过错误继续执行HNP 打包hnpcli pack无法执行因为没有配置文件建议即使暂时不用 HNP 打包也保留最小化的hnp.json。Q2: type 字段可以自定义吗A:不建议。type: hnp-config是工具链识别配置文件类型的关键标识。如果改成其他值hnpcli可能无法识别并拒绝处理其他依赖 HNP 规范的工具也会失效Q3: name 和 pkgname 为什么不同A:它们服务于不同目的pkgname(HPKBUILD)lycium 内部标识用于目录名、构建命令、依赖解析name(hnp.json)HNP 包的显示名称面向最终用户通常与上游项目名一致例如pkgname AES→ 构建命令./build.sh AESname tiny-AES-c→ HNP 包名tiny-AES-c-1.0.0.hnpQ4: version 不一致会怎样A:如果hnp.json的 version 与HPKBUILD的pkgver不一致构建产物使用pkgver版本的源码HNP 包元数据使用hnp.json的 version结果包名与内容不匹配用户安装后可能遇到版本混乱最佳实践在 CI/CD 中添加检查脚本确保两者一致。与其他配置文件的关系与 HPKBUILD 的配合HPKBUILD (构建逻辑) ↓ package() (安装产物到 usr/) ↓ archive() (复制 hnp.json 打包) ↓ hnpcli pack (读取 hnp.json 生成 HNP 包)关键点HPKBUILD决定构建什么hnp.json决定如何打包和分发两者通过archive()函数连接与 README.OpenSource 的对应字段hnp.jsonREADME.OpenSource名称nameName(第一条)版本versionVersion Number协议无License说明hnp.json不包含许可证信息因为许可证已在源码和产物中体现HNP 包管理器通常有独立的许可证数据库避免重复维护验证与测试验证 hnp.json 格式# 使用 jq 验证 JSON 格式jq.hnp.json# 或使用 pythonpython-mjson.tool hnp.json测试 HNP 打包流程# 1. 构建库./build.sh AES# 2. 检查产物ls-llycium/usr/AES/arm64-v8a/# 3. 检查 hnp.json 是否被复制ls-llycium/usr/AES/arm64-v8a/hnp.json# 4. 手动测试 hnpcli如果可用hnpcli pack lycium/usr/AES/arm64-v8a/常见错误排查错误现象可能原因解决方法hnp.json not found文件不存在或路径错误检查archive()中的复制路径Invalid JSON格式错误缺少逗号、引号等使用jq或json.tool验证Unknown typetype字段值不正确改为hnp-confighnpcli: command not found工具未安装安装 HNP 工具链或跳过打包最佳实践总结1. 版本同步# 检查脚本示例#!/bin/bashpkgver$(grep^pkgverHPKBUILD|cut-d-f2)hnp_ver$(jq-r.version hnp.json)if[$pkgver!$hnp_ver];thenechoERROR: Version mismatch!echo HPKBUILD:$pkgverecho hnp.json:$hnp_verexit1fi2. 最小化原则如果不需要特殊安装规则保持install为空对象{type:hnp-config,name:tiny-AES-c,version:1.0.0,install:{}}3. 文档化在README_zh.md中说明 HNP 包的使用方式## HNP 包使用 本库提供 HNP 格式的预编译包可通过以下方式安装 \\\bash hnpcli install tiny-AES-c-1.0.0.hnp \\\ 安装后头文件和库文件位于标准路径。扩展阅读HNP 包格式规范HNP (HarmonyOS Native Package) 是鸿蒙生态的原生包格式特点支持多架构arm64-v8a, armeabi-v7a包含元数据名称、版本、依赖支持安装脚本和卸载脚本与 OpenHarmony 包管理系统集成相关工具hnpcliHNP 包管理命令行工具hnp-buildHNP 包构建工具hnp-registryHNP 包仓库服务