本頁面由 Cloud Translation API 翻譯而成。

為 FIDL 貢獻心力

總覽

FIDL 工具鍊由大約三個部分組成：

前端，又稱 fidlc
- 剖析及驗證 .fidl 檔案
- 計算不同結構體的大小、對齊方式及偏移
- 產生 JSON IR (中級表示法)
後端
- 可在紅外線運作 (C 後端除外)
- 產生指定語言專屬程式碼，並與該語言的程式庫連結。
執行階段程式庫
- 實作訊息的編碼/解碼/驗證作業
- 方法調度機制

程式碼位置

編譯器前端

前端位於 //tools/fidl/fidlc/，並使用 //tools/fidl/fidlc/tests 中的測試。

編譯器後端

目標	Codegen	執行階段程式庫	測試
HLCPP (舊)	/tools/fidl/fidlgen_hlcpp	/sdk/lib/fidl/cpp	(與執行階段程式庫一併提供)
全新 C++	/tools/fidl/fidlgen_cpp	/sdk/lib/fidl/cpp	/src/lib/fidl/llcpp 和 /src/lib/fidl/cpp
查看	/tools/fidl/fidlgen_go	/third_party/go/src/syscall/zx/fidl	(與執行階段程式庫一併提供)
Rust	/tools/fidl/fidlgen_rust	/src/lib/fidl/rust	(與執行階段程式庫一併提供)

目標特定後端的支援程式碼位於 /tools/fidl/lib/fidlgen。

測試工具

GIDL

GIDL 這項工具可用於建立一般「寫入一次，為每個後端產生」程式。目前 GIDL 是用於產生編碼或解碼測試 (「一致性測試」) 和基準測試。

路徑	說明
/tools/fidl/gidl	GIDL 工具本身的原始碼和建構範本。
/src/tests/fidl/conformance_suite	測試一致性測試的定義 (`.fidl` 和 `.gidl` 檔案)。
/sdk/ctf/tests/pkg/fidl/cpp/test/{test,handle}_util.h	支援 HLCPP 一致性測試的執行階段。
/src/lib/fidl/llcpp/tests/conformance/conformance_utils.h	針對 C++ 線型類型一致性測試的執行階段支援。
/src/lib/fidl/rust/gidl_util	Rust 一致性測試的執行階段支援。
/third_party/go/src/syscall/zx/fidl/fidl_test	支援 Go 合法性測試的執行階段。
/src/tests/benchmarks/fidl/benchmark_suite	基準定義 (`.fidl` 和 `.gidl` 檔案)。
/src/tests/benchmarks/fidl	支援基準測試的執行階段。

每個後端中符合性測試的實際測試目標通常會與該後端的相應測試一起定義。詳情請參閱繫結測試一節。

相容性

相容性測試是整合測試，使用不同繫結執行 FIDL 用戶端和伺服器，以便測試是否相容。如需相容性測試，請前往 /src/tests/fidl/compatibility/。

危險 ID

您可以在 /src/tests/fidl/dangerous_identifiers 中找到危險的 ID 測試。

其他

其他 FIDL 相關領域如下：

路徑	目錄
/tools/fidl/fidlgen_*	其他編譯器後端。
/tools/fidl/fidlc/cmd/fidl-format	FIDL 格式器。
/tools/fidl/fidlc/cmd/fidl-lint	FIDL Linter。
/tools/fidl/fidldoc	產生 FIDL 的說明文件。
/tools/fidl/fidlmerge	用於從 FIDL JSON 產生程式碼的工具。
/tools/fidl/measure-tape	用於避免分頁上限的工具。
/tools/fidl/scripts	通常是一次性指令碼，例如執行遷移作業保留供日後參考的一次性指令碼。
/src/lib/fostr	以 `fidlmerge` 為基礎的工具，以 C++ 產生格式設定程式碼。
/src/lib/fostr/build	建立 `fostr` 格式資料庫的範本。
/src/lib/fidl_codec	用於編碼/解碼 FIDL 訊息的程式庫 (由 `fidlcat` 使用)。

其他 FIDL 工具

許多 FIDL 工具位於 fidl-misc 存放區中。如要複製這個存放區，請執行

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

因此，建議您匯出路徑至這個目錄，以便輕鬆設定別名：

export FIDLMISC_DIR=...

常見的開發工具

這是 FIDL 團隊提供的群眾外包區段，旨在說明他們用於 FIDL 程式碼集的實用工具。

IDE

大部分的 FIDL 團隊都使用 VS Code 進行開發。以下是一些實用的外掛程式和工作流程：

遠端 SSH 功能非常適合使用筆記型電腦進行遠端工作。
- 設定 tmux 或螢幕也有助於遠端工作，從而保存記錄，以及在殼層中管理多個工作階段。
Fuchsia 說明文件提供設定語言伺服器的操作說明：
- 適用於 c++ 的 clangd
- rust-analyzer，用於 Rust
重新包裝擴充功能適用於將行自動重排到特定長度 (例如在編輯 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。

// 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 測試，而不是整個系統，這可能變得很緩慢且麻煩。

fx 工具支援隨選範圍的隨選建構作業和套件發布作業，可協助您處理這種情況。如要啟用這項功能，請在 ~/.bashrc (或同等變數) 中設定下列環境變數：

export FUCHSIA_DISABLED_incremental=0

編譯及執行測試

我們主要提供單行程式碼測試各個部分。如有任何問題，請參閱 Git 修訂版本訊息中的「Test:」註解。我們會盡可能描述用於驗證作業的指令。

測試會使用 fidldev 工具執行。我們假設 fidldev 指令碼位於路徑上的某處，例如新增別名：

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` 偵錯

如要在偵錯版本中輕鬆執行測試，請略為設定您的環境：

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 巨集編寫的測試必須有採用 <CATEGORY>Tests 格式的 UpperCamelCased 群組名稱。和 UpperCamelCased 測試案例名稱。例如：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

這些「黃金」檔案是 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

如要執行特定測試或將標記傳送至特定測試，請使用 --dry-run、--no-build、--no-regen 標記執行 fidldev，取得所需的測試指令。

相容性測試

如要進一步瞭解相容性測試的運作方式，以及程式碼的位置，請參閱 //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

所有測試

本節提供完整的 fx test 指令，可用於執行所有 FIDL 相關測試。如要執行特定測試，請使用這些測試，而不是 fidldev test。

繫結測試

由於裝置端測試僅支援在主機上執行部分功能，因此裝置測試的涵蓋範圍通常大於主機測試。不過，對於妨礙裝置啟動的問題進行偵錯，主機測試可能就非常實用。

裝置中

名稱	測試指令	涵蓋率
c 執行階段測試、編碼資料表	`fx test fidl_c_tests`	//sdk/lib/fidl_base
Walker, misc	`fx test fidl-walker-tests`	//sdk/lib/fidl_base
步行者測試 (可處理封閉檢查)	`fx test fidl-handle-closing-tests`	//sdk/lib/fidl_base
hlcpp 繫結測試，包括合規測試	`fx test fidl_hlcpp_unit_test_package fidl_hlcpp_conformance_test_package`	//sdk/lib/fidl
全新 C++ 線路測試	`fx test //src/lib/fidl/llcpp`	//sdk/lib/fidl/cpp/wire
新的 C++ 測試	`fx test //src/lib/fidl/cpp`	//src/lib/fidl/cpp
go 繫結測試	`fx test go-fidl-tests`	//third_party/go/syscall/zx/fidl //third_party/go/syscall/zx/fidl/fidl_test //src/tests/fidl/go_bindings_test
Rust 繫結測試	`fx test //src/lib/fidl/rust`	//src/lib/fidl/rust

主機

名稱	測試指令	涵蓋率
Walker, misc	`fx test --host fidl-walker-host-tests`	//sdk/lib/fidl_base
hlcpp 單元測試	`fx test --host fidl_hlcpp_unit_tests`	//sdk/lib/fidl
hlcpp 符合性測試	`fx test --host fidl_hlcpp_conformance_tests`	//sdk/lib/fidl
C++ 線型合規性測試	`fx test --host fidl_llcpp_conformance_tests`	//sdk/lib/fidl/cpp/wire
C++ 自然類型一致性測試	`fx test --host fidl_cpp_conformance_tests`	//src/lib/fidl/cpp
rust 合規性測試	`fx test --host fidl_rust_conformance_tests`	//src/lib/fidl/rust
rust fidl lib 測試	`fx test --host fidl_rust_lib_tests`	//src/lib/fidl/rust
GO 合規性測試	`fx test --host fidl_go_conformance_tests`	//third_party/go/syscall/zx/fidl
go fidl 測試 (擴充)	`fx test --host go_extended_fidl_test`	//third_party/go/syscall/zx/fidl
前往不安全的值測試	`fx test --host go_unsafevalue_test`	//third_party/go/syscall/zx/fidl/internal/unsafevalue

宗旨測試

名稱	測試指令	涵蓋率
fidlgen 類型定義	`fx test fidlgen_lib_test`	//tools/fidl/lib/fidlgen
fidlgen C++ 特定 IR	`fx test fidlgen_cpp_ir_test`	//tools/fidl/lib/fidlgen_cpp
fidlgen hlcpp	`fx test fidlgen_hlcpp_golden_tests`	//tools/fidl/fidlgen_hlcpp
fidlgen 全新 C++	`fx test fidlgen_cpp_golden_tests`	//tools/fidl/fidlgen_cpp
費德金戈蘭	`fx test fidlgen_go_{lib,golden}_tests`	//tools/fidl/fidlgen_golang
Fidlgen Rust	`fx test fidlgen_rust_{lib,golden}_tests`	//tools/fidl/fidlgen_rust
Fidlgen Syzkaller	`fx test fidlgen_syzkaller_golden_tests`	//tools/fidl/fidlgen_syzkaller

其他

名稱	測試指令	涵蓋率
fidlc 編譯器	`fx test fidlc-test` `fx test fidlc_golden_tests`	//tools/fidl/fidlc
gidl 剖析器	`fx test gidl_parser_test`	//tools/fidl/gidl/parser
測量捲尺測試	`fx test measure-tape_test`	//tools/fidl/measure-tape
Rust IR 剖析器	`fx build`	//src/devices/tools/fidlgen_banjo/tests/parser

所有基準

基準測試可以直接執行，也可透過以下兩個測試執行者之一執行：fuchsia_benchmarks (舊版)、SL4F (新)。

chromeperf 的基準目前是透過 fuchsia_benchmarks 執行元件產生，但即將轉換至 SL4F。在此轉換期間，兩個系統都應該整合基準測試。

直接執行基準測試

確認您的版本包含基準測試：

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

您必須 fx build 並重新啟動 qemu，才能使用套件。

可用的基準：

名稱	基準指令	附註
Go 基準	`fx shell /bin/go_fidl_microbenchmarks`
Rust 基準	`fx shell /bin/rust_fidl_microbenchmarks /tmp/myresultsfile`	你可以使用「`fx shell cat /tmp/myresultsfile/`」查看結果
C++ 線型類型基準	`fx shell /bin/llcpp_fidl_microbenchmarks`
lib/fidl 基準	`fx shell /bin/lib_fidl_microbenchmarks`
往返基準	`fx shell /bin/roundtrip_fidl_benchmarks`

使用 SL4F 基準執行元件執行所有基準測試

這執行基準測試的方式與在 CQ 上執行的方式相同。SL4F 需要 terminal.x64 產品。使用 fx set 切換產品：

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

如要執行所有 FIDL 測試，請使用：

fx test --e2e fidl_microbenchmarks_test

所有重新產生指令

本節提供 fx check-goldens 指令，可重新產生所有 FIDL 相關的 Golden 檔案。這是 fidldev regen 實際使用的方式。

名稱	重新產生指令	輸入	輸出內容
(所有金色)	FX Check-goldens
費德克金斯	Fx check-goldens fidlc	tools/fidl/fidlc/testdata	tools/fidl/fidlc/goldens
費德金金斯	外匯支票 $TOOL	tools/fidl/fidlc/testdata	tools/fidl/$TOOL/goldens
費德菲克黃金斯	FX check-goldens fidldoc	tools/fidl/fidlc/testdata	tools/fidl/fidldoc/goldens
鍍金金黃	FX 打勾	src/tests/fidl/conformance_suite/golden{.gidl,.test.fidl}	tools/fidl/gidl/goldens
第三方 Go	fx 主管 $FUCHSIA_DIR/third_party/go/regen-fidl

使用 `ninja` 進行編譯

在某些情況下，GN 可以建立許多不需要的目標。您可以不使用 GN 而使用 ninja 建構特定目標。在多數情況下，您可以 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 至建構目錄。您也可以保留 $FUCHSIA_DIR，但必須在 GDB 中執行 dir out/default，才能尋找來源檔案。

cd $FUCHSIA_DIR/out/default

接著，請啟動 GDB。系統上的副本也許可以使用，但預先建構的 fx gdb 較有可能使用 Fuchsia 專案中的建構構件。如需預先建構的 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 相同。

瓦格林德

在 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

為 FIDL 貢獻心力

總覽

程式碼位置

編譯器前端

編譯器後端

測試工具

GIDL

相容性

危險 ID

其他

其他 FIDL 工具

常見的開發工具

IDE

修訂訊息樣式指南

C++ 樣式指南

留言

Lambda 拍攝

一般設定

Fuchsia 設定

fx set

符號化工具

快速測試版本

編譯及執行測試

fidlc

fidlc 項測試

fidlc 偵錯

fidlc 測試樣式指南

fidlc 金黃

fidlgen (新 C++、HLCPP、Rust、Go、Dart)

fidlgen_banjo

繫結

相容性測試

GIDL

測量捲尺

所有測試

繫結測試

裝置中

主機

宗旨測試

其他

所有基準

直接執行基準測試

使用 SL4F 基準執行元件執行所有基準測試

所有重新產生指令

使用 ninja 進行編譯

偵錯 (主機)

GDB

ASan

瓦格林德

工作流程

前往 fuchsia.io 和 fuchsia.net

常見問題

為什麼 C 後端與所有其他後端不同？

為什麼不是將所有後端都彙整到單一工具？

`fx set`

`fidlc`

`fidlc` 項測試

`fidlc` 偵錯

`fidlc` 測試樣式指南

`fidlc` 金黃

使用 `ninja` 進行編譯