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

RFC-0106：Fuchsia SDK 中包含的元件資訊清單

RFC-0106：Fchsia SDK 中包含的元件資訊清單
狀態	已接受
領域	元件架構
說明	建立元件資訊清單，在 SDK 中加入資料分割 sysroot，並發布到樹狀結構外整合商。
問題	76601
毛皮變化	529382
作者	shayba@google.com jayzhuang@google.com
審查人員	crjohns@google.com geb@google.com ddorwin@google.com gridman@google.com jayzhuang@google.com
提交日期 (年-月-日)	2021-05-12
審查日期 (年-月-日)	2021-06-23

編輯此 RFC

編輯 RFC 中繼資料

摘要

本文件說明如何在 Integrator Development Kit (IDK)。這會建立標準預設用途將元件資訊清單資料分割發布至樹狀結構外 (OOT) 開發人員建立一個通用模式，讓資訊清單資料分割可在不同開發人員環境

讀者應熟悉以下功能：

元件資訊清單
尤其是元件中的 include 語法資訊清單。

提振精神

讓不同環境的工作流程保持一致

自推出以來，元件資訊清單資料分割與 include 語法 cml和cmx有廣泛採用。這類模型用於例如減少樣板封裝實作詳細資料，簡化開發人員工作流程核心領域變化。

目前處理資訊清單的機制包括仰賴來源就能瞭解 Fuchsia 樹狀結構的版面配置如果資訊清單位於毛茸茸星，但是對於 OOT 開發的開發不太好。例如本指南說明如何在 C/C++ 元件中記錄。指南開啟時間：指示開發人員在元件資訊清單中加入以下內容：

{
  include: [ "sdk/lib/diagnostics/syslog/client.shard.cml" ],
}

但本指南指出上述方法僅適用於樹狀結構 (IT) 中。自 OOT 起本指南將說明改為在元件資訊清單中加入以下內容如何有效內嵌資料分割的內容：

{
  use: [
    { protocol: "fuchsia.logger.LogSink" },
  ],
}

其他地方也出現相同的問題。例如「測試執行工具」測試執行工具架構 (支援各種 Fuchsia 上的測試類型，例如 C/C++ GoogleTest、Rust libtest、Gotest ) 的操作說明僅適用於 IT 團隊。但這會不利於給 OOT 開發人員的良好測試做法

此入侵破壞了針對首次加入資訊清單資料分割的目的。位置。不僅如此，當大型資源規模變更時例如針對 Google Cloud 從元件發布記錄最後，AI 和 OOT 開發人員工作流程

遮蓋實作詳細資料

再次查看 LogSink 資料分割範例時，建議採用 Syslog 用戶端以便納入這個資料分割，因為該資料分割會傳入元件的沙箱中讓用戶端程式庫正常運作

目前這組功能非常簡單，只是單一通訊協定預期日後會改變例如，而非目前的通訊協定，用戶端會先將通訊端連線至 Syslog，然後再將緩衝區字元連線至這個通訊協定到該通訊端進行記錄，我們可能會導入一個用於編寫結構化檔案的系統匯出採特殊格式的資料到 VMO，然後在用戶端與有別於目前的追蹤方式

釐清資料分割背後的細節可降低元件作者，並且只想寫入 Syslog (與而且也不會在意這些細節但這也使系統記錄檔維護工具逐步發展這些細節，不需只有元件擁有者的注意

同樣的運作流程也是反向操作 (從元件，而非使用元件)，而且功能類型也不同 (例如目錄功能，而非通訊協定功能)。舉例來說「檢查發現和代管」指南。指南說明開發人員必須新增以下內容至其元件中資訊清單：

{
    capabilities: [
        {
            directory: "diagnostics",
            rights: [ "connect" ],
            path: "/diagnostics",
        },
    ],
    expose: [
        {
            directory: "diagnostics",
            from: "self",
            to: "framework",
        },
    ],
}

開發人員也可以直接加入資料分割。這樣可以減少開發人員從 14 行樣板講解例如向架構公開目錄能力 (大部分而且不必熟悉日後可以視需求變更此機制最後，如果資料分割可攜性和 OOT 元件資訊清單之間，檢查指南會是則縮短了，因為系統不必分別指定專為 IT 與 OOT 開發人員提供的指示。

簡化系統功能的耗用量

另一個更複雜的例子是各種功能也就是以 FIDL 用戶端身分直接使用網路引擎與先前範例一樣，透過用戶端程式庫網路執行階段功能強大且強大，現在的網頁應用程式能執行多種應用程式具備必要權限的裝置作業。 fuchsia.web 定義了網路提供的各種功能必須能夠代管特定的網頁應用程式。

為了簡化在環境中使用相同功能的方式，然後提供給網路引擎，我們將這些資料分割集中處理所有 AI 功能舉例來說，這個資料分割定義了基準成套的「桌子攻擊」網路引擎所需的功能：

{
    "sandbox": {
        "services": [
            "fuchsia.device.NameProvider",
            "fuchsia.fonts.Provider",
            "fuchsia.intl.PropertyProvider",
            "fuchsia.logger.LogSink",
            "fuchsia.memorypressure.Provider",
            "fuchsia.process.Launcher",
            "fuchsia.sysmem.Allocator",
        ]
    }
}

這個資料分割用於定義網頁應用程式所需的額外功能非本機且/或需要網路：

{
    "sandbox": {
        "services": [
            "fuchsia.net.name.Lookup",
            "fuchsia.net.interfaces.State",
            "fuchsia.posix.socket.Provider"
        ]
    }
}

而需要使用這個資料分割，才能在「景觀檢視」中顯示網頁應用程式：

{
    "sandbox": {
        "services": [
            "fuchsia.accessibility.semantics.SemanticsManager",
            "fuchsia.ui.input.ImeService",
            "fuchsia.ui.input.ImeVisibilityService",
            "fuchsia.ui.scenic.Scenic"
        ]
    }
}

有其他資料分割，用於解鎖硬體加速圖形或硬體媒體轉碼器

這類資訊相當豐富，把它放在自己的資料分割中，比將模型加到元件沙箱。而且，這次進化也更加容易。

請注意，此為假設範例。如今，這些資料分割就存在了 IT 人員。這是探索如何將這些資料分割移至 IDK 以建立並不保證一定會這麼做。此外，以上資料分割的內容本例中僅做為說明範例，並非參考用說明文件。

實作

封裝 IDK 發行版本的資訊清單資料分割

透過設定 include 指令路徑 (如同透過 --include-directory 指定至編譯器的路徑) 或 -I 標記)，指向一或多個包含特別巢狀結構的目錄子目錄和標頭檔案的階層結構這樣一來，程式碼就會包含 IT 和 OOT 版本之間可移動的 Fuchsia 專屬標頭。

例如，以下這行 C 代碼同時為 IT 和 OOT 有效：

#include <lib/zx/process.h>

這是因為在 Fuchsia 和 OOT 鎖定的架構中包含的目錄路徑下方有 lib/zx/process.h 檔案。在 Fuchsia 檢查對應的 include 目錄為 //zircon/system/ulib/zx/include/，而在 OOT 建構中，這個路徑需要設為 $FUCHSIA_SDK/pkg/zx/include/。另請參閱：IDK 版面配置。

如要在 include 路徑中設定目錄，以便將 include 指令設為可攜性，請參閱這也稱為設定「sysroot」

我們會以類似的方式，部署位於 $FUCHSIA_SDK/pkg/ 以下的元件資訊清單資料分割：概念上與資料分割用途相關聯的子路徑。依照 IT 和 OOT 中的指示，在 cmc 中設定 --includepath 旗標建構應用程式

例如，上述範例使用的系統記錄檔資料分割為：

納入方式如下：include: [ "syslog/client.shard.cml" ]。
於 //sdk/lib/syslog/client.shard.cml 下找到 IT，因此我們會進行設定 cmc IT 和--includepath $FUCHSIA_CHECKOUT/sdk/lib/。
根據 $FUCHSIA_SDK/pkg/syslog/client.shard.cml 發現 OOT，因此我們會使用 --includepath $FUCHSIA_SDK_ROOT/pkg/ 設定 cmc OOT。

可攜式資料分割與本機資料分割

一般而言，我們會提供部分資料分割給 OOT 開發人員卻只用於 IT 領域以上是我們檢視的一些資料分割的例子 OOT 基本技術以資訊科技為目的的資料分割為例這個資料分割，其中之一是一個是系統元件的測試雙重測試。另有沒有用於這個特定的資料分割 OOT。

因此，部分資料分割應設為可攜性並發布於 IDK 中其他元件應保持私人狀態，只供特定存放區存取。

我們現在要用相對和做為絕對路徑資訊清單 include 指令中應解析的路徑至可攜碼的資料分割中不應使用前置 //，例如 syslog/client.shard.cml。系統會依據資料分割的 sysroot 來解決這些問題。另一方面，只有特定存放區本機的資料分割路徑開頭應為 //，並解析為設定容器例如，這個資料分割應由 IT 管理員透過路徑 //src/sys/test_manager/meta/common.shard.cml。

與 `cmc` 整合建構系統

建構系統，例如主目錄 GN 和Ninja 版本所有指定 Fuchsia 的樹狀結構外版本，都已與 cmc 整合。這些整合服務必須針對新的納入行為加以修改。特別針對下列 cmc 子指令：

compile
include
check-includes

叫用 cmc 時需要指定下列標記：

--includeroot：解析前置字串為 // 的路徑，包含的路徑。
--includepath：零或多個要解析其他路徑的路徑，位於指定的順序 (第一個比對符合)。

將資料分割做為 SDK Atom

資料分割會由建構系統納入 IDK 中，做法類似其他 IDK 則都會受到處理。我們會重複使用現有的 sdk_atom() 範本指定 id 參數 IDK 版面配置。

將資料分割新增至 IDK 的程序

資料分割可以指定可能與平台重疊的合約期望途徑。例如，系統日誌資料分割參照了 Fuchsia 中的通訊協定命名空間 - fuchsia.logger.LogSink - 全球知名的 Fuchsia 系統元件。因此，透過 IDK 發布的資料分割視為 API 和 SDK Atom，並且會透過其他管道進行 API 審查就像現在用來新增或修改 FIDL 檔案發行為 IDK你也可以使用sdk_atom()概念舉例來說，先引進資料分割為「內部」(不得為然後再透過現有程序。

日後的工作

通訊埠 `expect_includes()`

Fuchsia 的 GN 版本提供範本，可預期該相依元件在資訊清單中加入特定資料分割 (請參閱本指南)。這項解決方案的其中一項好處是引導已新增依附元件的開發人員新增某項服務的資訊清單資料分割確保程式庫能存取才能正常運作

IT 開發人員對此提供相當正面的評價，有些 OOT 開發人員表達興趣。這個範本或其概念可攜碼轉移傳送至 GN SDK，以及使用 Bazel 的 Bazel/Blaze SDK 切面或 Bazel 提供者。

另請參閱：https://fxbug.dev/42156975

成效

由於所有工作都是在下列時間完成，因此本提案不會影響執行階段效能建構時間

系統在建構期間進行處理會增加一些額外工作。不過，這個狀況是正常情況不會影響建構的實際時間根據先前的研究即使建構不在關鍵路徑上的作業，通常也不會增加建構延遲時間，但直接衍生自來源 (例如 cmc 叫用、fidlc 叫用等) 零在關鍵路徑上，因為這項工作可順暢平行處理安排彈性工作時間

舉例來說，請考慮採用這項變更，其中有一個常見的作業 cmc 的叫用速度已達約 300 毫秒，但其實有數千次叫用我們測量的版本中的 cmc 對建構實際時間沒有影響。

人體工學

我們重視的原則是確保資訊清單內含機制簡單、公開透明。舉例來說，您可以產生後續處理的元件其中 include 指令取代為包含檔案的內容 (視需要使用簡單的指令)。

fx cmc include manifest --includepath $(fx get-src-dir)

這與在 C/C++ 原始碼執行 C 預先處理器的原則類似 (請參閱 man cpp)。

此外，cmc 還會產生易於排解的簡單錯誤，包括包含循環等異常錯誤情況。所有支援的錯誤都是單元測試

隨附於 Fuchsia IDK 中預先建構的 cmc 工具。是完全密封，且在不任何外部依附元件的情況下執行。系統可能會叫用就不需要進行建構系統整合。

回溯相容性

變更 IDK 中的資料分割會影響在選擇後新建的 OOT 元件最新 IDK 版本，但不會影響舊的預先建構。必須接受治療避免破壞性變更，並對平台變更採用標準做法：軟能否切換多個版本、支援視窗以及與利害關係人

就像對平台演進的所有層面一樣，變更都應經過全面測試。以及破壞性變更的管理方式，應該要能承受破壞、例如使用某些版本管理機制請注意，平台問題版本管理，以及這個問題的子集 (如 FIDL) 版本管理，目前保持開啟，且不在墨西哥的 RFC。

安全性考量

元件資訊清單會定義能力轉送和沙箱，這會影響安全性然而，資訊清單的目標並非最終會產生不同的資訊清單，但故意產生相同的資訊清單更符合人體工學只要這些裝置的處理程序，因此不會對安全性造成任何影響。

協助開發人員瞭解資訊清單的顯示內容都已經過處理，可以使用上述的 cmc include。

測試

cmc 中的現有功能已由單元和整合服務使用測試。cmc的測試涵蓋率超過 90%，特別是加入子指令執行完畢。對於 Fuchsia 的所有待變更項目 IDK 或 OOT 整合將依 SDK 指示測試，並依預期方式測試。

IDK 中的元件資訊清單應視為任何其他 IDK 並發生在 CTS 測試涵蓋範圍內

說明文件

已記錄過 include 語法。

cmc include 指令是透過 cmc help include 自行記錄。

目前指示 OOT 開發人員使用資訊清單的替換項目將停止更新，即可。

缺點、替代方案和未知

不執行任何動作

我們可以維持現狀，但代價是不解決所述問題。

將 IDK 中的資料分割整理為頂層構件

替代發布元件資訊清單資料分割的替代方案。 IDK 中的地點，例如 $FUCHSIA_SDK_ROOT/pkg 或 $FUCHSIA_SDK_ROOT/fidl (根據資料分割的邏輯關聯)，我們也探索了建立單一基本目錄的替代方案。分別是元件資訊清單資料分割。例如： $FUCHSIA_SDK_ROOT/component_manifests/。這與所有 .fidl 的情況類似檔案會整理在「$FUCHSIA_SDK_ROOT/fidl/」底下，也就是按類型匯總 (為 FIDL 檔案)，而不是由另一個邏輯關聯匯總 (例如 pkg/async/、pkg/memfs/、pkg/zx/)。

這個替代選項已根據 SDK 客戶的意見回饋遭拒，並表示他們更偏好 SDK 內容的邏輯關聯，而不是使用可以將不同類型的檔案分散至不同的基本目錄已接受的設計例如，您可以將元件資訊清單資料分割，用於使用 Syslog C++ 標頭，用於從以 C++ 編寫的元件寫入 syslog。

既有藝術品和參考資料

元件資訊清單所含項目是以 C/C++ 包含為靈感來源。

cmc include 指令是以執行 C 的 cpp 指令做為靈感來源並列印後續處理結果。請參閱以下內容： man cpp。