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

    列出軟體的版本號碼或修訂版本 ID。如果該版本從網址或修訂版本記錄中明顯，則可以略過。

    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 標籤，指出套件是否具備安全性，有助於評估套件中對 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.