fx 工作流程

fx 是一組子指令的進入點，可執行許多工作 與 Fuchsia 開發有關。執行 fx help 以查看所有可用的 子指令。如果您使用 bash 或 zsh 做為殼層，來源為 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
• 使用 direnv 或 dotenv 才能加入 處理特別的工作，$FUCHSIA_DIR/.jiri_root/bin到您的 $PATH Fuchsia 目錄。

常見的日常工具

瀏覽過紫紅色樹後，您首先應該做： 然後安裝到裝置上fx可以提供一些指令 改用：

• fx set 設定建構
• fx build 執行建構
• fx flash ; fx mkzedboot 刷新目標；或是準備 zedboot USB 金鑰
• fx serve 提供版本
• fx publish cache 在快取套件上疊代
• fx ota 更新目標
• fx test 執行測試
• fx shell 連線至目標殼層
• 和許多其他小任務

設定版本

先設定版本。為此，您必須選擇以下幾個選項：

• 您想要哪一種產品設定？ (不確定：改為使用 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 板無法互換，您 最有可能需要給 fx set 這個特定的開發板。 arm64 架構。執行 fx list-boards 以取得已知主面板的清單 configurations.)
• 您正在在 universe 套件組合中暫時建構 tests， 未當做鋪面圖片的一部分。

套件部署選項

--with 選項有三個變化版本，與套件部署至 Fuchsia 裝置：--with-base、--with-cache 和 --with (意即 universe)。(請注意，fx set 也提供 --with-host 選項，用於建構 僅限主機的目標，例如主機式工具和程式庫)。

那麼 base、cache 和 universe 是什麼？

設定最終會指定依附元件 (大部分為套件) 這會影響建構的輸出構件 (主要是映像檔和套件) 存放區)。系統會將建構作業參數化，以判斷哪些依附元件 (大部分套件) 會新增到輸出構件 (映像檔或套件) 中 存放區)。這三個軸稱為「基準」、「快取」和「宇宙」：

• 基礎：新增至基準的套件會納入 貼上建構作業產生的圖片。涵蓋內容 無線更新，且一律視為單一單元。中的包裹 您無法在執行階段撤銷裝置基底元件，因此會將 最小的可能設定大小
• 快取：快取包含的套件包含在快取中 「鋪砌」圖片，但圖片中不會包含 也可能從系統中移除 資源需求，例如磁碟空間壓力。快取中的套件 以及更新的所有套件 可能會單獨更新。這是「選擇性」的軟體， 最好能立即「開箱」
• 宇宙：宇宙套件是額外的選用套件，可進行下列設定 隨選擷取及執行，但未預先準備至任何 正在儲存圖片。

「棋盤」和「產品」系統會在設定節點時 建立個別的套件組合在大多數情況下，主機板設定會指定 要新增至基本依附元件集的一組啟動重要驅動程式，並可能 例如，在 Cloud Shell 中納入一些 快取集。主機板也可能包括一些特定主機專用的設定 開發工具 (較常見的主機工具，而非目標套件) 以「宇宙」與董事會互動產品設定可帶來 選擇在基礎、快取或宇宙中增加或減少軟體 根據其產品的定義和功能組合 。舉例來說，音箱產品會加入許多與音訊相關的媒體 把套件送到底板工作台產品加入了各式各樣的 GUI 媒體和許多其他套件

主要產品設定

這個工具有許多功能， 請務必熟悉以下重要設定：

• 「bringup」是最簡單的功能組合產品，著重於 變得非常簡單它的確提供快速建構和小型映像檔 (主要用於 netboot， 「鋪砌」)，非常適合用於 低階設施，例如 Zircon 核心或董事會專用驅動程式 和配置因為它缺乏大部分的網路功能， 無法在執行階段新增軟體或自行升級。這也表示 部分 fx 指令，例如 fx serve 和 fx shell 無法與 bringup 產品。
• core 是最基本的功能組合，可安裝其他軟體 (例如 已將 個項目新增至「宇宙」依附元件集)。這是 Google 網路的起點 所有較高層級的產品設定它具備常見的網路功能 就能在無線更新系統上更新系統
• workbench_eng 是一般用途開發環境的基礎， 以便處理 UI、媒體和許多其他高階功能這也 是最適合玩遊戲和探索的環境

其他重要建構目標

fx set 的 --with 標記採用任意值 建構目標。 為了方便起見，我們定義了幾個套件， 常用的建構目標請務必熟悉 下列項目組合：

• //bundles/tools 包含多種最常用的開發人員工具。 包括透過指令列殼層產生元件的工具、工具 ，用於重新設定及測試網路、提出 http 要求、偵錯 節目、變更音量等。核心產品包括 根據預設，宇宙套件中的 //bundles/tools。
• //bundles/tests 會建構所有測試計畫。大部分的測試計畫 可在裝置上透過 run-test-suite 叫用，或透過 fx 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 publish cache會員價 fx build。以下是典型的模樣 開發工作流程：

# 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」build-with-labels功能， 就可以直接將 GN 標籤傳遞至 fx build例如： fx build //examples/hello_world 會建構 //examples/hello_world:hello_world 建立 Fuchsia 的 GN 目標，fx build --host //examples/hello_world 則會建立 設定容器

如未啟用這項功能，您也可以透過 GN 目標的輸出內容針對預設工具鍊中定義的 GN 目標，GN 會定義 Ninja 看起來像是無開頭 // 前置字元的 GN 標籤 fx build examples/hello_world:hello_world 會建構 GN 的輸出內容 在預設工具鍊中指定 //examples/hello_world。

如果目標是在非預設工具鍊中宣告，您就必須 猜測 Ninja 輸出路徑，但這通常難度很高。主機二進位檔 但通常位於 host_x64 子目錄下。因此 可使用 fx build host_x64/blah 建構 //foo/bar:blah(//build/toolchain:host_x64) 如果該目標僅定義為 executable() 則適合使用此選項。

如需更詳細的討論內容，請參閱建構系統總覽 建構目標

產生版本封存檔

除了執行建構之外，您可以使用 fx build 指令 即可產生建構封存檔案 (即 .tar、.tgz 或 .zip)。這個版本 封存檔，當中包含 fx build 產生的版本構件特定組合 讓您建構的輸出內容可因應各種用途舉例來說，您可以提供 這個建構封存檔案做為 ffx target flash 指令的輸入內容 以便將版本刷新到 Fuchsia 裝置上

如要產生建構封存檔案，請使用下列特殊目標執行 fx build：

fx build build-archive.FORMAT

將 FORMAT 替換為 tar、tgz 或 zip，例如：

fx build build-archive.zip

建構完成後，這個指令會建立建構封存檔案 (上述範例中的 build-archive.zip)，也就是 Fuchsia 建構目錄中的， 預設為 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，執行以下兩者的原始寫入作業 進入裝置，同時準備進行鋪路程序。
• 大多數的 x64 裝置都使用 fx mkzedboot，以便準備可開機的 USB 金鑰 啟動 Zedboot，並為裝置做好鋪路準備。

什麼是 Zedboot？

Zedboot 是 Zircon 的特殊設定，內含簡單網路 還有一組簡易的裝置通告和探索通訊協定 將 Fuchsia 寫入目標磁碟和/或網路啟動目標的通訊協定 有些人會將 Cloud Storage 視為檔案系統 但實際上不是Zedboot 是用於整個程序的術語，及 特殊的建構設定許多人把這款應用程式稱為「藍色螢幕」 。」

如要在 arm64 目標上進入 Zedboot，請在觸發 啟動快速開機閃爍模式 (通常包括 按鈕，而重新啟動或開機時會因特定硬體而異 目標)。進入刷新模式後，在主機系統上執行 fx flash。

如要在 x64 目標上進入 Zedboot，請先產生一個 Zedboot USB 金鑰： fx mkzedboot <path-to-usb-device> (列出裝置上合適的 USB 裝置) 執行 fx list-usb-disks)。完成後，請移除 USB 金鑰。 將其插入目標裝置，重新啟動目標裝置，選取 [Boot] "從啟動選項或裝置 BIOS 中存取。

什麼是鋪路？

鋪路方式有很多種，與「閃爍」的方式類似然而，它卻是 有些差異具體來說，貼上是指一組程序 將一組構件傳輸到目標系統 會寫入目標系統上的各個分區。相對地 「刷新」的過程比較像是編寫原始資料串流的原始程序 原始磁碟裝置，並非完全以分區為主。

如要啟動鋪面程序，使用者必須先使用 fx flash 刷新 Zedboot。 或是啟動由 fx mkzedboot 建立的 Zedboot USB 金鑰，然後執行 fx pave 在主機系統上一般來說，大多數使用者會希望使用 fx serve 而不是 fx pave。fx serve 包含在提供建構項目中 專區。

什麼是網路啟動？

Fuchsia 中的「netboot」是指將一組構件傳送至 Zedboot 而是直接從 RAM。使用者可以執行「網路啟動」(netboot)方法是 使用 fx flash (arm64) 或 fx mkzedboot (x64)，然後執行 主機系統上的 fx netboot。

提供版本

Fuchsia 中有許多建構設定包含 立即包含在建構產生的基本映像檔中 寫入餐點寫入裝置。這類軟體為 指定隨選裝置 (通常稱為口語式) 「暫時軟體」。

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

• fx pave 啟動貼上伺服器，用於「即時安裝」紫紅色 裝置就會從 Zedboot 狀態中移除
• fx serve 啟動用於動態的套件存放區伺服器 軟體在執行階段安裝，以及完整系統更新。

在內部使用 fx serve 指令時，也會搜尋要設定的裝置，以及 目標裝置被設為使用存放區伺服器做為來源fx set-devicefx -d 動態套件和系統更新

更新目標裝置

如前幾節所述， Fuchsia 裝置：

• 屬於核心系統「基礎」的軟體，以 單筆交易。
• Zedboot 映像檔以外的軟體 (快取) 以便暫時更新
• 一律短暫使用的軟體 (反向操作)。

對於新使用者開發工作流程，這是最能協助 正在更新目標裝置為 fx ota。請先使用 fx ota 指令 更新「base」以及「快取」然後重新啟動目標裝置 建立完成這項程序的最終結果 難以區分的軟體版本和執行新的 包括裝置在內

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 指令首次執行建構時，會對以下項目執行測試： 這個組合提供了便利的自動測試迴圈 例如測試導向開發

連線至目標殼層

大部分的產品設定包含 SSH 配置了 Fuchsia 專屬設定。fx shell 指令是 方便的包裝函式透過 SSH 連接到目標裝置，並提供 存取非常簡單的 POSIX 型殼層使用者需要注意的是 shell 是 POSIX 殼層的分支，並沒有提供 常見的 Unix 殼層尤其使用者也會發現 CTRL+C 有奇怪的東西 而且通常能找到精密的次層運算式，以及更進階的 IO 重新導向或環境變數。下列功能有誤 因為 Fuchsia 並非 POSIX 系統的副作用。

儘管透過 fx shell 提供的殼層對於 迫切地對 Fuchsia 目標執行程式，並探索 檔案系統提供的一些診斷 / 偵錯介面 樹狀結構，例如 /hub 和 /dev。對叫用像 做為 /bin/run，可提供啟動 Fuchsia 元件的設施。如果 tools 套件可在建構設定中取得，有許多共通的工具 到 Unix 殼層環境已轉移且可供使用，例如 ps、 ls、cat、curl、vim、fortune 等。

執行其他一般工作

正在取得記錄檔

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 cp 會在 scp 前後提供基本包裝函式，類似 fx shell 為 ssh 前後的包裝函式。

# 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

此外，若使用者想針對某個 目前預設建構目錄中的 Fuchsia 裝置 (一次性) 指令，fx 通用旗標 -d 可讓您覆寫目標節點的名稱： 單一指令叫用

重新啟動裝置

fx reboot

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

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

決定 CL 的狀態

fx whereiscl <query>

這個指令會指出指定的變更是否已合併，以及是否要傳送變更 全域整合。查詢可以是 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> -h或 fx <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。