README.fuchsia 文件语法

README.fuchsia 文件用于使用一些有用的元数据（例如代码来源、版本、许可和安全关键标签）来注释第三方源库。

这些文件的格式包含一个或多个指令行，后跟非结构化说明和注释。

指令由行开头的指令关键字组成，紧随其后的是一个冒号和一个延伸到行尾的值。该值可能包含周围的空格，并且指令之前或之间可能会出现空白行。

下文介绍了几个指令，但 README.fuchsia 文件中可能会出现其他指令，使用这些文件的软件不应将出现未知指令视为错误。同样，此类软件应不区分大小写地匹配指令关键字。

说明行是可选的，并且遵循 Description 指令，该指令必须单独出现在一行中，位于任何非结构化说明文本之前。

语法

file                  := directive-line* description?
directive-line        := directive | blank-line
directive             := keyword ":" SPACE* value SPACE* EOL
value                 := NONBLANK ANYCHAR*
description           := description-directive description-line*
description-directive := "Description:" SPACE* EOL
description-line      := ANYCHAR* EOL
keyword               := [A-Za-z0-9][A-Za-z0-9 ]*
blank-line            := SPACE* EOL
SPACE                 := any whitespace character
EOL                   := end of line character
NONBLANK              := any non-whitespace, non-EOL character
ANYCHAR               := any character but EOL

要求

指令关键字及其定义如下。本部分总结了每个 README.fuchsia 需要包含的内容，并说明了如何随着时间的推移保持这些内容处于最新状态：

  • 出于漏洞扫描目的，每个 README.fuchsia 都需要包含以下方面的最新信息：

    • URL 和 Revision：如果是 Git 代码库，则必须使用此选项。 或
    • CPEPrefix 和 Version 此信息可为漏洞扫描器提供足够的信息，以便准确扫描这些依赖项。

  • 出于许可方面的考虑，每个 README.fuchsia 都需要包含有关以下方面的最新信息：

    • License和License File

常见指令关键字

常见的指令关键字包括：

  • Name

    软件包的描述性名称。

    Name: OpenSSH

  • Short Name

    （可选）软件包的分发名称（例如 libxml、openssl 等）。

    Short Name: openssh

  • URL

    （必需）软件包所在的网址，即 Git 代码库的可克隆网址、软件包管理器的软件包管理器网址，或此处列出的网址类型（根据 AutoVM 的元数据 proto）。如果没有上游，请使用“这是规范的公共代码库”。对于来自 Google 内部代码库的软件包，请使用“Google Internal”。 如有必要，此指令可重复使用以包含多个网址。

    示例： URL: https://github.com/openssh/openssh-portable URL: https://chromium.googlesource.com/chromium/src/

  • Revision

    （对于将 Git 代码库作为上游的依赖项，此参数为必需参数；如果上游不是 Git 代码库，并且提供了版本或日期，此参数为可选参数）。修订版本通常是 Git 哈希。如果依赖项由自动滚动器或脚本管理，您必须确保升级流程也会使用正确的修订版本更新 README.fuchsia 文件。

    Revision: 8950d99ba1ba67280fbd1e5445214d2cebe966bb

  • Date

    • 相应软件包的更新日期，格式为 YYYY-MM-DD。
    Date: 2018-02-14

  • License

    分发相应软件包所依据的许可。如需了解有关允许使用的许可的政策和其他指南，请参阅 Fuchsia 开源许可政策。 License: BSD

  • License File

    从 README.fuchsia 文件到许可文件的相对路径。该文件应包含软件包许可的副本，并且应与上面提供的许可相对应。所有软件包都应包含有效的许可，无论是否已发货。 如有必要，此指令可重复使用以包含多个文件。

    License File: LICENSE

  • Security Critical

    yes 或 no 标签，用于指示软件包是否对安全性至关重要，有助于评估软件包中的安全 bug 对 Fuchsia 的影响。

    如果软件包用于生产用途，并且执行以下任何操作，则该软件包在安全性方面至关重要：

    • 接受来自互联网的不可信输入
    • 解析或解读复杂的输入格式
    • 将数据发送到互联网服务器
    • 收集新数据
    • 影响或设置与安全性相关的政策（包括用户体验）
    • 使用内存不安全的语言编写（例如：C/C++、Rust（含不安全块）

    此指令是必需的。

    Security Critical: yes

  • License Android Compatible

    （如果软件包未附带许可或使用标准格式的许可，则为可选）yes 或 no，具体取决于软件包使用的许可是否与 Android 兼容。

    License Android Compatible: yes

  • CPEPrefix

    （可选，但如果未提供网址和修订版本，则为必需）根据搜索结果，表示上游软件包的“通用平台枚举”版本 2.3（首选）或 2.2。此信息将用于报告上游软件包中的已知漏洞，以便我们确保合并这些漏洞的修复。请确保您使用的是最接近的适用上游版本，并遵循相应软件包的 CPE 标准格式。例如 cpe:/a:xmlsoft:libxslt:1.0.10。如果软件包没有可用的 CPE，请指定“unknown”。如果您使用的是介于两个公开版本之间的已修补或修改版本，请“向下舍入”到较低的公开版本。

  • Version

    （如果使用 CPEPrefix 进行漏洞扫描，则为必需字段）软件包的可搜索版本号（如果软件包没有版本或按日期或修订版本进行版本控制，则此字段应为“N/A”，并且修订版本或日期应在相应字段中列出）。如果依赖项由自动滚动器或脚本管理，您必须确保升级流程也会使用正确的版本更新 README.fuchsia 文件。

    Version: 7.6

  • Description

    简要说明相应软件包是什么以及用于什么。

    Description:

This package does x, y, and z.

  • Local Modifications

    列举对上述交付版本中的软件包所做的任何本地更改。

    如果第三方软件包（例如在 git checkout 期间提取的）中的文件未修改，请在此处放置“None”（不带英文引号）。

    Local Modifications:

Added README.fuchsia.
Ported build rules from CMake to GN.

参考文档

README.fuchsia 格式基于 Chromium 的 README.chromium 格式。 请参阅 Chromium 的 adding_to_third_party.md 作为补充参考。