本文档将引导您了解 ffx 的一些功能。概览
ffx 的设计和组件，请参阅 ffx 概览。
与 ffx 团队联系
如果您发现可能存在的错误或者有疑问或建议， 提交 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
-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如果在启动守护程序之前已设置默认目标，请等待几秒钟
应使 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 状态，并且
在最初启动之前已将此目标的节点名称设置为 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 命令都使用名称作为参数。如需详细了解
名称及其语法，请参阅组件名称文档。
发现结果组件
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 命令验证所有 capability
并成功路由该组件
例如：
$ 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 守护程序通信，即将终止
并根据需要重新启动如果成功，它将尝试通过 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 主要用于
检查当前环境的配置，
后台守护程序，用于协调与 Fuchsia 设备的通信。这个
使得编写使用 ffx 的自动化测试变得更加复杂，因为
和守护程序应该进行隔离，以避免副作用或
全球环境
为了实现这种隔离，测试作者需要使用隔离目录
使用 ffx 运行测试。
后续步骤
- 请与 ffx 团队联系，提供有关此文档的反馈！
- 了解如何扩展
ffx。