fx 工作流程

fx 是可执行多个任务的一组子命令的入口点 更轻松地进行 Fuchsia 开发。运行 fx help 以查看所有可用的 子命令。如果您使用 bash 或 zsh 作为 shell，请运行源代码 scripts/fx-env.sh 以获取一些自动补全功能。

正在设置 fx

强烈建议您source scripts/fx-env.sh shell。这经过测试，并经常与 Bash 和 ZSH 结合使用。它可能适合 其他兼容的 shell。

# In your fuchsia checkout:
$ cd fuchsia
# Add a configuration to your shell to include fx-env.sh
$ echo "source \"$PWD/scripts/fx-env.sh\"" >> "$HOME/.$(basename "$SHELL")rc"
# If you would like additional convenience tools from the Fuchsia scripts, also
# optionally run the following:
$ echo "fx-update-path" >> "$HOME/.$(basename "$SHELL")rc"
# Restart your shell
$ exec "$SHELL"

上述方法提供的特征集最明确， 一般是非侵入性的。如果它导致 shell 环境中出错，请 提交项目 bug。

如果出于某种原因，您需要使用多次 Fuchsia 结账 （下面推荐的工作流程应该可以避免这种需求），那么您可能需要 执行除上述操作之外的其他操作在这个示例中， 支持的方法：

• 始终显式执行 $FUCHSIA_DIR/scripts/fx
• 使用 direnv 或 dotenv 在特定区域内工作时将$FUCHSIA_DIR/.jiri_root/bin转移到$PATH Fuchsia 目录。

常用的日常工具

看看紫红色树后您要做的第一件事是 构建 Fuchsia，然后将其安装到设备上。fx 提供了一些命令来帮助 替换为：

• fx set 配置 build
• fx build 执行构建
• fx flash ; fx mkzedboot 刷写目标；或准备一个 zedboot USB 密钥
• fx serve 提供构建
• fx publish cache 迭代缓存软件包
• fx ota 更新目标
• fx test 执行测试
• fx shell 连接到目标 shell
• 以及许多其他小任务

配置 build

首先，我们来配置构建。为此，您需要做出一些选择：

• 您想要哪种产品配置？ （不确定：请尝试workbench_eng）
• 您要构建什么板？（不确定：请尝试x64）
• 您需要哪些额外的测试目标？（不确定：尝试 //bundles/tools，如果您要开发一些功能，则可能需要 //bundles/tests)

凭借我们的上述选择（如果您没有阅读上文，请马上行动），您就是 配置 build：

fx set workbench_eng.x64 --with //bundles/tests

在结账中运行 fx set 后，无需再次运行，除非 您需要修改后面的参数。

fx set 将其配置存储在输出目录下的 args.gn 文件中。 直接输出为 out/default。你可以指定其他目录 使用 fx --dir <out_dir> set <set_args>。

您可以使用 fx args 命令修改生成的 args.gn 文件， 更复杂的配置fx args 会在编辑器中打开 args.gn， 您进行更改并重新生成构建图。

刚刚发生了什么？

• 您已选择产品“workbench_eng”（运行 fx list-products，以获取 其他产品配置）。
• 您选择了 x64 板，它支持许多典型的板，基于 x64 架构。（请注意，arm64 板的互换性较低， 在向fx set提供特定开发板时， arm64 架构。运行 fx list-boards 以获取已知开发板的列表 configurations.)
• 您正在临时构建 tests 作为 universe 软件包集的一部分， 不得用作铺路图片的一部分。

软件包部署选项

--with 选项有三个变体，这些变体与将软件包部署到 Fuchsia 设备：--with-base、--with-cache 和 --with（表示 universe）。（请注意，fx set 还有一个 --with-host 选项，用于构建 主机专用目标，例如基于主机的工具和库。）

那么 base、cache 和 universe 是什么？

配置最终会指定依赖项（大多数是软件包）， 有助于构建的输出工件（主要是映像和软件包） 代码库）。build 会进行参数化处理，以确定哪些依赖项 （大多数是软件包）添加到了输出工件（图片或软件包）中， 代码库）。这三个轴分别称为“底轴”“缓存”和“宇宙”：

• 基础版：添加到基础版的软件包会包含在 铺路映像。它们包含在 无线下载更新，并且始终作为一个单元进行更新。中的包 base 不能在运行时从设备中逐出 - 它们会对 可能的最小配置大小
• 缓存：缓存中的软件包包含在 铺砌图片，但这些图片不包括在无线下载中 系统更新，并可以在收到响应请求时从系统中逐出 资源需求，例如磁盘空间压力。缓存中的软件包可以 这些软件包都会随时更新 可以单独更新该软件为“可选”软件，但 提供“开箱即用”的便利功能。
• Universe：Universe 中的软件包是附加的可选软件包， 按需提取和运行，但不会预置到 铺砌图像。

“董事会”和“产品”为集群内的用户选择一组预定义的成员 每个软件包集内的一个 Pod最常见的板级配置会指定 一组要添加到基础依赖项集中的启动关键型驱动程序， 例如，添加一些可选但常用的外设驱动程序， 缓存集。板级配置还可能包括一些板级 开发工具（更常用的是托管工具，而不是目标软件包）， 在“宇宙”中与面板互动产品配置使 可增加或减少基础、缓存或全部软件的选择 根据产品的定义和功能集来决定产品 代表其状态。例如，音响设备产品会将许多与音频媒体相关的 基本上Workbench 产品添加了多种 GUI， 和许多其他软件包

关键产品配置

下面列举了更多类型，但以下 3 种 需要熟悉的重要配置：

• bringup 是一款精简功能集产品，专注于提供非常实用的服务 它旨在提供快速构建和小映像 （主要用于 netboot，而不是 铺砌平整的时尚面具），非常适合用于 底层设施，如 Zircon 内核或板专属驱动程序 和配置它缺乏大部分网络功能， 无法在运行时添加新软件或自行升级。这也意味着 一些 fx 命令，例如 fx serve 和 fx shell 不能与 bringup产品。
• core 是最小的功能集，可以安装其他软件（例如 添加到“宇宙”的物品依赖项集）。它是您构建 所有更高级别的产品配置。具有常见的网络功能 还可以通过无线下载方式更新系统
• workbench_eng 是通用开发环境的基础，适合 专门负责开发界面、媒体和许多其他高级功能。这也是 为爱好者提供玩乐和探索的最佳环境

其他关键构建目标

fx set 的 --with 标志可采用任意值 构建目标。 为方便起见，我们定义了许多捆绑包，其中包括 常用的构建目标。请务必熟悉 以下软件包：

• //bundles/tools 包含各种最常用的开发者工具。 这包括用于从命令行 shell 生成组件的工具、 用于重新配置和测试网络、发出 http 请求、调试 例如节目、更改音量等等。核心产品包括 Universe 软件包中的 //bundles/tools。
• //bundles/tests 会导致构建所有测试程序。大多数测试计划 可以在设备上使用 run-test-suite 进行调用，也可以通过 fx test。
• //bundles/kitchen_sink 是会导致所有其他构建目标 包括在内。在测试核心更改的影响，或在 对代码库进行大规模更改的过程。这也可能是一件有趣的事 因为其中包含所有软件 提供的资源请注意，厨房水槽的水量 20GB 的构建工件，并且要求在目标平台上至少 2GB 的存储空间 设备大小（根据 2019 年第 1 季度估算的大小）。

执行构建

按上述方法使用 fx set 配置 build 后，您就可以运行 build 了 和fx build。此命令会构建所有必需的目标及其输出。

清理 build

您可以继续更改结账中的文件，并运行 fx build 以 重建。如果构建系统会尝试减少工作量， 先前版本。使用之前构建结果的构建称为增量更改 而且通常比干净的重新构建要快得多

更改配置不应该会导致增量构建损坏，但这 由于构建系统的限制，在极少数情况下可能仍会发生这种情况。 如果发生这种情况，请提交详细的错误报告，并记录重现问题的步骤 问题和任何诊断信息，例如构建日志。然后使用以下命令进行恢复：

• fx clean 将清除所有构建工件。
• fx clean-build 相当于 fx clean，然后是 fx build。

如果您发现自己正在更改配置并清理输出目录 那么您可以考虑改用 fx set --auto-dir。在此模式下，fx set将 为不同的配置选择不同的输出目录。请注意， 会增加磁盘使用量，并且您可能需要删除旧的输出目录 一些不再需要的功能。

启用增量软件包重新构建

默认情况下，fx build 会为指定的产品配置构建所有软件包。 这对某些开发者工作流来说是必要的，但对许多其他工作流来说过于复杂。 如果只是对测试进行迭代，则不需要重新生成和重新发布 所有临时（通用）软件包

您可以通过添加 export FUCHSIA_DISABLED_incremental=0 来启用增量重新构建。 添加到 ~/.bashrc 或等效项。此更改会导致以下情况：

• pm（因此 fx serve）会在软件包被发现之前监视它们 创建。创建或修改软件包后，pm 会自动发布该软件包。 因此，您可以让 fx serve 从空树中保持运行，它会发布 随着您的学习逐步成长

• fx test 仅构建运行所需的最小目标。对于组件测试 即软件包及其 GN 依赖项和 //zircon。

• fx serve无法铺路或闪光。

• 默认情况下，fx pave 会在铺完一次后退出。使用 --keep-running 执行以下操作： 覆盖。

请注意，fx build 的行为保持不变。

迭代缓存包

运行 fx build 不仅会触发编译和 发布缓存软件包。如果您的工作流程 仅迭代重新构建缓存软件包，运行 fx build 可能会过多 并导致减速

对于重新构建缓存软件包，您可以通过将 fx publish cache会员价为 fx build。下面是一个典型的 开发工作流：

# Set up your workspace here.
$ fx serve

# Make changes to cache packages here.

# Rebuild and publish cache packages:
$ fx publish cache

# Restart your component, for example:
$ ffx component stop /core/your_component
$ ffx session restart

已知问题：重新启动 Fuchsia 模拟器不会导致组件运行 从更新后的软件包中选择您需要手动重启这些组件。

如需查看所有缓存软件包的列表，您可以运行 fx list-packages --cache。

构建具体目标

可以为 fx build 指定要构建的特定目标或文件的名称。

如果启用了实验性 build-with-labels 功能， 可以直接将 GN 标签传递给 fx build。例如 fx build //examples/hello_world 将构建 //examples/hello_world:hello_world 适用于 Fuchsia 的 GN 目标，以及 fx build --host //examples/hello_world 将构建 供主机使用

如果未启用该功能，您还可以传递您的某个 GN 目标的输出。对于在默认工具链中定义的 GN 目标，GN 会定义 Ninja 与 GN 标签相似的没有起始 // 前缀的别名，因此 fx build examples/hello_world:hello_world 将构建 GN 的输出 默认工具链中的目标 //examples/hello_world。

但是，如果目标是在非默认工具链中声明的，则您必须执行以下操作： 猜测 Ninja 输出路径，这通常非常棘手。对于主机二进制文件 不过，它通常位于 host_x64 子目录下。因此 可通过 fx build host_x64/blah 构建 //foo/bar:blah(//build/toolchain:host_x64) 如果该目标仅定义为 executable()，则会发生此错误。

如需查看更详细的介绍，请参阅构建系统概览 部分构建目标。

生成 build 归档

除了执行构建之外，您还可以使用 fx build 命令 以生成 build 归档文件（即 .tar、.tgz 或 .zip）。此版本 归档文件包含由 fx build 生成的特定构建工件， 使构建输出可移植 以用于各种目的例如，您可以提供 此 build 归档文件，作为 ffx target flash 命令的输入 用于将 build 刷写到 Fuchsia 设备上。

如需生成 build 归档文件，请使用以下特殊目标运行 fx build：

fx build build-archive.FORMAT

将 FORMAT 替换为 tar、tgz 或 zip，例如：

fx build build-archive.zip

构建完成后，此命令将创建构建归档文件 （上述示例中的 build-archive.zip）位于 Fuchsia build 目录（即 默认为 out/default。（要查看构建目录的确切位置， 运行 fx get-build-dir。）

创建商品套装 ZIP 文件

如果您已经通过运行 fx build 构建了 Fuchsia 产品，则可以 运行以下命令，创建一个 ZIP 文件 包含此商品套装：

fx create-pb-zip -o <path-to-pb-zip>

此命令会创建一个 ZIP 文件，该文件包含 指定路径。

刷写开发板并准备 Zedboot

将 Fuchsia 置于目标设备上所需的确切准备工作因 但目前有两个通用的群组， fx 命令后会非常方便：

• fx flash 用于大多数 arm64 设备，用于对 Zedboot 到设备，为铺路做准备。
• fx mkzedboot 用于大多数 x64 设备，用于准备可启动的 USB 密钥 启动到 Zedboot，为设备进行铺路准备。

什么是 Zedboot？

Zedboot 是 Zircon 的一种特殊配置，包含一个简单的网络 简单的设备通告和发现协议，以及一套 将 Fuchsia 写入目标磁盘和/或网络启动目标的协议 系统。Zedboot 是一个术语，同时表示整个进程和 特殊的 build 配置。很多人将它称为 “采用 ASCII 码艺术”。

要在 arm64 目标上进入 Zedboot，请在触发 启动进入 fastboot 刷写模式（通常需要 按钮（因特定硬件而异） 目标）。进入刷写模式后，在主机系统上执行 fx flash。

如需在 x64 目标上进入 Zedboot，请先使用以下命令生成 Zedboot USB 密钥： fx mkzedboot <path-to-usb-device>（用于列出您 则执行 fx list-usb-disks）。完成后，移除 USB 密钥。 将其插入目标设备，然后重新启动目标设备，并选择“Boot”（启动） 通过 USB”启动选项或设备 BIOS。

什么是铺路面？

路面在很多方面与“闪烁”类似然而， 有一些差异。具体来说，铺路是指一组 将一组工件传输到目标系统， 将被写入目标系统上的各个分区。相比之下， 也就是“刷写”更像是写入原始数据流的原始过程 而不是严格面向分区。

用户可以通过先使用 fx flash 刷写 Zedboot 来启动铺砌过程， 或者启动由 fx mkzedboot 创建的 Zedboot USB 密钥，然后执行 fx pave 主机系统上。一般来说，大多数用户实际上想要使用 fx serve 而非 fx pave。提供构建部分中介绍了 fx serve 部分。

什么是 Netbooting？

在 Fuchsia 中，“netboot”是指将一组工件发送到 Zedboot 不会对磁盘进行任何更改 RAM。用户可以执行“netboot”方法是先将设备启动到 Zedboot， 使用 fx flash (arm64) 或 fx mkzedboot (x64)，然后执行 fx netboot。

提供 build

Fuchsia 的很多构建配置包含 直接包含在 build 生成的基础映像中， 会写入到设备。此类软件会改为提供给 按需定位设备，通常俗称为 “临时软件”。

fx serve 命令在内部执行两项功能：

• fx pave 会启动铺路服务器，用于“全新安装”紫红色的天地 从 Zedboot 状态启动。
• fx serve 可启动软件包代码库服务器，用于动态 包括在运行时安装软件，以及对整个系统更新过程。

在内部，fx serve 命令还会搜索要配置的设备，以及 发现时（可能会通过 fx set-device 或 fx -d 加以限制/调制），目标设备会被配置为使用存储库服务器作为 动态软件包和系统更新

更新目标设备

如前几部分所述， Fuchsia 设备：

• 软件是核心系统“基础”的一部分， 单个事务。
• 除基本（缓存）映像以外的 Zedboot 映像中包含的软件 可临时更新的
• 始终是短暂（全局）的软件。

对于新用户开发工作流， 更新目标设备需要 fx ota。fx ota 命令首先 更新“base”和“缓存”软件，然后重新启动目标设备 。该过程的最终结果应为： 软件版本和全新模型版本 设备的实际铺路面

由于 fx ota 进程会导致设备重新启动，因此有时并不是 最高效的诊断、调试或其他非测试性 工作流或需求。在这种情况下，用户可通过一些选择 确保设备上的软件会定期更新。

fx serve 进程使用 自动更新功能存储库会通知目标设备 更新软件。 在每个成功的 fx build 结束时发生）。适用于许多软件 组件，在开发过程中更新它们的最简单方法是确保 它们未包含在基本集中，而是包含在 “缓存”或“宇宙”在这种情况下，只需重启 （例如，完全关闭该软件，或调用 killall），则当该软件更新 然后重新开始

执行测试

Fuchsia 代码库包含许多测试。其中大部分测试本身 组件，并且可以像其他组件一样在目标设备上启动 组件。在目标设备上，一些程序还可以协助进行特定于测试的测试 组件启动问题，例如 run-test-suite。这个过程还可以 可以方便地从开发主机通过 fx test 进行控制。请参阅 如需了解详情，请运行 Fuchsia 测试。

有些用户发现，使用系统编写代码是实现高重点工作流程的有效方式 在保存源代码时构建、推送和执行测试。这可以 使用 fx 可以非常容易实现，例如：

fx -i test hello-world-rust-tests

上述命令将在每次发生更改时执行测试 添加到源代码树中的源代码fx 的 -i 标志会导致 fx 重复 命令的其余部分。 由于 fx test 命令会先执行构建，然后在 这种组合提供了一种方便的自动测试循环，非常适合 高度集中的工作流，例如测试驱动开发。

连接到目标 shell

大多数产品配置都包含 SSH 具有 Fuchsia 特定配置的服务器。fx shell 命令是一个 方便的封装容器通过 SSH 连接到目标设备， 访问非常简单的 POSIX 式 shell。用户应注意 shell 是 POSIX shell 的一个分支，但它不提供 通用 Unix shell。特别是用户会发现，CTRL+C 有奇怪之处 并且可能会经常发现子 shell 表达式和某些更高级的 IO 重定向或环境变量传播。这些错误功能 Fuchsia 不是 POSIX 系统的副作用。

尽管如此，通过 fx shell 提供的 shell 对 命令式执行针对 Fuchsia 目标的程序， 文件系统中提供的一些诊断 / 调试接口 例如 /hub 和 /dev。它也有助于调用 作为 /bin/run，用于提供启动 Fuchsia 组件的工具。如果 build 配置中提供了 tools 软件包，许多常用工具都有 已移植到 unix shell 环境并可供使用，例如 ps ls、cat、curl、vim、fortune 等。

执行其他常见任务

获取日志

fx log 会捕获来自低级别和高级别程序的所有日志， 包括内核、驱动程序和其他用户空间程序。fx log 依赖于有效的高层级网络堆栈和 SSH。因此，fx log 不适用于 Zedboot 或“启动”产品配置。如果设备 处于 fx log 停止运行的状态， 切换到 fx klog 可捕获有关可能原因的更多信息。

fx klog 仅捕获名为“klog”的低级别日志流。“klog”信息流 包括来自 Zircon 内核本身的日志，以及一部分用户空间 软件（最值得关注的是驱动程序和低级别核心软件）。fx klog视情况而定 调用 netsvc 的轻量级网络堆栈上，该堆栈始终会保持 即使在较高级别软件出现问题后仍可使用。netsvc 套件是 也可在“预发布”中产品配置，例如 fx klog 在处理低级软件（例如 Zircon 内核）时非常有用， 或司机。

如需了解详情，请参阅查看日志。

正在复制文件

fx cp 提供了一个围绕 scp 的基本封装容器，类似于 fx shell 是一个 ssh 的封装容器。

# copy ./book.txt from the host, to /tmp/book.txt on the target
$ fx cp book.txt /tmp/book.txt
# copy /tmp/poem.txt on the target to poem.txt on the host
$ fx cp --to-host /tmp/poem.txt poem.txt

使用多个 Fuchsia 设备

有些用户在一个网络中会有多个 Fuchsia 设备，他们希望 将各种命令的效果限定 到这些设备上的特定设备通过 存在 fx set-device 命令来帮助处理此用例。

fx set-device 命令可将特定设备节点名称绑定到 特定 build 目录中。如果用户希望 在多种 build 配置中保留几种不同的设备， 设置如下：

$ fx --dir out/workbench set workbench_eng.x64
$ fx build
$ fx set-device <workbench-node-name>

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

# Start a server for the workbench:
$ fx --dir=out/workbench 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

此外，对于希望对单个 来自当前默认 build 目录的 Fuchsia 设备（一次性） fx 全局标志 -d 允许替换 执行一次命令调用

重新启动设备

fx reboot

在某些设备（目前大多数 arm64 设备）上，还有一些有用的标志：

• fx reboot -r重新启动并进入“recovery”(Zedboot)
• fx reboot -b重新启动并进入“引导加载程序”(Flash)

确定 CL 的状态

fx whereiscl <query>

此命令会指示是否合并给定更改；如果合并，该更改是否通过 Global Integration。查询可以是 Gerrit 评价网址、更改编号、 Change-Id 或 Git 修订版本。

$ fx whereiscl fxr/286748
CL status: MERGED
GI status: PASSED

$ fx whereiscl
https://fuchsia-review.googlesource.com/c/fuchsia/+/287311/1/garnet/go/src/amber/source/source.go
CL status: NEW

$ fx whereiscl I94c56fa4e59842d398bfa90a48c45b388f095184
CL status: MERGED
GI status: PASSED

$ fx whereiscl 6575aee
CL status: MERGED
GI status: PENDING

调试和开发 fx 命令

• fx -x，-x 标志会开启对 fx 脚本的跟踪，输出所有 在 fx 调用期间计算的表达式。
• fx exec 执行当前内跟随的任意程序 fx 环境。例如，fx exec env 会输出所有环境 变量（fx exec env | grep FUCHSIA 很可能是 利益）。

获取与 fx 相关的帮助

fx help <command> 提供了最适合的入门文档 命令。有些命令还支持并提供 fx <command> -h 或 fx <command> --help，但此帮助不适用于所有命令。 这种情况并不常见，但与实现细节有关。内部很多 fx 命令只运行其他程序，通常是由 build 和标志在许多情况下会原封不动地传递给这些程序。在 在这些情况下，传递常规的 -h 或 --help 标志可能无法提供 针对 fx <command> 的文档，而是针对所调用的程序 fx 的下游消息。

用户应始终以 fx help <command> 开头。

不含其他参数的 fx help 提供了所有可用命令的列表 以及 fx 全局标志的文档。fx

显示待处理的提交

fx pending-commits 显示尚未回滚到全局的提交 集成。

如需查看 Fuchsia 的集成信息中心，请参阅 Builders。

将 Fuchsia 检出同步到版本分支

如需将本地 Fuchsia 检出同步到特定版本分支，请执行以下操作： 运行以下命令：

fx sync-to RELEASE_BRANCH

将 RELEASE_BRANCH 替换为要切换到的版本分支 （例如 refs/heads/releases/f6）。要查看所有可用资源的列表 请参阅 Fuchsia 全局集成代码库页面。

以下示例命令可将 Fuchsia 检出同步到 F6 版本 分支：

fx sync-to refs/heads/releases/f6

如需将 Fuchsia 检出重置到树的顶部，请运行以下命令：

fx sync-to reset

如需了解更多选项，请参阅 fx sync-to 参考页面。

定义永久性本地构建参数

如果您想定义运行时将包含的构建参数 fx set，请将它们添加到 $FUCHSIA_DIR/local/args.gn。它们会附加到 $FUCHSIA_BUILD_DIR/args.gn。

如需禁止包含 local/args.gn，请运行 fx set ... --skip-local-args。