Fuchsia Build 系統使用的資訊清單檔案格式

Fuchsia 建構系統使用許多「資訊清單」會說明如何 例如將檔案複製到容器中,例如複製到 Fuchsia 套件 封存檔,或是開機檔案系統映像檔 / ZBI 檔案 ,直接在 Google Cloud 控制台實際操作。

本頁面說明在版本中使用的檔案格式,但 請勿對外公開

請注意,產生及處理這些檔案的指令碼與 .gni 檔案 位於 Fuchsia 來源樹的 //build/dist/ 下。

FINI (Fuchsia INI) 資訊清單檔案格式

這個 FINI 資訊清單格式由在構建期間叫用的幾個工具使用: ffx package build 指令 (或舊版 pm 工具), 產生 Fuchsia 套件封存檔或 zbi 工具, ZBI 映像檔。

語法非常簡單:每一行文字看起來都像 <destination>=<source>。 其中 <destination> 是目的地檔案路徑 (相對於網頁的頂端) 最後,<source> 則是來源內容的檔案路徑 至目前的目錄 (在大多數情況下是建構目錄)。

請注意,目的地路徑不得以目錄分隔符開頭。 而且 FINI 檔案不支援 Windows INI 檔案格式

例如:

bin/foo=foo
lib/ld.so.1=user.libc_x64/libc.so
meta/foo.cm=obj/src/foo/cml/foo_component/foo.cm
meta/package=gen/src/foo/foo_meta_package.txt

發布資訊清單檔案格式

這是必須包含清單的 JSON 檔案,其中每個項目都是 JSON 物件 視為單一的「發布管道」項目,說明如何安裝 並將來源檔案新增至容器,並提供目標的 GN 標籤 產生憑證這裡使用的結構定義如下:

  • source:來源路徑字串 (必要)。

  • destination:目的地路徑字串 (必要)。

  • label:指向產生來源檔案目標的 GN 標籤。 僅適用於偵錯 (選用)。

範例:

  {
    "destination": "bin/foo",
    "source": "x64-asan/foo",
    "label": "//some/dir:foo"
  }

雖然與 FINI 資訊清單在概念上相似,但分佈 資訊清單提供了其他詳細資訊 (GN 標籤), 有助於偵錯也由不同的集合使用 工具

部分發行的資訊清單檔案格式

FINI發行資訊清單 是由處理名為「部分發行資訊清單」的中繼檔案所產生。

部分資訊清單是由產生目標的 GN 中繼資料集合所產生 同一個依附元件樹狀結構中這是 JSON 檔案,內含 「entries」物件

數種項目類型可用來描述不同面向 建構與安裝需求這些信號全合併成 。

//build/dist/distribution_manifest.py 中的 Python 模組包含 處理這些檔案時使用的函式

一般項目

這些項目與發行資訊清單使用的結構定義相符。他們 就會對應至簡單的來源檔案,以便安裝到指定目的地 路徑。

  • source:來源路徑字串 (必要)。

  • destination:目的地路徑字串 (必要)。

  • label:指向產生來源檔案目標的 GN 標籤。 僅適用於偵錯 (選用)。

  • elf_runtime_dir:僅適用於 ELF 執行檔和可載入的模組, 可指定此連結位置的選用目的地目錄路徑 二進位檔的 ELF 依附元件應在執行階段。 預設值為「lib」

使用時產生發行資訊清單時,系統會將其依原樣複製, 並在輸出檔案中不含 elf_runtime_dir 金鑰 符合以下條件:

  • 他們擁有與另一個一般項目相同的來源 (請參閱 本節),以備不時之需 但會保留其中一個項目

  • 重新命名的項目會使用其來源路徑 (請參閱下方說明)。

範例:

  {
    "destination": "bin/foo",
    "source": "x64-asan/foo",
    "label": "//some/dir:foo",
    "elf_runtime_dir": "lib/asan"
  },

複製項目。

這些項目用於表示建構作業已將特定檔案複製到 新的輸出位置這項資訊稍後會用來處理重新命名 正確 (請見下方說明) 以及其他條件,否則一律予以忽略。其結構定義如下:

  • copy_from:相對於建構目錄的來源路徑字串 (必要)。

  • copy_to:相對於建構目錄的目的地路徑字串 (必要)。

  • label:指向產生這個項目的目標的 GN 標籤 (選用)。

例如,下列項目用於表示「foo」 可使用「asan」指令建構變數 已一併將${BUILD_DIR}/x64-asan/foo複製到 ${BUILD_DIR}/foo

範例:

  {
    "copy_from": "x64-asan/foo",
    "copy_to": "foo"
    "label": "//some/dir:foo"
  }

請參閱以下章節,瞭解複製和重新命名項目會如何互動。 提供實際範例

已重新命名的項目

這些項目用於表示指定的一般項目 安裝在替代目的地位置這對於 程式 (例如 busybox) 會根據 計劃名稱。renamed_binary() GN 範本必須使用 具體做法是指示 Kubernetes 建立並維護 一或多個代表這些 Pod 的物件其結構定義如下:

  • destination:目的地路徑字串 (必要)。

  • renamed_source:符合另一個一般項目的來源路徑 (必要)。

  • label:指向產生這個項目的目標的 GB 標籤 (選用)。

  • keep_original:布林值標記,設為 true 表示原始標記 容器中的重新命名二進位檔應該仍然安裝在容器中 (OPTIONAL)。

請注意,重新命名項目只能指向一般的 source 路徑 或副本項目的 copy_to 路徑。使用不明的路徑,或 另一個重新命名項目的目的地路徑發生建構錯誤。

您可以多次重新命名相同的項目。如果系統判定 相同的原始二進位需要多次安裝於不同名稱下。

以下範例將 busybox 二進位檔安裝為 bin/cp。 位於同一容器中的 bin/catbin/ls。請注意,bin/busybox 會 「不會」安裝至容器。

  {
    "destination": "bin/busybox",
    "source": "busybox",
    "label": "//third_party/busybox:busybox"
  },
  {
    "destination": "bin/cp",
    "renamed_from": "busybox"
  },
  {
    "destination": "bin/cat",
    "renamed_from": "busybox"
  },
  {
    "destination": "bin/ls",
    "renamed_from": "busybox"
  }

如果重新命名項目將 keep_original 標記設為 true,原始項目 則不會從資訊清單中移除,而是保留其中的原始二進位檔,如下所示:

  {
    "destination": "bin/busybox",
    "source": "busybox",
    "label": "//third_party/busybox:busybox"
  },
  {
    "destination": "bin/cp",
    "renamed_from": "busybox",
    "keep_original": true
  }

這樣就能確保 bin/busyboxbin/cp 都已安裝到 都會在 Docker 容器中執行

檔案項目

這些項目是用來納入其他發行版資訊清單檔案 可能由其他目標產生其結構定義如下:

  • file:檔案路徑字串,指向另一個發布資訊清單 檔案 (必要)。

  • label:預設的 GN 標籤,會套用至 加入檔案 (如果本身沒有 label 值)。

發布檔案可以採用遞迴方式。

範例:

  {
    "file": "path/to/other.dist_manifest",
    "label": "//some/dir:label"
  }

資訊清單檔案中有重複的項目

由於 Fuchsia 版本的運作方式, 格式) 來提供使用相同 <destination> 路徑的多個項目。這是 但只要來源路徑或內容的內容相同,即屬有效;在其中 系統會忽略大小寫重複的項目

當多個項目擁有相同的目的地路徑,但不同時的情況 處理來源路徑時,系統會將來源路徑「和」內容視為建構錯誤 指令碼

複製項目和已重新命名項目之間的互動狀況

如要瞭解複製和重新命名項目的互動方式,請參考 renamed_binary() 目標用於重新命名 foo 二進位檔的安裝位置。 如未選取任何建構變數,相應的建構資訊清單將包含 有兩個項目如下所示:

  {
    "destination": "bin/foo",
    "source": "foo",
    "label": "//src:foo",
  },
  {
    "destination": "bin/foo_renamed",
    "renamed_from": "foo",
  },

第一個一般項目指出 ${BUILD_DIR}/foo 是由 //src:foo 目標,應安裝在預設工具鍊中 容器內的 bin/foo

第二個複製項目會說明以 ${BUILD_DIR}/foo 建構的二進位檔應 確實改用「bin/foo_renamed」而非預設位置 (即 bin/foo)。

理論上,這相當於單一項目:

  {
    "destination": "bin/foo_renamed",
    "source": "foo",
    "label": "//src/foo",
  },

例如:第一個項目,只有目的地路徑有所變更。

不過,使用 asan 變數建構相同項目時,系統會啟用 資訊清單內容會與之前稍有不同:

  {
    "destination": "bin/foo",
    "source": "x64-asan/foo",
    "label": "//src:foo(//build/toolchain:x64-asan)",
  },
  {
    "copy_from": "x64-asan/foo",
    "copy_to": "foo",
  },
  {
    "destination": "bin/foo_renamed",
    "renamed_from": "foo",
  },

現在,第一個項目會告訴已建構 ${BUILD_DIR}/x64-asan/foo 工具鍊中的 //src:foo 目標 (//build/toolchain:x64-asan), 並依預設安裝在 bin/foo

第二個項目會告訴 ${BUILD_DIR}/foo${BUILD_DIR}/x64-asan/foo,因為這是我們的建構系統。

第三個項目與先前相同,因為 renamed_binary() 目標 不知道使用哪個工具鍊或變化版本建構 ${BUILD_DIR}/foo

完全等同於單一項目,如下所示:

  {
    "destination": "bin/foo_renamed",
    "source": "x64-shared/foo",
    "label": "//src/foo(//build/toolchain:x64-asan)",
  },

只有在建構變數啟用時,才能使用複製項目,這些項目會重新命名 項目。理由 每個項目都會透過 建構圖表時,如果每個項目都無法連結 呈現出 GN 網路