為 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

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

其他

其他與 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 (適用於 Rust)
• rewrap 擴充功能可用於自動將行重新排版至特定長度 (例如編輯 Markdown 檔案時)。

• 如要為繫結金文件自動標示語法，請更新 file.associations 設定：

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

修訂版本訊息格式指南

撰寫變更訊息時，請遵循修訂版本訊息格式指南。

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-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 巨集編寫的測試必須具有 <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

這些「黃金」檔案是 fidlc 產生的 JSON IR 範例，可用於追蹤變更。每次以任何方式變更 JSON IR 時，都必須重新產生黃金檔案，否則 json_generator_tests 會失敗。

fidlgen (New 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 中的 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 叫用。

例如，您可以將 grep 替換為 fidlgen_cpp：

fx ninja -C out/default -t targets all | grep -e 'fidlgen_cpp:'

這個範例會輸出包含 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

工作流程

Go 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