为 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",
  },
  

提交消息风格指南

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

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-test //bundles/fidl:tests

如果您使用的是 LSC，请执行以下操作：

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

符号化工具

如需对回溯进行符号化处理，您需要在范围内使用符号化程序：

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

快速测试 build

FIDL 是系统中根深蒂固的一部分，因此修改它通常会导致“重建整个世界”，进行细微更改可能会触发数万个编译操作，并且需要数分钟才能完成 build。如果您只是尝试构建和运行一些 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。以及采用 UpperCamelCase 格式的测试用例名称。例如：TEST(BitsTests, GoodValidBits) {...。
• 测试用例名称不应以“Test”开头或结尾，因为这会造成重复。
• 用于测试解析和/或编译的测试用例名称必须以以下某个前缀开头：
  • Good：测试用例预计会通过。例如：GoodValidMethod。
  • Bad：测试用例预计会通过。例如：BadMustBeDense。
  • Warn：当测试用例预计会通过，但存在报告程序警告时。警告旨在引入新检查时暂时使用，因此在移除检查后，应将前缀为 Warn 的测试更改为 Good 或 Bad。例如：WarnTooManyProvidedLibraries。

此外，如果预期编译失败，则测试用例应分别使用 ASSERT_ERRORED_DURING_COMPILE 和 ASSERT_ERRORED_TWICE_DURING_COMPILE 宏（分别预期出现 1 个和 2 个错误）。

fidlc goldens

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

fidldev regen fidlc

这些“金标准”文件展示了 fidlc 会生成什么类型的 JSON IR，并用于跟踪更改。每次以任何方式更改 JSON IR 时，都必须重新生成金标准文件，否则 json_generator_tests 将失败。

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

构建：

fx build tools/fidl

运行以下命令：

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

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

fx test fidlgen_hlcpp_golden_tests
fx test fidlgen_golang_lib_tests
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 来测试已更改的文件：

fidldev test

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

兼容性测试

如需详细了解兼容性测试的运作方式以及代码所在的位置，请参阅 //src/tests/fidl/compatibility 中的自述文件。

如需运行兼容性测试，您首先需要在模拟器中运行 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 调用。

例如，您可以将 grep 替换为 fidlgen_cpp：

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 工件搭配使用。如需查看预构建 GNU 工具的完整列表，请参阅 fx gnu --help。

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 绑定已废弃。如需详细了解未来如何在 C 中使用 FIDL，请参阅 https://fxbug.dev/42159192。

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

我们实际上希望所有后端都使用单独的工具！

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

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

或者，使用以下命令就地格式化库：

fidl fmt --library my_library.fidl -i