为 FIDL 做贡献

概览

FIDL 工具链大致由三个部分组成：

1. 前端（也称为 fidlc）
   • 解析和验证 .fidl 文件
   • 计算各种结构的大小、对齐方式和偏移量
   • 生成一个 JSON IR（中间表示）
2. 后端
   • 脱离 IR（C 后端除外）
   • 生成目标语言的特定代码，这些代码与该语言的库相关联
3. 运行时库
   • 实现消息的编码/解码/验证
   • 方法调度机制

代码位置

编译器前端

前端位于 //tools/fidl/fidlc/，测试位于 //tools/fidl/fidlc/tests。

编译器后端

目标专用后端的支持代码位于 /tools/fidl/lib/fidlgen.

测试工具

GIDL

GIDL 是一种用于创建通用“只需编写一次，即可为每个后端生成”程序的工具。目前，GIDL 用于生成编码或解码测试 （“一致性测试”）以及基准测试。

每个后端中一致性测试的实际测试目标通常与相应后端的测试一起定义。如需了解详情，请参阅绑定测试部分。

兼容性

兼容性测试是运行 FIDL 客户端的集成测试 和来自不同绑定的服务器相互连接，以测试它们 是否兼容。兼容性测试位于 /src/tests/fidl/compatibility/。

危险标识符

危险标识符测试位于 /src/tests/fidl/dangerous_identifiers。

其他

其他一些与 FIDL 相关的领域包括：

其他 FIDL 工具

许多 FIDL 工具位于 fidl-misc 代码库中。如需克隆此代码库，请运行以下命令：

git clone https://fuchsia.googlesource.com/fidl-misc

然后，建议导出此目录的路径，以便更轻松地设置别名：

export FIDLMISC_DIR=...

常用开发工具

这是 FIDL 团队聚集的一节，其中介绍了 用于处理 FIDL 代码库。

IDE

FIDL 团队的大多数人都使用 VS Code 进行开发。一些实用的插件和工作流：

• 远程 SSH 功能的工作原理 非常适合通过笔记本电脑远程工作。
  • 设置 tmux 或 screen 还有助于远程工作，以保留历史记录并在 Shell 中管理多个会话。
• Fuchsia 文档中提供了有关设置语言服务器的说明：
  • 适用于 C++ 的 clangd
  • 适用于 Rust 的 rust-analyzer
• 换行扩展非常适合自动将行换行到特定长度（例如在编辑 Markdown 文件时）。

• 如需为绑定金文件自动突出显示语法，请更新 file.associations 设置：

  "files.associations": {
        "*.json.golden": "json",
        "*.rs.golden": "rust",
        "*.cc.golden": "cpp",
        "*.h.golden": "cpp",
        "*.go.golden": "go",
        "*.dart.golden": "dart",
  },
  

提交消息样式指南

编写更改消息时，请遵循提交消息样式 指南。

C++ 风格指南

我们遵循 Fuchsia C++ 样式指南，并添加了其他规则，以进一步消除有关指南应用或解释的模糊性。

评论

注释必须符合 80 列的行大小限制，这一点与可扩展 不能超过 100 行。

Lambda 捕获

• 如果 lambda 转义当前作用域，则显式捕获所有变量。
• 如果 lambda 是本地的（不会逃出当前作用域），请优先使用默认的引用捕获（“[&]”）。

看到 [&] 即表示 lambda 仅存在于当前作用域内，并且可以 用于区分局部 lambda 和非本地 lambda。

// Correct.
std::set<const flat::Library*, LibraryComparator> dependencies;
auto add_dependency = [&](const flat::Library* dep_library) {
  if (!dep_library->HasAttribute("Internal")) {
    dependencies.insert(dep_library);
  }
};

基本设置

Fuchsia 设置

请先阅读 Fuchsia 入门指南。

fx set

如果您使用的是 FIDL 工具链，请使用：

fx set core.x64 --with //bundles/fidl:tests --with-base //src/dart:dart_jit_runner

必须使用 --with-base 标志才能运行 Dart 测试和基准测试。

如果您正在处理 LSC，请执行以下操作：

fx set terminal.x64 --with //bundles/kitchen_sink \

符号化工具

如需对回溯进行符号化处理，您需要在作用域内使用一个符号化程序：

export ASAN_SYMBOLIZER_PATH="$(find `pwd` -name llvm-symbolizer | grep clang | head -1)"

快速测试构建

FIDL 是系统内非常深层的部分，因此修改 FIDL 通常会导致 其中的微小变化可能引发数十万次重建 数千个编译操作和几分钟的构建。如果您只是尝试构建和运行一些 FIDL 测试，而不是整个系统，这种方法可能会很慢且很麻烦。

fx 工具支持按需发布范围较小的 build 和软件包，可帮助解决这种情况。如需启用它，请设置以下环境 变量（或等效项）：~/.bashrc

export FUCHSIA_DISABLED_incremental=0

编译和运行测试

我们主要提供一行代码来对各个部分运行测试。 如果有疑问，请参阅 git 提交消息中的“Test:”注释；我们会尽力在其中说明用于验证工作内容的命令。

测试使用 fidldev 工具运行。示例假定 fidldev 脚本位于 PATH 的某个位置，例如通过添加别名：

alias fidldev=$FIDLMISC_DIR/fidldev/fidldev.py

fidlc

# optional; builds fidlc for the host with ASan <https://github.com/google/sanitizers/wiki/AddressSanitizer>
fx set core.x64 --variant=host_asan

fx build host_x64/fidlc

如果您在 fidlc 上进行大量的修改-编译-测试周期，则减少优化步骤可以显著提高构建速度。为此，请将 zircon/public/gn/config/levels.gni 中的 optimization 设置从 default 更改为 debug 或 none。

为避免意外提交此更改，请运行以下命令：

git update-index --skip-worktree zircon/public/gn/config/levels.gni

如果要允许再次提交更改，请运行以下命令：

git update-index --no-skip-worktree zircon/public/gn/config/levels.gni

fidlc 测试

fidlc 测试位于以下位置：

• //tools/fidl/fidlc/{tests,goldens,testdata}。

如需构建并运行 fidlc 测试，请执行以下操作：

fx test //tools/fidl/fidlc

如果您希望直接使用 ninja，请执行以下操作：

fx_build_dir=$(cat .fx-build-dir) \
    fidlc_tests_target=$(fx ninja -C $fx_build_dir -t targets all | grep -e 'unstripped.*fidlc-test:' | awk -F : '{ print $1; }') \
    fx ninja -C $fx_build_dir $fidlc_tests_target && ./$fx_build_dir/$fidlc_tests_target

如需运行特定测试套件，请将 --gtest_filter 与适当的模式搭配使用。例如：

fx_build_dir=$(cat .fx-build-dir) \
    fidlc_tests_target=$(fx ninja -C $fx_build_dir -t targets all | grep -e 'unstripped.*fidlc-test:' | awk -F : '{ print $1; }') \
    fx ninja -C $fx_build_dir $fidlc_tests_target && ./$fx_build_dir/$fidlc_tests_target --gtest_filter 'EnumsTests.*'

fidlc 调试

为了在调试 build 中轻松运行测试，请以略微不同的方式设置您的环境：

fx set core.x64 --variant=host_asan --with //bundles/fidl:tests
export ASAN_SYMBOLIZER_PATH="$(find `pwd` -name llvm-symbolizer | grep clang | head -1)"

正确设置后，您可以使用之前列出的命令运行测试， 还是不过滤。

如需逐步执行测试，您可以使用 GDB：

fx_build_dir=$(cat .fx-build-dir) \
    fidlc_tests_target=$(fx ninja -C $fx_build_dir -t targets all | grep -e 'unstripped.*fidlc-test:' | awk -F : '{ print $1; }') \
    fx ninja -C $fx_build_dir $fidlc_tests_target && fx gdb --args ./$fx_build_dir/$fidlc_tests_target --gtest_filter 'AliasTests.invalid_recursive_alias'

fidlc 测试样式指南

使用 C++ 编写的所有 fidlc 编译器测试都必须符合以下规则：

• 使用 TEST 宏编写的测试必须采用 UpperCamelCase 格式的组名称，格式为 <CATEGORY>Tests。以及 UpperCamelCased 测试用例名称。 例如：TEST(BitsTests, GoodValidBits) {...。
• 测试用例名称不应以“Test”开头或结尾，因为这会造成重复。
• 测试解析和/或编译的测试用例名称必须带有前缀 以下项之一：
  • Good：测试用例预计会通过。例如：GoodValidMethod。
  • Bad：测试用例预计会通过。例如：BadMustBeDense。
  • Warn：预计何时通过测试用例，但使用报告程序 警告。在引入 新的检查，因此带有 Warn 前缀的测试应更改为 Good 或 Bad。例如：WarnTooManyProvidedLibraries。

此外，预计会遇到编译失败的测试用例应使用 ASSERT_ERRORED_DURING_COMPILE 和 ASSERT_ERRORED_TWICE_DURING_COMPILE 宏 。

fidlc goldens

如需重新生成 fidlc JSON 金标准，请执行以下操作：

fidldev regen fidlc

这些“黄金”是 JSON IR fidlc 生成哪些类型的文件， 来跟踪更改每次以任何方式更改 JSON IR 时，都必须重新生成金标准文件，否则 json_generator_tests 将失败。

fidlgen（新版 C++、HLCPP、Rust、Go、Dart）

构建：

fx build tools/fidl

运行以下命令：

$FUCHSIA_DIR/out/default/host_x64/fidlgen_{cpp,hlcpp,rust,go,dart}

以下是一些您可以运行的示例测试：

fx test fidlgen_hlcpp_golden_tests
fx test fidlgen_golang_lib_tests
fx test dart-bindings-test
fidldev test --no-regen fidlgen

如需重新生成金色，请执行以下操作：

fidldev regen fidlgen

fidlgen_banjo

构建：

fx build host_x64/fidlgen_banjo

运行测试：

fx build host_x64/fidlgen_banjo_unittests
./out/default/host_x64/fidlgen_banjo_unittests

绑定

fidldev 支持对每个绑定进行测试。部分绑定测试 在设备上运行，并要求在模拟器中运行 Fuchsia。具体步骤如下：

Tab 1> fx build && fx serve

Tab 2> fx qemu -kN

-k 标志用于启用 KVM。这不是必需项，但模拟器的速度要慢得多 没有它。-N 标志用于启用网络功能。

然后，您可以使用 fidldev 运行绑定测试：

fidldev test --no-regen hlcpp
fidldev test --no-regen llcpp
fidldev test --no-regen c
fidldev test --no-regen go
fidldev test --no-regen rust
fidldev test --no-regen dart

或者，运行 fidldev，而不用任何参数来测试已更改的文件：

fidldev test

如需运行特定测试或将标志传递给特定测试，请使用以下代码运行 fidldev： --dry-run、--no-build、--no-regen 标志以获取所需的测试 命令。

兼容性测试

如需详细了解兼容性测试的工作原理以及代码所在位置，请访问 （位于 //src/tests/fidl/compatibility）内的 README 文件中。

如需运行兼容性测试，您首先需要在模拟器中运行 Fuchsia：

Tab 1> fx build && fx serve

Tab 2> fx qemu -kN

如需运行兼容性测试，请执行以下操作：

Tab 3> fx set core.x64 --with //src/tests/fidl/compatibility
Tab 3> fx test fidl-compatibility-test

GIDL

如需重新构建 GIDL，请执行以下操作：

fx build host-tools/gidl

测量磁带

fx set core.x64 --with //tools/fidl/measure-tape/src:host
fx build

所有测试

本部分提供了用于运行所有与 FIDL 相关的测试的完整 fx test 命令。如果您想运行特定测试，请使用这些命令，而不是 fidldev test。

绑定测试

由于支持，设备端测试通常比主机测试的覆盖范围更大 以便在主机上运行部分功能。不过，主机测试 有助于调试阻止设备启动的问题。

已保存在设备上

主机

fidlgen 测试

其他

所有基准

基准测试可以直接运行，也可以通过以下两个测试运行程序之一运行：fuchsia_benchmarks（旧版），SL4F（新版）。

chromeperf 的基准测试目前通过 fuchsia_benchmarks 运行程序生成，但正在过渡到 SL4F。在此过渡期间，应在两个系统中集成基准测试。

直接运行基准测试

确保基准测试包含在 build 中：

fx set core.x64 --with //src/tests/benchmarks

您需要 fx build 并重启 qemu，才能使用这些软件包。

可用的基准测试：

使用 SL4F 基准测试运行程序运行所有基准测试

这与在 CQ 上运行基准的方式相同。 SL4F 需要 terminal.x64 产品。使用 fx set 切换产品：

fx set terminal.x64 --with //bundles/buildbot/terminal

如需运行所有 FIDL 测试，请使用以下命令：

fx test --e2e fidl_microbenchmarks_test

所有 regen 命令

本部分介绍了用于重新生成所有 FIDL 相关金文件的 fx check-goldens 命令。fidldev regen 在后台使用的就是它。

使用 ninja 进行编译

在某些情况下，GN 可能会构建许多不需要的目标。您可以使用 ninja 而非 GN 构建特定目标。在大多数情况下，您可以对二进制名称执行 grep 以确定 ninja 调用。

例如，您可以对 fidlgen_cpp 使用 grep：

fx ninja -C out/default -t targets all | grep -e 'fidlgen_cpp:'

此示例会输出一个 Ninja 目标列表，其中包括 host_x64/fidlgen_cpp。因此， 构建 fidlgen_cpp 运行以下 ninja 命令：

fx ninja -C out/default host_x64/fidlgen_cpp

调试（主机）

您可以通过多种方式调试主机二进制文件中的问题。本部分介绍了在 fidlc --files test.fidl 发生崩溃时应如何处理：

• GDB
• ASan
• Valgrind

GDB

首先，使用 cd 命令进入 build 目录。您也可选择入住 $FUCHSIA_DIR，但 则您需要在 GDB 中运行 dir out/default 来查找源文件。

cd $FUCHSIA_DIR/out/default

接下来，启动 GDB。系统上的副本可能会起作用，但预构建的 fx gdb 更有可能与 Fuchsia 项目中的 build 工件搭配使用。请参阅 fx gnu --help：获取预构建 GNU 工具的完整列表。

fx gdb --args host_x64/exe.unstripped/fidlc --files test.fidl

然后，输入“r”以启动程序。如需了解其他用法以及方便快速查阅，我们发现此 GDB 备忘单非常有用。

ASan

确保在启用 ASan 的情况下进行编译：

fx set core.x64 --variant=host_asan
fx build host_x64/fidlc

然后运行 out/default/host_x64/fidlc --files test.fidl。该二进制文件应该是 与 out/default/host_x64-asan/fidlc 相同。

Valgrind

在 Google Linux 计算机上，您可能需要安装标准版本的 Valgrind，而不是使用预安装的二进制文件：

sudo apt-get install valgrind

然后：

valgrind -v -- out/default/host_x64/exe.unstripped/fidlc --files test.fidl

工作流

访问 fuchsia.io 和 fuchsia.net

如需更新所有已保存的 fidlgen 文件，请运行以下命令： 该命令会自动搜索并生成必要的 go 文件：

fx exec $FUCHSIA_DIR/third_party/go/regen-fidl

常见问题解答

为什么 C 后端与所有其他后端不同？

当前的 C 绑定已废弃。如需了解详情，请参阅 https://fxbug.dev/42159192 有关未来在 C 中使用 FIDL 的信息。

为什么所有后端都没有在一个工具中？

实际上，我们希望所有后端都位于不同的工具中！

日后，我们计划针对所有各种工具（fidlc、fidlfmt、各种后端）编写一个脚本，以便轻松访问所有内容，并管理这些内容的链接。例如，应该可以在一个命令中生成 Go 绑定，例如：

fidl gen --library my_library.fidl --binding go --out-dir go/src/my/library

或者，使用以下代码设置库的格式：

fidl fmt --library my_library.fidl -i