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

常用指令关键字

常用指令关键字包括：

  • Name

    组件的描述性名称。如果名称在上下文中无法明显看出，则应添加此名称。

    Name: OpenSSH

  • URL

    组件所在的网址。如果该组件基于特定版本，请明确列出该版本。

    URL: https://ftp.openbsd.org/pub/OpenBSD/OpenSSH/openssh-7.6.tar.gz

    否则，请列出供应商的网站。

    URL: https://www.openssh.com/

    如有必要，可重复此指令以包含多个 网址。

  • Version

    列出软件的版本号或提交标识符。如果从网址或提交历史记录中可以明显看出该版本，则可以忽略此信息。

    Version: 7.6

  • License

    分发组件时所依据的许可。仅接受标准表单，例如 MIT/X11、BSD、Apache 2.0。

    License: BSD

  • License File

    包含组件许可副本的文件。这必须相对于 README.fuchsia 文件命名代码库中的现有文件。

    License File: LICENSE

    如有必要，可重复此指令以包含多个文件。

  • Upstream Git

    指向此组件所属的上游 Git 代码库的链接。对于从外部 Git 代码库分支的任何软件，都应包含此代码。

    Upstream Git: https://github.com/openssh/openssh-portable

  • Security Critical

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

    如果用于生产用途的软件包，则安全性至关重要，并且可执行以下任一操作：

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

    此指令为必需指令。

    Security Critical: yes

  • Description

    标记指令的结尾和非结构化说明的开头，并且必须单独占据一行。

    Description:

A short description of what the package is and is used for.

  • Local Modifications

    枚举从上述配送版本中对软件包进行的任何本地更改。

    Local Modifications:

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