此页面由 Cloud Translation API 翻译。

Fuchsia 构建系统使用的清单文件格式

本页记录了在 build 中使用（但不应在 build 之外公开）的文件格式。

请注意，生成和处理这些文件的脚本和 .gni 文件位于 Fuchsia 源代码树中的 //build/dist/ 下。

FINI (Fuchsia INI) 清单文件格式

在构建期间调用的多种工具会使用 FINI 清单格式：生成 Fuchsia 软件包归档的 ffx package build 命令（或旧版 pm 工具），或生成 ZBI 映像的 zbi 工具。

语法非常简单：每行文本都类似于 <destination>=<source>，其中 <destination> 是相对于最终容器顶部的目标文件路径，<source> 是源内容相对于当前目录（在大多数情况下，即 build 目录）的文件路径。

请注意，目标路径绝不能以目录分隔符开头，并且 FINI 文件不支持 Windows INI 文件格式的注释、部分和其他功能

例如：

bin/foo=foo
lib/ld.so.1=user.libc_x64/libc.so
meta/foo.cm=obj/src/foo/cml/foo_component/foo.cm
meta/package=gen/src/foo/foo_meta_package.txt

分发清单文件格式

这是一个必须包含列表的 JSON 文件，其中每个列表项都是一个作为单个“分发”条目的 JSON 对象，其中介绍了如何将一个源文件安装到容器中，以及如何为生成该文件的目标提供 GN 标签。此处使用的架构如下：

source：源路径字符串（必需）。
destination：目标路径字符串（必需）。
label：指向生成源文件的目标的 GN 标签。仅用于调试（可选）。

示例：

  {
    "destination": "bin/foo",
    "source": "x64-asan/foo",
    "label": "//some/dir:foo"
  }

虽然在概念上与 FINI 清单类似，但分发清单能够提供更多一些信息（GN 标签），这在出现问题时对调试非常有用。它们还由一组不同的工具使用。

部分分发清单文件格式

FINI 和分发清单是通过处理称为“部分分发清单”的中间文件生成的。

GN 元数据收集在同一依赖项树中的目标上会生成部分清单。它是一个包含对象“条目”列表的 JSON 文件。

有几种类型的条目用于描述构建和安装要求的各个方面。它们会合并到 FINI 或分发清单中。

//build/dist/distribution_manifest.py 下的 Python 模块包含用于处理这些文件的函数。

常规条目

这些条目与用于分发清单的架构匹配。它们对应于要安装到给定目标路径的简单源文件。

source：源路径字符串（必需）。
destination：目标路径字符串（必需）。
label：指向生成源文件的目标的 GN 标签。仅用于调试（可选）。
elf_runtime_dir：仅用于 ELF 可执行文件和可加载模块，可选的目标目录路径，用于指定此二进制文件的 ELF 依赖项在运行时应位于何处。默认值为“lib”

当用于生成分发清单时，除非满足以下某个条件，否则这些清单会按原样复制到输出文件中，而不使用 elf_runtime_dir 键：

它们与另一个常规条目的来源相同（如需了解详情，请参阅此部分），在这种情况下，只保留其中一个条目。
其源路径会被重命名的条目使用（见下文）。

示例：

  {
    "destination": "bin/foo",
    "source": "x64-asan/foo",
    "label": "//some/dir:foo",
    "elf_runtime_dir": "lib/asan"
  },

复制条目。

这些条目用于表示 build 将特定文件复制到新的输出位置。此信息稍后会用于正确处理重命名的条目（见下文），在其他情况下会被忽略。其架构为：

copy_from：相对于 build 目录的源代码路径字符串（必需）。
copy_to：相对于 build 目录的目标路径字符串（必需）。
label：指向生成此条目的目标的 GN 标签（可选）。

例如，以下条目用于表示使用 ${BUILD_DIR}/x64-asan/foo 中的“asan”build 变体构建的“foo”可执行二进制文件也复制到了 ${BUILD_DIR}/foo 中。

示例：

  {
    "copy_from": "x64-asan/foo",
    "copy_to": "foo"
    "label": "//some/dir:foo"
  }

请参阅以下部分，了解复制条目和重命名的条目如何与实际示例交互。

已重命名的条目

这些条目用于指示应将给定的常规条目安装在替代目标位置。这对于某些程序（例如 busybox）非常有用，这些程序的行为因用于启动它们的程序名称而异。renamed_binary() GN 模板依赖于这些库。其架构为：

destination：目标路径字符串（必需）。
renamed_source：与另一个常规条目（必需）匹配的来源路径。
label：指向生成此条目的目标的 GB 标签（可选）。
keep_original：布尔值标志，设置为 true 以指示仍应安装在容器中的原始二进制文件（可选）。

请注意，重命名条目只能指向常规条目的 source 路径，或指向副本条目的 copy_to 路径。使用未知路径或其他重命名条目的目标路径属于构建错误。

您可以多次重命名同一条目。如果需要以不同名称多次安装同一原始二进制文件，这会非常有用。

以下示例将 busybox 二进制文件作为 bin/cp、bin/cat 和 bin/ls 安装在同一容器中。但请注意，bin/busybox 不会安装到容器中。

  {
    "destination": "bin/busybox",
    "source": "busybox",
    "label": "//third_party/busybox:busybox"
  },
  {
    "destination": "bin/cp",
    "renamed_from": "busybox"
  },
  {
    "destination": "bin/cat",
    "renamed_from": "busybox"
  },
  {
    "destination": "bin/ls",
    "renamed_from": "busybox"
  }

如果任何重命名条目将 keep_original 标志设置为 true，则原始条目不会从清单中移除，原始条目会保留在清单中，如下所示：

  {
    "destination": "bin/busybox",
    "source": "busybox",
    "label": "//third_party/busybox:busybox"
  },
  {
    "destination": "bin/cp",
    "renamed_from": "busybox",
    "keep_original": true
  }

这可确保 bin/busybox 和 bin/cp 均已安装到容器中。

文件条目

这些条目用于包含其他分发清单文件，这些文件可以由其他目标生成。其架构为：

file：指向另一个发行版清单文件（必需）的文件路径字符串。
label：如果所含文件中的所有条目没有自己的 label 值，则将应用于这些条目的默认 GN 标签（可选）。

分发文件包含可以是递归的。

示例：

  {
    "file": "path/to/other.dist_manifest",
    "label": "//some/dir:label"
  }

清单文件中的重复条目

根据 Fuchsia build 的运作方式，清单文件（格式不限）都可以提供使用同一 <destination> 路径的多个条目。不过，只要源路径或其内容相同，这种做法就有效；在这种情况下，系统会直接忽略重复的。

如果多个条目具有相同的目标路径，但来源路径和内容不同，则处理脚本会将此类情况视为构建错误。

副本条目与重命名的条目之间的交互

为了阐明复制条目和重命名条目如何相互作用，请参考用于重命名 foo 二进制文件的安装位置的给定 renamed_binary() 目标的示例。如果未选择 build 变体，相应的 build 清单将包含如下所示的两个条目：

  {
    "destination": "bin/foo",
    "source": "foo",
    "label": "//src:foo",
  },
  {
    "destination": "bin/foo_renamed",
    "renamed_from": "foo",
  },

第一个常规条目表明 ${BUILD_DIR}/foo 由默认工具链中的 //src:foo 目标构建，并且应安装到容器内的 bin/foo。

第二个副本条目表明，作为 ${BUILD_DIR}/foo 构建的二进制文件实际上应固定到 bin/foo_renamed，而不是其默认位置（即 bin/foo）。

从逻辑上讲，这相当于单个条目：

  {
    "destination": "bin/foo_renamed",
    "source": "foo",
    "label": "//src/foo",
  },

即仅更改了目标路径的第一个条目。

不过，在启用 asan 变体的情况下构建相同的内容时，清单内容将与之前略有不同：

  {
    "destination": "bin/foo",
    "source": "x64-asan/foo",
    "label": "//src:foo(//build/toolchain:x64-asan)",
  },
  {
    "copy_from": "x64-asan/foo",
    "copy_to": "foo",
  },
  {
    "destination": "bin/foo_renamed",
    "renamed_from": "foo",
  },

现在，第一个条目表明 ${BUILD_DIR}/x64-asan/foo 由 Asan 工具链 (//build/toolchain:x64-asan) 中的 //src:foo 目标构建，并且默认情况下仍会安装到 bin/foo。

第二个条目表明 ${BUILD_DIR}/foo 是 ${BUILD_DIR}/x64-asan/foo 的实际副本，因为这是构建系统执行的操作。

第三个条目与之前相同，因为 renamed_binary() 目标并不知道用于构建 ${BUILD_DIR}/foo 的工具链或变体。

这在逻辑上都等同于如下所示的单个条目：

  {
    "destination": "bin/foo_renamed",
    "source": "x64-shared/foo",
    "label": "//src/foo(//build/toolchain:x64-asan)",
  },

复制条目仅在 build 变体已启用时使用，它们会将重命名的条目与特定于变体的常规条目相关联。所有这些信息之所以分散，是因为每个条目都是通过 build 图中的不同目标生成的，并且在 GN 生成过程期间无法将所有内容关联起来。