RFC-0268：SDK 類別更新

RFC-0268：SDK 類別更新
狀態已接受
區域
  • 開發人員
說明

更新 SDK 類別組合並說明其意義。
問題
Gerrit 變更
作者
審查人員
提交日期 (年-月-日)2025-02-20
審查日期 (年-月-日)2025-04-02

編輯這份 RFC

編輯 RFC 中繼資料

問題陳述

更新 RFC-0165 中記錄的 SDK 類別組合，反映目前的使用情況並釐清意義。

摘要

這項 RFC 會變更 SDK 類別的集合，並更新所有 SDK 類別的意義和用途說明。這些類別會取代 RFC-0165 中記錄的 SDK 類別。「設計」一節中的類別詳細資料可做為SDK 類別說明文件的更新依據。

利害關係人

協助人員：neelsa@google.com

審查者：

  • 平台版本控管：hjfreyer@google.com
  • 開發人員：wilkinsonclay@google.com
  • 測試：crjohns@google.com

社交：

這份 RFC 中的變更是由平台版本管理團隊提議並討論。問題 367760026 和相關問題中討論了 CTF 測試的規定。

需求條件

更新類別的目標如下：

  • 減少對 SDK 類別和使用時機的困惑。包括移除未使用的過時類別。
  • 具體來說，請釐清有關 partner_internal 的常見誤解，這項功能經常遭到誤解，部分原因在於名稱含糊不清，且包含「內部」一詞。
    • 這個類別並非 RFC-0165 中記錄的 SDK 類別，而是 API 委員會討論串的結果。
    • 這個類別適用於 SDK 中隨附的預先編譯程式庫，以及主機工具所用的 ABI。雖然前者也新增了這項功能，但後者的用途是前者的兩倍。此外，RealmFactory SDK 需求目前建議使用這個類別。
    • 運送元件中使用的程式庫，以及開發人員使用的工具，可能會有非常不同的相容性視窗需求。隨著 Fuchsia 日趨成熟，以及 Sunset 階段的 API 級別數量增加，這種差異可能會顯著擴大。
  • 定義解決方案，穩定 CTF 測試使用的 API，且不會增加 SDK 中 API 的運送負擔或承諾 (問題 367760026)。
  • 根據用途、曝光度或風險，設定不同的程序和相容性時間範圍。
    • 具體來說，就是減少穩定 CTF 測試所需 API 的負擔，以及主機工具使用的 API，因為過去這些 API 不穩定，因此有相容性中斷的風險。

本 RFC 不會嘗試解決理論或非常罕見的情況，例如問題 369892217 中所述的情況。

設計

如 RFC-0165 所述，新類別會依單調遞增的目標對象排序。系統會以括號標示取代的現有類別。

  • compat_test (原為 cts)
  • host_tool (原為 partner_internal 內)
  • prebuilt (原為 partner_internal 內)
  • partner

每個類別名稱都是單數名詞，用來描述目標對象，或說明該類別中的 API 可用於何處。如要為目標對象命名，請在類別名稱中加入「開發人員」。例如「主機工具開發人員」。

除了上述要取代的類別，我們也移除了 RFC-0165 中記錄的 SDK 類別：

  • excluded：功能上等同於未指定 SDK 類別。這個類別很少使用，而且無法明確指出這些用途是否表示原子絕不應納入 SDK。建議改用註解，因為註解更具彈性，也較不會造成混淆。
  • experimental：RFC-0165 說明這項功能意義不大。
  • internal：等同於未指定 SDK 類別。(大多數用途已移除。其餘用途已重新利用這個類別 - 請參閱問題 372986936。在這些用途減少期間，我們仍會提供有限的支援服務。
  • public：從未實作。擴大 SDK 的目標對象時，我們可以重新評估機制。日後可輕鬆新增這類別。

移除 public 後，partner 就等同於「在 SDK 中發布」。 由於現有名稱廣為使用，且大家普遍瞭解其含義，因此我們保留了這個名稱，並可能在日後納入 public 或類似功能。

以下各節將詳細說明每個類別的意義和相容性規定，首先是簡短說明，可用於 sdk_atom() 範本等位置。以下是重點摘要：

  • prebuilt 和 partner 類別中的程式庫可用於使用者裝置的正式版應用程式，因此平台實作的相容性需求相同。
  • 只有 partner 類別中的 API 可供樹狀結構外的開發人員 (SDK 消費者) 直接使用。
  • 所有類別都可用於 FIDL 程式庫。其他 SDK 原子類型通常會直接向開發人員公開，因此其他類別對他們來說不太有意義。
    • 因此，目前的實作方式只允許非 FIDL 原子類型位於 partner 類別中。
  • 不穩定的程式庫 (在 SDK 中公開，但僅位於 HEAD，且不保證相容性) 可用於 partner 類別。其他類別的用途是相容性，因此不穩定的程式庫不太適合這些類別。
    • 因此，目前的實作方式只允許 partner 類別中的程式庫不穩定。
  • 所有類別的程式庫都會受到相同機制處理，以偵測及防止穩定版 API 級別發生變更。
    • 目前這類測試只有 FIDL 程式庫的 API 摘要黃金檔案比較。每個穩定的數字 API 級別都會在建立時進行快照。系統也會維護 NEXT 的快照，做為偵測及核准 API 變更的機制。詳情請參閱「SDK 記錄」。

下表總結上述資訊。系統會標示反映目前實作情況的資料欄。

名稱 先前的類別 可於最終使用者裝置的正式版中使用 可供 OOT 開發人員直接使用 (「在 SDK 中」) 強制執行變更偵測 是否與 FIDL 程式庫搭配使用？ 可與其他 SDK 原子類型搭配使用嗎？(目前導入方式) 可能不穩定 (目前實作方式)
compat_test cts (未實作) 否 否 是 是 否 否
host_tool partner_internal內 否 否 是 是 否 否
prebuilt partner_internal內 是 否 是 是 否 否
partner 無 是 是 是 是 是 是

compat_test

「可用於設定及執行相容性測試，但可能不會在 SDK 中公開供正式版使用，也不會由主機工具使用。」

注意：為清楚說明現有機制和做法，本節會以「CTF」取代「相容性測試」。不過，這項 RFC 並未禁止用於日後可能出現的類似平台相容性測試。

這類程式庫最有可能包含 CTF 測試領域工廠通訊協定，或透過領域工廠傳回的 fuchsia.testing.harness/RealmProxy 或 fuchsia.component.sandbox/Dictionary 提供給測試。這些通訊協定提供穩定的測試架構，可比較 Fuchsia 版本之間相同作業的行為，且架構通訊協定本身也必須有相容性保證，確保相容性測試可在相關 Fuchsia 版本上執行。

雖然這個類別的 API 可在平台內的正式版程式碼中使用，但只能透過 CTF 測試領域或類似方式，在平台外公開。

注意：這個類別中的 FIDL 程式庫 (所有 SDK 類別中的程式庫也一樣) 必須在 "fuchsia" FIDL 平台中進行版本控管。因此，如果程式庫名稱開頭為 test. 或 fuchsia. 以外的任何字串，則必須在程式庫的 @available 屬性中指定 platform="fuchsia"。

  • 曝光：CTF 測試和負責 Fuchsia 平台開發人員。CTF 測試非常重要，因為有助於確保 ABI 相容性，尤其是舊版 API 級別的執行階段支援。
  • ABI 相容性窗口：只要我們需要執行相關 CTF 測試，就必須支援 API。
    • 一般來說，只要在「支援」或「淘汰」階段 (「執行階段支援」) 的 API 級別測試使用這些項目，就表示支援。
    • 我們可以選擇停止執行測試、重建測試以使用其他 API，或是導入 Proxy 來使用新的 API。

host_tool

「可供平台機構提供的主機工具 (例如 ffx) 使用，但不得供 SDK 中的正式版程式碼或預先建構的二進位檔使用。」

  • 曝光：開發人員使用平台提供的工具，與支援工具支援的 API 級別的目標 Fuchsia 裝置互動。
  • ABI 相容性窗口：API 必須支援到平台不再支援與主機工具通訊為止，且 API 支援的任何 API 級別都適用此規定。
    • 這與使用不同版本的主機工具，與特定平台版本通訊有關。
    • 注意：平台為這個主機工具提供的執行階段支援 API 級別組合，可能與下列一或多項不同：
      • 目前平台版本支援的一組元件目標 API 級別 (元件執行階段相容性)。
      • 目前版本的主機工具支援的 API 級別組合，可用於與目標裝置通訊。
  • 因為這個類別的 API 不會用於 IDK/SDK：
    • 非平台元件 (即由樹狀結構外的開發人員建構的元件) 無法使用這些 API (除非破解)。
    • 只要我們願意處理對下游開發人員的影響，就可以中斷這些 API，不會影響終端使用者。我們也需要考慮 CTF 測試的任何用途。

實作注意事項：IDK/SDK 中的主機工具具有 "partner" 類別，但可能會使用這個類別的 API。不過，"partner" 中的 API、程式碼、預先編譯的程式庫和預先建構的套件，不得使用這個類別中的 API。

預建

「可能是 SDK 中預先建構的二進位檔用來與平台互動的 ABI 一部分。此類別中的 API 不會提供給樹狀結構外的開發人員直接使用。」

SDK 中預先建構的二進位檔 (用於正式環境) 目前包含預先編譯的靜態程式庫、預先編譯的共用程式庫和套件。從樹狀結構外的開發人員角度來看，這些是二進位檔的實作詳細資料，不會用於程式庫或封裝元件的開發人員專用 API。預先建構的程式庫和套件內部使用的來源集和程式庫不需要屬於任何 SDK 類別，但這些程式庫用來與平台互動的 API 則需要。

  • 曝光：使用者。
  • ABI 相容性窗口：只要支援 API 的 API 級別處於「支援」或「淘汰」階段，就必須支援 API。也就是說，與 partner 相同的視窗。
  • 因為平台團隊會控管使用這類 API 的所有軟體：
    • 我們不一定需要太過擔心開發人員的人體工學。
    • 我們不必擔心第三方元件的使用情形。
    • 我們可以取代 SDK 預先編譯程式庫和預先建構套件中新 API 級別 (NEXT) 的用途，因此與擔心下游用途相比，可以更快捨棄執行階段支援 (不會遭到淘汰)。

合作夥伴

「Included in the SDK for direct use of the API by 樹狀結構外 developers.」

  • 曝光：最終使用者、樹狀結構外的開發人員和產品負責人。
  • ABI 相容性窗口：只要支援 API 的 API 級別處於「支援」或「淘汰」階段，就必須支援 API。
  • 這個類別包含由樹狀結構外的開發人員和/或產品元件，從元件路徑傳送或傳送至元件的功能。
    • 舉例來說，功能產品負責人必須將功能導向平台，以及必須導向 SDK 中預先建構套件的功能。

實作

導入作業將分為下列階段：

  1. 「excluded」和「experimental」已移除。
  2. 移除對「public」的參照。
  3. 將 cts 替換為 compat_test 並實作。
  4. 將 https://fxbug.dev/365602422 中追蹤的 FIDL 程式庫新增至 compat_test 類別，並從允許清單中移除。
  5. 將 partner_internal 替換為 host_test 和 prebuilt。
    • 更新 ffx 外掛程式和工具使用的 SDK 標記機制，允許同時使用兩者。
    • 新增住宿，以便將 FIDL 程式庫的重新指派作業延後至下一個步驟。
  6. 視需要使用 partner_internal 將 FIDL 程式庫指派給 host_test 或 prebuilt。
  7. 現有用途升級至支援的類別或移除後，請最終移除 internal 的支援 (問題 372986936)。

效能

由於類別只會影響建構作業，且只會變更現有機制中使用的字串，因此不會影響效能。

人體工學

平台開發人員使用的機制維持不變。減少類別數量並使用更精確的名稱，有助於瞭解這些類別的意義，以及哪個類別適合特定用途。

回溯相容性

這項 RFC 只會影響平台建構規則。實作時，系統會更新所有已移除類別的使用情形。

安全性考量

這項 RFC 不會變更建構作業中或向開發人員公開的 ABI 介面。

隱私權注意事項

這項 RFC 不會變更建構作業中或向開發人員公開的 ABI 介面。

測試

//build/sdk/sdk_common/sdk_common_unittest.py 中的類別測試會更新，以反映各類別的變更。

此外，上述任一類別中的 FIDL 程式庫都應在 //sdk/history 中含有 <library_name>.api_summary.json 檔案。您可以驗證新增至 compat_test 的程式庫。此外，我們可以在本機刪除所有這類檔案，並確保檔案已產生 (Git 中沒有遺失的檔案)。

說明文件

主要 SDK 類別說明文件將會更新。RealmFactory SDK 規定參考資料也會更新為 partner_internal。

缺點、替代方案和未知事項

大多數替代方案的選項較少，可減少平台開發人員需要瞭解和決策的內容。舉例來說，由於 partner 和 prebuilt 具有相同的相容性需求，因此可以合併，甚至可以只用一個位元，表示「在 SDK 中」/「需要相容性」或「不需要相容性」。有人提議以兩個布林值完全取代現有類別

雖然這些選項可確保適當的相容性，但無法滿足部分非技術性需求。舉例來說，平台開發人員希望確保相容性，但不想負擔完整 API 校準的成本。(或許未來這方面就不會是問題。)此外，如果我們知道平台團隊擁有 API 的所有用途，彈性會稍微大一點。這或許與平台是用戶端的 FIDL 通訊協定特別相關 (請參閱 RFC-0241)。建議採用命名慣例，保留部分屬性。不過，這可能會造成更多混淆，且更難強制執行，例如在建構規則中。

這項 RFC 的變更幅度較小，仍會使用類別字串的概念和現有的強制執行機制，因此可快速實作。我們日後若有更多經驗，且更瞭解相容性需求，仍可能做出這類變更。具體來說，我們可能需要定義 SDK 中 API 的不同相容性視窗。

另一個替代方案是保留單一類別 partner_internal，可能使用新名稱，用於主機工具和預先編譯的程式庫。不過，相較於找出涵蓋兩者的明確名稱，似乎透過描述用途來解釋某件事更容易。如果日後需要打破相容性，這些獨立類別也能提供使用記錄。如果平台和主機工具的相容 API 級別範圍不同，分開處理也能讓兩者的支援時間範圍有所差異。

既有技術和參考資料

  • RFC-0165 定義了目前的類別集，這些類別記錄在現有 SDK 類別說明文件中。
  • 這個 API 委員會討論串促成了 partner_internal 類別的定義，並討論了許多相關問題，包括：
    • 需要 SDK 中沒有的穩定版 API。
    • 不希望應用程式直接使用某些 API，以及控管所有使用 API 的程式碼所帶來的優勢。
    • CTF 測試作者也會有類似的用途。
    • 新類別的說明為「internal-visible, partner-stable」，可提供最終名稱 partner_internal 的背景資訊。
    • 系統建議將新類別命名為「"prebuilts"」。
      • 這個名稱有其他含義，因此遭到部分反對，但據說在 SDK 中，這個詞彙似乎已越來越常指稱靜態和共用程式庫。
  • 問題 328322682 包含現有 SDK 類別的早期評估結果。
  • 問題 367760026 說明瞭 compat_test 的動機。
  • RealmFactory SDK 規定說明 RealmFactory FIDL 通訊協定的規定。