| RFC-0169：SDK 工具相容性 | |
|---|---|
| 狀態 | 已接受 |
| 區域 |
|
| 說明 | 說明 SDK 工具的相容性規定 |
| 問題 | |
| Gerrit 變更 | |
| 作者 | |
| 審查人員 | |
| 提交日期 (年-月-日) | 2022-05-06 |
| 審查日期 (年-月-日) | 2022-06-16 |
摘要
開發人員需要使用各種以 Fuchsia 為基礎的產品，而每個產品可能支援不同的 Fuchsia ABI 修訂版本。開發人員會使用主機端工具連線至 Fuchsia 系統，並與這些系統互動。這些工具必須針對所連線的 Fuchsia 系統，制定明確的相容性政策，確保使用者能獲得可預測且清楚的行為。
這項 RFC 列出一組政策，說明工具何時應與以 Fuchsia 為基礎的產品版本相容，以及我們打算採取哪些初步措施來確保相容性。
政策的極簡版內容如下：如果 SDK 隨附支援的開發人員工具，該開發人員工具的相容性保證，與以該 SDK 支援的最新 ABI 修訂版本為目標的元件相同。因此，只要後續的 Fuchsia 產品套件 (如 RFC-0100 所述) 支援該 ABI，工具就一定能正常運作。
提振精神
Fuchsia 對於元件與特定系統的相容性有明確定義。如 RFC-0002 所述，每個 Fuchsia SDK 版本都支援一組 API 級別和 ABI 修訂版本。如果元件以特定 ABI 修訂版本為目標，且 Fuchsia 產品套件 (執行 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 和工具。這些項目會隨附在公開 SDK 中。請注意，撰寫本文時，只有合作夥伴 SDK，沒有公開 SDK。
在本文件中，我們使用「穩定」一詞，同時指稱 a) 以公開或合作夥伴 ABI 為目標的支援合作夥伴工具 / API，以及 b) 以公開 API 為目標的假設未來公開工具 / API。未來，公有和合作夥伴平台介面可能會有不同的相容性時間範圍，但這份文件不討論這項差異。
如果 SDK 工具沒有任何實驗性指標 (透過指令列標記、工具本身的命名 (例如 foo_internal) 或文件)，即為支援的工具。舉例來說，ffx 工具有幾個實驗性子指令，不屬於支援範圍。即使系統聲稱與特定 ABI 修訂版本相容，也不保證不支援的工具可以正常運作。
政策
本 RFC 導入一項規定，即 SDK 隨附的支援開發人員工具與系統互動時，必須透過對應 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 測試集 (定義為CTS tests(請參閱 RFC-0015)) 中執行，確保新版平台建構作業與測試功能保持相容。ffx的指令列和 JSON 介面會進行版本控管，且這些版本會強制執行相容性。ffx工具和底層的 Overnet 傳輸機制，會具有相容的目標 ABI 修訂版本，這可能是建構時fuchsia.git的修訂版本。這項工具會向 Fuchsia 目標上的服務回報目標 ABI 修訂版本。服務會回報 ABI 是否屬於支援的集合。如果不是，ffx會向使用者顯示錯誤訊息，並將使用者導向相容版本的ffx。隨著相容性強制執行措施的演進，我們可能需要重新審查這個做法的具體細節；在短期內，我們只會提供靜態 ABI 修訂版本 (即在組裝時決定)，但從長遠來看，系統的不同部分會公開不同的 ABI，因此我們需要提供更動態的檢查。內建的穩定版
ffx外掛程式fuchsia.git會使用建構限制，將使用的 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 瞭解一組類別檔案版本號碼。如果類別檔案過舊，可能無法正常運作。