企业官网建设流程全解析

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

目录

• 前言
• 文件概览
• 逐字段详解
• JSON 格式规范
• 与构建系统的关联
• 开源合规性分析
• 常见问题与改进建议
• 最佳实践

欢迎大家加入鸿蒙PC开发者社区

项目路径

前言

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

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

文件概览

原始文件内容

[{"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."}]

文件结构

逐字段详解

1. Name — 组件名称

"Name": "sha"

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

说明：

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

与其他文件的对应关系：

命名规范：

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

2. License — 许可证标识

"License": ""

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

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

分析：

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

建议值：

"License":"BSD-2-Clause"

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

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

许可证对项目的影响：

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

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

"License File": ""

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

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

分析：

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

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

"License File":"LICENSE"

或

"License File":"LICENSE.txt"

许可证文件的作用：

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

4. Version Number — 版本号

"Version Number": "3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb"

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

分析：

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

commit hash 作为版本号的特点：

与 HPKBUILD 的对应关系：

# HPKBUILDpkgver=3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb

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

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

如何验证此版本号：

# 克隆仓库gitclone https://github.com/BrianGladman/sha.git# 查看该提交cdshagitshow 3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb# 切换到该版本gitreset--hard3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb

5. Owner — 维护者

"Owner": "jianguo@nutpi.net"

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

分析：

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

Owner 的职责：

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

与 HPKBUILD 的对应关系：

# 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 的对应关系：

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

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

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

Upstream URL 的作用：

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

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 算法本身。更精确的描述应强调这是一个加密库实现

建议的改进描述：

"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 数组格式，支持声明多个开源组件：

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

为什么使用数组？

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

字段汇总

格式验证

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

# 使用 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 的字段映射

在构建流程中的位置

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

开源合规性分析

合规检查清单

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

许可证合规风险

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

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

风险等级：中等

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

合规修复建议

[{"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 是唯一能精确标识源码版本的方式
• 这在开源社区中是常见做法，尤其是对于未正式发布版本的库

优缺点：

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

区别：

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

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

验证步骤：

# 1. 验证上游仓库可访问gitls-remote https://github.com/BrianGladman/sha.git# 2. 验证 commit hash 存在gitclone https://github.com/BrianGladman/sha.gitcdshagitcat-file-t3ee0d88fc4f629b2e084f1b4cbf22cd3597542fb# 应输出: commit# 3. 验证许可证文件存在lsLICENSE* COPYING*2>/dev/null# 4. 验证 JSON 格式python3-c"import json; data=json.load(open('../README.OpenSource')); print(data)"

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

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

[{"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：

{"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 许可证标识符，而非自定义名称：

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

3. 与 HPKBUILD 保持一致

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

4. 版本号可追溯

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

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

5. 定期审查更新

建立定期审查机制：

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

6. 自动化验证

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

#!/bin/bash# validate_opensource.sh - 验证 README.OpenSourceecho"=== 验证 README.OpenSource ==="# 1. JSON 格式验证if!python3-c"import json; json.load(open('README.OpenSource'))"2>/dev/null;thenecho"ERROR: JSON 格式无效"exit1fi# 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"];thenpkgname=$(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)') "fiecho"验证完成"

总结

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

核心要点

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

当前问题

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

改进优先级

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

相关文档：

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