RFC-0144：大小檢查工具

摘要

本文件建議開發新的大小檢查工具，並將其新增至 SDK，讓開發人員和產品擁有者能夠驗證其套件和產品不會超過指定的大小預算。雖然實作細節已刻意排除，因為樹狀結構外組裝會持續改變基礎，但我們會提及設計需求和目標。

提振精神

在軟體開發期間，瞭解軟體是否符合目標的大小限制很有幫助。Fuchsia 提供大小檢查工具，可分析不同軟體群組所耗用的空間，並為每個群組強制執行預算。此工具與 fuchsia.git 的實作細節緊密相關，因此必須先執行 fuchsia.git 檢查，才能使用此工具。因此，Fuchsia 的使用者 (例如 Chromium) 已實作專屬的臨時方法，用於檢查軟體大小。將大小檢查工具重寫為 ffx 外掛程式，並將其新增至 Fuchsia SDK，這樣一來，在 Fuchsia 軟體上強制執行大小預算的方法就會統一，讓未來的開發人員更容易開始使用 Fuchsia。

相關人員

誰會影響這項 RFC 是否獲得核准。

協助人員：

• Hunter Freyer (hjfreyer@google.com)

審查者：

• Saman Sami (samans@google.com) - 功能
• Anthony Fadrianto (atyfto@google.com) - 與基礎架構整合
• Sébastien Marchand (sebmarchand@google.com) - 與基礎架構整合
• Rohan Pavone (rohpavone@google.com) - 與 Chromium 整合
• Amit Uttamchandani (amituttam@google.com) - 整合至 ffx

諮詢：

• Aaron Wood (aaronwood@google.com) - 組裝整合

社會化：

這個專案以內部文件的形式公開，並在會議中與利益相關者提前討論。我們在起草這份 RFC 前，就已收集到相關需求。

背景

本 RFC 假設您瞭解下列主題。

• 檔案系統
• 套件
• BlobFS
• OTA

兩種大小檢查方式

大小檢查可分為兩類：

1. 圖片在刷新時不會超過目標分區大小。
2. 更新期間，Blob 會符合 FVM 預算。

刷新：開發人員可以將新映像檔刷新至 Fuchsia 目標。當您刷新映像檔時，新映像檔的位元組會完全取代分割區的內容。為確保刷新作業成功，新映像檔的大小不得超過分割區的大小。

更新：Fuchsia 目標可以接受無線下載更新。為確保更新成功，Blob 所占用的總空間不得超過 FVM 設定的預算。通常，FVM 中的空間會保留給 UpdatePackage 和其他 Blob，這表示工具無法只填入 FVM，然後檢查最終映像是否可放入分區。

目前的工具

Fuchsia 提供兩種可協助檢查大小的工具：

• size_checker.go
• blobfs-compression

size_checker.go

來源連結

這項工具可用於樹狀結構內 (fuchsia.git 內)，確保 Blob 符合預算。size_checker.go 會透過判斷 Fuchsia 存放區中 blob 目錄的壓縮和對齊大小，完成這項作業。預算可依產品個別定義，但目前並未用於 fuchsia.git 中的任何產品。由於該工具會特別檢查 fuchsia.git 中的目錄，因此必須先執行 fuchsia.git 檢查，才能使用該工具。

首先，Fuchsia 建構作業會產生 blobs.json 檔案，列出 blobfs 中每個 blob 的壓縮和對齊大小，以及 blob.manifest 檔案，列出這些 blob 的 Merkle 和來源路徑。

接著，系統會執行 size_checker.go，並執行下列操作：

1. 讀取 blobs.json 以收集每個 blob 的壓縮大小：compressed_size。
2. 讀取 blob.manifest 以收集所有套件。
3. 計算 Blob 在套件中出現的次數：share_count。
4. 計算每個 blob 的共用大小：shared_size = compressed_size / share_count。由於多個預算可能包含相同的 Blob，我們會使用 Blob 的 shared_size，將大小用量平均分配至各預算。
5. 藉由將每個 blob 的 shared_size 新增至 blob 路徑中的節點，建構 N-ary 和總和樹狀圖，代表建構輸出內容中每個目錄所耗用的空間。
6. 會依序檢查每個預算，並斷言目錄的預算大小大於所耗用的空間。
7. 會對預算中的每個非 blobfs 套件進行疊代，使用 blobfs-compression 計算 blob 大小的總和，並斷言該總和在預算範圍內。
8. 列印結果。

blobfs-compression

來源連結

這項工具可估算一組 Blob 的壓縮和對齊大小，但準確度不一定是 100%，有時可能會高估 Blob 的大小。這項工具絕不會低估 blob 的大小。

blobfs-compression 會透過 Fuchsia SDK 傳送至用戶端，目前是唯一可用於估算 fuchsia.git 以外的 Fuchsia 建構程式碼大小的方法。Chromium 是這項工具的用戶端。

目前工具的問題

• 用於檢查套件大小的樹狀結構內和樹狀結構外方法是不同的工具。
• 這兩種工具都無法直接檢查圖片大小，以確保刷新作業成功。
• size_checker.go
  • 未記錄。
  • 取決於 Fuchsia 版本的實作細節，這不是穩定的契約。
  • 無法在樹狀結構外運作。
• blobfs-compression
  • 不保證會傳回 Blob 的正確壓縮大小。
  • 在 blob 層級運作，這不如在套件層級運作那麼實用。開發人員會依套件將軟體新增至產品。
  • 沒有標準的輸出格式，因此不易編寫指令碼，且自動化使用方式不穩定。

需求條件

1. 在 SDK 中提供可在樹內和樹外運作的工具。
2. 工具支援目前工具的所有現有用途。
3. 這項工具可執行兩種大小檢查：
   • (a) 圖片
   • (b) 一組套件中的 Blob
4. 在案例 (2) 中，系統會執行所有組合中所有套件的 blob 去重作業。
5. 如果超出使用者指定的預算，工具就會傳回失敗。
6. 這些工具可與其他 SDK 工具(例如圖片彙整工具) 搭配使用 (RFC-0072)。
7. 這項工具可輕鬆用於指令碼，並產生可剖析的輸出內容，且可產生 Gerrit Size Plugin 使用的輸出內容。
8. 工具的使用方式和架構將記錄在 fuchsia.dev 中。

設計

一致的開發人員體驗

我們會以 Rust 編寫新的 ffx 外掛程式，執行兩種大小檢查。根據指令列介面評量標準，建議將其納入 ffx，以鼓勵共用工作流程並提高可發現性。此外，我們會優先擴充現有的檔案格式，而非發明新的格式。

可編寫指令碼

這個工具主要用於建構系統，因此輸出內容應可剖析。輸出格式很可能會使用 json5，但隨著組合語言專案的進展，我們可能會考慮使用其他格式。

圖片大小

圖片大小檢查器應在建構 Flash 資訊清單時一併執行，以便將組合完成的圖片對應至區隔。目前，Flash 資訊清單建立作業是在 Fuchsia 建構系統中完成，因此會透過 GN 動作叫用 ffx 外掛程式。日後，我們可能會提供 SDK 工具來建構 Flash 資訊清單，而我們的大小檢查工具會以 ffx 外掛程式的形式，在該情況下流暢運作。

測量圖片大小的方法很簡單，只要開啟檔案並讀取中繼資料中的長度即可。這項功能適用於任何未壓縮或稀疏的圖片。這項方法無法運作的例子是稀疏 FVM，由於目前沒有任何程式庫可計算稀疏 FVM 的展開大小，因此這項工具會忽略稀疏 FVM 的大小檢查。

套件大小

Blob 和套件大小檢查應與組合作業密切整合，因為工程師會在組合作業期間將套件分組成組合，並將這些組合組合起來指定產品。

大小檢查工具會使用 blobs.json 檔案，列出每個 blob 的壓縮和對齊大小。開發人員可以提供多個 blobs.json 檔案做為工具的輸入內容。如果在任何提供的 blobs.json 檔案中找不到套件的 blob，大小檢查工具就會使用 blobfs 工具為所有遺漏的 blob 產生單一 blobfs 映像檔，進而產生額外的 blobs.json。大小檢查工具會讀取產生的 blobs.json，取得缺少的 Blob 大小。

與現有的 size_checker.go 工具類似，新的大小檢查工具會將大小除以使用該 blob 的套件數量，藉此計算每個 blob 的共用大小。這個共用大小會在預算期間使用。

實作

這項工具的導入和整合作業將分幾個階段完成。

1. 宣告套件組合的預算。請參閱下方的說明。
2. 編寫 ffx 外掛程式，確保套件組合符合預算
3. 請確認 ffx 外掛程式的輸出內容與建構系統中的先前工具輸出內容相符。如果輸出內容不同，則建構作業應會失敗。請參閱下方的說明。
4. 宣告圖片的預算
5. 新增功能，確保圖片大小符合預算
6. 停用 size_checker.go，並讓新的 ffx 外掛程式負載
7. 刪除 size_checker.go 程式碼。

預算檔案產生作業

為避免為特定產品維護兩組相同的預算，系統會更新建構系統，以便讀取現有的 size_limits.json 和組合產品設定，並產生新的預算檔案。系統會剖析產品設定，收集每個套件資訊清單，並根據 size_limits.json 中設定的目錄預算，將這些資訊清單分類。

預算檔案的可能格式如下：

[
    {
        name: "name-of-package-set",
        packages: [
            "path/to/manifest1.json",
            "path/to/manifest2.json",
        ],
        budget_bytes: 12000,
    },
]

新的大小檢查工具可負荷建構作業後，系統會將產生的預算檔案簽入存放區，並刪除產生的程式碼。

輸出比較

在轉換至新大小檢查器的過程中，建構系統會斷言新工具的輸出內容與新工具的輸出內容相符。我們會編寫指令碼來剖析這兩個工具的輸出內容，並確保每個套件群組 (或目錄) 的預算和計算消耗量相等。為了將兩種輸出格式連結起來，指令碼會假設用於識別套件組合的名稱相同。由於舊工具和新工具都使用相同的基礎機制來計算 blob 大小 (使用 blobfs)，因此計算出來的用量也會相同。

成效

大小檢查工具適用於建構系統，因此相較於網路堆疊，它對效能不穩定的容忍度較高。另一方面，縮短建構時間對開發人員的生產力而言十分重要。此外，由於這項工具必須等待所有套件建構完成，且圖片組合完成後才能開始執行，因此位於建構作業的關鍵路徑上，因此無法並行執行。

目前的 size_checker.go 工具大約需要 1 到 2 秒才能執行，而我們的新工具應可達到相同的時間長度。

人體工學

請參閱「設計」一節。

回溯相容性

這項設計不需要回溯相容。

安全性考量

這項設計不會影響安全性。

隱私權注意事項

這項設計不會影響隱私權。

測試

在 Fuchsia 版本中，新大小檢查工具會與 size_checker.go 一併執行，並比較輸出內容，確保兩者具有相同的預算和計算空間用量。

在工具中新增功能時，也會編寫單元測試。

說明文件

說明文件會新增至 fuchsia.dev。

缺點、替代方案和未知事項

但也有一些不理想的替代方案。

不採取任何行動：這會要求客戶自行建立專用方法來完成大小檢查，但隨著客戶群增加，這項做法無法順利擴充。

重構現有工具：size_checker.go 可重構為支援樹狀結構外。根據命令列指南評分標準，建議將公開工具新增至 ffx，以鼓勵使用者共用工作流程，並提升工具的曝光率。此外，重新設計目前程式碼所需的變更幅度太大，因此實際上，重新編寫工具會更省事。

使用 blobfs 壓縮功能：為了計算每個 blob 的壓縮和對齊大小，可以使用 blobfs-compression 工具，而非產生新的 blobfs 映像檔。這個替代方案的主要缺點是，blobfs-compression 工具無法保證準確的壓縮或對齊。具體來說，blobfs-compression 工具會假設非精簡的 Merkle 樹狀圖，這通常會導致 Blob 大小大於實際大小。此外，blobfs-compression 工具一次只能測量一個 Blob，因此使用起來較為麻煩，而且可能比執行 blobfs 工具一次還要慢。生成 blobfs 圖片會更符合目前的 size_checker.go，且更準確。

既有技術與參考資料

請參閱「背景」一節。