本文档将向您介绍 ffx
的一些功能。如需简要了解 ffx
的设计和组件,请参阅 ffx 概览。
与 ffx 团队联系
如果您发现可能的 bug 或者有疑问或建议,请提交 bug。
前提条件
如要按照本文档中的示例操作,您需要运行一台 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
如果在启动守护程序之前已设置默认目标,请等待几秒钟,RCS
状态应更改为显示 Y
。
如果在启动守护程序后设置了默认目标,则尝试与目标交互应该足以启动连接,如下所示
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
命令将称谓作为参数。您可以参阅组件名称文档,详细了解名称及其语法。
查找组件
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
命令通过网址 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
命令诊断并尝试解决这些问题。如果您提交的 bug 涉及目标设备,我们通常会要求您提供 ffx doctor
的输出,以提供有关问题所在位置的信息。
doctor
会尝试与 ffx 守护程序通信,根据需要终止和重新启动 ffx 守护程序。如果成功,它将尝试通过 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 团队提交 bug。例如,如果 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 进行测试
在编写需要与 Fuchsia 环境交互的集成测试时,ffx
命令很有用。不过,由于 ffx
主要为开发者设计,因此它会检查当前环境的配置情况,还会在后台启动守护程序以协调与 Fuchsia 设备的通信。这会使编写使用 ffx
的自动化测试变得更加复杂,因为应隔离配置和守护程序,以避免附带效应或来自全局环境的干扰。
为了实现这种隔离,测试作者在运行使用 ffx
的测试时需要使用隔离目录。
后续步骤
- 请与 ffx 团队联系,提供有关此文档的反馈!
- 了解如何扩展
ffx
。