RFC-0169：SDK 工具相容性

RFC-0169：SDK 工具相容性
狀態已接受
區域
  • 開發人員
說明

說明 SDK 工具的相容性需求
問題
變更
作者
審查人員
提交日期 (年/月)2022-05-06
審查日期 (年/月)2022-06-16

編輯此 RFC

編輯 RFC 中繼資料

摘要

開發人員需要合作的 Fuchsia 型產品，每項產品都支援可能不同的 Fuchsia ABI 修訂版本。開發人員會使用主機端工具連線至 Fuchsia 系統，並與這些系統互動。這些工具需要針對要連結的 Fuchsia 系統制定相容性政策，以確保使用者能夠預測且明確的行為。

這個 RFC 概述了一套政策，說明工具何時預計能與 Fuchsia 型產品相容，以及我們打算採取哪些初始步驟來強制執行相容性。

極簡短版政策是指，如果 SDK 隨附支援的開發人員工具，該開發人員工具的相容性保證會與 SDK 支援的最新 ABI 修訂元件相同。因此，該工具一定會與支援該 ABI 的任何後續 Fuchsia 產品套裝組合 (如 RFC-0100 中所述)。

提振精神

Fuchsia 有明確定義的概念，說明元件與特定系統相容的意義。如 RFC-0002 中所述，每個 Fuchsia SDK 版本都支援一組 API 級別和 ABI 修訂版本。如果元件指定特定 ABI 修訂版本和 Fuuchsia 產品套裝組合 (也就是執行 Fuchsia 產品所需的一組構件，但不包括 SDK 及其工具)，則該元件支援該項修訂版本。

新的 Fuchsia 平台版本在推出後持續支援 ABI 修訂版本的特定時間長度 (或相容性期)。(即將推出的 RFC 將制定新政策，規範系統如何判斷相容性時間範圍的長度)。因此，在相容性期間，該元件將與新的 Fuchsia 版本相容。

與 Fuchsia SDK 一起發布的工具沒有任何類似的概念，也就是目前具備特殊的相容性機制，能夠反映特定團隊和開發人員的意圖。這個 RFC 位址會相當短。

工具和元件不相符可能會讓使用者感到困擾。許多 Fuchsia 使用者會透過工具分開下載產品套裝組合。這會導致開發人員使用的工具，與其嘗試監控及管理的產品所支援 ABI 不同的 ABI。導致開發人員難以診斷及解決的錯誤。

在本 RFC 中，我們設定了工具何時應使用特定 Fuchsia 產品組合來制定初始政策，並說明我們打算強制執行和傳達這項政策的步驟。這項政策未另行規定。SDK 工具相容性的其他方面並未在此處理，例如：保證指令列選項的生命週期，或是工具與舊版 C/C++/FIDL 標頭的工具相容性。

相關人員

講師：

Abarth

審查者：

abarth (版本管理、Fuchsia TL) amituttam (工具) dschuyler (SDK) Sebmarchand (客戶代表) sethladd (SDK、版本管理)

顧問：

ffx 團隊 CTF 團隊 編輯團隊 wilkinsonclay (開發人員關係) yaar (客戶代表)

社群媒體化：

這個 RFC 會由元件架構和開發人員領域的代表交流，並針對 Fuchsia 版本管理中的相關人員在郵寄清單上進行討論。

設計

定義

SDK 工具是一種隨附於 SDK 的執行檔。請注意，基於這項政策的目的，會將個別 ffx 外掛程式計為個別工具。

合作夥伴 API 和合作夥伴工具具有支援的 API 和工具，可供目標個人及團隊與 Fuchsia 團隊密切合作進行功能開發。且會透過合作夥伴 SDK 傳送。

公用 API 和公用工具是任何人都支援的 API 和工具。這些 API 是透過 Public SDK 傳送。請注意，為本文件撰寫時，沒有任何公用 SDK，只有合作夥伴 SDK。

在本文件中，我們使用「stable」一詞來指 a) 支援的合作夥伴工具 / API，其中以公開或合作夥伴 ABI 為目標；以及 b) 以公用 API 為目標的假設未來公用工具 / API。日後公開和合作夥伴平台的途徑區域可能會有不同的相容性期間，但差別在於本文件並無差別。

如果 SDK 工具沒有任何跡象 (透過指令列標記、工具本身命名 (例如 foo_internal) 或說明文件)，表示該 SDK 仍處於實驗階段，則支援該工具。舉例來說，ffx 工具有幾個系統不視為支援的實驗性子指令。即使系統聲明與特定 ABI 修訂版本的相容性，不支援的工具也無法保證可以運作。

政策

這項 RFC 規定，如果 SDK 支援搭配 SDK 的開發人員工具，在與系統互動時，必須透過對應 SDK 支援的 ABI/API 直接與平台互動。

如果工具支援合作夥伴使用，則只能透過合作夥伴或公開 ABI / API 進行互動。如果工具支援公開使用，則只能使用公開的 ABI / API 進行互動。支援的 SDK 工具不得使用內部或實驗性 ABI / API。

根據這個做法，支援的 SDK 工具保證可與所有在 ABI 和 ABI 相容性期間開發的 Fuchsia 產品相容，或從分支版本開發的所有 Fuchsia 產品。

穩定版開發人員工具可能會指定先前穩定的 API / ABI，也就是已在平台上淘汰或移除的穩定版 API / ABI。舉例來說，Fchsia 專案若具備的工具，能將新映像檔刷新至執行舊版相容性視窗的裝置，可能會很有幫助。說明文件中應清楚說明這類行為。在這種情況下，除非這些工具本身已淘汰，否則必須繼續搭配穩定的 API/ABI 使用。

除了已淘汰及已移除的 API / ABI 以外，當穩定版工具指定非穩定版 API/ABI 時，系統會將其視為錯誤，且必須制定計畫以便將其轉換為穩定版 API/ABI 或移除。這包括 SDK 中目前支援的工具 (使用非穩定版 API)。

為了進行實驗，SDK 可能包含非穩定版的開發人員工具。這類模型必須加上標籤。非穩定版的開發人員工具可能會使用不穩定的 ABI / API。非穩定版工具的說明文件必須表明不受支援。叫用非穩定版工具時，應明確指出不支援這類工具 (例如需要額外的指令列旗標)。這類工具在使用時可能會產生警告。

只要將個別 ffx 外掛程式視為個別工具，就代表 ffx foo 可視為穩定，但在相同版本中可能不是 ffx bar。其他工具可能也有類似的政策，因此應充分說明。

Fuchsia 平台不保證其工具的前瞻相容性。較新版本的工具可能無法與舊版產品搭配使用。開發人員應盡最大努力，確保工具可在這類情況下提供清楚且可做為行動依據的錯誤。

實作

個別 SDK 工具擁有者可以透過測試和建構支援等機制，決定在開發期間強制執行相容性需求。日後 SDK 工具可能會強制採用這些強制執行機制。

處理 ffx 工具的團隊計劃採取下列行動，以強制執行相容性。這份清單並非詳盡無遺，僅列舉幾個例子，說明團隊可以採取哪些行動來強制執行這些政策。

  • 舊版 ffx 將做為 CTF 測試組合的一部分執行 (在 RFC-0015 中定義為 CTS tests)，強制新版平台建構能維持與測試功能的相容性。

  • 系統會為 ffx 的指令列和 JSON 介面建立版本，並強制執行這些版本的相容性。

  • ffx 工具和基礎 Overnet 傳輸都會有相容的目標 ABI 修訂版本，該修訂版本可能是相容的目標 ABI 修訂版本，其可能是建構時位於 fuchsia.git 標頭的修訂版本。這項工具會針對 Fuchsia 目標，向服務回報目標 ABI 修訂版本。服務會回報 ABI 是否屬於支援的集合。如果不是，ffx 會為使用者產生錯誤，並將使用者導向相容的 ffx 版本。隨著相容性強制執行的演進，我們可能需要重新審視這個方法的具體細節；在短期內，只有靜態 ABI 修訂版本 (亦即在組合時間決定) 可供使用，但長期來看，整個系統的不同部分都會揭露不同的 ABI，而我們也需要提供更多動態檢查。

  • fuchsia.git 內建的穩定 ffx 外掛程式將運用建構限制，將 FIDL 定義組合用於公開和合作夥伴 SDK 中提供的項目。

  • 我們希望 Fuchsia 工具擁有者遷移 ffx 外掛程式，以便長期支援不穩定的 API 和 ABI。

  • ABI 修訂版本將納入產品套件中繼資料，協助開發人員在執行產品組合前，找出將搭配該產品組合的 ffx 版本。我們的目標是將版本識別資訊附加到任何需要的輸入ffx中。

效能

這些政策不會影響效能。強制執行這些政策可能會影響效能，但這是個別工具的服務品質問題。

人體工學

這些政策會明確指出特定工具何時與特定 Fuchsia 目標相容，藉此改善工具人體工學。

回溯相容性

許多現有 SDK 工具都不支援偵測或強制執行相容性保證的機制，而且許多工具都使用不穩定的 API 和 ABI。部分工具需要轉換至長期穩定的 ABI。一如往常，您必須謹慎進行轉換，盡可能減少對使用者的干擾。開發人員應考慮選擇將工具中使用的非穩定版 API 和 ABI 視為穩定版，並在完整相容性期間繼續支援，並進行軟性轉換轉換成穩定替換。

安全性考量

這些政策沒有任何已知的安全性考量。

有時候，安全性問題可能需要我們破壞相容性保證。舉例來說，我們可能會發現用來從主機與主機進行通訊的 Overnet 傳輸安全性問題。

隱私權注意事項

這些政策與使用者資料的收集行為無關。

測試

雖然最佳做法是利用測試來確保與 SDK 相關的開發人員工具符合這些政策，但這項 RFC 不需要開發人員工具執行此作業。Fuchsia CTF (舊稱 CTS) 提供了測試部分工具開發人員可能想採用的機制。

說明文件

請務必更新工具說明文件，參照這項政策。

缺點、替代方案和未知

其中一種替代方法可以臨時相容於相容性，也就是每項工具都有其專屬的最小相容性期間。實際上，我們發現這會造成大量使用者混淆，因為使用者通常不會獨立使用單一工具。舉例來說，如果 ffx log 正常運作且 ffx component 無法運作，使用者可能會感到驚訝。

先前的圖片和參考資料

許多系統的工具都面臨回溯相容性挑戰。例如在 Java 中，位元碼會加上類別檔案版本號碼。JVM 有一組可以理解的類別檔案版本號碼。過舊的課程檔案可能無法運作。