本页记录了在 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 生成过程期间无法将所有内容关联起来。