1# 开源软件 `README.OpenSource` 工具使用文档 2 3## 目录 4 5- 开源软件 `README.OpenSource` 工具使用文档 6 - 简介 7 - 功能概述 8 - 安装与环境配置 9 - 环境要求 10 - 安装步骤 11 - 使用指南 12 - 生成 `README.OpenSource` 文件 13 - 验证 `README.OpenSource` 文件 14 - 验证格式 15 - 验证内容 16 - 命令行参数 17 - 目录结构 18 - 工作流程概览 19 - 生成工具流程图 20 - 验证工具流程图 21 22## 简介 23 24本工具旨在为项目中的每个开源部件创建标准化的 `README.OpenSource` 文件，并提供验证这些文件格式和内容的功能。该工具仅使用 Python 标准库开发，易于安装和使用。通过合并生成和验证功能，用户可以使用单个脚本完成所有操作，并根据需要选择不同的功能场景。 25 26## 功能概述 27 28- 生成工具 ： 29 - 通过交互方式，用户输入开源部件的信息，支持多个部件的输入。 30 - 支持一对一、一对多、多对一的许可证和许可证文件关系配置。 31 - 支持可选的依赖项配置，以逗号分隔多个依赖。 32 - 生成符合规范的 `README.OpenSource` 文件，包含所有输入的部件信息。 33 34- 验证工具： 35 - **格式验证**：验证项目中所有 `README.OpenSource` 文件的格式，检查必需字段是否完整，JSON 格式是否正确。 36 - **内容验证**：验证以下内容： 37 - 对 `"Name"`、`"License"`、`"Version Number"`、`"Upstream URL"` 等字段与参考数据比对。 38 - 验证 `"License File"` 字段指向的文件是否存在。 39 - 验证 `"Dependencies"` 字段（若存在）是否为有效的字符串数组。 40 41## 安装与环境配置 42 43### 环境要求 44 45- **Python 版本**：Python 3.6 或更高版本 46- **操作系统**：跨平台，支持 Linux/Windows 47 48### 安装步骤 49 501. **克隆或下载项目代码** 51 52 ``` 53 git clone https://gitee.com/openharmony/developtools_integration_verification.git 54 cd tools/opensource_tools 55 ``` 56 572. **（可选）创建虚拟环境** 58 59 ``` 60 python -m venv venv 61 source venv/bin/activate # Linux/macOS 62 # 或 63 venv\Scripts\activate # Windows 64 ``` 65 663. **安装依赖** 67 68 由于该工具仅使用 Python 标准库，无需安装额外依赖。 69 70## 使用指南 71 72### 生成 `README.OpenSource` 文件 73 74运行 `generate_readme_opensource.py` 脚本，按照提示输入开源部件的信息。 75 76**步骤：** 77 781. **进入项目目录** 79 80 ``` 81 cd src 82 ``` 83 842. **运行生成脚本** 85 86 ``` 87 python generate_readme_opensource.py 88 ``` 89 903. **按照提示输入信息** 91 - 输入输出目录（默认为当前目录） 92 - 依次输入每个部件的详细信息： 93 - Name：组件名称 94 - Version Number：版本号 95 - Owner：维护者 96 - Upstream URL：上游地址 97 - Description：描述信息 98 - License：许可证（多个许可证用分号分隔） 99 - License File：许可证文件路径（多个文件用分号分隔） 100 - Dependencies（可选）：依赖项（多个依赖用逗号分隔） 101 - 每个部件信息输入完成后，选择是否添加另一个部件 102 1034. **完成生成** 104 - 脚本将在指定的输出目录下生成JSON格式的 `README.OpenSource` 文件 105 106### 验证 `README.OpenSource` 文件 107 108#### 验证格式 109 110验证项目中所有 `README.OpenSource` 文件的格式和必需字段。 111 112**命令：** 113 114```bash 115python validate_readme_opensource.py --validate-format [目录路径] 116``` 117 118验证检查内容： 119- JSON格式的正确性 120- 必需字段的完整性 121- Dependencies字段（若存在）的数组格式 122 123#### 验证内容 124 125验证 `README.OpenSource` 文件内容与参考数据的一致性。 126 127**命令：** 128 129```bash 130python validate_readme_opensource.py --validate-content --reference-data reference_data.json [目录路径] 131``` 132 133验证内容包括： 134- 核心字段（Name、License、Version Number、Upstream URL）与参考数据的一致性 135- License File 文件实际存在性检查 136- Dependencies字段（若存在）的有效性检查 137 138### 命令行参数 139 140验证工具支持以下命令行参数： 141 142- `project_root`：必需，项目根目录路径 143- `--validate-format`：执行格式验证 144- `--validate-content`：执行内容验证 145- `--reference-data`：参考数据JSON文件路径（内容验证必需） 146- `--log-file`：日志文件路径，用于保存验证结果 147 148## 目录结构 149 150- **src/** 151 - `generate_readme_opensource.py`：生成README.OpenSource开源部件配置信息脚本 152 - `validate_readme_opensource.py`：验证工具脚本，包含JSON格式验证和内容验证功能 153- **README_OSS.md**：使用文档（本文件） 154 155## 工作流程概览 156 157### 生成工具流程图 158 159```mermaid 160sequenceDiagram 161 participant User as 用户 162 participant Script as generate_readme_opensource.py 163 participant FileSystem as 文件系统 164 165 User->>Script: 运行脚本 166 Script-->>User: 请求输出目录 167 User->>Script: 输入目录路径 168 169 loop 添加开源部件 170 Script-->>User: 请求基本信息 (Name等) 171 User->>Script: 输入基本信息 172 Script-->>User: 请求许可证信息 173 User->>Script: 输入许可证及文件路径 174 Script-->>User: 请求依赖项信息(可选) 175 User->>Script: 输入依赖项 176 Script-->>User: 是否继续添加?(y/n) 177 User->>Script: 选择是否继续 178 end 179 180 Script->>FileSystem: 生成 README.OpenSource 181 Script-->>User: 完成生成 182``` 183 184### 验证工具流程图 185 186```mermaid 187sequenceDiagram 188 participant User as 用户 189 participant Script as validate_readme_opensource.py 190 participant FileSystem as 文件系统 191 192 User->>Script: 运行验证命令 193 Script->>FileSystem: 搜索 README.OpenSource 文件 194 195 alt 格式验证 196 Script->>Script: 检查JSON格式 197 Script->>Script: 检查必需字段 198 Script->>Script: 检查Dependencies格式 199 end 200 201 alt 内容验证 202 Script->>Script: 加载参考数据 203 Script->>Script: 比对字段内容 204 Script->>FileSystem: 检查License文件 205 Script->>Script: 验证Dependencies 206 end 207 208 alt 验证通过 209 Script-->>User: 报告成功 210 else 验证失败 211 Script-->>User: 输出错误信息 212 end