本頁面由 Cloud Translation API 翻譯而成。

FHO 子工具介面

FHO (Fuchsia 主機物件) 是一組程式庫介面，用於連結 ffx 與子工具搭配使用，無論是編譯為 ffx Cli 二進位檔或另外建構樹狀結構或 SDK 中的二進位檔這個設計可以允許泛舟具備前瞻相容性，讓以 FHO 建構的二進位檔透過大量不同版本相互通訊

在 ffx 子工具 (以 ffx 前置字串執行的頂層指令) 中，FHO 為最好是這款程式與裝置之間的相容性層執行 Fuchsia 的虛擬機器，讓工具忽略所有設定才能連上裝置、為各項服務建立 FIDL 管道裝置，並記錄與互動情形相關的實用資訊。

FHO 主機端 (`ffx` CLI)

在 FHO 架構中，主機二進位檔 (ffx) 負責找出請提供子工具執行所在環境的重要資訊。可能包含下列詳細資料：

使用者和專案設定檔及其內容。
管理使用中的 Daemon 及其提供的服務。
探索和連結到目標裝置，特別是使用預設裝置 (如果有的話)。
發現專案和/或 SDK 內子工具的位置。
發現 SDK 及驗證裝置之間的版本限制 SDK 和子工具

大多數工具都應建立為外部程序，並經由 SDK 或建構輸出目錄，但部分仍內建於 ffx 二進位檔中。這些工具不一定要與單獨編譯的工具不同但相容性限制較為有限不過有些工具甚至不需要 SDK 就能存取

本文件的其餘部分介紹的是獨立編譯的子工具如何發掘及執行這些動作

FHO 工具端

在理想情況下，以 FHO 為基礎的子工具只是 Fuchsia，但在具有 ffx 主機結構定義資訊的主機上執行二進位檔，用於連線至裝置上的服務。

不過，由 ffx 執行的工具具有特殊的進入點，可以傳達讓工具正確執行所需的背景資訊。還需要一些中繼資料，ffx 能用來探索、確認相容性，並執行相關測試

工具中繼資料

工具通常會有與其相關聯的 JSON 中繼資料檔案，如下所示：

{
  "name": "echo",
  "description": "run echo test against the daemon",
  "requires_fho": 0,
  "fho_details": {
    "FhoVersion0": {}
  }
}

這個 JSON 檔案旨在將版本資訊提供給 ffx，以及執行 ffx help 或 ffx commands 時將輸出的資訊上述檔案為「版本 0」FHO 說明：最精簡的內容子工具介面的起點

FHO 中繼資料版本

系統會依序為 FHO 版本加上編號。任一指定廣告素材的支援版本子工具的判斷依據是 requires_fho 鍵到數字的範圍貼在 fho_details 對應中最高值項目的結尾處。子工具就能以這兩個值之間的任何版本執行。

在上述範例中，子工具「只」支援 FHO 版本 0。如果主辦人此工具不支援版本 0，必須忽略子工具的例項以便使用在其他位置找到的新版本；如果沒有相符的版本，則會發生錯誤完全都能找到。

主機工具應使用 fho_details。舉例來說如果您執行的ffx版本 3 與以下中繼資料：

{
  "name": "echo",
  "description": "run echo test against the daemon",
  "requires_fho": 0,
  "fho_details": {
    "FhoVersion2": { "some_thing": "is_something" },
    "FhoVersion4": { "some_thing_else": "is_something_else" },
  }
}

一般而言，主機工具會從 FhoVersion4 提取中繼資料並以 FhoVersion3 程式的形式執行程式。

隨著時間的推移，中繼資料可進行漸進式及破壞性變更。同時讓工具本身支援多種版本您隨時可以在目前版本的中繼資料欄位中新增漸進式變更舊版主機工具會忽略這些版本，新版則會使用它們。

如果需要破壞中繼資料，所有新項目，而舊版本將繼續使用舊版中繼資料結構。

子工具允許加入 FhoVersion0 區段。因此即使 requires_fho 較高，也表示可在使用精簡模式FhoVersion0 部分不應包含任何鍵。

如要查看目前的 FHO 中繼資料 JSON 結構定義

工具探索

目前子工具的搜尋位置如下：

在 FFX 二進位檔本身中。
位於專案專屬的建構輸出位置。
已設定 SDK 的中繼資料。

路徑型探索

如果 ffx 已設定建構輸出目錄或任何其他位置搜尋子工具，可能會搜尋這些位置，找出符合模式：

/ffx-([-_a-zA-Z0-9]/) 或 ffx-toolname，其中 toolname 是子指令呼叫容器的名稱請注意，「不要」處理進一步的連字號以及更深層的巢狀結構，例如ffx-some-sub-tool 以 ffx some-sub-tool 的身分執行，而非ffx some sub tool。子工具負責自己的巢狀指令但 FHO 程式庫本身可能會提供輔助工具。

這些檔案必須伴隨名稱與 .json 相同的檔案副檔名。這個檔案將是前述章節所述的中繼資料且必須符合執行的二進位檔詳細資料 (例如 name 頂層的金鑰必須與二進位檔和中繼資料中的 toolname 相同。

符合此模式的檔案但沒有隨附中繼資料檔案不會視為子工具，系統會予以忽略。

SDK 探索

在 SDK 中，您可以透過中繼資料搜尋找到工具。有人搜尋 SDK 資訊清單，搜尋類型為 atoms ffx_tool，指向 SDK 相關中繼資料和可執行二進位檔的位置。

如要執行子指令，與 ffx_tool 類型相符的 SDK 項目將會直到找到相符的名稱為止。與路徑式搜尋一樣，在搜尋中使用連字號這個名稱不會建立更深層的指令名稱巢狀結構。

主機工具可將 SDK 中的主要 ffx host_tool 二進位檔視為「預設」命令提示詞，讓系統在找不到子工具的情況下，將其叫用為 FHO 版本 0 (基本上，子工具會以 ffx 的形式處理，一個子指令)。

工具介面

如上所述，中繼資料在 ffx 之間宣告一個版本化介面二進位檔和正在執行的子工具目的在於透過這個介面但從相對簡單地著手破壞子工具中目前內建的所有預期行為。

子工具可能支援較舊版本的 FHO 介面會納入其中繼資料，尤其是部分子工具在 ffx 停止支援後，您還需要繼續實作 0 版視其用於建構指令碼等項目而定。

FHO 版本 0

FHO 版本 0 是第一個簡易的 FHO 版本。僅支援不應在 SDK 中加入版本 0，但 SDK 中包含的工具可能會額外支援版本 0。

FHO 第 0 版子工具的叫用程序非常簡單。只要執行含有發出呼叫 ffx 的確切引數，包括所有引數給 ffx 本身。也就是說，如果叫用：

> ffx --isolate-dir "/tmp/blah" echo stuff

執行的 ffx 二進位檔會搜尋相符的 ffx-echo 二進位檔，其最高通用支援版本為 0 時會以下列方式叫用：

> ffx-echo --isolate-dir "/tmp/blah" echo stuff

子工具必須支援各版本已知的所有頂層 ffx 引數 (共 ffx 個)。也透過環境變數執行 FFX_BIN_ENV，指向頂層叫用的檔案系統路徑 ffx 是在下執行 (但不應覆寫)，或可以執行以便從子工具執行的相同內容環境重新開始處理下方。

否則，子項程序會獲得相同的 (stdin,stdout,stderr) 原先 ffx 叫用會在下執行的三倍和環境變數。

原因是：

這可讓您在建構中直接叫用子工具，不必建構主要 ffx 二進位檔，從版本的建構中移除不必要的目標關鍵路徑
但不會幹擾需要完整功能的現有外掛程式並控管執行時的輸入和輸出環境
因此，這個架構的第一版將著重於瞭解建構這項能力的各個面向