组件结构化配置参考

本页详细介绍了结构化配置的行为和实现。有关使用结构化配置的指南,请参阅:

生命周期

配置值会在创建组件时进行解析。

解决优先级

组件配置“根据组件实例运行时的上下文定制组件实例的行为”,这意味着最权威的配置值应该编码最多的组件实例上下文。

组件管理器将解析每个配置字段的值,并按以下顺序优先选择每个来源:

  1. 来自开发者替换服务的值 (WIP)
  2. 来自组件父级的值
  3. 值来自组件自己的软件包

开发工程 build 的组件开发者可以了解系统上运行的一切,从而使这些替换项具有最权威性。父级可以理解它为子级提供的上下文。最后,由于组件自身软件包中的值只能对关于组件打包方式的了解进行编码,因此所有其他信息都必须从外部来源提供。

生成的客户端库

组件作者应使用 configc 工具生成的客户端库访问其配置值。这些库会通过组件运行程序提供的 API(例如 ELF 运行程序的 procarg)使用已解析的 VMO,验证校验和是否正确,并将解析后的配置值返回给调用方。

客户端库通过配置返回本地非静态值,使用户能够选择是将值作为参数向下传递其堆栈,或者将配置值明确放置在全局可访问的位置。

由于组件管理器只会在组件具有有效配置值时启动组件,因此客户端库对调用方来说是绝对可靠的,如果它们无法检索或解析配置值,则会使组件实例崩溃。

配置值文件

返回包含 config 架构的组件清单的组件解析器也必须返回配置值文件。

配置值文件是 fuchsia.component.decl/ConfigValuesData 类型的持久性 FIDL 消息

已编译的组件清单通常作为 meta/*.cm 存储在软件包中,配置值文件通常作为 meta/*.cvf 存储在软件包中。

已解决的 VMO

组件管理器通过组合来自组件解析器的值和任何运行时替换值解析了组件的配置值后,会将配置编码成 VMO,并在 fuchsia.component.runner/ComponentStartInfo.encoded_config 中提供给运行程序。

VMO 的前 2 个字节应解释为无符号的 16 位小端字节序整数,表示 VMO 后面包含配置校验和的字节数。校验和之后,所有剩余字节都是顶级结构体的持久性 FIDL 消息,与生成的客户端库使用的布局匹配。结构体的字段以相同的顺序匹配组件的已编译清单的配置字段。

校验和验证

为防止在打包已配置的组件时出现意外配置错误,cmc 会在编译组件的 CML 时计算其 config 架构的哈希值,并将其作为校验和包含在已编译的清单 (*.cm) 中。此校验和也包含在配置值文件生成的客户端库已解决的 VMO 中。

在构建时和创建组件时,系统会验证已编译清单的校验和是否与配置值文件中的校验和匹配。然后,组件管理器会在启动组件时将校验和放入已解析的 VMO 中。在解析实际配置值之前,生成的客户端库会在运行时检查已解析的 VMO 中的值是否匹配。