元件資訊清單 (.cml) 參考資料

.cml 檔案包含單一 json5 物件常值，其中包含下列鍵。

在預期使用字串值的地方，通常會列出有效值清單。以下字串值類型會重複使用，且必須遵循特定規則。

.cml 檔案會編譯為 FIDL 線路格式 (.cm) 檔案。

字串類型

名稱

功能和元件的子項都會命名。名稱字串可包含下列一或多個字元：A-Z、a-z、0-9、_、.、-。長度不得超過 255 個半形字元，且開頭不得為 . 或 -。

路徑

路徑是 / 字元分隔的名稱序列。路徑長度不得超過 4095 個半形字元。整份文件中

• 相對路徑的開頭不能為 / 字元。
• 命名空間和傳出目錄路徑必須以 / 字元開頭。

參考資料

參照字串的格式為 #<name>，其中 <name> 是子項的名稱：

• 名稱為 <name> 的靜態子項例，或
• 名稱為 <name> 的集合。

頂層鍵

include

string 陣列 (選用)

選用的 include 屬性會描述要合併至此元件資訊清單的零個或多個其他元件資訊清單檔案。例如：

include: [ "syslog/client.shard.cml" ]

在上述範例中，元件資訊清單會納入 syslog 程式庫提供的資訊清單區塊內容，藉此確保元件在嘗試寫入 syslog 時，能正確執行。依慣例，這類檔案稱為「資訊清單區塊」，結尾為 .shard.cml。

以 // 開頭的包含路徑相對於 Fuchsia 檢出的來源根目錄。不過，如果包含路徑前方沒有 // (如上例所示)，系統會從匯出元件資訊清單碎片的 Fuchsia SDK 程式庫 (//sdk/lib) 中解析路徑。

以下是 Fuchsia 檢查作業中的兩個相等的包含路徑，供您參考：

• syslog/client.shard.cml
• //sdk/lib/syslog/client.shard.cml

您可以叫用下列指令，查看將任何和所有包含項目合併至元件資訊清單檔案的結果：

fx cmc include cml_file --includeroot $FUCHSIA_DIR --includepath $FUCHSIA_DIR/sdk/lib

只要屬性相同，包含功能就能處理參照相同能力的重複 use、offer、expose 或 capabilities 宣告。例如：

// my_component.cml
include: [ "syslog.client.shard.cml" ]
use: [
    {
        protocol: [
            "fuchsia.posix.socket.Provider",
            "fuchsia.logger.LogSink",
        ],
    },
],

// syslog.client.shard.cml
use: [
    { protocol: "fuchsia.logger.LogSink" },
],

在這個範例中，合併檔案的內容會與 my_component.cml 相同，fuchsia.logger.LogSink 會進行重複資料移除。

不過，這會導致編譯失敗：

// my_component.cml
include: [ "syslog.client.shard.cml" ]
use: [
    {
        protocol: "fuchsia.logger.LogSink",
        // properties for fuchsia.logger.LogSink don't match
        from: "#archivist",
    },
],

// syslog.client.shard.cml
use: [
    { protocol: "fuchsia.logger.LogSink" },
],

availability 屬性是這項限制的例外狀況。如果兩個路由宣告相同，且其中一個可用性強於另一個，系統會將可用性「提升」至較強的值 (如果缺少 availability，則預設為 required)。例如：

// my_component.cml
include: [ "syslog.client.shard.cml" ]
use: [
    {
        protocol: [
            "fuchsia.posix.socket.Provider",
            "fuchsia.logger.LogSink",
        ],
        availability: "optional",
    },
],

// syslog.client.shard.cml
use: [
    {
        protocol: "fuchsia.logger.LogSink
        availability: "required",  // This is the default
    },
],

變成：

use: [
    {
        protocol: "fuchsia.posix.socket.Provider",
        availability: "optional",
    },
    {
        protocol: "fuchsia.logger.LogSink",
        availability: "required",
    },
],

包含項目是傳遞的，也就是說每個分片都可以有自己的包含項目。

包含路徑可能會有菱形依附元件。例如，以下是有效的例子： A 包含 B、A 包含 C、B 包含 D、C 包含 D。在這種情況下，A 會間接包含 B、C、D。

包含路徑不得有循環。例如，以下情況無效：A 包含 B，B 包含 A。上述循環會導致編譯時錯誤。

program

object (選用)

可執行的元件包含 program 區段。program 區段必須設定 runner 屬性，才能選取執行程式來執行元件。program 部分的其餘格式由該特定執行元件決定。

ELF 執行緒

如果元件使用 ELF 執行元件，program 至少必須包含下列屬性：

• runner：必須設為 "elf"
• binary：可執行二進位檔的套件相對路徑
• args (選用)：引數清單

範例：

program: {
    runner: "elf",
    binary: "bin/hippo",
    args: [ "Hello", "hippos!" ],
},

如需完整的屬性清單，請參閱：ELF Runner

其他跑者

如果元件使用自訂執行元件，則 program 節內的值 (除了 runner 以外) 皆為執行元件專屬。執行程式會以鍵/值組合的字典形式接收引數。請參閱所使用的特定執行元件，判斷該執行程式預期收到哪些鍵，以及如何解讀這些鍵。

children

object 陣列 (選用)

children 部分會宣告子項元件執行個體，如「子項元件執行個體」一節所述。

• name：(string) 子項元件執行個體的名稱，為以下一個或多個字元的字串：a-z、0-9、_、.、-。當您在參照中使用此元件時，名稱會識別此元件。
• url：(string) 子項元件執行個體的元件網址。
• startup：(string) 元件執行個體的啟動模式。下列任一項：
  • lazy (預設)：只有在其他元件執行個體繫結至該元件執行個體時，才啟動元件執行個體。
  • eager：在父項啟動後立即啟動元件執行個體。
• on_terminate：(選用 string) 決定在這個元件終止時要套用的錯誤復原政策。
  • none (預設)：不採取任何行動。
  • reboot：如果元件因非正常關閉以外的任何原因而終止，請妥善重新啟動系統。這是一項特殊功能，僅供少數元件使用。詳情請參閱終止政策。
• environment：(選用 string) 如果存在，則為要指派給子項元件執行個體的環境名稱，其中一個為 environments。如果省略，子項會繼承指派給此元件的相同環境。

children: [
    {
        name: "logger",
        url: "fuchsia-pkg://fuchsia.com/logger#logger.cm",
    },
    {
        name: "pkg_cache",
        url: "fuchsia-pkg://fuchsia.com/pkg_cache#meta/pkg_cache.cm",
        startup: "eager",
    },
    {
        name: "child",
        url: "#meta/child.cm",
    }
],

collections: [
    {
        name: "tests",
        durability: "transient",
    },
],

• name：(string) 環境名稱，為以下字元之一或多個字元的字串：a-z、0-9、_、.、-。在參照中使用時，名稱會識別此環境。
• extends：(選用 string) 環境應如何擴充此領域的環境。
  • realm：繼承此元件環境的所有屬性。
  • none：從空環境開始，不要繼承任何內容。

• runners：(選用 object 陣列) 在環境中註冊的執行者。物件陣列，具有下列屬性：

  • runner：(string) 執行元件能力的名稱，來源在 from 中指定。
  • from：(string) 執行元件能力的來源，可選值如下：
    • parent：元件的父項。
    • self：這個元件。
    • #<child-name>：子元件執行個體的參照。
  • as：(選用 string) 執行元件的明確名稱，這個名稱會在這個環境中使用。如果省略此屬性，系統會預設為 runner。

• resolvers：(選用的 object 陣列) 在環境中註冊的解析器。物件陣列，其中包含下列屬性：

  • resolver：(string) 解析器能力的名稱，其來源在 from 中指定。
  • from：(string) 解析器能力的來源，其中包括：
    • parent：元件的父項。
    • self：這個元件。
    • #<child-name>：子元件例項的參照。
  • scheme：(string) 解析器應處理解析的網址架構。

• debug：(可選的 object 陣列) 可供透過 use from debug 取得的此環境中的任何元件使用的偵錯通訊協定。

  • protocol：(選用 string or array of strings) 要提供的通訊協定名稱。
  • from：(string) 功能的來源，可選填：
    • parent：元件的父項。
    • self：這個元件。
    • #<child-name>：子元件例項的參照。
  • as：(選用 string) 如果指定此值，protocol 中的能力應提供給用戶端的名稱。如果 protocol 是陣列，則不允許。

• __stop_timeout_ms：(選用 number) 在通知此環境中的元件應終止後，等待強制終止元件的毫秒數。如果環境是從 none 延伸而來，則這是必填欄位。

environments: [
    {
        name: "test-env",
        extends: "realm",
        runners: [
            {
                runner: "gtest-runner",
                from: "#gtest",
            },
        ],
        resolvers: [
            {
                resolver: "full-resolver",
                from: "parent",
                scheme: "fuchsia-pkg",
            },
        ],
    },
],

• path：(選用 string) 元件程式的傳出目錄中，用來擷取能力的路徑。

  對於 protocol 和 service，預設為 /svc/${protocol}，否則為必要。

  對於 protocol，路徑的目標必須是管道，通常會使用與這項能力名稱相符的通訊協定。

  對於 service 和 directory，路徑的目標必須是目錄。

  對於 runner，路徑的目標必須是管道，且必須使用通訊協定 fuchsia.component.runner.ComponentRunner。

  對於 resolver，路徑的目標必須是管道，且必須使用通訊協定 fuchsia.component.resolution.Resolver。

  對於 dictionary，這是選用項目。如果提供，則為程式提供的 fuchsia.component.sandbox/DictionaryRouter 路徑，應傳回 fuchsia.component.sandbox/DictionaryRef，藉此讓程式可動態提供自身的字典。如果這是 dictionary 的設定，則不允許 offer 使用此字典。

• rights：(選用 array of string) (僅限 directory) 使用此目錄時，可設定的最大目錄權限。

• from：(選用 string) (僅限 storage) 支援此儲存空間能力的現有目錄能力的來源元件，其中包括：

  • parent：元件的父項。
  • self：這個元件。
  • #<child-name>：子元件例項的參照。

• backing_dir：(選用 string) (僅限 storage) 支援儲存空間的目錄能力名稱。該能力必須可從 from 中參照的元件取得。

• subdir：(選用 string) (僅限 storage) backing_dir 中的子目錄，用於建立各個元件的隔離儲存空間目錄

• storage_id：(選用 string) (僅限 storage) 用於元件隔離儲存空間的 ID，可選填：

  • static_instance_id：元件 ID 索引中的執行個體 ID 會做為元件儲存空間的鍵。未列於元件 ID 索引中的元件無法使用這項儲存空間能力。
  • static_instance_id_or_moniker：如果元件列於元件 ID 索引中，系統會使用執行個體 ID 做為元件儲存空間的鍵。否則，系統會使用儲存空間能力的元件路徑名稱。

• type：(選用 string) (僅限 configuration) 設定類型，其中包括：

  • bool：布林值類型。
  • uint8：未簽署的 8 位元類型。
  • uint16：無符號 16 位元類型。
  • uint32：未簽署的 32 位元類型。
  • uint64：不帶正負號的 64 位元類型。
  • int8：已簽署的 8 位元類型。
  • int16：已簽署的 16 位元型別。
  • int32：已簽署的 32 位元類型。
  • int64：已簽署的 64 位元類型。
  • string：ASCII 字串類型。
  • vector：向量類型。如需瞭解向量中的元素類型，請參閱 element。

• max_size：(選用 non-zero number) (僅限 configuration) 僅在這個設定 type 為「字串」時支援。這是字串的大小上限。

• max_count：(選用 non-zero number) (僅限 configuration) 僅在這個設定 type 為「向量」時支援。這是向量中的元素數量上限。

• element：(選用 object) (僅限 configuration) 僅在這個設定 type 為「向量」時支援。這是設定向量中的元素類型。

  範例 (簡單型別)：

  { type: "uint8" }
  

  範例 (字串類型)：

  {
    type: "string",
    max_size: 100,
  }
  

• value：(選用 any) (僅限 configuration) 設定值。

• delivery：(選用 string) (僅限 protocol) 指定架構在使用者要求能力時，從這個元件的傳出目錄開啟通訊協定的時間。允許的值如下：

  • eager：(預設) 架構會在某些使用者元件要求時，立即開啟能力。
  • on_readable：當連線要求中管道的伺服器端點可讀取時，架構就會開啟這項能力。

• from：(選用 string) 能力的來源。預設值為 parent。下列其中一個項目：

  • parent：元件的父項。
  • debug：指派給此元件的環境中的 [debug_capabilities][fidl-environment-decl] 之一。
  • framework：元件架構執行階段。
  • self：這個元件。
  • #<capability-name>：所要求能力衍生自的其他能力名稱。
  • #<child-name>：子元件例項的參照。

  [fidl-環境-decl]: /reference/fidl/fuchsia.component.decl#Environment

• path：(選用 string) 在元件命名空間中安裝能力的路徑。通訊協定預設為 /svc/${protocol}。這是 directory 和 storage 的必要欄位。此屬性不適用於包含能力名稱陣列的宣告，以及執行元件可用性。

• rights：(選用 array of string) (僅限 directory) 要套用至元件命名空間中的目錄的最大目錄權限。

• subdir：(選用 string) (僅限 directory) 目錄能力中的子目錄，可在元件命名空間中提供。

• scope：(選用 string or array of strings) (僅限 event_stream) 定義後，事件串流只會包含範圍中定義的元件相關事件。

• filter：(選用 object) (僅限 event_stream) 要求功能的事件串流需要指定篩選器，以便參照事件串流中事件適用的通訊協定。篩選器的內容會是從「名稱」對應到「通訊協定名稱」的物件。

• dependency：(選用 string) 來源和此元件之間的依附元件類型，可選下列任一項：

  • strong：強依附元件，用於決定關機順序。元件管理員保證會在來源之前停止目標。此為預設值。
  • weak：弱依附元件，系統會在關機時忽略。當元件管理員停止父項領域時，來源可能會在用戶端之前停止。弱依附元件的用戶端必須能夠處理這些依附元件無法使用的問題。這項屬性不允許使用於執行元件功能，因為執行器功能一律是 strong 依附元件。

• availability：(選填 string) 這項能力的供應情形。以下任一項目：

  • required (預設)：必要的依附元件，元件無法在沒有此能力的情況下執行其工作。
  • optional：選用依附元件，元件可在沒有此能力情況下運作 (但如果無法使用此能力，部分功能可能會停用)。
  • transitional：來源可能完全省略路徑，甚至不必從 void 轉送。用於引入新功能的軟性轉場。這個屬性不允許使用於執行元件功能，因為執行器功能一律為 required。

  詳情請參閱可用性說明文件。

• key：(選用 string) (僅限 config) 元件 config 區塊中的設定鍵，這項能力會設定此鍵。

• type：(選用 string) (僅限 config) 設定類型，其中包括：

  • bool：布林值類型。
  • uint8：未簽署的 8 位元類型。
  • uint16：無符號 16 位元類型。
  • uint32：未簽署的 32 位元類型。
  • uint64：不帶正負號的 64 位元類型。
  • int8：已簽署的 8 位元類型。
  • int16：已簽署的 16 位元型別。
  • int32：已簽署的 32 位元類型。
  • int64：已簽署的 64 位元類型。
  • string：ASCII 字串類型。
  • vector：向量類型。如要瞭解向量中的元素類型，請參閱 element

• max_size：(選用 non-zero number) (僅限 configuration) 僅在這個設定 type 為「字串」時支援。這是字串的大小上限。

• max_count：(選用 non-zero number) (僅限 configuration) 僅在這個設定 type 為「向量」時支援。這是向量中的元素數量上限。

• element：(選用 object) (僅限 configuration) 僅在這個設定 type 為「向量」時支援。這是設定向量中的元素類型。

  範例 (簡單型別)：

  { type: "uint8" }
  

  範例 (字串類型)：

  {
    type: "string",
    max_size: 100,
  }
  

• default：(選用 any) (僅限 configuration) 此設定的預設值。如果能力為選用功能且從 void 路由，系統會使用預設值。只有在 availability 不是 required 時，系統才支援這項功能。

use: [
    {
        protocol: [
            "fuchsia.ui.scenic.Scenic",
            "fuchsia.accessibility.Manager",
        ]
    },
    {
        directory: "themes",
        path: "/data/themes",
        rights: [ "r*" ],
    },
    {
        storage: "persistent",
        path: "/data",
    },
    {
        event_stream: [
            "started",
            "stopped",
        ],
        from: "framework",
    },
    {
        runner: "own_test_runner".
        from: "#test_runner",
    },
],

• from：(string or array of strings) from：能力的來源，其中之一：
  • self：這個元件。需要對應的 capability 宣告。
  • framework：元件架構執行階段。
  • #<child-name>：子元件例項的參照。
• as：(選用 string) 目標會知道能力的名稱。如果省略，系統會預設為原始名稱。提供多個能力名稱陣列時，無法使用 as。
• to：(選用 string) 能力目標。parent 或 framework。預設為 parent。
• rights：(選用 array of string) (僅限 directory) 要套用至公開目錄功能的最大目錄權限。
• subdir：(選用 string) (僅限 directory) 來源目錄能力中子目錄的相對路徑，用於路由。
• event_stream：(選用 string or array of strings) (僅限 event_stream) 公開的事件串流名稱。
• scope：(選用 string or array of strings) (僅限 event_stream) 公開的事件串流範圍。這可用於將事件串流參照的元件範圍縮小，並讓事件串流只參照範圍內定義的元件。

• availability：(選用 string) availability (選用)：這項能力的供應情形。會影響建構時間和執行階段路徑驗證。下列其中一個項目：

  • required (預設)：必要依附元件，來源必須存在且提供。如果此公開項目的目標需要此能力才能正常運作，請使用此選項。
  • optional：選用依附元件。當公開目標可在有或沒有此能力的情況下運作時，請使用此選項。目標不得對能力有 required 依附元件。此公開的最終來源必須是 void 或實際元件。
  • same_as_target：這項能力的預期可用性會與目標一致。如果目標需要這項能力，則這個欄位會設為 required。如果目標對能力有選用依附元件，則欄位會設為 optional。
  • transitional：類似 optional，但會容許來源缺少的情況。請僅在多步驟程式碼變更的轉換期間使用此方法，以免發生驗證錯誤。

  詳情請參閱可用性說明文件。

• source_availability：(選用 string) 這項商品的來源是否必須存在。下列其中一個項目：

  • required (預設)：來源 (from) 必須在這個資訊清單中定義。
  • unknown：如果在處理包含項目後，此優惠的來源 (from) 未在資訊清單中定義，則來源會重寫為 void。

expose: [
    {
        directory: "themes",
        from: "self",
    },
    {
        protocol: "pkg.Cache",
        from: "#pkg_cache",
        as: "fuchsia.pkg.PackageCache",
    },
    {
        protocol: [
            "fuchsia.ui.app.ViewProvider",
            "fuchsia.fonts.Provider",
        ],
        from: "self",
    },
    {
        runner: "web-chromium",
        from: "#web_runner",
        as: "web",
    },
    {
        resolver: "full-resolver",
        from: "#full-resolver",
    },
],

• service：(選用 string or array of strings) 在轉送服務時，服務功能的名稱。
• protocol：(選用 string or array of strings) 轉送通訊協定時，通訊協定功能的名稱。
• directory：(選用 string or array of strings) 在路由目錄時，目錄功能的名稱。
• runner：(選用 string or array of strings) 在路由執行元件時，執行者功能的名稱。
• resolver：(選用 string or array of strings) 在路由解析工具時，名稱的解析工具功能。
• storage：(選用 string or array of strings) 轉送儲存空間能力時，儲存空間功能的名稱。
• dictionary：(選用 string or array of strings) 傳送字典時，字典功能的名稱。
• config：(選用 string or array of strings) 轉送設定時，設定能力的名稱。
• from：(string or array of strings) from：能力的來源，其中之一：
  • parent：元件的父項。這個來源可用於所有能力類型。
  • self：這個元件。需要對應的 capability 宣告。
  • framework：元件架構執行階段。
  • #<child-name>：子元件例項的參照。您只能在提供通訊協定、目錄或執行元件功能時使用這個來源。
  • void：來源經過刻意省略。只有在 availability 為 optional 或 transitional 時才有效。
• to：(string or array of strings) 能力目標。下列任一項：
  • #<target-name> 或 [#name1, ...]：子項或集合的參照，或參照陣列。
  • all：包含所有子項參照的 offer 子句的簡寫形式。
• as：(選用 string) 能力的明確名稱，因為目標會知道該名稱。如果省略，系統會預設為原始名稱。提供多個名稱的陣列時，無法使用 as。
• dependency：(選用 string) 來源和目標之間的依附元件類型，可選下列任一項：
  • strong：強依附元件，用於決定關機順序。元件管理員保證會在來源之前停止目標。此為預設值。
  • weak：弱依附元件，會在關機期間忽略。元件管理員停止上層領域時，來源可能會在用戶端之前停止。弱依附元件的用戶端必須能夠處理這些依附元件無法使用的問題。
• rights：(選用 array of string) (僅限 directory) 要套用至提供的目錄能力的最大目錄權限。
• subdir：(選用 string) (僅限 directory) 來源目錄能力中子目錄的相對路徑，用於路由。
• event_stream：(選用 string or array of strings) (僅限 event_stream) 提供的事件串流名稱。
• scope：(選用 string or array of strings) (僅限 event_stream) 定義後，事件串流只會包含範圍中定義的元件相關事件。

• availability：(選用 string) availability (選用)：這項能力的供應情形。會影響建構時間和執行階段路徑驗證。下列其中一個項目：

  • required (預設)：必要依附元件，來源必須存在且提供。如果這項商品的目標需要這項能力才能正常運作，請使用此選項。
  • optional：選用依附元件。當商品目標不論是否具備這項能力都能運作時，請使用此選項。目標不得對能力有 required 依附元件。此優惠的最終來源必須為 void 或實際元件。
  • same_as_target：這項能力的預期可用性會與目標一致。如果目標需要這項能力，則這個欄位會設為 required。如果目標對能力有選用依附元件，則欄位會設為 optional。
  • transitional：類似 optional，但會容許來源缺少的情況。請僅在多步驟程式碼變更的轉換期間使用此方法，以免發生驗證錯誤。

  詳情請參閱可用性說明文件。

• source_availability：(選用 string) 這項商品的來源是否必須存在。下列其中一個項目：

  • required (預設)：來源 (from) 必須在這個資訊清單中定義。
  • unknown：如果在處理包含項目後，此優惠的來源 (from) 未在資訊清單中定義，則來源會重寫為 void。

offer: [
    {
        protocol: "fuchsia.logger.LogSink",
        from: "#logger",
        to: [ "#fshost", "#pkg_cache" ],
        dependency: "weak",
    },
    {
        protocol: [
            "fuchsia.ui.app.ViewProvider",
            "fuchsia.fonts.Provider",
        ],
        from: "#session",
        to: [ "#ui_shell" ],
        dependency: "strong",
    },
    {
        directory: "blobfs",
        from: "self",
        to: [ "#pkg_cache" ],
    },
    {
        directory: "fshost-config",
        from: "parent",
        to: [ "#fshost" ],
        as: "config",
    },
    {
        storage: "cache",
        from: "parent",
        to: [ "#logger" ],
    },
    {
        runner: "web",
        from: "parent",
        to: [ "#user-shell" ],
    },
    {
        resolver: "full-resolver",
        from: "parent",
        to: [ "#user-shell" ],
    },
    {
        event_stream: "stopped",
        from: "framework",
        to: [ "#logger" ],
    },
],

config: {
    debug_mode: {
        type: "bool"
    },
}

config: {
    verbose: {
        type: "bool",
        mutability: [ "parent" ],
    },
},

config: {
    verbosity: {
        type: "string",
        max_size: 20,
    }
}

config: {
    tags: {
        type: "vector",
        max_count: 20,
        element: {
            type: "string",
            max_size: 50,
        }
    }
}