fx 工作流程

fx 是一組子指令的進入點,能讓許多與 Fuchsia 開發相關的工作更輕鬆。執行 fx help 查看所有可用的子指令。如果您使用 bashzsh 做為殼層,則請來源 scripts/fx-env.sh 來執行自動完成功能。

設定 fx

強烈建議您在殼層中使用 source scripts/fx-env.sh。這個測試工具會定期與 Bash 和 ZSH 搭配使用。但可能適用於其他相容的殼層。

# In your fuchsia checkout:
$ cd fuchsia
# Add a configuration to your shell to include fx-env.sh
$ echo "source \"$PWD/scripts/fx-env.sh\"" >> "$HOME/.$(basename "$SHELL")rc"
# If you would like additional convenience tools from the Fuchsia scripts, also
# optionally run the following:
$ echo "fx-update-path" >> "$HOME/.$(basename "$SHELL")rc"
# Restart your shell
$ exec "$SHELL"

上述方法提供定義最完善的功能集,通常不會具侵入性。如果它在殼層環境中產生錯誤,請提交專案錯誤。

如果您出於某種原因需要處理多個 Fuchsia 結帳 (下方建議工作流程應已足夠),建議您採取上述以外的做法。在這種情況下,有幾種妥善支援的方法:

  • 一律明確執行 $FUCHSIA_DIR/scripts/fx
  • 使用 direnvdotenv 等工具,在特定 Fuchsia 目錄中工作時,將 $FUCHSIA_DIR/.jiri_root/bin 新增至 $PATH

常用每日工具

瞭解 Fuchsia 樹狀圖後,首先想建立的是 Fuchsia,然後推送到裝置上。fx 可以提供一些指令來協助完成這項操作:

設定建構作業

首先請設定版本。如要這麼做,您需要進行幾項選擇:

  • 您想要進行何種產品設定? (不確定:試用 workbench_eng)
  • 您想為哪個白板打造產品?(不確定:試用 x64)
  • 您想要哪些額外的測試目標?(不確定:試用 //bundles/tools;如果您正在處理功能,您可能會需要 //bundles/tests)

運用我們的上述選項 (如果您尚未讀取上述內容),您已準備好設定建構作業:

fx set workbench_eng.x64 --with //bundles/tests

在結帳程序中執行 fx set 後,除非您需要修改後續引數,否則不需要再次執行該引數。

fx set 會將其設定儲存在輸出目錄中的 args.gn 檔案。直接輸出結果為 out/default。您可以使用 fx --dir <out_dir> set <set_args> 指定不同的目錄。

您可以使用 fx args 指令編輯產生的 args.gn 檔案,以建立更複雜的設定。fx args 會在編輯器中開啟 args.gn,讓您進行變更,然後重新產生建構圖。

發生什麼事了?

  • 您已選取產品 workbench_eng (執行 fx list-products 以取得其他產品設定的清單)。
  • 您已選取主面板 x64,該主面板支援以 x64 架構為基礎的許多一般主面板。(請注意,arm64 主面板無法互換,因此您在建構到 arm64 架構時,很可能需要為 fx set 提供特定的主面板。執行 fx list-boards 以取得已知面板設定的清單)。
  • 您只是在 universe 套件集中建構 tests,而非儲存映像檔的一部分。

套件部署選項

--with 選項有三個變數,分別與將套件部署至 Fauchsia 裝置的方式有關:--with-base--with-cache--with (意指 universe)。(請注意,fx set 也提供 --with-host 選項,可用來建構主機專用目標,例如主機式工具和程式庫。)

那麼 basecacheuniverse 是什麼?

設定最終會指定有助於建構輸出構件的依附元件 (大部分是套件),主要是映像檔和套件存放區。系統會將建構參數化,以判斷要將哪些依附元件 (大部分是套件) 新增至哪些輸出構件 (映像檔或套件存放區)。三個軸稱為「基數」、「快取」和「宇宙」:

  • 基本:已新增至基礎的套件會納入建構產生的「儲存」映像檔。這些程式庫包含在無線更新中,而且一律會更新為單一單元。基礎套件無法在執行階段從裝置中剔除,而是對設定大小的最小可能尺寸進行編碼。
  • 快取:快取中的套件會包含在「貼上」映像檔中,但不包含在無線系統更新中,而且可以因應資源需求 (例如磁碟空間壓力) 從系統中移除。當有可用的更新時,快取中的套件都可以更新,且每個套件都可以獨立更新。這是一種「選擇性」軟體,但建議您「立即可用」。
  • Universe:宇宙中的套件是額外的選用套件,可隨需擷取和執行,但不會預先製入任何「儲存」映像檔中。

「主面板」和「產品」設定會為每個套件組合挑選一組預先定義的成員。通常主機設定會指定一組啟動關鍵驅動程式,用於加入基本依附元件集,也許可以在快取集中納入一些選擇性但常見的周邊裝置驅動程式。主機板設定也可能包含一些棋盤專用的開發工具 (較常見的主機工具,而不是目標套件),以便在「宇宙」中與主面板互動。產品設定會根據所代表產品的定義和功能組合,選擇在基礎、快取或宇宙套件中加入更多或較少軟體。舉例來說,揚聲器產品會在基礎中新增多個音訊媒體相關套件。Workbench 產品會將各種 GUI、媒體和其他許多套件新增至基本套件。

主要產品設定

其中還有更多功能,但請留意下列三項特別重要的設定:

  • bringup 是一種極簡的功能組合,著重於非常簡單、精簡。這種方式是為了提供快速的建構作業和小型映像檔 (主要用於網路啟動而非鋪砌),適合用於極低層級的設施,例如 Zircon 核心或主機專用的驅動程式和設定。它缺少大多數網路功能,因此無法在執行階段新增軟體,也無法自行升級。這也表示部分 fx 指令 (例如 fx servefx shell) 無法與 bringup 產品搭配使用。
  • core 是最基本的功能集,可安裝額外軟體 (例如新增至「宇宙」依附元件集的項目)。這是所有更高層級產品設定的起點。它具有常見的網路功能,也能更新無線系統。
  • workbench_eng 是一般用途開發環境的基礎,適用於處理 UI、媒體和其他許多高階功能。也非常適合愛好者盡情探索及探索。

其他重要的建構目標

fx set--with 旗標會採用任意建構目標。為方便起見,我們定義了多個套件,包括各種常用的建構目標。請務必熟悉下列套件:

  • //bundles/tools 包含各種最常用的開發人員工具。這包括可透過指令列殼層產生元件的工具、重新設定和測試網路的工具、提出 http 要求、對程式進行偵錯、變更音訊音量等。根據預設,核心產品包含的宇宙套件中的 //bundles/tools
  • //bundles/tests 會導致系統建構所有測試計畫。大多數的測試程式都可透過裝置上的 run-test-suitefx test 叫用。
  • //bundles/kitchen_sink 是能夠納入所有其他建構目標的目標。如要測試核心變更的影響,或在程式碼集進行大規模變更時,這就非常實用。這對愛好者來說也是有趣的設定,因為其中包含來源樹狀結構中的所有軟體。請注意,廚房接收器會產生超過 20 GB 的建構構件,並需要目標裝置至少 2 GB 儲存空間 (自 2019 年第 1 季起的預估大小)。

執行建構作業

如上所示,使用 fx set 設定建構後,您就可以使用 fx build 執行建構作業。這個指令會建構所有必要的目標及其輸出內容。

清除建構作業

您可以在結帳時繼續變更檔案,並執行 fx build 重新建構。當先前版本有結果時,建構系統會嘗試減少工作。使用先前建構結果的建構作業稱為漸進式建構作業,通常比使用乾淨的重新建構作業快上許多。

變更設定應該不會導致漸進式建構作業損毀,但在極少數情況下,是因為建構系統的限制。如果發生這種情況,請提交詳細錯誤,擷取重現問題和任何診斷步驟,例如建構記錄。接著,請使用下列指令復原:

  • fx clean 會清除所有建構構件。
  • fx clean-build 等同於 fx clean,之後是 fx build

如果您發現自己正在變更設定並清理輸出目錄,請考慮改用 fx set --auto-dir。在這個模式下,fx set 會針對不同設定選擇不同的輸出目錄。請注意,這樣會增加磁碟用量,屆時您可能需要刪除不再需要的舊版輸出目錄。

啟用漸進式套件重新建構功能

根據預設,fx build 會為指定的產品設定建構所有套件。 對部分開發人員工作流程而言,這是必要做法,但對許多其他工作流程來說,則過多。如果您只是在測試時進行疊代,就不需要重新建構及重新發布所有暫時 (宇宙) 套件。

如要啟用漸進式重新建構功能,請將 export FUCHSIA_DISABLED_incremental=0 新增至 ~/.bashrc 或同等項目。這項變更會產生以下結果:

  • pm (及結果由 fx serve) 會監控套件,然後再建立套件。建立或修改套件時,pm 會自動發布該套件,讓您可以保持 fx serve 從空白的樹狀結構執行,且後續發布將逐步增加。

  • fx test 只會建構執行所需的最低目標。元件測試就是套件,也就是其 GN 依附元件和 //zircon

  • fx serve 不會緩衝或閃爍。

  • 根據預設,fx pave 會在貼上單次後結束。使用 --keep-running 覆寫。

請注意,fx build 的行為維持不變。

疊代快取套件

除了編譯和發布快取套件以外,執行 fx build 會觸發完整的系統組合作業。如果您的工作流程只需要疊代重新建構快取套件,執行 fx build 可能會過度,並導致速度變慢。

如要重新建構快取套件,只要將 fx build 替換為 fx publish cache,即可加快建構速度。以下是在一般開發工作流程中可能顯示的流程:

# Set up your workspace here.
$ fx serve

# Make changes to cache packages here.

# Rebuild and publish cache packages:
$ fx publish cache

# Restart your component, for example:
$ ffx component stop /core/your_component
$ ffx session restart

已知問題:重新啟動 Fuchsia 模擬器不會導致元件透過已更新的套件執行。必須手動重新啟動元件。

如要查看所有快取套件的清單,可以執行 fx list-packages --cache

建立特定目標

fx build 可以是要建構的特定目標或檔案名稱。

如果啟用了實驗性 build-with-labels 功能,可以將 GN 標籤直接傳送至 fx build。舉例來說,fx build //examples/hello_world 將為 Fuchsia 建構 //examples/hello_world:hello_world GN 目標,而 fx build --host //examples/hello_world 則會為主體機器建構該目標。

如果這項功能未啟用,您也可以針對其中一個 GN 目標輸出傳遞 Ninja 目標路徑。針對預設工具鍊中定義的 GN 目標,GN 會定義看起來像 GN 標籤的 Ninja 別名,但不含起始 // 前置字串,因此 fx build examples/hello_world:hello_world 會在預設工具鍊中建構 GN 目標 //examples/hello_world 的輸出內容。

但是,如果已在非預設工具鍊中宣告目標,則您必須猜測 Ninja 輸出路徑,但這個路徑通常相當棘手。不過,主機二進位檔通常位於 host_x64 子目錄下。因此,如果目標僅定義為 executable(),則可使用 fx build host_x64/blah 建構 //foo/bar:blah(//build/toolchain:host_x64)

如要更詳細地討論建構目標,請參閱建構系統總覽

產生版本封存檔

除了執行建構之外,您也可以使用 fx build 指令產生建構封存檔案,也就是 .tar.tgz.zip。這個建構封存檔案會包含 fx build 產生的特定建構構件,讓建構作業輸出內容可以移植於各種用途。例如,您可以將這個建構封存檔提供至 ffx target flash 指令的輸入內容,以將版本刷新至 Fuchsia 裝置。

如要產生建構封存檔案,請以下列特殊目標執行 fx build

fx build build-archive.FORMAT

FORMAT 替換為 tartgzzip,例如:

fx build build-archive.zip

建構完成後,這個指令會在 Fuchsia 建構目錄中建立建構封存檔案 (上述範例中的 build-archive.zip),其中預設的目錄為 out/default。(如要查看建構目錄的確切位置,請執行 fx get-build-dir)。

建立產品組合 ZIP 檔案

如果您已透過執行 fx build 建構 Fuchsia 產品,可以執行下列指令,建立包含產品套件的 ZIP 檔案

fx create-pb-zip -o <path-to-pb-zip>

這個指令會建立包含指定路徑中產品套件的 ZIP 檔案。

刷新遊戲板並準備 Zedboot 系統

將 Fuchsia 用於目標裝置的確切準備工作會因裝置而異,但現今的常見用途有兩個,因此更容易遵循 fx 指令:

  • 大多數的 arm64 裝置都會使用 fx flash,以便對裝置執行原始 Zedboot 寫入作業,為裝置進行剖析準備。
  • 大多數的 x64 裝置都會使用 fx mkzedboot,準備可啟動的 USB 金鑰,該金鑰可啟動至 Zedboot,為裝置進行剖析

什麼是 Zedboot?

Zedboot 是 Zircon 的特殊設定,其中包含簡單的網路堆疊、簡易的裝置通告與探索通訊協定,以及一組通訊協定,可將 Fuchsia 寫入目標磁碟和/或網路啟動目標系統。Zedboot 這個術語適用於整個程序與特殊建構設定。許多人都知道這是「帶有 ASCII 藝術的藍色螢幕」。

如要依 arm64 目標進入 Zedboot,請在裝置上開機並觸發 Fastboot 刷新模式 (通常在重新啟動或開機時,需要按住特定按鈕 (視硬體目標而定)。進入刷新模式後,在主機系統上執行 fx flash

如要在 x64 目標上進入 Zedboot,請先使用 fx mkzedboot <path-to-usb-device> 產生 Zedboot USB 金鑰,在系統中列出合適的 USB 裝置,執行 fx list-usb-disks。完成後,請移除 USB 金鑰,將其插入目標裝置,然後重新啟動目標裝置,然後從啟動選項或裝置 BIOS 中選取「從 USB 啟動」。

什麼是路面鋪設?

鋪路有許多方式,就像從其他世界「閃爍」一樣,但有些差異。具體來說,步道是指 Fuchsia 中的一組程序和通訊協定,用於將一組構件傳輸到目標系統,這些構件將寫入目標系統上的不同分區。相反地,「刷新」程序比較原始的流程是將原始資料串流寫入原始磁碟裝置,而不是嚴格執行分區導向。

如要啟動暫存程序,使用者可使用 fx flash 先刷新 Zedboot,或是啟動由 fx mkzedboot 製作的 Zedboot USB 金鑰,然後在主機系統上執行 fx pave。一般來說,大多數使用者會想要使用 fx serve,而非 fx pavefx serve 會在「提供版本」一節中說明。

什麼是 Netbooting?

在 Fuchsia 中,「netboot」是指將一組構件傳送至 Zedboot 執行個體,而該執行個體不會變更磁碟,而是僅透過 RAM 啟動。使用者可使用 fx flash (arm64) 或 fx mkzedboot (x64) 先啟動裝置進入 Zedboot,然後在主機系統上執行 fx netboot,藉此執行「網路啟動」(Netboot)。

提供版本

Fuchsia 的許多建構設定包括沒有立即包含在建構的基本映像檔中的軟體,在編寫期間寫入裝置。這類軟體是為了隨選指定裝置才能提供給使用者,而這類軟體通常通稱「臨時軟體」。

fx serve 指令會在內部執行兩個函式:

  • fx pave 會啟動準備伺服器,用於在 Zedboot 狀態下「重新安裝」 Fuchsia 裝置。
  • fx serve 會啟動套件存放區伺服器,用於在執行階段動態安裝軟體,以及整個系統更新。

fx serve 指令也會在內部搜尋要設定的裝置,並在探索時 (可能會限制/修改 fx set-devicefx -d) 使用存放區伺服器做為動態套件和系統更新的來源。

更新目標裝置

如前幾節所述,Fuchia 裝置上有不同的軟體群組:

  • 屬於核心系統「基本」的軟體,會在單一交易中更新。
  • 除了可暫時更新的 Zedboot 映像檔之外,可暫時更新的 Zedboot 映像檔軟體。
  • 始終是暫時性的軟體 (宇宙)。

如果是新使用者開發工作流程,在目標裝置更新時最常見的指令為 fx otafx ota 指令會先更新「base」和「cache」軟體,並在完成後重新啟動目標裝置。這項程序的最終結果,應與軟體版本自己不相同,而無法執行全新的裝置環境。

fx ota 程序會導致裝置重新啟動,因此在診斷、偵錯或其他非測試式工作流程或需求方面,有時並不是最有效的程序。在這類情況下,使用者可透過某些選項確保裝置上的軟體定期更新。

fx serve 程序會設定具備自動更新功能的 Fuchsia 軟體存放區。每當基礎存放區更新時 (每次成功 fx build 結束時),存放區都會通知目標裝置更新。對許多軟體元件而言,最簡單的更新方式是在開發期間確保這些元件不包含在基本集中,而改為包含在「快取」或「宇宙」中。在這種情況下,只要重新啟動目標上的軟體 (例如完全關閉或叫用 killall),就會在軟體再次啟動時立即更新。

執行測試

Fuchsia 程式碼集包含許多測試。這些測試大多是元件,可以比照其他元件在目標裝置上啟動。在目標裝置上,部分程式也可協助啟動元件 (例如 run-test-suite) 的測試專屬問題。您也可以透過 fx test 輕鬆從開發主機控管這個程序。詳情請參閱執行 Fuchsia 測試

部分使用者發現,每當儲存原始碼時,都要讓系統建構、推送及執行測試,才能達到有效的高度聚焦工作流程。只要使用 fx 就能輕鬆完成,例如:

fx -i test hello-world-rust-tests

上述指令在每次變更樹狀結構中的原始碼時都會執行測試。如果將 -i 旗標設為 fx,則每當樹狀結構中的原始碼有所變更時,fx 都會重複執行其餘的指令。由於 fx test 指令會先執行建構作業,然後在目標上執行測試,因此這個組合可提供便利的自動測試迴圈,非常適合用於測試驅動開發等高度聚焦的工作流程。

連線至目標殼層

大多數產品設定包含採用 Fuchsia 專屬設定的 SSH 伺服器。fx shell 指令是方便的包裝函式,可透過 SSH 連線至目標裝置,並提供簡易的 POSIX 樣式殼層的存取權。使用者應注意,雖然殼層是 POSIX 殼層的分支,但無法提供常見的 Unix 殼層的所有功能。尤其是 CTRL+C 有奇怪的特性,而且通常會發現子 shell 運算式和更進階的 IO 重新導向或環境變數傳播。這些錯誤特徵是 Fuchsia 並非 POSIX 系統的副作用。

雖然可透過 fx shell 提供的殼層在 Fuchsia 目標上強制執行程式,以及探索檔案系統樹狀結構中提供的某些診斷 / 偵錯介面,例如 /hub/dev。也適合用於叫用提供啟動 Fuchsia 元件設施的程式,例如 /bin/run。如果建構設定中有 tools 套件,則許多與 Unix 殼層環境相同的工具都已移植並且可供使用,例如 pslscatcurlvimfortune 等。

執行其他一般工作

取得記錄檔

fx log 會從低層級程式和高階程式擷取所有記錄,包括核心、驅動程式及其他使用者空間程式。fx log 取決於運作中的高層級網路堆疊和 SSH。因此,fx log 無法與 Zedboot 或「啟動」產品設定搭配使用。如果裝置處於 fx log 停止運作的狀態,建議您切換至 fx klog 以擷取可能原因的詳細資訊。

fx klog 只會擷取名為「klog」的低階記錄串流。klog 串流包含 Zircon 核心本身的記錄,以及一部分使用者空間軟體 (主要是驅動程式和低階核心軟體)。fx klog 仰賴稱為 netsvc 的輕量級網路堆疊,即使在高階軟體中發生問題,系統仍可能保持可用。netsvc 套件也適用於「啟動」產品設定,例如,fx klog 在處理低階軟體 (例如 Zircon 核心或驅動程式) 時最為實用。

詳情請參閱查看記錄一文。

複製檔案

fx cpscp 提供基本包裝函式,類似於 fx shellssh 周圍的包裝函式。

# copy ./book.txt from the host, to /tmp/book.txt on the target
$ fx cp book.txt /tmp/book.txt
# copy /tmp/poem.txt on the target to poem.txt on the host
$ fx cp --to-host /tmp/poem.txt poem.txt

使用多個 Fuchsia 裝置

部分使用者在網路上會同時使用多部 Fuchsia 裝置,並希望限制這些裝置的特定指令對各種指令的效果。存在 fx set-device 指令有助於此用途。

fx set-device 指令會將特定裝置節點名稱繫結至特定建構目錄。如果使用者希望以多種建構設定保留數個不同的裝置,這個功能就特別實用,可以按照以下步驟進行設定:

$ fx --dir out/workbench set workbench_eng.x64
$ fx build
$ fx set-device <workbench-node-name>

$ fx --dir out/core set core.arm64
$ fx build
$ fx set-device <core-node-name>

# Start a server for the workbench:
$ fx --dir=out/workbench serve
# Set the default build-dir and target device to the arm64 core, and
# connect to a shell on that device:
$ fx use out/core
$ fx shell

此外,如果使用者想將目前預設建構目錄中的單一 Fauchsia 裝置執行指令做為一次性指令,可使用 fx 通用旗標 -d 覆寫單一指令叫用的目標節點名稱。

重新啟動裝置

fx reboot

在某些裝置 (目前大多數 arm64 裝置) 上也有一些實用的標記:

  • fx reboot -r 重新啟動並進入「recovery」(Zedboot)
  • fx reboot -b 重新啟動並進入「系統啟動載入程式」(Flash)

判斷 CL 狀態

fx whereiscl <query>

這個指令會告知指定變更是否已合併,以及是否傳遞 Global Integration。查詢可以是 Gerrit 評論網址、變更編號、Change-Id 或 Git 修訂版本。

$ fx whereiscl fxr/286748
CL status: MERGED
GI status: PASSED

$ fx whereiscl
https://fuchsia-review.googlesource.com/c/fuchsia/+/287311/1/garnet/go/src/amber/source/source.go
CL status: NEW

$ fx whereiscl I94c56fa4e59842d398bfa90a48c45b388f095184
CL status: MERGED
GI status: PASSED

$ fx whereiscl 6575aee
CL status: MERGED
GI status: PENDING

偵錯及開發 fx 指令

  • fx -x -x 標記會開啟 fx 指令碼的追蹤功能,並輸出在 fx 叫用期間評估的所有運算式。
  • fx exec 會執行在目前 fx 環境內跟進的任意程式。舉例來說,fx exec env 會輸出該環境中的所有環境變數 (fx exec env | grep FUCHSIA 可能有興趣)。

取得「fx」的相關協助

fx help <command> 提供該指令的最佳簡介說明文件。部分指令也支援及提供 fx <command> -hfx <command> --help,但並非所有指令都能使用這項說明。這是特殊情形,但這是實作詳細資料的功能。在內部,許多 fx 指令只會執行其他程式 (通常是由建構產生的程式),而標記在許多情況下都會未經變更傳遞至這些程式。在這類情況下,傳遞一般的 -h--help 旗標可能不會提供 fx <command> 的說明文件,而會改為針對叫用 fx 的下游程式提供說明文件。

使用者應一律以 fx help <command> 開頭。

如果 fx help 不含其他引數,則會列出 fx 中所有可用指令的清單,以及 fx 通用旗標的說明文件。

顯示待處理的修訂版本

fx pending-commits 會顯示尚未推送至全域整合的修訂版本。

如要查看 Fuchsia 的整合資訊主頁,請參閱建構工具

將 Fuchsia 結帳系統同步處理至發布分支版本

如要將本機 Fuchsia 結帳功能同步處理至特定發布分支版本,請執行下列指令:

fx sync-to RELEASE_BRANCH

RELEASE_BRANCH 替換為您要改用的發布分支版本 (例如 refs/heads/releases/f6)。如要查看所有可用發布分支版本的清單,請參閱 Fuchsia 全域整合存放區頁面上的「分支版本」一節。

下列範例指令會將 Fuchsia 結帳系統同步處理至 F6 發布分支版本:

fx sync-to refs/heads/releases/f6

若要將 Fuchsia 結帳重設為樹狀圖頂部,請執行下列指令:

fx sync-to reset

如需更多選項,請參閱 fx sync-to 參考資料頁面。

定義永久的本機建構引數

如要定義每次執行 fx set 時會納入的建構引數,請將這些引數新增至 $FUCHSIA_DIR/local/args.gn。每次重新產生建構引數時,這些引數都會附加至 $FUCHSIA_BUILD_DIR/args.gn

如要略過納入 local/args.gn,請執行 fx set ... --skip-local-args