為 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/。

危險 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 適用：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。

// 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)"

快速測試版本

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 巨集編寫的測試必須採用 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 的 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。

繫結測試

由於主機僅支援執行部分功能，因此裝置端測試的涵蓋範圍通常比主機端測試更廣。不過，主機測試可用於偵錯，解決裝置無法啟動的問題。

裝置上

主機

fidlgen 測試

其他

所有基準

基準測試可以直接執行，也可以透過下列其中一個測試執行工具執行：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 專案中的建構構件搭配運作。如需預建 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