| RFC-0169：SDK 工具相容性 | |
|---|---|
| 狀態 | 已接受 |
| 區域 |
|
| 說明 | 說明 SDK 工具的相容性規定 |
| 問題 | |
| Gerrit 變更 | |
| 作者 | |
| 審查人員 | |
| 提交日期 (年-月-日) | 2022-05-06 |
| 審查日期 (年-月-日) | 2022-06-16 |
摘要
開發人員需要使用各種以 Fuchsia 為基礎的產品，每個產品都支援可能不同的 Fuchsia ABI 修訂版本。開發人員會使用主機端工具連線至 Fuchsia 系統，並與這些系統互動。這些工具必須針對連線的 Fuchsia 系統定義相容性政策，確保使用者能獲得可預測且明確的行為。
這份 RFC 列出一系列政策，說明工具與以 Fuchsia 為基礎的產品版本相容的時間點，以及我們打算採取的部分初始步驟，以便強制相容性。
政策的極簡版說明如下：如果 SDK 與支援的開發人員工具一併發布，該開發人員工具就會提供與元件相同的相容性保證，該元件鎖定的是 SDK 支援的最新 ABI 修訂版本。因此，這項工具可保證與任何後續支援該 ABI 的 Fuchsia 產品套件 (如 RFC-0100 所述) 搭配運作。
提振精神
Fuchsia 已明確定義元件與特定系統相容的概念。如 RFC-0002 所述，Fuchsia SDK 的每個版本都支援一組 API 級別和 ABI 修訂版本。如果元件指定特定 ABI 修訂版本，且 Fuchsia 產品套件 (執行 Fuchsia 產品所需的一系列構件，不含 SDK 及其工具) 支援該修訂版本，則元件與指定產品套件相容。
新的 Fuchsia 平台版本會在推出後的特定時間 (或相容性時間窗口) 持續支援 ABI 修訂版本。(即將推出的 RFC 將說明我們如何決定相容性窗口的長度，這項政策是全新的政策)。因此，在相容性時段內，元件將與新的 Fuchsia 版本相容。
對於透過 Fuchsia SDK 發布的工具，目前沒有類似的相容性概念，因為這些工具目前具有專屬的相容性機制，主要反映特定團隊和開發人員的意圖。這份 RFC 解決了這個缺點。
工具和元件不相符可能會讓使用者感到相當不便。許多 Fuchsia 使用者會從工具中分別下載產品套件。這會導致開發人員使用支援不同 ABI 的工具，而這些 ABI 與他們嘗試監控及管理的產品所支援的 ABI 不同。這會導致開發人員難以診斷及解決的錯誤。
在本 RFC 中，我們針對工具與特定 Fuchsia 產品套件的預期相容性，設定初始政策，並說明我們打算採取哪些步驟來實施及傳達這項政策。這項政策並非完整政策。SDK 工具相容性還有其他方面，我們在此處未加以討論，例如指令列選項的生命週期保證，或是工具與舊版 C/C++/FIDL 標頭的相容性。
相關人員
協助人員：
abarth
審查者：
abarth (版本管理、Fuchsia TL) amituttam (工具) dschuyler (SDK) sebmarchand (客戶代表) sethladd (SDK、版本管理)
諮詢：
ffx 團隊 CTF 團隊 編輯團隊 wilkinsonclay (開發人員關係) yaar (客戶代表)
社會化：
我們已與元件架構和開發人員領域的代表進行交流，並在郵寄清單上與 Fuchsia 版本管理的利害關係人討論此 RFC。
設計
定義
SDK 工具是 SDK 隨附的可執行檔。請注意，就這項政策而言，個別的 ffx 外掛程式會視為個別工具。
合作夥伴 API 和合作夥伴工具是針對與 Fuchsia 團隊密切合作，協助開發功能的指定人員和團隊所支援的 API 和工具。這些元素會透過 合作夥伴 SDK 發布。
公用 API 和公用工具是指任何人皆可使用的 API 和工具。這些功能會在 Public SDK 中發布。請注意，在撰寫本文時，並沒有公開的 SDK，只有合作夥伴 SDK。
在本文件中，我們使用「穩定」一詞來指稱 a) 以公用或合作夥伴 ABI 為目標的支援合作夥伴工具 / API，以及 b) 假設未來以公用 API 為目標的公用工具 / API。日後，公開和合作夥伴平台的介面可能會有不同的相容性時間窗，但這項差異與本文無關。
如果 SDK 工具沒有任何實驗性質的跡象 (透過指令列標記、工具本身的命名 (例如 foo_internal) 或說明文件)，則該工具受支援。舉例來說，ffx 工具有幾個實驗性子指令，不屬於支援的項目。即使系統聲稱與特定 ABI 修訂版本相容，也不保證不支援的工具一定能正常運作。
政策
這份 RFC 規定，在與系統互動時，透過對應 SDK 支援的 ABI/API 與平台互動時，支援的開發人員工具必須透過 SDK 提供的 ABI/API 與平台互動。
如果工具支援合作夥伴使用，則必須僅使用合作夥伴或公開 ABI / API 進行互動。如果工具支援公開使用，則必須僅使用公開 ABI / API 進行互動。支援的 SDK 工具不得使用內部或實驗性 ABI / API。
遵循這項規範後，支援的 SDK 工具就會保證與在主分支或分支中開發的所有 Fuchsia 產品相容，這些分支是在 ABI 和 ABI 的相容性時間範圍內建立。
穩定的開發人員工具可能會指定先前穩定的 API / ABI，也就是已淘汰或從平台移除的穩定 API / ABI。舉例來說，Fuchsia 專案可能會發現，在裝置上執行的映像檔早於相容性時間窗口，因此需要工具將新映像檔刷新到裝置上。說明文件應清楚說明這類行為。在這種情況下，除非工具本身已淘汰，否則必須繼續使用穩定的 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 修訂版本，這很可能是fuchsia.git建構時的修訂版本。這項工具會將目標 ABI 修訂版本回報至 Fuchsia 目標上的服務。服務會回報 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 有一組可解讀的類別檔案版本號碼。舊版的類別檔案可能無法運作。