开始开发 ffx 子工具

FFX 子工具是 ffx cli 运行。它们可以直接编译为 ffx 和/或作为单独的 命令，并在 build 输出目录或 SDK 中找到这些命令； 系统将使用 FHO 工具接口调用该方法。

放置位置

首先，在 fuchsia.git 树中的某个位置创建一个目录来存放您的子工具。目前，子工具位于以下位置：

• ffx 插件树，仅内置插件和混合插件/子工具位于此处。通常，不应将新子工具放置在此处。
• ffx 工具树，其中包含仅限外部运行的子工具 。将其放在此处可让 ffx 的维护者更轻松地协助解决任何问题或 使用 ffx 与该工具之间的接口更改来更新您的子工具。 如果您在此处输入名称，但 FFX 团队不是此工具的主要维护人员， 则必须将 OWNERS 文件放在添加该文件的目录中 和一些单独的负责人，这样我们知道如何对问题进行分类， 工具。
• 项目自己的树中的某个位置。如果 ffx 工具只是现有程序的封装容器，这种做法可能有意义，但如果您这样做，则必须设置 OWNERS 文件，以便 FFX 团队可以批准与 ffx 交互的部分的更新。为此，您可以添加 file:/src/developer/ffx/OWNERS 附加到 OWNERS 文件（位于该工具所在子目录下）。

除了不要将新工具放入插件之外，在确定具体位置时，可能还需要与工具团队讨论，以确定最佳位置。

哪些文件

确定好工具的存储位置后，即可创建源代码 文件。最佳实践是将工具的代码拆分为实现各项的库和仅调用该库的 main.rs。

以下文件集是一个正常的起点：

BUILD.gn
src/lib.rs
src/main.rs
OWNERS

当然，如果您愿意，也可以将内容拆分到更多库中。请注意，这些示例均基于示例 echo 子工具，但为简洁起见，可能会移除或简化部分内容。查看以下位置中的文件： 该目录下的任何项目。

BUILD.gn

以下是一个简单子工具的 BUILD.gn 文件示例。注意事项 如果您习惯使用旧版插件接口，那么 ffx_tool 操作不会 强制实施库结构，或执行任何非常复杂的操作。它是 rustc_binary 操作的封装容器，但添加了一些额外的目标，用于生成元数据、生成宿主工具和生成 SDK Atom。

# Copyright 2022 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

import("//build/host.gni")
import("//build/rust/rustc_library.gni")
import("//src/developer/ffx/build/ffx_tool.gni")
import("//src/developer/ffx/lib/version/build/ffx_apply_version.gni")

rustc_library("lib") {
  # This is named as such to avoid a conflict with an existing ffx echo command.
  name = "ffx_tool_echo"
  edition = "2021"
  with_unit_tests = true

  deps = [
    "//src/developer/ffx/fidl:fuchsia.developer.ffx_rust",
    "//src/developer/ffx/lib/fho:lib",
    "//third_party/rust_crates:argh",
    "//third_party/rust_crates:async-trait",
  ]

  test_deps = [
    "//src/lib/fidl/rust/fidl",
    "//src/lib/fuchsia",
    "//src/lib/fuchsia-async",
    "//third_party/rust_crates:futures-lite",
  ]

  sources = [ "src/lib.rs" ]
}

ffx_tool("ffx_echo") {
  edition = "2021"
  output_name = "ffx-echo"
  deps = [
    ":lib",
    "//src/developer/ffx/lib/fho:lib",
    "//src/lib/fuchsia-async",
  ]
  sources = [ "src/main.rs" ]
}

group("echo") {
  public_deps = [
    ":ffx_echo",
    ":ffx_echo_host_tool",
  ]
}

group("bin") {
  public_deps = [ ":ffx_echo_versioned" ]
}

group("tests") {
  testonly = true
  deps = [ ":lib_test($host_toolchain)" ]
}

main.rs

主要 Rust 文件通常相当简单，只需使用以下代码调用 FHO： 用作入口点的正确类型，ffx 知道如何传达 替换为：

// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use ffx_tool_echo::EchoTool;
use fho::FfxTool;

#[fuchsia_async::run_singlethreaded]
async fn main() {
    EchoTool::execute_tool().await
}

lib.rs

工具的主要代码将位于此处。在这里，您将为命令参数设置基于 argh 的结构体，并从用于存储工具运行所需上下文的结构体派生 FfxTool 和 FfxMain 实现。

参数

#[derive(ArgsInfo, FromArgs, Debug, PartialEq)]
#[argh(subcommand, name = "echo", description = "run echo test against the daemon")]
pub struct EchoCommand {
    #[argh(positional)]
    /// text string to echo back and forth
    pub text: Option<String>,
}

此结构体用于定义子工具在其子命令名称后面需要的所有参数。

工具结构

#[derive(FfxTool)]
pub struct EchoTool {
    #[command]
    cmd: EchoCommand,
    #[with(daemon_protocol())]
    echo_proxy: ffx::EchoProxy,
}

这是用于存储工具所需上下文的结构。这包括 如上面定义的参数结构，守护程序或 可能需要使用的设备，或者其他您可以自行定义的内容。

此结构体中必须有一个元素引用上述参数类型，并且该元素应具有 #[command] 属性，以便为 FfxTool 实现设置正确的关联类型。

此结构中的所有内容都必须实现 TryFromEnv 或具有 #[with()] 该注解指向一个函数，该函数返回实现 TryFromEnvWith。fho 库或其他 ffx 库中还内置了这些功能的多个实现。

此外，工具上方的 #[check()] 注解使用 CheckEnv 的实现来验证命令应在不为结构体本身生成项的情况下运行。此处的 AvailabilityFlag 将检查 如果未启用，则会提前退出。在编写新的 子命令中，则应添加此声明，以防止人们依赖 然后再发布。

FIDL 协议

FFX 子工具可以通过 FIDL 协议与目标设备通信， Overnet。如需从您的子工具访问 FIDL 协议，请执行以下操作：

1. 将 FIDL Rust 绑定作为依赖项添加到子工具的 BUILD.gn 文件中。以下示例为 fuchsia.device FIDL 库添加了绑定：

     deps = [
       "//sdk/fidl/fuchsia.device:fuchsia.device_rust",
     ]
   

2. 将必要的绑定导入到子工具实现中。以下 示例从 fuchsia.device 导入 NameProviderProxy：

   use fidl_fuchsia_device::NameProviderProxy;
   

3. 声明工具结构的成员字段。由于 FIDL 代理会实现 TryFromEnv trait，因此 FHO 框架会为您创建并初始化该字段。

   #[derive(FfxTool)]
   pub struct EchoTool {
     #[command]
     cmd: EchoCommand,
     name_proxy: NameProviderProxy,
   }
   

FfxMain 实现

#[async_trait(?Send)]
impl FfxMain for EchoTool {
    type Writer = MachineWriter<String>;
    async fn main(self, mut writer: Self::Writer) -> Result<()> {
        let text = self.cmd.text.as_deref().unwrap_or("FFX");
        let echo_out = self
            .echo_proxy
            .echo_string(text)
            .await
            .user_message("Error returned from echo service")?;
        writer.item(&echo_out)?;
        Ok(())
    }
}

您可以在此处实现实际的工具逻辑。您可以为 Writer 关联 trait 指定类型，系统会根据 ffx 的运行上下文为您初始化该类型（通过 TryFromEnv）。大多数新的子工具应该 使用 MachineWriter<> 类型，指定一个比示例更宽泛的类型 String，但有意义的内容因工具而异。未来，所有新工具都可能需要实现机器接口。

此外，此函数的结果类型默认使用 fho Error 类型，可用于区分因用户互动而导致的错误和意外错误。如需了解详情，请参阅 （位于错误文档中）。

单元测试

如果您想对子工具进行单元测试，只需按照在主机上测试 Rust 代码的标准方法操作即可。当 with_unit_tests 参数设置为 true 时，ffx_plugin() GN 模板会为单元测试生成 <target_name>_lib_test 库目标。

如果您的 lib.rs 包含测试，则可以使用 fx test 调用这些测试：

fx test ffx_example_lib_test

如果 fx 测试找不到您的测试，请检查产品配置是否包含您的测试。您可以使用以下命令添加所有 ffx 测试：

fx set ... --with=//src/developer/ffx:tests

在测试中使用虚构的 FIDL 代理

测试子工具的常见模式是为 FIDL 创建虚构代理 协议。这样，您就可以通过调用代理返回各种各样的结果，而无需实际处理集成测试的复杂性。

    fn setup_fake_echo_proxy() -> ffx::EchoProxy {
        let (proxy, mut stream) =
            fidl::endpoints::create_proxy_and_stream::<ffx::EchoMarker>().unwrap();
        fuchsia_async::Task::local(async move {
            while let Ok(Some(req)) = stream.try_next().await {
                match req {
                    ffx::EchoRequest::EchoString { value, responder } => {
                        responder.send(value.as_ref()).unwrap();
                    }
                }
            }
        })
        .detach();
        proxy
    }

然后，在单元测试中使用此虚构代理

    #[fuchsia::test]
    async fn test_regular_run() {
        const ECHO: &'static str = "foo";
        let cmd = EchoCommand { text: Some(ECHO.to_owned()) };
        let echo_proxy = setup_fake_echo_proxy();
        let test_stdout = TestBuffer::default();
        let writer = MachineWriter::new_buffers(None, test_stdout.clone(), Vec::new());
        let tool = EchoTool { cmd, echo_proxy };
        tool.main(writer).await.unwrap();
        assert_eq!(format!("{ECHO}\n"), test_stdout.into_string());
    }

OWNERS

如果此子工具位于 ffx 树中，您需要添加 OWNERS 文件，以告知我们谁负责此代码，以及如何在分类中转送与此代码相关的问题。它应如下所示：

file:/path/to/authoritative/OWNERS

最好将其添加为引用（使用 file: 或可能的 include），而不是 作为直接的参与者名单，这样就不会因退出 。

添加到 build

如需将该工具作为托管工具添加到 GN build 图中，您需要在 ffx 工具 gn 文件的主列表中引用该工具，并将其添加到 tools 和 test 组的 public_deps。

之后，如果您fx build ffx，应该能在列表中看到您的工具 即 ffx commands 输出中的 Workspace Commands，您应该能够 运行应用所需的资源

实验性子工具和子命令

建议子工具最初不要在其 BUILD.gn 中包含 sdk_category。这些未指定类别的子工具将被视为“实验性”，不会包含在 SDK build 中。如果用户想使用该二进制文件，则必须直接向他们提供该二进制文件。

不过，子命令的处理方式不同。

子命令需要向工具添加 AvailabilityFlag 属性（如需查看示例，请参阅 ffx target update 历史记录中的提交）。如果用户想使用子命令，则需要设置关联的配置选项，才能调用该子命令。

不过，这种方法存在一些问题，例如缺少任何验证 该子命令的 FIDL 依赖项。因此，自 2023 年 12 月起，我们将更改处理子命令的机制。

与子工具类似，子命令也能够声明其 SDK 类别（使用 默认值为“experimental”），以确定子命令是否可用。 子工具将仅使用子工具类别级别或更高级别的子命令进行构建。FIDL 依赖关系检查将正确验证子命令的要求。

添加到 SDK

工具稳定下来并准备好将其添加到 SDK 中后，您需要将二进制文件添加到 SDK build 中。请注意，在执行此操作之前 必须被视为相对稳定且经过充分测试（在没有 已将其包含在 SDK 中），您需要确保您已考虑 兼容性问题。

兼容性

在将子工具添加到 SDK 和 IDK：

1. FIDL 库 - 您需要添加所依赖的任何 FIDL 库 您向 SDK 添加子工具时，会应用到 SDK。（如需了解详情，请参阅将 API 提升为 partner_internal。）

2. 命令行参数 - 用于测试因命令行而导致的破坏性更改 ArgsInfo 派生宏用于生成 JSON 表示法 。

   这用于黄金文件测试，以检测 差异。黄金文件。最终，此测试将得到增强，以检测破坏向后兼容性的更改并发出警告。

3. 机器友好型输出 - 工具和子命令需要有机器输出 尤其是在测试或构建脚本中使用的工具。 MachineWriter 对象用于以 JSON 格式对输出进行编码 并提供用于检测输出结构更改的架构。

   机器输出必须在当前兼容性时间范围内保持稳定。最终，系统将针对机器输出格式提供黄金检查。 使用机器写入程序输出的好处是 自由文本中的不稳定输出。

更新子工具

如需将子工具添加到 SDK，请将其 BUILD.gn 中的 sdk_category 设置为相应类别（例如 partner）。如果子工具包含不再处于实验阶段的子命令，请移除其 AvailabilityFlag 属性，以便它们不再需要特殊的配置选项即可调用。

包含在 SDK 中

您还需要将子工具添加到 SDK GN 文件的 host_tools 分子中，例如：

sdk_molecule("host_tools") {
  visibility = [ ":*" ]

  _host_tools = [
    ...
    "//path/to/your/tool:sdk", # <-- insert this
    ...
  ]
]

用户体验和 SDK 审核

子工具必须遵循 CLI 准则。