本頁面由 Cloud Translation API 翻譯而成。

RFC-0246：API 級別為 32 位元

RFC-0246：API 級別為 32 位元
狀態	已接受
領域	一般
說明	將 API 級別重新定義為 32 位元數字而非 64 位元
毛皮變化	1009253 年
作者	hjfreyer@google.com
審查人員	ddorwin@google.com mkember@google.com
提交日期 (年-月-日)	2024-04-01
審查日期 (年-月-日)	2024-04-29

編輯此 RFC

編輯 RFC 中繼資料

摘要

本提案將 API 級別的定義變更為未簽署的 32 位元整數值。這麼做會取代 RFC-0002，將 RFC-0002 定義為未簽署的 64 位元整數值。

提振精神

您可以在下列位置找到下列程式碼： target_api_level.gni (為求明確，已改寫)：

if (override_target_api_level == -1) {
    clang_fuchsia_api_level = 4294967295
    fidl_fuchsia_api_level = "LEGACY"
}

大致上來說，如果建構時未指定 API 級別在 fuchsia.git 中，clang_fuchsia_api_level 應設為 0xFFFFFFFF，且 fidl_fuchsia_api_level 應設為字串值 "LEGACY"。這個字串稍後會由 fidlc 解譯為值的別名 0xFFFFFFFFFFFFFFFF，如 RFC-0083 所定義。

這示範了兩個問題：

有一個「clang API 級別」和「FIDL API 級別」不同的價值
API 級別有時會以字串表示，有時以整數表示。

Clang、FIDL 與...？

RFC-0002 將 API 級別定義為 64 位元整數，而後續的 RFC 分配特定的 64 位元整數，並指定這些整數的名稱和意義。適用對象執行個體 LEGACY 是由 0xFFFFFFFFFFFFFFFF 識別。但從程式碼上方，我們會改將 0xFFFFFFFF 傳遞至 Clang，因為很抱歉，API 在 Clang 中，等級不得超過 32 位元。

答錯了。

透過 availability 處理相容性方面的 Clang 原因屬性，代表版本 VersionTuple。VersionTuple 包了四個元組代表版本的整數 major[.minor[.subminor[.build]]] 轉換為 128 位元結構。Fuchsia API 級別模擬為「主要版本」在此流程的各個階段因此上限為 32 位元

Clang 是 Fuchsia 平台版本管理的重要一環您必須解決不一致的問題

`string`對`int`對...？

主機工具和建構系統用於儲存資料的類型不一致代表 API 級別即使在 fuchsia.git 的建構系統中不一致，如上方程式碼區塊所示。

這不一定是問題，而且 RFC 無法完全解決問題。不過，它會嘗試提供相關指引，協助您釐清狀況。

需求條件

API 級別必須能夠以字串表示，包括兩行指令列上的檔案和目錄的名稱

API 級別必須完整排序，因此我們可以說出「Foo 已新增在 API 級別 N和 N <= M 中，Foo 屬於 API 級別 M 的一部分。

我們必須能夠指派某些 API 級別的特殊名稱和行為。另一個本節規定也適用於這些「特殊」項目API 級別。

設計

整數表示法

API 級別將重新定義為無正負號的 32 位元整數。

這個空間的下半部 (亦即 API 級別低於 0x80000000) 視為「正常」API 級別。這裡的上半部為預留空間。這個 RFC 和未來的 RFC 會定義大於或等於 0x80000000。

統一處理所有 API 級別的工具可能會忽略這兩者「標準」和保留值，然後全部視為無正負號的 32 位元整數按一般方式排列

如果工具含有特定 API 級別的特殊邏輯，這類工具應會拒絕輸入指定無法理解的保留 ABI 層級值。

字串表示法

API 級別可透過多種不同方式以字串表示：

代表介於 [0, 2³²) 是 API 級別的字串表示法 (例如 "7")。
特殊 API 級別可使用名稱，以大寫表示 (例如例如："HEAD")。
工具不應接受較多的可提供分數值，例如 "0016"、"0x20"、以免造成混淆例如，為十進位的 "0016" 或小數？"2A" 可能是十六進位數字，但若這種格式接受此值，則為 "29" 的十六進位還是十進位？不過，字串剖析邏輯通常都會處理不受個別工具作者控制的程式庫影響，因此工具「可能」接受如此可達到這個目的

每個 API 級別只有一個標準字串表示：

適用於「標準」API 級別， base-10 UTF-8 字串表示為標準 (例如 "13")。
適用於「特殊」API 級別，大寫的名稱為標準格式 (例如 "NEXT")。

需要瞭解 API 級別標準字串表示法的工具如要取得預留的 API 級別 (亦即大於或等於 0x80000000) 他們不知道該品牌的專有名稱

特殊 API 級別

下列 API 級別有特殊名稱：

PLATFORM = 0xFFF00000 = 4293918720。PLATFORM曾扮演角色預設提供的平台類型，LEGACY將會透過 API 建立平台第 PLATFORM 級。先前 LEGACY 的值是 0xFFFFFFFFFFFFFFFF FIDL，無法在 Clang 中代表。

LEGACY 已由 RFC-0232 淘汰，目前正在移除從 FIDL 載入物件，但作業完成後，仍會將平台建構、C++ 和 Rust 程式碼會使用 PLATFORM 偵測正常的平台版本。

PLATFORM 僅適用於同時用於 OS 版本和第三是 IDK 的一部分在這類程式庫中，目標 API 級別低於 PLATFORM 表示程式碼是以 SDK 形式建構而成，因此只能使用 API 元素中的可用元素。如果目標 API 級別「等於」PLATFORM，程式碼建立在 OS，且必須為「支援」中所有的 API 級別提供支援或「日落」事實上，Gartner 的資料顯示只有一半的企業機器學習專案通過前測階段詳情請參閱 RFC-0239。
HEAD = 0xFFE00000 = 4292870144。先前，HEAD 的值是 FIDL 中的 0xFFFFFFFFFFFFFFFE，以及 Clang 中的 0xFFFFFFFF。
NEXT = 0xFFD00000 = 4291821568。NEXT 已在 RFC-0239 中所述，但之前為未指定數值

這個組合會隨時間變化或縮小。

一開始，這些值會以硬式編碼的方式寫入支援指定目標功能的 SDK HEAD 或 NEXT，但最終應在 //sdk/version_history.json。

使用整數與字串的時機

指令列工具接受輸入內容，並產生字串形式的輸出內容，因此應接受上述 API 級別的任何字串表示法。而且最好能使用標準字串格式輸出 API 級別不過，有時這種做法無法執行，或效果非常不方便，因此，標準字串表單不是必要的。例如，Clang 並未發現特殊 Fuchsia API 級別的名稱，因此 -ffuchsia-api-level 的值必須以整數格式提供

在建構工具的實作中，將 API 級別以整數形式儲存建議採用。

建構系統能以最自然的方式表示 API 級別建構系統

成效

這項異動應該不會影響效能。

回溯相容性

LEGACY 和 HEAD 數值的變動未發生回溯相容、嚴格地說不過，先前的 64 位元值僅在 fidlc 內使用，基本上，只有 Fuchsia SDK 規格。

C++ 程式碼中目前以 0xFFFFFFFF 定義的 HEAD 理論上 SDK 使用者看得到，但因為 Fuchsia 來源樹狀結構外沒有程式碼目前指定 HEAD 或 LEGACY，但變更仍要被忽略。LSC 就能確認這一點

PLATFORM (先前為 LEGACY)、HEAD 和 NEXT 的新值是以彌補彼此的不足方便我們不必重新定義現有 API 級別任何這類新功能我們建立的 API 級別應在兩個相鄰的 API 之間相加時加入級別。在最糟糕的情況下，我們可以細分每個間隔 20 次。

安全性考量

這項變更不會影響安全性。

隱私權注意事項

這項異動應該不會對隱私權造成任何影響。

測試

這個 RFC 主要適用於 Fuchsia 建構系統和 SDK 中的程式碼。適用對象或更糟的是，專屬的自動測試能測試程式碼。不過但如果建構系統故障，應用程式很快就會發現異常終止情形當測試失敗、建構中斷與本機開發流程時就會發生 Haywire。

說明文件

NEXT、HEAD 和 PLATFORM 的意義和值將包含在，取得 RFC-0239 中介紹概念的說明文件。

缺點、替代方案和未知

缺點：32 位元是否足夠？

如果按順序分配，即使我們每小時核發新的 API 級別從已設定的 2³¹ 個 API 級別中，大約需要 245,000 年來做為 RFC 的一環這樣應該就夠了。

不過，您不一定要密集分配 API 級別。這個非常 RFC 會定義特殊的 3 個 API 級別，每個級別之間有 1048576 個未使用的 API 級別。不知道你方便嗎？

在 64 位元 API 級別中，很難想到即使過度分配 (例如 Clang 生成多個連續版本之間的差距與 VersionTuple 搭配使用)。

使用 32 位元 API 級別時，我們必須更審慎斟酌如何分配。

不如願望成為歷史悠久食物的笑料庫，我該說： 2³² API 級別應該足以滿足所有人的需求。

替代方案：改用輕度架構

VersionTuple.h 的撰寫方式是以功能為假設可能在類似 12.5 或甚至是 30.1.2.3。以這種方式建構版本的平台可代表多達 2¹²⁵¹ 個不同版本。或許 Fuchsia 可以只使用 2³² 個值代表 Fuchsia 的版本管理配置不適當？

目前有多個成功的平台會使用單一整數 (例如 Chromium 和 Android)。原因不足認為採用相同策略也無法成功。

Clang 會使用各 minor 中最重要的位元。 subminor 和 build 做為旗標。↩