本文件將逐步介紹 ffx 的部分功能。如需 ffx 的設計和元件總覽，請參閱「ffx 總覽」。
與 ffx 團隊聯絡
如果您發現潛在的錯誤或問題或建議，請回報錯誤。
必要條件
如要執行本文件中的範例，您需要執行 Fuchsia 裝置。如果您沒有連接實體裝置，可以使用模擬器。
如要啟動已啟用網路但不支援圖形使用者介面的模擬器，請執行 ffx emu start --headless。
如要進一步瞭解如何設定模擬器，請參閱「啟動 Fuchsia 模擬器」一文。
裝置必須執行 core
產品設定或擴充 core 的產品設定 (例如 workstation_eng)。
或者，您也可以執行 ffx log，提供 ffx 與 Fuchsia 目標裝置之間的互動額外資訊。
說明
符合所有必要條件後，請在終端機中執行下列指令：
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
--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
vendor Run partner plugins
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，且您在初次啟動 ffx 「之前」已將目標的節點名稱設為 target.default，請聯絡 ffx 團隊。
預設目標
之前我們介紹瞭如何使用
fx ffx target default set
您也可以使用 --target 旗標，依指令逐一設定預設目標。
fx ffx --target $NODENAME component list
與多部裝置互動
待辦事項：請填寫
控制目標裝置的狀態
您可以使用 target off 和 target reboot 子指令分別關閉或重新啟動裝置。
設定
請參閱 config 指令的說明文件。
與元件互動
莫尼克爾
許多使用元件的 ffx 指令都會接受 Monikers 做為參數。如要進一步瞭解首字母開發人員及其語法，請參閱路徑名稱文件。
尋找元件
component list 指令會輸出元件拓撲中所有目前存在的元件。
$ 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 指令，透過路徑名稱 /core/ffx-laboratory:hello-world-rust 的 fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm 網址建立及啟動元件執行個體：
$ 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。