Fuchsia的fx命令

之前在介绍fuchsia的编译(fuchsia的编译参考文章:Fuchsia的运行初体验)的时候提到配置fuchsia的编译产品,以及编译fuchsia系统都会使用到fx命令。
fx对于Fuchsia的重要性,大概等于编译命令+adb 对于Android的重要性。而且fx有非常多的自命令,本文仅参考官方文档fx workflows,对部分fx的自命令进行简单介绍。

fx 是一个入口命令,通过它开发着可以使用大量的开发过程中将使用到的工具脚本。查看fx支持的子命令可以使用fx help。如果使用bash或者zsh作为shell的话,还可以通过执行脚本scripts/fx-env.h将fx的自动补全功能包含进当前shell中。下面为fx help列出的fx子命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
» fx help               
usage: fx [--dir BUILD_DIR] [-d DEVICE_NAME] [-i] [-x] COMMAND [...]

Run Fuchsia development commands. Must be run with either a current working
directory that is contained in a Platform Source Tree or the FUCHSIA_DIR
environment variable set to the root of a Platform Source Tree.

commands:
add-update-source register dev host as target's update source
aemu start fuchsia in aemu
args `gn args` the FUCHSIA_BUILD_DIR
blobstats compute some blobfs statistics from the build
bugreport Obtain and parse a bugreport from a connected target.
build Run Ninja to build Fuchsia
build-push build Fuchsia and push to device
catapult_converter
cgpt
check-deps checks dependency graph in areas
clang-tidy runs clang-tidy on specified files
clean `gn clean` the ZIRCON_BUILDROOT and FUCHSIA_BUILD_DIR
clean-build clean the build directory and then perform a full build
compdb generate a compilation database for the current build configuration
cp copy a file to/from a target device
cpuperf_print
dart-remote-test runs a single remote test target through //scripts/run-dart-action.py
dart-tunnel forward local ports to Dart VMs on the device.
debug run the debug agent on target and connect to it with zxdb
delta compare all built Fuchsia packages with a prior package snapshot
dockyard_host
doctor run various checks to determine the health of a Fuchsia checkout
exec read the current build config, then exec
exec-host-tests
far
fidlcat run fidlcat on given target.
fidldoc
fidlgen
fidlgen_dart
fidlgen_llcpp
fidlmerge
flash
flutter-attach attach to a running flutter module to enable hot reload and debugging
format-code runs source formatters on modified files
futility
fuzz run a fuzz test on target a device
gce Google Compute Engine commands
gen `gn gen` the Zircon and Fuchsia build directories.
gen-cargo
get-build-dir print the current fuchsia build directory
get-device print the current selected device name
get-device-addr print the Fuchsia IPv6 address of the current selected device
gidl
gn
ninja
cipd
jiri
insntrace_print
iquery generate a report with component exposed data
kazoo
lint runs source linters on modified files
list-boards list boards available for building
list-packages list packages are built
list-products list products available for building
list-usb-disks list attached usb disks
log listen for kernel logs.
make-efi
make-fuchsia-vol build a fuchsia persistent disk
make-integration-patch Creates a CL in an integration repository suitable for testing other CLs
metrics manage collection of metrics in fx tools
mkzedboot make a zedboot USB key
multi Run an `fx` command across multiple build directories.
netaddr get the address of a running fuchsia system
netboot run bootserver for netbooting
netls list running fuchsia systems on the local network
net-run run Fuchsia on QEMU in background and runs SSH command after netstack runs
ninjatrace2json Collect Ninja trace information for analysis in chrome://tracing
ota do a system OTA
pave run bootserver for paving
pave-zedboot run bootserver for paving zedboot
pending-commits view commits not yet published to global integration
pm
push-package push packages to a device
qemu-cipd-ensure Generate CIPD files to download the current QEMU package.
reboot reboot a target fuchsia system
remote_module_resolver
run start fuchsia in qemu with a FVM disk
run-bash-test runs tests using bash_test_framework.sh
run-dart-action Run Dart actions (analysis, test, target-test)
run-e2e-tests run e2e tests
run-host-tests build and run tests on host
run-netboot start fuchsia in qemu via netboot
run-recovery start Fuchsia System Recovery in qem
run-test build a test package and run on target.
run-test-component build a test package and run on target.
rustdoc
rustfmt
save-package-stats take a snapshot of all built Fuchsia packages
scp invoke scp with the build ssh config
screenshot takes a screenshot and copies it to the host
serial attach to a serial console
serve start `pave` and `serve-updates` in a single command
serve-updates start the update server and attach to a running fuchsia device
set set up a build directory
set-build-dir set the default build directory used by other fx commands
set-clock set the clock on target using host clock
set-device set the default device to interact with
set-petal configure jiri to manage a specific petal
set-relay
setup-macos register Zircon tools at MacOS Application Firewall
setup-usb-ethernet Setup udev rules for USB CDC ethernet
sftp invoke sftp with the build ssh config
shell start a remote interactive shell in the target device
sniff
ssh invoke ssh with the keys from $FUCHSIA_BUILD_DIR/ssh-keys
status print relevant information about the developer setup
symbolize symbolize backtraces and program locations provided as input on stdin
syslog listen for logs
trace2json
traceutil
traceutil-generate-tally
unset-device unset the default device to interact with
update do a full update of a target system
update-rustc-crate-map
update-rustc-third-party updates rustc_library and rustc_binary third_party dependencies
use re-use a previous build directory set up by `fx set`
vendor forward commands to vendor/*/scripts/devshell
verify-build-packages verify the structure of the build package directory in a layer
wait wait for a shell to become available
whereiscl
zxdb

Global fx options: fx [OPTION] ...
--dir=BUILD_DIR Path to the build directory to use when running COMMAND.
-d=DEVICE_NAME Target a specific device. DEVICE_NAME may be a Fuchsia
device name. Note: "fx set-device" can be used to set a
default DEVICE_NAME for a BUILD_DIR.
-i Iterative mode. Repeat the command whenever a file is
modified under your Fuchsia directory, not including
out/.
-x Print commands and their arguments as they are executed.

optional shell extensions:
fx-go
fx-update-path
fx-set-prompt

To use these shell extensions, first source fx-env.sh into your shell:

$ source scripts/fx-env.sh

生成build配置的命令

Fuchsia的编译需要做如下几个选择:

  1. 你想编译什么产品?
  2. 你想编译什么平台?
  3. 你想要包含哪些额外的包?

有了以上的选择,就可以使用fx set配置build了,例如:

1
$ fx set workstation.x64 --with //bundles:tests

将此次build设置为运行于x64平台的workstation产品,且将测试程序包也一同进行了编译。这个命令将配置存储在args.gn文件中(该文件默认在out/default/目录下),然后可以使用命令

1
fx args

对该文件进行编辑,编辑关闭文件后,会重新生成配置文件。
这里引入了三个新的概念叫 base、cache、universe。要理解这三个概念需要先理解下另一个概念 Paving images ,后文会对其详细介绍,此处可简单理解为是一种刷机方式的刷机包。build配置就是用来决定对哪些依赖进行编译,哪些编译结果文件会被包含到哪个产物中。base、cache、universe就是在这个概念上的三个空间(范围)。

  • base
    添加入base的包会被打包进Paviing Image中,他们会和OTA升级包一起升级。在base中的包在运行时不可以被去除-它们决定了一个配置的最小的镜像大小。
  • cache
    在cache中的包会被打井Paving Image中,但是它们不包含在OTA升级包中。它们也可以在运行时由于资源限制导致被去除,例如磁盘空间不足。cache中的包可以在任意可升级的时间进行独立升级。这些包是可选的,但是为了体验在满足条件的情况下打包进Paving image中,方便用户开箱即使用。
  • universe
    universe 中的包是附加可选包,这些包可以按需下载运行。它们不会运行打包到Paving image中。
    配置平台架构和产品的时候,会将预定义好的一系列包放到如上三种包空间内。平台架构配置会将一些关键的启动驱动放到base中,将一些通用的外围设备的驱动放到cache中,将一些与硬件平台交互用的开发调试用的工具包放到universe中。产品的配置会根据所配置的产品的功能选择一些包分别放入base、cache、universe中。例如,如果编译speaker产品,将增加很多音频多媒体的包到base中,如果编译workstation产品,将会增加一些图形界面、多媒体的包到base中。

关键的产品介绍

使用命令

1
fx list-products

查看支持的产品,此处介绍其中的三个。

  • bringup
    最小功能集的镜像,足够精简。通常用来netboot。它通常用来工作在一些低端设备上,只包含zircon内核和平台特有的驱动,因为缺少必要的网络组件,所以一般情况下也不能进行在线升级。
  • core
    允许安装附加功能(universe中的包)的最小的镜像包。是许多高端产品使用镜像的基础功能包,以进行OTA升级。
  • workstation
    通用开发环境的基础镜像,包含UI、Media和许多高级别的附加功能。适合爱好者把玩探索。

关键的bundles介绍

和产品一样,还有更多的捆绑包,如下几个是最重要的

  • tools
    包含一系列的开发工具。这些工具包含命令行的组件启动工具、配置和测试网络的工具、http请求工具、程序调试工具、调整音量的工具得。在产品core配置上,bundles:tools 会默认配置到universe空间中。
  • tests
    测试程序集合。可以在设备上运行run-test-componet运行,或者使用fx run-test运行。
  • kitchen_sink
    将导致其他所有的目标一同编译。它将消耗host机子的20G存储空间,在设备上也将占用2G的存储空间。

执行build

1
fx build

通常情况下执行build,运行上面的命令就够了。fuchsia的build采用增量编译,仅对修改的部分进行重复编译。
还有一些其他的编译命令,这边也简单介绍下:

1
2
3
fx clean //清除所有生成的产品
fx clean-build //先清除再编译
fx gen //重复fx set执行时的gn gen过程。进行细粒度参数更改(例如直接编辑args.gn)的用户可以运行fx gen来重新配置其build。

刷写设备

1
fx flash

通常用于arm64架构的设备,用来将zedboot刷入设备,为praving做准备。

1
fx mkzedboot

通常用于x64架构的设备,用来制作zedboot的USB引导盘,为praving做准备。

zedboot 是啥

zedboot是zircon的一个特殊配置,它包含简单的网络栈、一个简单的设备广播和发现协议、一个可将fuchsia写入磁盘的套件等。在arm64的设备上进入zedboot,需开机上电时按住特定的按键,然后使设备进入fastboot flashing模式,这时候在主机上执行fx flash;在x64的设备上,首先需要使用fx mkzedboot制作usb引导盘,然后制作好后,将usb设备插入目标设备,目标设备修改BIOS的引导顺序为从USB启动。(期间若要查看可用的usb设备,可使用命令fx list-usb-disks)

paving是啥

paving与其他操作系统的flashing非常相似。具体的讲,Paving使用定好要的一组fuchsia协议和规范将组件传输到目标系统,该目标系统将被写入目标设备的各个分区中。flashing只是将原始数据写入磁盘,而paving增加对了对分区的操作。

netbooting是啥

netboot是fuchisa的一种特殊引导方式,fuchsia可以通过fx flash或者fx mkzedboot制作的usb引导设备使设备进入zedboot状态,然后可以使用fx netboot命令将要启动的组件直接交给zedboot进行引导,这种方式并未修改目标设备上的系统,而仅仅是从ram进行了启动。

其他开发中用到的命令

打印log

1
fx syslog

用来从各级程序获取log,包含内核、驱动及应用程序的log,因为该命令依赖与网络栈的使用,所以运行zedboot和bringup的设备无法使用该命令获取到日志。

1
fx log

获取zircon内核log

主从设备间传递文件

1
2
3
4
# 从编译主机复制文件到目标设备
$ fx cp book.txt /tmp/book.txt
# 从目标设备中复制文件到编译主机
$ fx cp --to-host /tmp/poem.txt poem.txt

编译多个目标

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
可以使用 --dir为要编译的目标指定存放目录,这样可以在多个编译目标间进行切换
$ fx --dir out/workstation set workstation.x64
$ fx build
为编译的目标设置名字
$ fx set-device <workstation-node-name>

$ fx --dir out/core set core.arm64
$ fx build
$ fx set-device <core-node-name>

# Start a server for the workstation:
$ fx --dir=out/workstation 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
robot wechat
欢迎您扫一扫上面的微信公众号,订阅我的博客!
坚持原创技术分享,您的支持将鼓励我继续创作!