RFC-0024：強制來源相容性

RFC-0024：必要來源相容性
狀態	已接受
領域	FIDL
說明	為 FIDL 語言繫結建立來源相容性標準，並制定一套改良該標準。
作者	cramertj@google.com
提交日期 (年-月-日)	2019-04-02
審查日期 (年-月-日)	2019-04-11

摘要

為 FIDL 語言繫結建立來源相容性標準，例如 並制定了一套進化標準的程序

提振精神

目前，語言產生的程式碼有一些書面規則 繫結。 應用程式通常符合特定的 ABI 線， 賦予具有約束力的作者能充分瞭解其塑造方式 相互整合 任何變更 FIDL 定義都可能導致 產生的繫結。

實務上，使用者會期望有「常識」 且應與原始碼相容，例如定義新的頂層類型。 但並沒有明確規定。 這個案例看起來有點怪，不過它說明瞭為何 可能會破壞使用者期望。 實際例子包括新增欄位 或是新增 xunion 變數，或將新的預設欄位新增至資料表 以及結構體 使用者可合理預期這些變更 但沒有明確指出這項機制 變更會導致一或多個語言繫結目前的來源層級中斷 (例如，因 C++ 或 Go 中的位置初始化器，或 Rust)。

此外，有些是非常實用的 FIDL 擴充功能 但由於其 與原始碼相容性互動 相關例子包括在類型清單中加入 copy 或 clone 函式 不含帳號代碼 無法複製含有任意帳號代碼的類型，因此請新增帳號代碼 導致無法提供 clone 函式 所提供的複製函式，可以任何速率運作)。 加入條件式納入 clone 函式的變更， 因缺少帳號代碼而產生的 Rust 繫結，會遭到拒絕 導致多次錯誤。 因此 Fuchsia 開發人員必須手動自行部署 clone 函式，並為 FIDL 產生的類型新增包裝函式類型， clone。 本文件提出一致標準，可用於評估 希望能提供更符合人體工學的 讓開發人員享有容易使用且無樣化的體驗

設計

流程

這個 FTP 會建立一組來源相容性限制條件的初始設定。 這個清單會記錄在 Fuchsia 來源樹狀結構中。 必須使用 FTP 新增其他來源相容性限制 上傳資料集之後，您可以運用 AutoML 自動完成部分資料準備工作 可以輕鬆加入與新版本相關的來源相容性規則 功能上的「回溯相容性」FTP 範本的部分 修改內容，納入新的原始碼相容性建議 以及限制條件 (如果適用的話)。

定義：來源相容性和可轉移性

下列變更必須與原始碼相容 (例如不會造成原始碼中斷) 或可轉換。

與來源相容的變更不得導致來源中斷 (編譯) 所產生 FIDL 繫結的公用 API 使用狀況。 對於 限制哪些功能屬於「public API」，哪些功能 因此在本文件中，我們視為「公開 API」： 使用產生的繫結 非凡的語言體操 (例如反思) 或明確開發人員 意圖侵犯隱私權 (例如撥打電話) __private_dont_use_me_function_2()). 公開的所有其他 API (例如位置初始化、模式比對、 等)，以防止使用者程式碼遭到 對 FIDL 程式庫的原始碼相容變更。

「可轉換」的變更是指「可以」寫入的變更 程式碼會同時編譯變更前後編譯。 每項可轉換的來源相容性規則都必須明確指定 「使用」必須能夠採用 API

初始來源相容性限制

以下是必須與來源相容的變更清單：

• 新增頂層項目 (通訊協定、類型或常數)。
  • 動機：使用者期望宣告新的通訊協定、類型和類型 常數可以在不破壞 FIDL 現有使用者的情況下完成 資源庫。
  • 豁免項目：用量搭配「*」從命名空間執行的大量匯入作業 導致多個項目之間出現模稜兩可的情況 來自同一名稱的其他程式庫
• 在非嚴格資料表中新增欄位。
  • 動力：表格是專為易於擴充而設計， 支援其他欄位而不中斷 如要選擇中斷，可以使用 strict 修飾符。
• 在非嚴格的可延伸聯集中新增變化版本。
  • 動機：可延伸的聯誼會更容易擴展 且應能在不會中斷的情況下支援其他變化版本 如要選擇啟用中斷情形，則可以使用 strict 修飾符。
• 將成員新增至非嚴格列舉
  • 動機：非嚴格的列舉會間接啟用擴展性 且應能在不會造成來源中斷的情況下延伸
• 將成員新增至非嚴格的「位元」
  • 動機：非嚴格的位元默示選擇擴展 且應能在不受來源破壞的情況下展開
• 將 [Layout = "Simple"] 新增至現有通訊協定
  • 動機：[Layout = "Simple"] 存在，以便啟用 簡單的 C 繫結 符合規則的現有通訊協定不應要求破壞性 變更原始碼，以指定要用在 C 繫結。
• 正在將「[MaxHandles]」新增至現有類型
  • 動機：[MaxHandles] 的存在，是為了提供有關 能以更寬鬆的方式使用這些型別 不應需要變更破壞來源，才能指定 代表某種類型已包含固定的帳號代碼數量上限 可假設仍包含最多的帳號代碼。

以下列出必須轉換的變更：

• 將 [Transitional] 新增至方法
  • 使用：必須能夠實作通訊協定，並提供 使用「之前」和「舊版本」相同的來源 ，再新增 [Transitional] 屬性至該方法。
  • 動力：必須能夠逐步新增或移除方法 延伸到通訊協定，前提是所有現有的實作項目 會逐漸適應新環境
• 新增 [Transitional] 方法
  • 使用：必須能夠以 擷取來源資料[Transitional] 方法 (但 API 不允許實作 方法) 轉換期間)。
  • 動力：必須能夠逐步新增或移除方法 延伸到通訊協定，前提是所有現有的實作項目 會逐漸適應新環境
• 移除 [Transitional] 方法
  • 使用：必須能夠以 擷取來源和來源的[Transitional]方法 (但 API 無法在 轉換)。
  • 動力：必須能夠逐步新增或移除方法 再逐步轉換為通訊協定 隨時以最佳方式做出調整
• 移除非嚴格資料表的欄位
  • 使用方式：必須能夠建立資料表並存取其欄位 (要移除的來源除外) 在兩個值之前使用相同來源 以及移除資料表欄位後
  • 動力：表格經過精心設計，可輕鬆進化， 支援移除作業沒有中斷 如要選擇中斷，可以使用 strict 修飾符： 表格。
• 移除非嚴格可延伸聯集的變體
  • 使用：必須能夠建立 xunion 並存取其 同時使用相同來源的變化版本 (但要移除的變化版本除外) xunion 變數移除前後的比較結果。
  • 動機：X Union 的設計易於進化，而且應該 支援移除作業沒有中斷 如要選擇中斷，可以使用 strict 修飾符： 表格。
• 將類型標示為 strict
  • 使用方式：必須能夠存取資料表的所有欄位或「位元」 以及列舉或 xunion 的所有變數，包括同時使用相同來源 strict之前和之後。
  • 動機：strict 預計會新增至類型宣告 因為這種模型如果日益穩定 以及開發人員工具 不過，您只需要進行可移轉的變更， 而不是零破壞 因為可擴充型別可能會想 允許存取無法辨識的欄位或變化版本。 這些功能對於 strict 類型並不合理，因為 系統會拒絕無法辨識的欄位或子類。
• 將 [Transitional] 新增至列舉或位元欄位的成員 或可延伸聯集的變體。
  • 使用：必須能存取所有非過渡性網站 成員/位元/欄位/變體，以及 不包含 [Transitional] 值在前後使用相同來源 引入 [Transitional] 之後。
  • 動力：必須能逐漸移除成員 或變化版本
• 新增列舉/位元、資料表欄位或變化版本的成員 即標示為 [Transitional] 的可延伸聯集。
  • 使用：必須能存取所有非過渡性網站 成員/位元/欄位/變體，以及 不包含 [Transitional] 值在前後使用相同來源 在啟用新 [Transitional] 欄位之後。
  • 動力：必須能夠逐漸加入新成員、領域， 或子類
• 移除列舉或位元的成員、資料表欄位或 標示為 [Transitional]. 的可延伸聯集
  • 使用：必須能存取所有非過渡性網站 成員/位元/欄位/變體，以及 不包含 [Transitional] 值在前後使用相同來源 移除 [Transitional] 欄位。
  • 動力：必須能逐漸移除成員 或變化版本

下方列出我們未採用的潛在限制條件 ，並附上說明遭省略的原因：

• 從結構體新增或移除欄位 (預設與否)
  • 這是一項具 ABI 破壞性的變更，需要其他 確保可以順利轉換 如要進行這項非破壞性變更，過程中不需要什麼 「用於所有欄位」的樣式推論 包括自動推導方法 (例如，「這個類型是否包含 任何浮點值」)、位置初始化器，以及完整的欄位比對 這裡的工具設計
• 從嚴格模式新增或移除欄位/變化版本 (預設為或不設定) 資料表和工會
  • strict 是用來啟用其他開發人員工具， 依賴「適用於所有欄位」樣式的類型推理，包括 自動衍生方法 (例如「這個類型是否包含任何浮點值」)， 位置初始化器和完整的欄位比對和結構。 強製做出這項非破壞性變更會導致 發展路徑可能包括 縮小技術提議用途的範圍
• 將包含帳號代碼的欄位或變體新增至未標示的類型 [MaxHandles]
  • 將欄位新增至嚴格類型或結構體已 基於其他原因而造成原始碼破壞性變更，因此會新增一個 處理常式類似破壞性變更，可能會影響產生的 API 進而

執行策略

此 FTP 會建立初始提議的語言相容性標準。 系統會將錯誤提報並指派給每個語言繫結的一位作者 確保其語言繫結符合規範。

人體工學

本次異動可為來源設定明確的標準，讓 FIDL 更易於使用 讓自動檢查、手動 正在檢查 FIDL 變更原始碼相容性 讓作者更清楚瞭解來源相容性，讓作者能更清楚瞭解來源 就能自由建立繫結，既符合語言習慣 符合專案的標準需求

說明文件和範例

接受此 FTP 之後，由 FTP 所建立的程序 會發布來源相容性規則本身 以及其他 FIDL 參考文件

回溯相容性

提議的指引可能需要變更繫結和 繫結作者則取決於各繫結作者 以便瀏覽相關變更

本節 (「回溯相容性」部分) 將修訂為 包括以下文字：

「如要導入新的資料類型或語言功能，請考量 您預期使用者會在沒有定義的 FIDL 定義的情況下進行 FIDL 定義 藉此破壞產生的程式碼 如果您的功能會影響任何新的來源相容性 對生成語言繫結的限制，請在這裡列出。」

請注意，您應加入來源相容性文字， 連結至這個 FTP，即：

[source compatibility](/docs/contribute/governance/rfcs/0024_mandatory_source_compatibility.md)

成效

這個 FTP 不會限制執行階段行為， 來源 API 可能會導致語言繫結作者設計更多或更少 高效能 API 使用支援的語言建立高效能繫結 。 。

如果推送專案，這項功能可能會影響編譯時間的效能 找出需要較多內嵌和編譯器最佳化的模式 以獲得最佳效能 (例如將複雜的建構工具 API 最佳化 簡單的結構初始化)。 繫結作者應致力做出不符需求的設計選擇 導致編譯時間差不多，但 都不應該能避免引入 新的來源相容性限制

安全性

這項功能不會影響安全性。

測試

許多來源相容性規則的格式為「沒有任何實體存在 完成這項變更後，就沒有所編譯的使用者程式碼。」 遺憾的是，這類限制很難或不可能在測試上 因為它們需要列舉所有可能的 API 使用情況 。

不過，我們可以 (也應該) 在 FIDL 變更測試中新增項目 ，指出有「部分」使用 API。 這只是滿足來源的必要條件 相容性需求

缺點、替代方案和未知

• 請勿導入這類規格。 允許繫結作者選擇破壞或無破壞方式的程度 都想套用變更 這與目前狀態大致類似，但會 繫結作者擁有比 而在這些系統上， 因而收到拒絕。
• 建立指定「允許」變更的規格 破壞來源，而不是「不」允許哪些 才會衍生出原始碼 這種做法較不容易執行，而且使用者必須繫結作者 預期其繫結必須保留的變更 原始碼相容
• 稍微修改，則是同時指定「屬於」和 「不會」，未指定任何變更，並預設為一種或另一個方式； 基本上與這個 FTP 或上述替代檔案相同 但會根據預設設定 來記錄不同 FIDL 變更的影響。

既有藝術品和參考資料

先前嘗試導入易變性限制 另外要透過 [MaxHandles] 屬性 提交變更要求。 相關設計以及該程式碼的預期修改內容，均已說明