为 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 文档中提供了有关设置语言服务器的说明：
  • clangd for c++
  • 适用于 Rust 的 rust-analyzer
• rewrap 扩展程序可用于自动将行重排到特定长度（例如，在修改 Markdown 文件时）。

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

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

提交消息样式指南

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

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 \

symbolizer

如需对回溯进行符号化处理，您需要一个范围内的符号化工具：

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

快速测试 build

FIDL 是系统的一个非常深层的部分，因此修改它通常会导致“重建世界”，微小的更改可能会触发数万个编译操作和长达数分钟的构建。如果您只是想构建和运行一些 FIDL 测试，而不是整个系统，这可能会很慢且很繁琐。

fx 工具支持按需、小范围构建和软件包发布，可帮助您应对这种情况。如需启用此功能，请在 ~/.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。以及采用大驼峰式命名法的测试用例名称。 例如：TEST(BitsTests, GoodValidBits) {...。
• 测试用例名称不应以“Test”开头或结尾，因为这属于冗余信息。
• 测试解析和/或编译的测试用例名称必须带有以下前缀之一：
  • Good：测试用例预计通过时。例如：GoodValidMethod。
  • Bad：测试用例预计通过时。例如：BadMustBeDense。
  • Warn：测试用例预计会通过，但会显示报告程序警告。警告旨在在引入新检查时临时使用，因此在移除检查时，应将前缀为 Warn 的测试更改为 Good 或 Bad。例如：WarnTooManyProvidedLibraries。

此外，如果测试用例预期会出现编译失败，则应在预期会出现一个和两个错误时分别使用 ASSERT_ERRORED_DURING_COMPILE 和 ASSERT_ERRORED_TWICE_DURING_COMPILE 宏。

fidlc 个黄金级

如需重新生成 fidlc JSON 黄金文件，请运行以下命令：

fidldev regen fidlc

这些“黄金”文件是 fidlc 生成的 JSON IR 类型的示例，用于跟踪更改。每次以任何方式更改 JSON IR 时，都需要重新生成黄金标准文件，否则 json_generator_tests 会失败。

fidlgen（新 C++、HLCPP、Rust）

构建：

fx build tools/fidl

运行以下命令：

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

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

fx test fidlgen_hlcpp_golden_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 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

所有重新生成命令

本部分提供了用于重新生成所有与 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 工件搭配使用。如需查看预构建 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

常见问题解答

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

当前的 C 绑定已弃用。如需详细了解在 C 语言中使用 FIDL 的未来发展，请参阅 https://fxbug.dev/42159192。

为什么不将所有后端整合到一个工具中？

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

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

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

或者，使用以下命令就地设置库的格式：

fidl fmt --library my_library.fidl -i