.cml 文件包含一个具有以下键的 JSON5 对象字面量。
如果需要提供字符串值，通常会提供有效值的列表。 以下字符串值类型会被重复使用，并且必须遵循特定规则。
.cml 文件会被编译为 FIDL 线格式 (.cm) 文件。
字符串类型
姓名
功能和组件的子级都有名称。名称字符串可以包含以下一个或多个字符：A-Z、a-z、0-9、_、.、-。长度不得超过 255 个字符，且不得以 . 或 - 开头。
路径
路径是由 / 字符分隔的名称序列。路径的长度不得超过 4095 个字符。在整个文档中，
- 相对路径不能以
/字符开头。 - 命名空间和输出目录路径必须以
/字符开头。
参考编号
引用字符串采用 #<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
您可以通过调用以下命令，查看将任何和所有 include 合并到组件清单文件中的结果：
fx cmc include cml_file --includeroot $FUCHSIA_DIR --includepath $FUCHSIA_DIR/sdk/lib
只要属性相同，include 就可以处理引用同一功能的重复 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 属性，以选择用于运行组件的 runner。其余 program 部分的格式由相应 runner 确定。
ELF 运行程序
如果组件使用 ELF Runner，program 必须至少包含以下属性：
runner：必须设置为"elf"binary：可执行二进制文件的软件包相关路径args（可选）：实参列表
示例：
program: {
runner: "elf",
binary: "bin/hippo",
args: [ "Hello", "hippos!" ],
},
如需查看完整的属性列表，请参阅：ELF Runner
其他跑步者
如果某个组件使用自定义 runner，则 program stanza 中除 runner 之外的值特定于该 runner。运行程序会收到以键值对字典形式呈现的实参。请参阅所用特定 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
object 的数组（可选）
collections 部分用于声明集合，如组件集合中所述。
name：(string) 组件集合的名称，是一个包含以下一个或多个字符的字符串：a-z、0-9、_、.、-。此名称用于在引用中标识相应集合。durability：(string) 集合中子组件实例的时长。transient：实例会一直存在，直到其父级停止或被明确销毁。single_run：实例在创建时启动，在停止时销毁。
environment：（可选，string）如果存在，则为将分配给此集合中实例的环境，为environments之一。如果省略，此集合中的实例将继承分配给相应组件的相同环境。allowed_offers：（可选string）针对相应集合中组件的动态优惠的限制。 在调用fuchsia.component.Realm/CreateChild时指定动态优惠。static_only：仅限此.cml文件中指定的那些。无动态优惠。 这是默认值。static_and_dynamic：允许静态优惠和在运行时通过CreateChild指定的优惠。
allow_long_names：（可选bool）允许子名称的长度最多为 1024 个字符，而不是通常的 255 个字符限制。 默认值为 false。persistent_storage：（可选bool）如果设置为true，则动态子实例及其后代使用的隔离存储空间中的数据将在实例销毁后保留。使用相同名称创建的新子实例将与之前的实例共用相同的存储路径。
示例：
collections: [
{
name: "tests",
durability: "transient",
},
],
environments
object 的数组（可选）
environments 部分用于声明环境，如环境中所述。
name：(string) 环境的名称，是一个包含以下一个或多个字符的字符串：a-z、0-9、_、.、-。该名称用于在引用中标识相应环境。extends：（可选string）环境应如何扩展此 realm 的环境。realm：从相应组件的环境继承所有属性。none：从空环境开始，不继承任何内容。
runners：（可选的object数组）环境中注册的 runner。一个对象数组，包含以下属性：resolvers：（可选的object数组）环境中注册的解析器。一个对象数组，包含以下属性：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",
},
],
},
],
capabilities
object 的数组（可选）
capabilities 部分定义了相应组件提供的功能。
必须在此处声明从 self 提供或公开的功能。
功能字段
这支持以下功能键。必须设置以下其中一个值：
protocol：（可选string or array of strings）service：（可选string or array of strings）directory：（可选string）storage：（可选string）runner：（可选string）resolver：（可选string）event_stream：（可选string or array of strings）dictionary：（可选string）config：（可选string）
其他字段
此功能支持以下额外字段：
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）用于隔离组件存储空间的标识符，可以是以下值之一：static_instance_id：组件 ID 索引中的实例 ID 用作组件存储空间的键。未在组件 ID 索引中列出的组件将无法使用此存储功能。static_instance_id_or_moniker：如果组件列在组件 ID 索引中，则实例 ID 用作组件存储空间的键。否则，将使用存储功能中的组件 moniker。
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为“vector”时受支持。 这是向量中的最大元素数。element：（可选object）（仅限configuration）仅当此配置type为“vector”时受支持。 这是配置向量中元素的类型。示例（简单类型）：
{ type: "uint8" }示例（字符串类型）：
{ type: "string", max_size: 100, }value：（可选，any）（仅限configuration）配置的值。delivery：（可选string）（仅限protocol）指定框架何时在有人请求相应功能时从相应组件的传出目录打开协议。允许的值有：eager：（默认）只要有某些使用方组件请求，框架就会立即打开功能。on_readable：当连接请求中流水线传输的服务器端点变为可读时，框架将打开相应功能。
use
object 的数组（可选）
对于可执行组件，声明此组件在运行时在其命名空间中所需的功能。功能从 parent 路由，除非另有指定；并且每个功能都必须通过此组件与功能来源之间的所有组件具有有效路由。
功能字段
这支持以下功能键。必须设置以下其中一个值：
service：（可选string or array of strings）directory：（可选string）protocol：（可选string or array of strings）dictionary：（可选string）storage：（可选string）event_stream：（可选string or array of strings）runner：（可选string）config：（可选string）
其他字段
此功能支持以下额外字段：
from：（可选，string）功能来源。默认值为parent。以下权限之一：parent：组件的父级。debug：分配给相应组件的环境中的 [debug_capabilities][fidl-environment-decl] 之一。framework：组件框架运行时。self：此组件。#<capability-name>：所请求的功能所派生自的另一功能的名称。#<child-name>：对子组件实例的引用。
[fidl-environment-decl]：/reference/fidl/fuchsia.component.decl#Environment
path：（可选string）在组件的命名空间中安装功能的路径。对于协议，默认值为/svc/${protocol}。directory和storage的必需参数。对于包含功能名称数组的声明和 runner 功能，此属性是不允许的。numbered_handle：（可选string）processargs 序号（也称为“processargs 索引”）。“编号句柄”），通过该句柄，此协议的渠道将传递到组件的 processargs。rights：（可选array of string）（仅限directory）要应用于组件命名空间中目录的最大目录权限。subdir：（可选string）（仅限directory）要在组件的命名空间中提供的目录功能中的子目录。scope：（可选，string or array of strings）（仅限event_stream）如果已定义，事件流将仅包含有关范围中所定义组件的事件。filter：（可选object）（仅限event_stream）请求的功能事件流需要指定一个过滤条件，该过滤条件引用事件流中事件所适用的协议。过滤器的内容将是一个从“名称”到“协议名称”的对象映射。dependency：（可选string）来源与此组件之间的依赖关系类型，可以是以下之一：strong：一种强依赖关系，用于确定关闭顺序。组件管理器保证在停止源之前停止目标。这是默认值。weak：一种弱依赖项，在关闭期间会被忽略。当组件管理器停止父 realm 时，来源可能会在客户端之前停止。弱依赖项的客户端必须能够处理这些依赖项变为不可用的情况。 此属性不允许用于 runner 功能，runner 功能始终是strong依赖项。
availability：（可选string）有关此功能可用性的预期。以下各项中的一项：required（默认）：必需的依赖项，组件在没有此功能的情况下无法正常运行。optional：可选依赖项，组件在没有此功能的情况下也能正常运行（不过，如果该功能不可用，某些功能可能会被停用）。transitional：来源可以完全省略路线，甚至无需从void进行路由。用于引入新功能的柔和过渡。 此属性不允许用于 runner 功能，runner 功能始终为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为“vector”时受支持。 这是向量中的最大元素数。element：（可选object）（仅限configuration）仅当此配置type为“vector”时受支持。 这是配置向量中元素的类型。示例（简单类型）：
{ 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",
},
],
expose
object 的数组（可选）
声明可供父组件或框架使用的功能。从 self 或从子组件到 expose 都是有效的。
功能字段
这支持以下功能键。必须设置以下其中一个值：
service：（可选string or array of strings）protocol：（可选string or array of strings）directory：（可选string）runner：（可选string）resolver：（可选string）dictionary：（可选string）config：（可选string）
其他字段
此功能支持以下额外字段：
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（可选）：此功能可用性方面的预期。影响 build 时和运行时路由验证。以下权限之一：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",
},
],
offer
object 的数组（可选）
功能字段
这支持以下功能键。必须设置以下其中一个值：
protocol：（可选string or array of strings）service：（可选string or array of strings）directory：（可选string）storage：（可选string）runner：（可选string）resolver：（可选string）event_stream：（可选string or array of strings）dictionary：（可选string）config：（可选string）
其他字段
此功能支持以下额外字段：
service：（可选，string or array of strings）在路由服务时，服务功能的名称。protocol：(可选string or array of strings) 路由协议时，协议功能的名称。directory：（可选string or array of strings）在路由目录时，目录功能的名称。runner：（可选string or array of strings）在路由 runner 时，runner 功能的名称。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>：对子组件实例的引用。仅在提供协议、目录或 runner 功能时才能使用此来源。void：来源有意省略。仅在availability为optional或transitional时有效。
to：(string or array of strings) 功能目标。以下值之一：as：（可选string）功能在目标平台上的明确名称。如果省略，则默认为原始名称。提供多个名称的数组时，不能使用as。dependency：（可选，string）来源与目标之间的依赖关系类型，可以是以下值之一：strong：一种强依赖关系，用于确定关闭顺序。组件管理器保证在停止源之前停止目标。这是默认值。weak：一种在关闭期间会被忽略的弱依赖项。当组件管理器停止父 realm 时，来源可能会在客户端之前停止。弱依赖项的客户端必须能够处理这些依赖项变为不可用的情况。
rights：（可选，array of string）(directoryonly) the maximum directory rights to apply to the offered directory capability.subdir：（可选string）（仅限directory）源目录中要路由的功能的子目录的相对路径。event_stream：（可选string or array of strings）（仅限event_stream）所提供事件流的名称。scope：（可选，string or array of strings）（仅限event_stream）如果已定义，事件流将仅包含有关范围中所定义组件的事件。availability：（可选string）availability（可选）：此功能可用性方面的预期。影响 build 时和运行时路由验证。以下权限之一：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" ],
},
],
facets
object（可选）
包含组件可能会出于自身目的而解读的元数据。组件框架不会对此部分强制执行任何架构，但第三方可能会要求其方面遵循特定架构。
config
object（可选）
由组件定义的配置架构。每个键都表示架构中的一个字段。
配置字段是 JSON 对象，必须定义一个 type，该值可以是以下字符串之一：bool、uint8、int8、uint16、int16、uint32、int32、uint64、int64、string、vector
示例：
config: {
debug_mode: {
type: "bool"
},
}
默认情况下，字段是从组件的软件包中解析的。如需能够在运行时更改值，则需要 mutability 说明符。
示例：
config: {
verbose: {
type: "bool",
mutability: [ "parent" ],
},
},
目前，唯一支持的可变性指定器是 "parent"。
字符串必须将 max_size 属性定义为非零整数。
示例：
config: {
verbosity: {
type: "string",
max_size: 20,
}
}
矢量必须将 max_count 属性设置为非零整数。向量还必须将 element 属性设置为一个 JSON 对象，用于描述向量中包含的元素。向量可以包含布尔值、整数和字符串，但不能包含其他向量。
示例：
config: {
tags: {
type: "vector",
max_count: 20,
element: {
type: "string",
max_size: 50,
}
}
}