總覽
FIDL 工具鍊大致由三個部分組成:
- 前端 (又稱
fidlc
)- 剖析並驗證
.fidl
檔案 - 計算各種結構的大小、對齊方式和偏移
- 產生 JSON IR (中介表示法)
- 剖析並驗證
- 後端
- 可在 IR 外運作 (C 後端除外)
- 產生目標語言專屬程式碼,並連結至該語言的程式庫
- 執行階段程式庫
- 實作訊息的編碼/解碼/驗證
- 方法調度機制
程式碼位置
編譯器前端
前端位於 //tools/fidl/fidlc/,測試則位於 //tools/fidl/fidlc/tests。
編譯器後端
目標 | Codegen | 執行階段程式庫 | 測試 |
---|---|---|---|
HLCPP (舊版) | /tools/fidl/fidlgen_hlcpp | /sdk/lib/fidl/hlcpp | (位於執行階段程式庫旁邊) |
新 C++ | /tools/fidl/fidlgen_cpp | /sdk/lib/fidl/cpp | /src/lib/fidl/llcpp 和 /sdk/lib/fidl/cpp |
查看 | /tools/fidl/fidlgen_go | /third_party/go/src/syscall/zx/fidl | (位於執行階段程式庫旁邊) |
荒漠油廠 | /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-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
測試位於:
如要建構及執行 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
。
繫結測試
由於只支援在主機上執行部分功能,因此裝置端測試的涵蓋率通常高於主機測試。不過,主機測試對於偵錯導致裝置無法啟動的相關問題相當實用。
裝置上
名稱 | 測試指令 | 涵蓋率 |
---|---|---|
c 執行階段測試,編碼表 | fx test fidl_c_tests |
//sdk/lib/fidl_base |
walker, misc | fx test fidl-walker-tests |
//sdk/lib/fidl_base |
使用處理關閉檢查的 walker 測試 | 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 //sdk/lib/fidl/cpp |
//sdk/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 |
//sdk/lib/fidl/cpp |
Rust 相容性測試 | fx test --host fidl_rust_conformance_tests |
//src/lib/fidl/rust |
rust fidl 程式庫測試 | 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 |
go unsafevalue 測試 | fx test --host go_unsafevalue_test |
//third_party/go/syscall/zx/fidl/internal/unsafevalue |
fidlgen 測試
名稱 | 測試指令 | 涵蓋率 |
---|---|---|
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 |
fidlgen golang | 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 相關的黃金檔案。這是 fidldev regen
在背景中使用的內容。
名稱 | 再生指令 | 輸入 | 輸出 |
---|---|---|---|
(所有金色) | fx check-goldens | ||
fidlc goldens | fx check-goldens fidlc | tools/fidl/fidlc/testdata | tools/fidl/fidlc/goldens |
Fidlgen Golden | fx check-goldens $TOOL | tools/fidl/fidlc/testdata | tools/fidl/$TOOL/goldens |
fidldoc 金標 | fx check-goldens fidldoc | tools/fidl/fidlc/testdata | tools/fidl/fidldoc/goldens |
gidl goldens | fx check-goldens gidl | src/tests/fidl/conformance_suite/golden{.gidl,.test.fidl} | tools/fidl/gidl/goldens |
third party go | fx exec $FUCHSIA_DIR/third_party/go/regen-fidl |
使用 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
首先,將 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