API 等級

Fuchsia 系統介面會不斷變更,且我們會持續建立新的 Fuchsia 版本。與其針對每個 Fuchsia 版本與其他版本的 Fuchsia 系統介面相容性進行推理,這麼做會讓人不知所措,不如讓每個版本只與少數 API 級別相容。

API 級別基本上是組成 Fuchsia 平台介面的 API 版本。舉例來說,API 級別 10 是 Fuchsia API 途徑的第 10 版。API 級別會與里程碑版本同步,因此在 F10 發布時,API 級別 10 也可以視為 Fuchsia 平台途徑的最新穩定數字版本。

API 級別無法變更。雖然 API 可能會隨著時間新增、移除或變更,但一旦發布特定 API 級別,該 API 級別的 API 集合及其語意就不會變更。也就是說,任何兩個瞭解特定 API 級別的 Fuchsia 版本,都會就組成該 API 級別的 API 元素集合和行為達成共識。

Fuchsia 系統介面不限於 FIDL,還包括系統呼叫、C++ 程式庫和其中的方法、持續性檔案格式等等。概念上,這些都會依 API 級別進行版本控制,但實際上,Fuchsia 系統介面的其他部分比 FIDL 程式庫更早支援版本控制。

身為 Fuchsia SDK 使用者,您在建構元件時會選取單一目標 API 級別。如果您指定 API 級別 11,您的元件將可存取 API 級別 11 中可用的 API 元素,無論您使用的是哪個版本的 Fuchsia SDK 都一樣。如果在 API 層級 12 中新增方法,元件就無法在產生的繫結中使用該方法。如果 API 級別 11 中可用的某個方法在 API 級別 12 中遭到移除,元件仍可繼續使用該方法。

建構元件時,SDK 中的工具會將目標 API 級別的相關聯 ABI 修訂版本嵌入元件的套件中。這就是元件的 ABI 修訂版本標記

ABI 修訂版本戳記可讓 Fuchsia 確保元件觀察到的執行階段行為,與其目標 API 級別指定的行為相符。ABI 修訂版本戳記的使用方式非常粗略:如果 Fuchsia 平台版本支援該 ABI 修訂版本的相應 API 級別,則可允許元件執行。否則 (例如,如果外部元件指定 API 級別 11,但作業系統二進位檔不再實作 API 級別 11 的部分方法),元件管理服務就會防止其啟動。

範例

您可以使用 API 級別建立陳述式,例如 fuchsia.lightsensor.LightSensorData FIDL 資料表在 API 級別 10 中包含三個欄位 (rgbccalculated_luxcorrelated_color_temperature),但在 API 級別 11 中新增了兩個欄位 (si_rgbcis_calibrated)。自 API 級別 11 以來,它已包含五個欄位,但在未來 (例如 API 級別 16),欄位可能會新增或移除。

Fuchsia SDK 的平台開發人員和使用者之間的差異

身為 Fuchsia SDK 的使用者,您可以選擇 API 級別,藉此定義可用的 API 組合,以及 (間接) 可執行 Fuchsia 元件的平台版本組合。元件只能使用特定 API 級別中的 API,而無法使用在所選 API 級別之前新增或之後刪除的任何 API。如要存取其他 API,請更新元件的目標 API 級別,以便存取新功能。

另一方面,平台建構作業會根據 version_history.json 的內容,指定一組 API 級別。因此,身為平台開發人員,您必須確保所有變更都與所有支援的 API 級別相容。新增功能或變更 Fuchsia 系統介面時,您必須在 HEADNEXT API 級別執行此操作。

階段

階段表示 Fuchsia 版本針對特定 API 級別提供的支援層級。API 級別可能處於支援、淘汰或已淘汰階段。

每個 Fuchsia 版本都支援多個 API 級別,並將每個 API 級別指派給一個階段。

API 級別可處於下列任一階段,以下列出各 API 級別的順序:

支援

在這個階段 (與任何版本) 以 API 級別為目標建構的元件,會在平台版本上執行。此外,您也可以使用 SDK 建構指定 API 級別的元件。

舉例來說,如果特定版本支援 API 級別 17,表示該版本的 OS 二進位檔可執行以 API 級別 17 為目標的元件,而該版本的 SDK 則可建構以 API 級別 17 為目標的元件。

日落

在這個階段中,以 API 級別為目標建構的元件會在平台版本上執行。不過,您無法使用 SDK 建構鎖定 API 級別的元件。

舉例來說,如果 API 級別 17 在特定版本中已停用,表示該版本的 OS 二進位檔可執行目標 API 級別 17 的元件,但該版本的 SDK 無法建構目標 API 級別 17 的元件。

已退休

在這個階段建構的元件若指定 API 級別,就無法在平台版本上執行,且 SDK 也不支援這些元件。

舉例來說,如果 API 級別 17 在特定版本中已淘汰,該版本的 OS 二進位檔就無法執行目標 API 級別 17 的元件,而該版本的 SDK 也無法建構目標 API 級別 17 的元件。

範例

舉例來說,Fuchsia 版本 20.20240203.2.1 可能包含:

  • 支援階段中的 API 級別 171819。也就是說,SDK 版本 20.20240203.2.1 可以建構指定任何 API 級別的元件,而搭載 Fuchsia 版本 20.20240203.2.1 的裝置則可執行指定任何 API 級別的元件。
  • 停用階段中的 API 級別 1516。Fuchsia 仍會執行以 Sunset API 級別為目標的元件,但 SDK 在建構元件時,將不再支援以這些 API 級別為目標。
  • 已淘汰階段的 API 級別 1-14。Fuchsia 不會建構或執行以已淘汰的 API 級別為目標的元件,但會保留這些元件供後代使用。

API 級別會在「支援」階段發布,也就是在對應里程碑分支版本推出前不久。上述假設的 20.20240203.2.1 測試群組版本來自 API 級別 20 發布之前,因此沒有 API 級別 20。在 F20 分支版本推出前不久,API 級別 20 就會發布,後續版本 (例如 20.20240301.4.1) 也會將 API 級別 20 列為「支援」。具體來說,所有里程碑版本都會在「支援」階段納入對應的 API 級別。

特殊 API 級別

除了穩定的數字 API 級別之外,還有三個特殊的 API 級別:

與其他 API 級別不同,NEXTHEAD 的內容可在不同版本之間以任意方式變更。API 元素可新增、修改、取代、淘汰和/或移除。原則上,20.20240203.1.1 中的 NEXT 可能與 20.20240203.2.1 中的 NEXT 完全不同,但實際上,變更會逐漸進行。

HEADNEXT 新,這表示 NEXT 中的所有 API 變更也包含在 HEAD 中。

作為 Fuchsia SDK 的使用者,指定 HEADNEXT 會使 APIABI 相容性保證失效。作為 Fuchsia SDK 的使用者,您不應直接指定 PLATFORM 級別。

NEXT

NEXT 代表下一個數字 API 級別的「草稿」版本。當發布團隊發布新的 API 級別時,NEXT 會在整個程式碼庫中替換為新的 API 級別。方法是建立變更清單,將 FIDL 註解、C 預處理器巨集和 Rust 巨集中的 NEXT 例項,替換為下一個里程碑分支的特定編號。NEXT 中的 API 元素必須可運作,且在下一個 API 級別發布前不太可能變更,但仍有可能變更。

HEAD 代表開發的最新進度,可供樹狀結構內的用戶端 (例如其他平台元件或整合測試) 使用,但不保證穩定性。HEAD 中導入的 API 元素可能無法正常運作;舉例來說,某個方法可能已新增至 HEAD 中的通訊協定,但通訊協定伺服器可能尚未實際導入該方法。

PLATFORM

PLATFORM 是特殊的元 API 級別,用於建構 Fuchsia 平台,並非 SDK 使用者指定的目標。

PLATFORM 代表 Fuchsia 平台目前版本必須支援的完整 API 組合,例如:

  • 所有目前支援的穩定數字 API 級別 (請參閱「支援」和「停用」)。
  • NEXT API 級別。
  • HEAD API 級別。

PLATFORM 的主要目的是確保平台可以執行針對任何支援的穩定 API 級別建構的元件,以及指定 NEXT andHEADAPI levels.PLATFORMincludes APIs from all supported stable numerical levels, so it may contain APIs that have already been removed fromNEXTorHEAD` 的元件。