【鸿蒙 PC三方库构建系统】README.OpenSource 文件深度解读

前言

README.OpenSource 是 OpenHarmony 三方库适配中的开源合规声明文件。它以结构化的 JSON 格式记录了所引入的开源组件的名称、许可证、版本、维护者和上游来源等关键信息，是开源治理和合规审计的基础数据源。

本文将对 SHA 库的 README.OpenSource 文件进行逐字段深度解读，并分析其在整个构建和合规体系中的作用。

文件概览

原始文件内容

json 复制代码

[
    {
        "Name": "sha",
        "License": "",
        "License File": "",
        "Version Number": "3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb",
        "Owner": "jianguo@nutpi.net",
        "Upstream URL": "https://github.com/BrianGladman/sha",
        "Description": "sha is an algorithm that calculates a fixed length string (also known as message digest) corresponding to a digital message."
    }
]

文件结构

属性	说明
格式	JSON 数组
元素类型	对象（每个对象代表一个开源组件）
元素数量	1（SHA 库仅引入一个上游组件）
编码	UTF-8
换行符	`\r\n`（CRLF，Windows 风格）

逐字段详解

1. Name --- 组件名称

复制代码

"Name": "sha"

含义：开源组件的名称标识符。

说明：

值为 "sha"，与 HPKBUILD 中的 pkgname=sha 保持一致
该名称在整个 Lycium 构建系统中作为包的唯一标识
用于目录命名（如 usr/sha/）、产物命名（如 sha.hnp）和依赖引用

与其他文件的对应关系：

文件	对应字段	值
HPKBUILD	`pkgname`	`sha`
hnp.json	`name`	`sha`
README.OpenSource	`Name`	`sha`

命名规范：

使用小写字母
与上游仓库名称保持一致
简洁、无歧义

2. License --- 许可证标识

复制代码

"License": ""

含义：开源组件所采用的开源许可证名称或标识符。

当前状态 ：空值 --- 这是一个需要关注的问题。

分析：

SHA 库（BrianGladman/sha）的上游仓库实际上采用的是 BSD 许可证 （或其变体）。BrianGladman 的加密库通常使用 BSD 2-Clause 或类似的宽松许可证。HPKBUILD 中有 license=("the sha license") 的声明，但 README.OpenSource 中此字段为空，存在信息缺失。

建议值：

json 复制代码

"License": "BSD-2-Clause"

或根据实际许可证文件确定准确的 SPDX 标识符。

常见开源许可证标识符（SPDX 格式）：

许可证	SPDX 标识符	类型
MIT	`MIT`	宽松
BSD 2-Clause	`BSD-2-Clause`	宽松
BSD 3-Clause	`BSD-3-Clause`	宽松
Apache 2.0	`Apache-2.0`	宽松
GPL 2.0	`GPL-2.0-only`	强传染性
GPL 3.0	`GPL-3.0-only`	强传染性
LGPL 2.1	`LGPL-2.1-only`	弱传染性

许可证对项目的影响：

宽松许可证（MIT/BSD/Apache）：可自由使用、修改和分发，无传染性要求
强传染性许可证（GPL）：衍生作品必须以相同许可证开源
弱传染性许可证（LGPL）：动态链接不受传染，静态链接需注意

3. License File --- 许可证文件路径

复制代码

"License File": ""

含义：源码中许可证文本文件的相对路径。

当前状态 ：空值 --- 同样需要关注。

分析：

大多数开源项目会在仓库根目录下包含 LICENSE、LICENSE.txt 或 COPYING 等文件。此字段应指向该文件的相对路径，便于构建系统自动提取和打包许可证文本。

建议值（需确认上游仓库实际文件名）：

json 复制代码

"License File": "LICENSE"

或

json 复制代码

"License File": "LICENSE.txt"

许可证文件的作用：

合规要求：分发开源软件时必须包含原始许可证文本
自动打包：构建系统可自动将许可证文件复制到产物中
审计依据：合规审计时需要查看完整的许可证条款
法律保护：明确使用条件，避免法律纠纷

4. Version Number --- 版本号

复制代码

"Version Number": "3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb"

含义：所使用的开源组件的版本标识。

分析：

此值是一个 40 位 Git commit hash ，而非传统的语义化版本号（如 1.0.0）。这是因为 BrianGladman/sha 仓库没有使用 Git tag 或 release 来标记版本，因此采用 commit hash 来精确标识所使用的源码快照。

commit hash 作为版本号的特点：

特性	说明
精确性	唯一标识源码的某一确切状态
可追溯	可通过 `git show <hash>` 查看具体提交
可重现	确保每次构建基于完全相同的源码
不可读	无法直观判断版本先后关系
无语义	不包含 major/minor/patch 语义信息

与 HPKBUILD 的对应关系：

bash 复制代码

# HPKBUILD
pkgver=3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb

json 复制代码

// README.OpenSource
"Version Number": "3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb"

两者完全一致，确保了构建和声明的一致性。

如何验证此版本号：

bash 复制代码

# 克隆仓库
git clone https://github.com/BrianGladman/sha.git

# 查看该提交
cd sha
git show 3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb

# 切换到该版本
git reset --hard 3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb

5. Owner --- 维护者

复制代码

"Owner": "jianguo@nutpi.net"

含义：该三方库在 OpenHarmony 适配中的负责人/维护者联系方式。

分析：

值为邮箱地址 jianguo@nutpi.net
这是内部维护者，而非上游项目作者
上游项目作者是 Brian Gladman，但此字段记录的是负责 OpenHarmony 平台适配的维护者
当适配出现问题时，可通过此邮箱联系负责人

Owner 的职责：

适配维护：负责该库在 OpenHarmony 平台的构建和适配
版本更新：跟踪上游版本变化，及时更新适配
问题处理：处理构建失败、运行时错误等问题
补丁管理 ：维护 sha_ohos.patch 等适配补丁
合规管理：确保许可证和声明信息准确

与 HPKBUILD 的对应关系：

bash 复制代码

# HPKBUILD 中的维护者信息
# Maintainer: huangminzhong <huangminzhong2@huawei.com>

注意：HPKBUILD 中的 Maintainer 与 README.OpenSource 中的 Owner 可能不同，前者是构建脚本的维护者，后者是包的整体负责人。

6. Upstream URL --- 上游仓库地址

复制代码

"Upstream URL": "https://github.com/BrianGladman/sha"

含义：开源组件的原始上游仓库 URL。

分析：

指向 GitHub 上的 BrianGladman/sha 仓库
这是源码的权威来源
与 HPKBUILD 中的 source 变量对应

与 HPKBUILD 的对应关系：

bash 复制代码

# HPKBUILD
source="https://github.com/BrianGladman/sha.git"
url="https://github.com/BrianGladman/sha"

json 复制代码

// README.OpenSource
"Upstream URL": "https://github.com/BrianGladman/sha"

注意细微差异：HPKBUILD 的 source 末尾有 .git（用于 git clone），而 Upstream URL 没有（用于人类浏览）。

Upstream URL 的作用：

源码获取：构建系统从此地址下载源码
问题追踪：向上游报告 bug 或查看 issue
版本跟踪：监控上游更新，及时同步
代码审查：查看原始代码和修改历史
合规审计：验证源码来源的合法性

7. Description --- 组件描述

复制代码

"Description": "sha is an algorithm that calculates a fixed length string (also known as message digest) corresponding to a digital message."

含义：对开源组件功能的简要描述。

分析：

该描述说明了 SHA 算法的核心功能：将任意长度的数字消息映射为固定长度的字符串（消息摘要）。

描述的准确性评估：

基本正确：SHA 确实是一种消息摘要算法
略有偏差 ：严格来说，此仓库提供的是 SHA 算法的实现库，而非 SHA 算法本身。更精确的描述应强调这是一个加密库实现

建议的改进描述：

json 复制代码

"Description": "A C library implementing SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 hash algorithms, HMAC, and PBKDF2 key derivation functions."

改进理由：

明确指出是 C 语言库实现
列出具体支持的算法（SHA-1/224/256/384/512）
包含 HMAC 和 PBKDF2 功能
更具信息量，便于使用者快速了解库的能力

JSON 格式规范

数组结构

README.OpenSource 使用 JSON 数组格式，支持声明多个开源组件：

json 复制代码

[
    {
        "Name": "组件1",
        ...
    },
    {
        "Name": "组件2",
        ...
    }
]

为什么使用数组？

一个三方包可能引入多个开源组件
例如：一个包可能同时包含 SHA 库和其依赖的另一个库
数组格式便于统一管理和扩展

字段汇总

字段	类型	必填	说明
`Name`	string	是	组件名称，与 pkgname 一致
`License`	string	是	SPDX 许可证标识符
`License File`	string	是	许可证文件相对路径
`Version Number`	string	是	版本号或 commit hash
`Owner`	string	是	维护者邮箱
`Upstream URL`	string	是	上游仓库地址
`Description`	string	是	组件功能描述

格式验证

可使用以下命令验证 JSON 格式的正确性：

bash 复制代码

# 使用 python 验证
python3 -c "import json; json.load(open('README.OpenSource')); print('Valid JSON')"

# 使用 jq 验证
jq . README.OpenSource

与构建系统的关联

数据流向图

复制代码

┌─────────────────────────────────────────────────────────────┐
│              README.OpenSource                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ Name: sha                                          │    │
│  │ License: (空)                                       │    │
│  │ Version Number: 3ee0d88...                          │    │
│  │ Owner: jianguo@nutpi.net                            │    │
│  │ Upstream URL: https://github.com/BrianGladman/sha   │    │
│  │ Description: sha is an algorithm...                 │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
              │                    │                    │
              ▼                    ▼                    ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│    HPKBUILD      │ │   合规审计系统   │ │   包管理仓库    │
│                  │ │                  │ │                  │
│ pkgname=sha      │ │ 许可证检查      │ │ 组件注册        │
│ pkgver=3ee0d88.. │ │ 版本追踪        │ │ 依赖解析        │
│ source=github... │ │ 来源验证        │ │ 信息展示        │
│ license=...      │ │ 合规报告        │ │                  │
└──────────────────┘ └──────────────────┘ └──────────────────┘

与 HPKBUILD 的字段映射

README.OpenSource	HPKBUILD	映射关系
`Name`	`pkgname`	完全一致
`License`	`license`	语义对应，格式可能不同
`Version Number`	`pkgver`	完全一致
`Upstream URL`	`source` / `url`	`source` 带 `.git` 后缀
`Owner`	`Maintainer`	可能不同（包负责人 vs 脚本维护者）
`Description`	`pkgdesc`	语义对应（HPKBUILD 中为空）

在构建流程中的位置

复制代码

┌─────────────────────────────────────────────────────────────┐
│                    构建流程                                  │
└─────────────────────────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────────┐
│  1. 读取 README.OpenSource                                  │
│     - 验证 JSON 格式                                       │
│     - 提取组件信息                                         │
│     - 合规性预检查                                         │
└─────────────────────────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────────┐
│  2. 读取 HPKBUILD                                          │
│     - 一致性校验（Name vs pkgname 等）                     │
│     - 加载构建配置                                         │
└─────────────────────────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────────┐
│  3. 执行构建（prepare → build → package → archive）         │
└─────────────────────────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────────┐
│  4. 合规检查                                                │
│     - 许可证文件是否包含在产物中                            │
│     - 声明信息是否完整                                     │
│     - 生成合规报告                                         │
└─────────────────────────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────────┐
│  5. 发布包                                                  │
│     - 上传到包管理仓库                                     │
│     - 关联开源声明信息                                     │
└─────────────────────────────────────────────────────────────┘

开源合规性分析

合规检查清单

对当前 README.OpenSource 的合规性评估：

检查项	状态	说明
Name 字段完整	通过	值为 `"sha"`
License 字段完整	未通过	值为空，需补充
License File 字段完整	未通过	值为空，需补充
Version Number 字段完整	通过	有明确的 commit hash
Owner 字段完整	通过	有维护者邮箱
Upstream URL 字段完整	通过	有上游仓库地址
Description 字段完整	通过	有功能描述
JSON 格式正确	通过	有效的 JSON

许可证合规风险

当前风险 ：License 和 License File 字段为空，存在以下合规风险：

分发合规：分发开源软件时，必须遵守其许可证条款。缺少许可证信息可能导致违规分发
传染性风险：如果上游采用 GPL 等传染性许可证，可能影响整个项目的许可证选择
审计障碍：合规审计无法通过，可能影响产品发布
法律风险：未经许可使用开源软件可能面临法律诉讼

风险等级 ：中等

SHA 库（BrianGladman）实际采用宽松许可证（BSD 类），传染性风险低
但缺少声明本身是合规流程的缺陷

合规修复建议

json 复制代码

[
    {
        "Name": "sha",
        "License": "BSD-2-Clause",
        "License File": "LICENSE",
        "Version Number": "3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb",
        "Owner": "jianguo@nutpi.net",
        "Upstream URL": "https://github.com/BrianGladman/sha",
        "Description": "A C library implementing SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 hash algorithms, HMAC, and PBKDF2 key derivation functions."
    }
]

常见问题与改进建议

Q1: 为什么 License 和 License File 字段为空？

可能原因：

适配初期遗漏，未及时补充
上游仓库的许可证标识不够明确
构建系统未强制要求这两个字段

影响：

合规审计不通过
无法自动提取许可证文件
分发时可能缺少许可证声明

建议：尽快确认上游许可证并补充完整。

Q2: 为什么使用 commit hash 而不是版本号？

原因：

BrianGladman/sha 仓库没有发布正式的版本 tag
使用 commit hash 是唯一能精确标识源码版本的方式
这在开源社区中是常见做法，尤其是对于未正式发布版本的库

优缺点：

方面	commit hash	语义化版本
精确性	极高	高
可读性	差	好
语义信息	无	有（major/minor/patch）
排序比较	不可直接比较	可直接比较
适用场景	无 tag 的仓库	有正式发布的仓库

Q3: Owner 和上游作者是什么关系？

区别：

角色	身份	职责
Owner（jianguo@nutpi.net）	OpenHarmony 适配维护者	平台适配、构建维护、问题处理
上游作者（Brian Gladman）	原始库开发者	算法实现、功能开发、上游维护

Owner 是内部角色，负责确保该库在 OpenHarmony 平台上正常工作；上游作者是外部角色，负责库本身的功能开发。

Q4: 如何验证 README.OpenSource 信息的准确性？

验证步骤：

bash 复制代码

# 1. 验证上游仓库可访问
git ls-remote https://github.com/BrianGladman/sha.git

# 2. 验证 commit hash 存在
git clone https://github.com/BrianGladman/sha.git
cd sha
git cat-file -t 3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb
# 应输出: commit

# 3. 验证许可证文件存在
ls LICENSE* COPYING* 2>/dev/null

# 4. 验证 JSON 格式
python3 -c "import json; data=json.load(open('../README.OpenSource')); print(data)"

Q5: 多组件场景如何声明？

如果一个包引入了多个开源组件，按如下格式声明：

json 复制代码

[
    {
        "Name": "sha",
        "License": "BSD-2-Clause",
        "License File": "LICENSE",
        "Version Number": "3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb",
        "Owner": "jianguo@nutpi.net",
        "Upstream URL": "https://github.com/BrianGladman/sha",
        "Description": "SHA hash algorithm library"
    },
    {
        "Name": "another-dep",
        "License": "MIT",
        "License File": "dep/LICENSE",
        "Version Number": "1.2.3",
        "Owner": "maintainer@example.com",
        "Upstream URL": "https://github.com/example/dep",
        "Description": "Another dependency"
    }
]

最佳实践

1. 信息完整性

确保所有字段都有有效值，特别是 License 和 License File：

json 复制代码

{
    "Name": "sha",
    "License": "BSD-2-Clause",        // 不要留空
    "License File": "LICENSE",         // 不要留空
    "Version Number": "3ee0d88...",
    "Owner": "jianguo@nutpi.net",
    "Upstream URL": "https://github.com/BrianGladman/sha",
    "Description": "..."
}

2. 许可证标识标准化

使用 SPDX 许可证标识符，而非自定义名称：

json 复制代码

// 推荐
"License": "BSD-2-Clause"

// 不推荐
"License": "the sha license"
"License": "BSD"
"License": "BSD 2-Clause License"

3. 与 HPKBUILD 保持一致

确保关键字段在两个文件间保持一致：

检查项	验证方法
Name == pkgname	`sha` == `sha`
Version Number == pkgver	`3ee0d88...` == `3ee0d88...`
Upstream URL 与 source 对应	去掉 `.git` 后缀应一致

4. 版本号可追溯

确保 Version Number 能精确追溯到源码状态：

优先使用上游的 tag 或 release 版本号
如无正式版本，使用 commit hash
避免使用分支名（如 main、master），因为分支指向会变化

5. 定期审查更新

建立定期审查机制：

跟踪上游版本更新
及时同步安全补丁
更新 Version Number 和对应补丁
验证新版本的合规性

6. 自动化验证

在构建流程中加入自动化验证：

bash 复制代码

#!/bin/bash
# validate_opensource.sh - 验证 README.OpenSource

echo "=== 验证 README.OpenSource ==="

# 1. JSON 格式验证
if ! python3 -c "import json; json.load(open('README.OpenSource'))" 2>/dev/null; then
    echo "ERROR: JSON 格式无效"
    exit 1
fi

# 2. 必填字段检查
python3 -c "
import json
data = json.load(open('README.OpenSource'))
required = ['Name', 'License', 'License File', 'Version Number', 'Owner', 'Upstream URL', 'Description']
for i, item in enumerate(data):
    for field in required:
        if not item.get(field):
            print(f'WARNING: Item {i}: {field} 为空')
"

# 3. 与 HPKBUILD 一致性检查
if [ -f "HPKBUILD" ]; then
    pkgname=$(grep '^pkgname=' HPKBUILD | cut -d= -f2)
    pkgver=$(grep '^pkgver=' HPKBUILD | cut -d= -f2)
    python3 -c "
import json
data = json.load(open('README.OpenSource'))
item = data[0]
if item['Name'] != '$pkgname':
    print(f'ERROR: Name ({item[\"Name\"]}) != pkgname ($pkgname)')
if item['Version Number'] != '$pkgver':
    print(f'ERROR: Version ({item[\"Version Number\"]}) != pkgver ($pkgver)')
"
fi

echo "验证完成"

总结

README.OpenSource 是 OpenHarmony 三方库适配中不可或缺的合规声明文件。通过对 SHA 库的 README.OpenSource 进行深度解读，我们得出以下关键结论：

核心要点

结构化声明：以 JSON 数组格式记录开源组件信息，支持多组件声明
七个字段：Name、License、License File、Version Number、Owner、Upstream URL、Description
与 HPKBUILD 对应：关键字段需保持一致，确保构建和声明同步
合规基础：是开源合规审计、许可证管理和依赖追踪的数据源

当前问题

License 字段为空，需补充 SPDX 标识符
License File 字段为空，需补充许可证文件路径
Description 可更精确，建议列出具体支持的算法

改进优先级

高：补充 License 和 License File 字段（合规必需）
中：改进 Description 的准确性
低：考虑添加更多元数据（如安全漏洞追踪 ID）

相关文档：

HPKBUILD 深度解读：理解 Version Number 与!pkgver 的一致性
hnp.json 解读：理解 Name 与 hnp.json name 的一致性
OAT.xml 与 SHA512SUM 解读：理解开源合规扫描与 README.OpenSource 的关系