開始使用 ffx

本文件將引導您瞭解 ffx 的部分功能。簡介 ffx的設計和元件，請參閱「ffx 總覽」。

與 ffx 團隊聯絡

如果你發現潛在錯誤、疑問或建議， 回報錯誤。

必要條件

如要按照本文件中的示例進行，您需要有 Fuchsia 裝置執行。如果發生以下情況： 未連接實體裝置，可以使用模擬器。

如何在已啟用網路但無圖形使用者的情況下啟動模擬器 介面支援，執行 ffx emu start --headless。

進一步瞭解如何設定模擬器 請參閱「啟動 Fuchsia 模擬器」。

裝置必須搭載 core 產品設定 或是擴充 core 的產品設定 (例如 workstation_eng)。

您也可以執行 ffx log，提供額外資訊 您的 Fuchsia 目標裝置與 ffx 的互動情形。

簡介

符合所有必要條件後，請在終端機中執行下列指令：

fx ffx help

這會列出所有可用的 ffx 子指令。您會看到一些提示 例如：

Usage: ffx [-c <config>] [-e <env>] [-t <target>] [<command>] [<args>]

Fuchsia's developer tool

Options:
  -c, --config      override default configuration
  -e, --env         override default environment settings
  -t, --target      apply operations across single or multiple targets
  -o, --log-output  specify destination of log output
  --help            display usage information

Commands:
  component         Discover and manage components
  config            View and switch default and user configurations
  daemon            Interact with/control the ffx daemon
  diagnostic        Run diagnostic tests on Fuchsia targets
  docs              View suite of docs for ffx and for Fuchsia
  doctor            Run common checks for the ffx tool and host environment
  emulator          Start and manage Fuchsia emulators
  overnet           Interact with the Overnet mesh
  package           Create and publish Fuchsia packages
  sdk               Modify or query the installed SDKs
  target            Interact with a target device or emulator
  version           Print out ffx tool and daemon versions

你可以使用「fx ffx help <subcommand>」或「fx ffx <subcommand> --help」查看 進一步瞭解子指令

與目標裝置互動

在終端機中，執行下列指令：

fx ffx target list

你會看到ffx發現的裝置清單。舉例來說 單一模擬器正在執行，輸出如下所示：

NAME                    SERIAL       TYPE       STATE      ADDRS/IP                       RCS
fuchsia-emulator  <unknown>    Unknown    Product    [fe80::5054:ff:fe63:5e7a%4]    N

RCS：指出遙控器是否有可連線的執行個體 裝置上執行的服務 (RCS)。

如要讓「ffx」自動與裝置連線，裝置必須符合以下條件： 將目標的節點名稱設為預設目標，或嘗試與 裝置。

如要將目標設為預設目標，請執行下列指令：

fx ffx target default set $NODENAME

如果在啟動 Daemon 前已設定預設目標，請等待幾秒鐘 應該產生 RCS 狀態的變更，以顯示 Y。

如果在啟動 Daemon 後已設定預設目標，就會嘗試 這類連線應該足以啟動連線，如下所示

fx ffx component list

下次列出目標時，您應該會看到 RCS 連結 已啟用。

$ fx ffx target list
NAME                    SERIAL       TYPE       STATE      ADDRS/IP                       RCS
fuchsia-emulator  <unknown>    Unknown    Product    [fe80::5054:ff:fe63:5e7a%4]    Y

如果已設為預設目標，旁邊會顯示 *。

如果您已執行 ffx log，您也會看到如下內容： 記錄檔：

[00009.776170][28540][28542][remote-control, remote_control_bin] INFO: published remote control service to overnet

注意：如果 RCS 資料欄長時間保持 N 狀態，且 已在最初將這個目標的節點名稱設為 target.default 之前 ffx，請聯絡 ffx 團隊。

預設目標

在上述步驟中，我們說明如何使用指令設定預設目標

fx ffx target default set

您也可以使用 --target 旗標。

fx ffx --target $NODENAME component list

與多部裝置互動

TODO：請填寫此表單

控制目標裝置的狀態

您可以使用 target off 和 target reboot 子指令關閉或開啟 分別重新啟動裝置。

ffx記錄

目的地

記錄通常會傳送至快取目錄 (在 Linux 中， $HOME/.local/share/Fuchsia/ffx/cache/logs)。 如要找出該位置，請執行以下指令：

fx ffx config get log.dir

不過，您可以使用 -o/--log-output <destination>、 其中 <destination> 可以是檔案名稱，或 stdout (透過指定 stdout 的方式) 或 -) 或 stderr (透過指定 stderr)。

紀錄層級

偵錯等級可使用 -l/--log-level <level>、 其中 <level> 為 off、error、warn、info、debug 或 trace 之一。 預設為 info。

也可透過設定 log.level 永久設定，例如：

fx ffx config set log.level debug

互動式使用

上述選項的常見用途是查看特定指令的偵錯資訊：

fx ffx -l debug -o - target echo

上述指令會在指令列產生偵錯記錄， 叫用。

目標層級

特定記錄檔「目標」可以提供不同層級 設定項目。log.target_levels。舉例來說 只查看 analytics 的偵錯記錄：

fx ffx config set log.target_levels.analytics debug

記錄「目標」就是在記錄行前面。

設定

請參閱 config 指令的說明文件。

與元件互動

蒙尼克爾

許多使用元件的 ffx 指令都會將單眼衣做為參數。如要進一步瞭解 monikers 及其語法請參閱路徑名稱。

尋找元件

component list 指令會輸出目前所有元件的 monikers 加入元件拓撲

$ fx ffx component list
/
/bootstrap
/bootstrap/archivist
/bootstrap/base_resolver
/bootstrap/console
/bootstrap/console-launcher
/bootstrap/cr50_agent
/bootstrap/device_name_provider
/bootstrap/driver_index
/bootstrap/driver_manager
/bootstrap/flashmap
/bootstrap/fshost
/bootstrap/fshost/blobfs
/bootstrap/fshost/blobfs/decompressor
...

您可以使用 component select capability 指令搜尋使用/公開的元件 具有指定名稱的能力

下列指令會顯示使用/公開 diagnostics 能力的所有元件：

$ fx ffx component capability diagnostics
Exposed:
  /bootstrap/archivist
  /bootstrap/base_resolver
  /bootstrap/driver_manager
  /bootstrap/fshost
  /bootstrap/fshost/blobfs
  /bootstrap/fshost/blobfs/decompressor
  /bootstrap/fshost/minfs
  /bootstrap/pkg-cache
  /bootstrap/power_manager
  ...

檢查元件

您可以使用 component show 指令取得特定物件的詳細資訊 元件。

component show 允許對網址、路徑名稱和元件執行個體 ID 進行部分比對。

下列指令會顯示 /core/network/dhcpd 元件的相關資訊：

$ fx ffx component show dhcpd
               Moniker:  /core/network/dhcpd
                   URL:  #meta/dhcpv4_server.cm
           Instance ID:  20b2c7aba6793929c252d4e933b8a1537f7bfe8e208ad228c50a896a18b2c4b5
                  Type:  CML Component
       Component State:  Resolved
 Incoming Capabilities:  /svc/fuchsia.net.name.Lookup
                         /svc/fuchsia.posix.socket.packet.Provider
                         /svc/fuchsia.posix.socket.Provider
                         /svc/fuchsia.stash.SecureStore
                         /svc/fuchsia.logger.LogSink
  Exposed Capabilities:  fuchsia.net.dhcp.Server
           Merkle root:  521109a2059e15acc93bf77cd20546d106dfb625f2d1a1105bb71a5e5ea6b3ca
       Execution State:  Running
          Start reason:  '/core/network/netcfg' requested capability 'fuchsia.net.dhcp.Server'
         Running since:  2022-09-15 16:07:48.469094140 UTC
                Job ID:  28641
            Process ID:  28690
 Outgoing Capabilities:  fuchsia.net.dhcp.Server

驗證能力路徑

您可以使用 component doctor 指令驗證所有功能 成功轉送並由元件使用

例如：

$ fx ffx component doctor /bootstrap/archivist
Querying component manager for /bootstrap/archivist
URL: fuchsia-boot:///#meta/archivist.cm
Instance ID: None

      Used Capability                      Error
 [✓]  fuchsia.boot.ReadOnlyLog             N/A
 [✓]  fuchsia.boot.WriteOnlyLog            N/A
 [✓]  fuchsia.component.DetectBinder       N/A
 [✓]  fuchsia.component.KcounterBinder     N/A
 [✓]  fuchsia.component.PersistenceBinder  N/A
 [✓]  fuchsia.component.SamplerBinder      N/A
 [✓]  fuchsia.sys.internal.ComponentEvent  N/A
      Provider
 [✓]  fuchsia.sys.internal.LogConnector    N/A
 [✓]  config-data                          N/A

      Exposed Capability                   Error
 [✓]  fuchsia.diagnostics.FeedbackArchive  N/A
      Accessor
 [✓]  fuchsia.diagnostics.LegacyMetricsAr  N/A
      chiveAccessor
 [✓]  fuchsia.diagnostics.LoWPANArchiveAc  N/A
      cessor
 [✓]  diagnostics                          N/A
 [✓]  fuchsia.diagnostics.ArchiveAccessor  N/A
 [✓]  fuchsia.diagnostics.LogSettings      N/A
 [✓]  fuchsia.logger.Log                   N/A
 [✓]  fuchsia.logger.LogSink               N/A

$ fx ffx component doctor /core/feedback
Querying component manager for /core/feedback
URL: fuchsia-pkg://fuchsia.com/forensics#meta/feedback.cm
Instance ID: eb345fb7dcaa4260ee0c65bb73ef0ec5341b15a4f603f358d6631c4be6bf7080

      Used Capability                      Error
 [✓]  fuchsia.boot.ReadOnlyLog             N/A
 [✓]  fuchsia.boot.WriteOnlyLog            N/A
 [✓]  fuchsia.diagnostics.FeedbackArchive  N/A
      Accessor
 [✓]  fuchsia.hardware.power.statecontrol  N/A
      .RebootMethodsWatcherRegister
 [✓]  fuchsia.hwinfo.Board                 N/A
 [✓]  fuchsia.hwinfo.Product               N/A
 [✓]  fuchsia.metrics.MetricEventLoggerFa  N/A
      ctory
 [✓]  fuchsia.net.http.Loader              N/A
 [✓]  fuchsia.process.Launcher             N/A
 [✓]  fuchsia.sysinfo.SysInfo              N/A
 [✓]  fuchsia.ui.activity.Provider         N/A
 [✗]  fuchsia.feedback.DeviceIdProvider    `/core/feedback` tried to use `fuchsia.feedback.DeviceIdProvider` from its parent,
                                           but the parent does not offer that capability. Note, use clauses in CML default to
                                           using from parent.
 ...

執行元件

component run 指令可在指定的獨立集合中建立和啟動元件。

以下是在 /core/ffx-laboratory 中執行 Rust hello-world 元件的範例 集合。首先，您需要宇宙中的 hello-world 套件：

$ fx set <product>.<board> --with //examples/hello_world/rust:hello-world-rust && fx build
...

然後使用 component run 指令，透過網址建立並啟動元件執行個體 fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm，路徑名稱 /core/ffx-laboratory:hello-world-rust:

$ fx ffx component run /core/ffx-laboratory:hello-world-rust fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
URL: fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
Moniker: /core/ffx-laboratory:hello-world-rust
Creating component instance...
...
$ fx ffx component show hello-world-rust
               Moniker: /core/ffx-laboratory:hello-world-rust
                   URL: fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
                  Type: v2 dynamic component
       Execution State: Running
                Job ID: 50775
            Process ID: 50819
...

解決連線問題

如果使用 ffx 與目標裝置通訊時發生問題， 您可以使用 doctor 指令診斷並嘗試解決問題。如果發生以下情況： 回報與目標裝置有關的錯誤，我們通常會要求 ，提供問題所在資訊。ffx doctor

doctor 會嘗試與 ffx Daemon 通訊，正在終止回應 並視需求重新啟動如果連線成功，系統會嘗試透過 SSH 連線至 然後啟動遠端控制服務

如果您在正常情況下嘗試執行 ffx doctor，應該會看到：

$ fx ffx doctor
Checking for a running daemon...none running.
Attempting to kill any zombie daemons...killed at least one daemon.
Starting a new daemon instance...success
Attempting to connect to the daemon. This may take a couple seconds...success
Attempting to communicate with the daemon...success
Attempting to list targets...success
Attempting to get an RCS connection...success
Attempting to communicate with RCS...success


SUCCESS. You should be able to run ffx commands now.

如果 doctor 失敗，系統會嘗試建議解決方法。如果不是，可以向 ffx 團隊回報錯誤 持續發生問題舉例來說，如果 doctor 無法啟動 RCS， 您會看到以下內容：

$ fx ffx doctor
Checking for a running daemon...found
Attempting to connect to the daemon. This may take a couple seconds...success
Attempting to communicate with the daemon...success
Attempting to list targets...success
Attempting to get an RCS connection...success
Attempting to communicate with RCS...FAILED. Timed out.


Attempt 2 of 3
Attempting to list targets...success
Attempting to get an RCS connection...success
Attempting to communicate with RCS...FAILED. Timed out.


Attempt 3 of 3
Attempting to list targets...success
Attempting to get an RCS connection...success
Attempting to communicate with RCS...FAILED. Timed out.


Connecting to RCS failed after maximum attempts. To resolve this issue, try
rebooting your device. If this persists, please file a bug at the link below
and include 1) all output
above and 2) device syslog if available.Bug link: ...

使用 ffx 進行測試

在編寫需要互動的整合測試時，ffx 指令非常實用 與 Fuchsia 環境互動。不過，由於 ffx 主要是針對 會檢查目前的環境以進行設定，並開始 在背景使用 Daemon 協調與 Fuchsia 裝置的通訊。這個 會讓編寫使用 ffx 的自動化測試變得更加複雜 和 Daemon 都必須隔離，以免副作用 打造出全球環境

為了達到這種隔離效果，測試作者必須使用隔離目錄 但如果您執行使用 ffx 的測試

後續步驟

• 請與 ffx 團隊聯絡，針對這份文件提供意見！
• 瞭解如何擴充 ffx。