本頁記錄了在建構中使用的檔案格式,但檔案外不應公開。
請注意,產生及處理這些檔案的指令碼和 .gni
檔案位於 Fuchsia 來源樹狀結構的 //build/dist/
下。
FINI (Fuchsia INI) 資訊清單檔案格式
建構期間叫用的多項工具都使用了 FINI 資訊清單格式:產生 Fuchsia 套件封存檔案的 ffx package build
指令 (或舊版 pm
工具),或是可產生 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 檔案。
有幾種類型的項目可以說明建構與安裝需求的各方面。全部都會合併成一個 FINI 或發布資訊清單。
//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 標籤 (選用)。
例如,下列項目的用途是表示在 ${BUILD_DIR}/x64-asan/foo
中使用「asan」建構變化版本建構的「foo」執行二進位檔,也複製到 ${BUILD_DIR}/foo
。
例子:
{
"copy_from": "x64-asan/foo",
"copy_to": "foo"
"label": "//some/dir:foo"
}
請參閱下文,瞭解如何透過實際範例,說明複製和重新命名項目如何互動。
已重新命名的項目
這些項目用於表示指定的一般項目應安裝在替代目的地位置。這對特定程式 (例如 busybox
) 來說很實用,因為啟動程式的程式名稱會有所不同,這些程式行為會有所不同。renamed_binary()
GN 範本依賴這些 GN 範本。他們的結構定義如下:
destination
:目的地路徑字串 (必要)。renamed_source
:與另一個一般項目相符的來源路徑 (必要)。label
:指向產生此項目的目標的 GB 標籤 (選用)。keep_original
:布林值標記,設為 true 表示容器仍應安裝原始重新命名的二進位檔 (選用)。
請注意,重新命名項目只能指向一般項目的 source
路徑,或複製項目的 copy_to
路徑。使用不明路徑或其他重新命名項目的目的地路徑屬於建構錯誤。
相同的項目可以多次重新命名。如果同一個原始二進位檔需要多次安裝不同名稱,這種做法就能派上用場。
在以下範例中,busybox
二進位檔是以 bin/cp
、bin/cat
和 bin/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/busybox
和 bin/cp
都已安裝至容器中。
檔案項目
這些項目可用來納入其他可能由不同目標產生的發布資訊清單檔案。他們的結構定義如下:
file
:指向另一個發布資訊清單檔案 (必要) 的檔案路徑字串。label
:如果不含自身的label
值 (選用),就會套用至納入檔案中所有項目的預設 GN 標籤。
發布檔案包含遞迴檔案。
例子:
{
"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
是由 asan 工具鍊 (//build/toolchain:x64-asan
) 中的 //src:foo
目標所建構,且依預設仍安裝至 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 產生過程中連結所有項目。