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 的疑慮，因為這個名稱容易引起誤解，部分原因是因為名稱含糊不清，且包含「internal」。
    • 這個類別並非 RFC-0165 中所述的 SDK 類別，而是 API 委員會討論串的結果。
    • 這個類別適用於 ABI，這些 ABI 同時用於 a) SDK 中發布的預先編譯程式庫，以及 b) 主機工具。雖然前者已新增，但後者的用途是前者的兩倍。此外，RealmFactory SDK 規定目前建議使用這個類別。
    • 在發布元件中使用的程式庫和開發人員使用的工具，可能會有非常不同的相容性視窗需求，而隨著 Fuchsia 的成熟度提升，以及 Sunset 階段的 API 級別數量增加，這項差異可能會大幅增加。
  • 定義解決方案，以便穩定 CTF 測試使用的 API，且不會產生額外負擔或承諾在 SDK 中發布 API (問題 367760026)。
  • 讓程序和相容性視窗能夠根據用途和風險或曝光程度而有所不同。
    • 具體來說，這項改進可減少 CTF 測試所需的 API 穩定化作業所需的額外負擔，以及主機工具所使用的 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 類別中。
  • partner 類別允許使用不穩定的程式庫 (在 SDK 中公開，但僅在 HEAD 時使用，且不保證相容性)。其他類別的用途是相容性，因此不太可能會納入不穩定的程式庫。
    • 因此，目前的實作方式只允許 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：
    • 這些元件無法 (在未經駭客入侵的情況下) 供任何非平台元件 (也就是由樹狀結構外開發人員建構的元件) 使用。
    • 只要我們願意處理對下游開發人員的影響，就可以在不影響使用者的情況下，中斷這些服務。我們也需要考量 CTF 測試的任何用途。

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

預建

「可能屬於 ABI 的一部分，該 ABI 包含 SDK 使用的預先建構二進位檔，用於與平台互動。這個類別中的 API 無法在 SDK 中使用，因此樹狀結構外開發人員無法直接使用。」

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

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

合作夥伴

「已納入 SDK，供樹狀結構外開發人員直接使用 API。」

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

實作

實作作業會在下列階段完成：

  1. excluded 和 experimental 已遭移除。
  2. 移除對 public 的參照。
  3. 將 cts 替換為 compat_test 並實作。
  4. 將 https://fxbug.dev/365602422 中追蹤的 FIDL 程式庫新增至 compat_test 類別，並將其從許可清單中移除。
  5. 以 host_test 和 prebuilt 取代 partner_internal。
    • 更新 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 測試作者會使用類似的用途。
    • 新類別的說明為「內部可見、合作夥伴穩定」，可為最終名稱 partner_internal 提供背景資訊。
    • 建議使用 "prebuilts" 做為新類別的名稱。
      • 這個名稱有其他含義，因此有些人反對使用這個名稱，但據說在提到 SDK 中的靜態和共用程式庫時，這個詞似乎已越來越常見。
  • 問題 328322682 包含對現有 SDK 類別的早期評估。
  • 問題 367760026 說明瞭 compat_test 的動機。
  • RealmFactory SDK 規定說明 RealmFactory FidL 通訊協定的規定。