本文件說明 Google 在平台來源樹狀結構中開發 Fuchsia IDK 時採用的標準。本文件的部分內容可能對 Fuchsia SDK 的用戶端感興趣,但本文件的主要重點在於 Fuchsia 專案開發 SDK 的方式。
管理事宜
Fuchsia IDK 的內容受 Fuchsia API 委員會規範。IDK 不包含在 Fuchsia 專案之外開發的元素 (程式庫、工具、圖片等),因為這些程式庫不受 Fuchsia API 委員會的管理規範。
除非外部程式庫已獲得 Fuchsia API 委員會核准,否則 IDK 中的用戶端程式庫不會依附 IDK 以外的程式庫。一般而言,除非依附元件設有嚴格的演進標準 (例如各種支援的語言的標準程式庫),否則委員會不會核准依附元件。
範例:Google 測試
Fuchsia IDK 不包括 Google Test 程式庫,因為 Google Test 程式庫的管理是由 Google 提供,而非 Fuchsia API 委員會。
Fuchsia IDK 不會依附於 Google Test 程式庫,因為 Google Test 程式庫的管理主體所做出的承諾與 Fuchsia IDK 使用的模型不相容。
Fuchsia 系統介面
Fuchsia 系統介面定義於 Fuchsia 系統介面中。一般而言,系統的二進位檔介面只是程式使用的 FIDL 傳輸格式,用於與系統和 libzircon
中公開的系統呼叫。
FIDL 通訊協定定義
二進位檔穩定性
FIDL 通訊協定是在 SDK 中的 .fidl
檔案中定義。所有在 IDK 中發布的 FIDL 定義都應視為系統的公開 ABI。系統也可能包含尚未在 IDK 中發布的其他 FIDL 定義。這些定義隨時可能變更,恕不另行通知,而且在日後的系統版本中可能無法正確運作,依賴 ABI 的程式。
來源穩定性
IDK 中的 FIDL 定義可能會以與來源不相容的方式發展。舉例來說,我們可能會在通訊協定中重新命名方法,同時保留其序數和語意 (您可以新增設定為原始名稱的 Selector
屬性來維護序數)。這項變更可以保留 ABI,但會破壞來源相容性。
針對何時應破壞來源相容性,我們目前還沒有任何標準。
命名
公開 FIDL 定義位於 //sdk/fidl/$LIBRARY_NAME
的來源樹狀結構中。目標名稱應為程式庫的名稱。
樣式
IDK 中的 FIDL 定義應符合 FIDL API 樣式的評分量表。
用戶端程式庫
Fuchsia IDK 包含多個「用戶端程式庫」(整合 IDK 的 SDK 用戶端可以連結至其程式的程式庫)。這些用戶端程式庫都是選用性質,僅供用戶端使用,並非供系統使用。系統不得仰賴使用任何特定用戶端程式庫的程式。請注意,libc
是用戶端程式庫 (不是系統程式庫)。
穩定性與包裝
只有 Fuchsia 系統介面是 ABI 穩定版。用戶端程式庫並非 API 或 ABI 穩定版。二進位檔和程式庫必須與其連結的用戶端程式庫使用相同的 IDK 版本進行建構。
除 Fuchsia 系統介面以外的程式連結 (包括用戶端程式庫) 的所有程式庫,都必須納入程式套件中。動態程式庫應放在程式套件的 lib
目錄中。
套件是軟體流動、推送和連結的單位。不同套件可包含相同程式庫的不同版本。執行程式時,系統會向該程式庫提供本身的套件,防止不同套件使用的不同程式庫,避免在同一個程式中發生衝突。
預先編譯的程式庫
Fuchsia IDK 不會要求客戶使用特定工具鍊。因此,預先編譯的用戶端程式庫必須具備 C 連結。舉例來說,預先編譯的用戶端程式庫無法匯出 C++ 符號,因為 C++ 沒有跨工具鍊 (甚至是工具鍊版本) 的標準 ABI。
依附元件
如果用戶端需要用戶端程式庫的依附元件,也必須採用該程式庫所有依附元件的依附元件。因此,用戶端程式庫應最少有依附元件。舉例來說,用戶端程式庫應避免使用依附元件,避免依附於 FBL、FXL、FSL 或其他不在 SDK 中的「基礎」程式庫。
需要執行非同步作業的用戶端程式庫應依附於 libasync.a
和 libasync-default.so
。但這些程式庫不應假設用戶端使用任何特定 async_dispatcher_t*
實作。舉例來說,這些程式庫不應假設 async_dispatcher_t*
實際上是由 libasync-loop.a
實作。需要填入 async_get_default_dispatcher
的程式庫應在說明文件中聲明這項規定。
如果預先編譯的程式庫在用戶端隱藏這些依附元件,就能擁有更多依附元件。例如,預先編譯的共用程式庫不應從這些依附元件匯出符號,且不應包含會暫時納入這些依附元件的標頭。
命名
請根據用戶端程式庫用戶端使用的語言命名用戶端程式庫。舉例來說,$NAME
程式庫的 C++ 變化版本應位於 //sdk/lib/$NAME/cpp
下方的來源樹狀結構中。C 變化版本只要位於 //sdk/lib/$NAME
下方。
樣式
用戶端程式庫應遵循 Fuchsia 樣式指南中撰寫的語言。
記錄
用戶端程式庫應避免記錄訊息。相反地,用戶端程式庫應將錯誤傳回給用戶端,由其判斷是否要記錄錯誤。
斷言
C 和 C++ 用戶端程式庫應使用 <zircon/assert.h>
中定義的 ZX_DEBUG_ASSERT
和 ZX_ASSERT
來宣告不變。用戶端程式庫也可能會使用 _MSG
變體,在斷言失敗時提供訊息。
用戶端程式碼建議
C
Fuchsia 系統介面使用開頭為 zx_
和 fuchsia_
的符號,以及前置字串為 ZX_
和 FUCHSIA_
的預先處理器巨集。為避免衝突,這些前置字串僅供 Fuchsia IDK 使用。Fuchsia IDK 的用戶端不應透過這些前置字串宣告符號或預先處理工具巨集。
C++
Fuchsia 系統介面中包含的 FIDL 通訊協定位於頂層 fuchsia
命名空間中。為避免衝突,這個命名空間保留給 Fuchsia IDK 使用。Fuchsia IDK 的用戶端不應在頂層 fuchsia
命名空間中宣告名稱。