為 FIDL 貢獻心力

總覽

FIDL 工具鏈大致由三個部分組成：

1. 前端，又稱為 fidlc
   • 剖析及驗證 .fidl 檔案
   • 計算各種結構物的大小、對齊方式和偏移
   • 產生 JSON IR (中介表示法)
2. 後端
   • 順暢運作 (C 後端除外)
   • 產生譯文語言專屬程式碼，並與該語言的程式庫建立關聯
3. 執行階段程式庫
   • 實作訊息的編碼/解碼/驗證
   • 方法調度機制

程式碼位置

編譯器前端

前端位於 //tools/fidl/fidlc/， //tools/fidl/fidlc/tests 中的測試

編譯器後端

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

測試工具

GIDL

GIDL 是用來建立一般「寫入一次，為每個後端產生的」工具 計畫。目前 GIDL 會用於產生編碼或解碼測試 (「相容性測試」) 以及基準測試。

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

相容性

相容性測試是執行 FIDL 用戶端的整合測試 以及不同繫結的伺服器 彼此相容如要查看相容性測試，請前往 /src/tests/fidl/compatibility/。

危險 ID

發現危險 ID 測試的位置 /src/tests/fidl/dangerous_identifiers.

其他

其他與 FIDL 相關的領域包括：

其他 FIDL 工具

您可以在 fidl-misc 存放區中找到許多 FIDL 工具。目的地： 複製這個存放區，執行

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

隨後，建議將路徑匯出到這個目錄，以進行設定 別名：

export FIDLMISC_DIR=...

常見的開發工具

這是 FIDL 團隊的群眾外包工具，專門提供實用工具 用於處理 FIDL 程式碼集

IDE

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

• 遠端 SSH 功能可以正常運作 非常適合使用筆電進行遠距工作
  • 設定 tmux 或 screen 也有助於遠端工作，可保留記錄並在殼層中管理多個工作階段。
• Fuchsia 說明文件提供語言設定伺服器的操作說明：
  • 適用於 C++ 的 clangd
  • rust-analyzer (信任)
• rewrap 擴充功能可用於自動將行重新流動至特定長度 (例如編輯 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++ 樣式指南，其中包含額外的規則 進一步釐清有關應用程式或指南解讀方式的混淆。

留言

與可擴充至 100 行大小限制的程式碼不同，註解必須遵守 80 欄的每行字數上限。

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 工具支援隨選且小範圍的建構和套件發布作業， 協助解決此問題如要啟用此功能，請在 ~/.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 偵錯

如要輕鬆在偵錯版本中執行測試，請稍微調整環境設定：

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 格式的大寫駝峰式群組名稱。以及大寫駝峰式測試案例名稱。例如：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 (New 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。

繫結測試

由於支援，裝置端測試的涵蓋範圍通常大於主機測試 執行某些功能不過，主機測試對於偵錯導致裝置無法啟動的相關問題相當實用。

裝置上

舉辦派對

纖維素測試

其他

所有基準

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

chromeperf 的基準資料目前是透過 fuchsia_benchmarks 執行程式產生，但正在轉換至 SL4F。在這個過渡期間，基準測試應整合至兩個系統。

直接執行基準測試

請確認基準測試已納入建構：

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

所有再生指令

本節提供 fx check-goldens 指令，以便重新產生所有與 FIDL 相關的黃金檔案。這是 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 至建構目錄。你也可以繼續停留在$FUCHSIA_DIR，但 您必須在 GDB 中執行 dir out/default，才能找出來源檔案。

cd $FUCHSIA_DIR/out/default

接著，啟動 GDB。系統中的副本可能可運作，但預先建構的 fx gdb 更有可能與 Fuchsia 專案中的建構構件搭配運作。詳情請見 fx gnu --help 提供完整的預建 GNU 工具清單。

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

然後輸入「r」啟動程式。其他用途 快速參考我們找到的 GDB Cheat 試算表非常實用。

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

工作流程

Go 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