FFX 設定

FFX 的設定管理功能可讓您在不重新編譯的情況下設定 FFX 程式碼。從高層面來看,設定可視為多層的鍵/值對應表。

值解析程序

設定管理程式碼會在多個位置搜尋與鍵相關聯的值。系統會依下列順序執行搜尋,並傳回找到的第一個值:

  1. 執行階段設定 (由指令列設定)
  2. 使用者層級設定 (由 ffx config set 設定)
  3. 建構目錄層級設定 (由建構作業產生)
  4. 全域層級設定變數
  5. 預設設定 (編譯為 ffx)

執行階段設定

使用者在叫用 ffx 時,會在指令列上設定執行階段設定。頂層指令可接受設定參數:

ffx --config "property-name=value" ...

由於這個參數並未強制型別,因此會採用以半形逗號分隔的鍵/值組合格式 ("{key}={value},{key}={value},等等...),因此系統會假設這裡設定的任何設定都是字串。

這個守護程式會以自己的程序執行,如果啟動守護程式,目前不會將執行階段設定從 CLI 轉移至守護程式。如果您想使用執行階段設定設定 Daemon,請手動執行 Daemon 指令:

ffx --config "config-test=runtime" daemon start --background

使用者設定

使用者設定是使用者主目錄中的設定,適用於該使用者對 ffx 的所有叫用。只有執行階段設定會覆寫使用者設定。

使用 ffx config set 指令設定使用者設定。

ffx config set property-name value

建構目錄設定

建構設定與建構目錄相關聯。其用途是設定描述建構輸出的屬性。應在建構程序中產生,並由 ffx 視為唯讀。

檔案格式為 JSON 物件:

{
    "product": {
        "path": "/out/project/dir/product_bundle",
        "name": "sample_project"
    },
    "fidl": {
        "ir": "$BUILD_DIR/fidling/gen/ir_root"
    }
}

本範例中的 $BUILD_DIR 並非 Shell 環境變數,而是內部 ffx 變數預留位置。詳情請參閱「值表示法」。

全域設定

全域設定是系統層級的設定層級。這個檔案可在主機系統上安裝 ffx 時使用,用於設定組織屬性,讓一組使用者皆可使用相同的屬性。

它是在 ffx 工作流程外建立,且 ffx 會將其視為唯讀。

檔案格式為 JSON 物件:

{
    "gcs": {
        "release_bucket": "gs://project/releases",
    }
}

預設設定

預設設定會透過 GN 建構規則在所有子指令中提供,且為硬式編碼且無法變更。

值表示

儲存在 ffx 設定中的值會以 JSON 值編碼。

  • 數字,包括整數和浮點數。
  • 字串
  • 布林值,true|false。
  • 空值,表示為 null
  • 值陣列
  • 物件

字串插補

部分字串可能包含經過插補的預留位置。這樣一來,您就能相對於目錄設定屬性,或從執行程序環境中解析值。

ffx 定義的預留位置如下:

  • $BUILD_DIR:執行 ffx 指令時決定的建構目錄。如果未找到或設定建構目錄,這個屬性可能會是空白。
  • $CACHE:用來儲存快取資料的目錄。
  • $CONFIG:儲存設定資料的目錄。
  • $DATA:儲存永久性資料的目錄。
  • $SHARED_DATA:持續性資料的資料夾,在目前主機電腦上,此資料夾會與所有隔離區和 ffx 例項共用。這項功能適用於用於管理全域狀態的資料,例如開啟 TCP/IP 通訊埠的程序。
  • $FIND_WORKSPACE_ROOT:包含 Bazel 工作區的第一個父項目錄。
  • $HOME:目前使用者的主目錄。
  • $RUNTIME:用於儲存所有執行階段資訊的目錄。在 Linux 上,這個值通常為 $HOME/.local/share/Fuchsia/ffx

此外,任何由 $ 開頭,後面接上全大寫名稱、數字和其他允許字元的字串,都會從程序環境中解析。

陣列處理

陣列通常用於提供可能值的排序清單,然後傳回第一個非空值。

例如,嘗試使用環境中的 SSH 金鑰,否則會改為使用標準位置:

{
    "ssh_key": [ "$SSH_KEY_FROM_ENV", "$HOME/.ssh/ssh_key"]
}

設定環境

指令集合 ffx config env 可用於管理如何定位各種設定層級資料檔案的設定。

舉例來說,如要設定全域設定的路徑:

ffx config env set --level global /etc/fuchsia/ffx_global_props.json