此页面由 Cloud Translation API 翻译。

组件 ID 索引

术语

范围

本文档介绍了如何定义将实例 ID 映射到名称的索引。这种映射对于使用隔离存储功能的组件非常重要。

概览

组件实例 ID 索引的目标是为组件实例分配稳定的标识符。这是通过将实例 ID 映射到名称实现的。为组件实例分配 ID 后，系统会使用此实例 ID 在磁盘上标识其永久性资源。这样一来，组件的网址或领域可以更改，而其资源仍会继续归因于它，只要此索引也相应更新即可。

当组件运行时发现实例 ID 到名称映射时，会自动将组件实例的现有存储目录移动到其实例 ID 下以键控。

只有使用存储空间的组件必须包含在索引中。测试组件不应包含在索引中。

定义新索引

索引文件是 JSON5 格式的文件，可将组件的实例 ID 映射到其名称。一个 build 树中可能有多个索引文件，但这些文件将合并为一个索引文件，并且此合并的文件将可供组件运行时使用。此合并的索引文件不可更改，只能通过另一系统更新进行更新。

以下示例介绍了索引文件的架构：

// Index files are written in JSON5, so you may use comments!
{
  // A list of entries, where each entry maps an instance ID to a moniker.
  instances: [
    // An entry, mapping an instance ID to a moniker.
    {
      // Instance IDs are randomly generated, 256-bits of base-16 encoded
      // strings (in lower case). To generate a new instance ID, set this to
      // an empty string (or other invalid value) and run the build; the build
      // will fail and suggest a new instance ID which you can copy-paste here.
      instance_id: "2bd6cc2bd10243354b873a4ddb8a188b1d29171e26eebac06567bcdc36614af6",
      // The `instance_id` above is associated to the following moniker:
      moniker: "/core/account/credential_manager",
    },

    // More than one entry can be included. However, all entries must be distinct:
    // * Two entries cannot reference the same `instance_id`
    // * Two entries cannot reference the same `moniker`
    {
      instance_id: "7db7e88479772e241229682b47f1794e12ac5d692f8d67421acd9d7ff318a975",
      moniker: "/core/account/password_authenticator",
    }
  ]
}

如需为 build 提供索引文件，请使用 component_id_index() GN 模板：

component_id_index("my_component_id_index") {
  source = "my_component_id_index.json5"
}

向索引添加组成部分

找到相应的索引文件

为了向索引添加组件，您必须在相应的索引文件中插入条目。目前，fuchsia.git 的组件已列在 core_component_id_index.json5 索引文件中。

向索引添加条目

第一步是确定组件实例的名称。您可以通过运行 ffx component show 在特定产品的 eng build 中找到组件的名称。

然后，使用组件名称向 instances 列表附加一个条目。将 instance_id 字段设置为无效值（例如空字符串）会使构建失败，并推荐您可以使用的新值。

示例

在此示例中，fuchsia-pkg://example.com/my_other_package#meta/my_other_component.cm 组件已添加到索引中。

如需确定组件实例的名称，您可以运行 ffx component show fuchsia-pkg://example.com/my_other_package#meta/my_other_component.cm：

$ ffx component show fuchsia-pkg://example.com/my_other_package#meta/my_other_component.cm
               Moniker:  /core/my_other_component
                   URL:  fuchsia-pkg://example.com/my_other_package#meta/my_other_component.cm
                      ...

上面的输出结果显示，此实例的名称为 /core/my_other_component

通过使用无效的空 instance_id 将此条目附加到 core_component_id_index.json5 的 instances 列表，将 /core/my_other_component 添加到索引：

  {
    instance_id: "",
    moniker: "/core/my_other_component"
  }

现在，运行构建。构建将失败，并显示新的实例 ID：

$ fx build
.
.
Product Assembly Failed
    ...
    4.  parsing obj/bundles/assembly/resources/core_component_id_index.json5
    5.  Invalid instance ID: invalid length; must be 64 characters

Here is a valid, randomly generated ID: 4251833a8d2e47b473732a23de84437e0b346a151ec1e7bdfd43b91e02f894a7

通过复制建议的 instance_id 字段来更新已添加的条目。构建现在应该会通过。

在系统汇编中添加组件 ID 索引

本部分的目标受众群体是正在设置系统组件的产品所有者

本部分介绍如何在系统汇编中添加组件 ID 索引。

如果系统组件包含使用隔离存储空间的组件，则应包含组件 ID 索引。任何基于 core 产品构建的产品都已在其组装中包含组件 ID 索引，因此可能不需要以下说明。

系统 build 中的所有 component_id_index() 均使用 component_id_index_config() 模板合并在一起。此模板目前在 assembled_system.gni 中使用，如果您同时定义自己的模板和 assembled_system.gni 中的模板，则汇编将会失败。

步骤

定义要包含在系统中的任何 component_id_index()。
将这些目标作为 base_packages 的依赖项添加到 assembled_system() 目标中。