Fuchsia 构建系统会结合使用平台、产品和主板配置来创建最终产品软件包。虽然这些配置定义了产品的规范版本,但您可能需要进行临时修改以进行测试或调试。如需详细了解软件组装的概念,请参阅软件组装。
开发者替换项提供了一种机制,用于对产品的配置进行仅限本地的修改,而无需更改 Fuchsia 树中的源文件。
本文档介绍了如何使用开发者替换项来修改产品的配置。
使用程序集替换项
如需使用程序集的开发者替换项,您需要:
- 在 GN 目标(通常在
//local/BUILD.gn
中)定义替换项。 - 将替换项应用到 build 配置。
例如,如需启用某个内核实参,请先在 //local/BUILD.gn
中定义替换项:
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("enable_kernel_debug") {
kernel = {
command_line_args = [ "foo" ]
}
}
然后,使用以下方法之一将此替换项应用于您的 build 配置:
使用 fx set
fx set
命令包含 --assembly-override
选项,用于指定对主产品 build(而非测试 build、恢复 build 等)的替换。例如:
fx set core.x64 --assembly-override //local:enable_kernel_debug
--assembly-override
选项支持两种格式:
--assembly-override <overrides_target>
:将替换项应用于主产品程序集。例如,以下命令会将
//local:enable_kernel_debug
替换项应用于core.x64
产品:fx set core.x64 --assembly-override //local:enable_kernel_debug
--assembly-override <assembly_target_pattern>=<overrides_target>
:将替换项应用于特定的程序集目标模式。例如,如需仅将
//local:zedboot_overrides
中定义的替换项应用于zedboot
程序集,您将运行以下命令:fx set core.x64 --assembly-override '//build/images/zedboot/*=//local:zedboot_overrides'
如需了解详情,请参阅以下部分:
- 如需了解如何指定程序集目标,请参阅产品标签模式。
- 如需了解如何定义替换目标,请参阅定义
assembly_developer_overrides
目标。
使用 fx args
或 args.gn
您可以通过修改 args.gn
文件或使用 fx args
来应用替换。以下 GN 实参可供使用:
product_assembly_overrides_label
:指定主产品程序集的一个替换目标。product_assembly_overrides_contents
:定义args.gn
中主产品程序集的内嵌替换项。product_assembly_overrides
:一个列表,用于将替换目标显式映射到它们所适用的程序集目标。
product_assembly_overrides_label
product_assembly_overrides_label
实参会将指定的替换项应用于所选产品的主程序集。它不会影响其他产品组件,例如恢复、zedboot 或测试。
args.gn
示例:
import("//products/...")
import("//boards/...")
product_assembly_overrides_label = "//local:my_overrides"
product_assembly_overrides_contents
借助 product_assembly_overrides_contents
实参,您可以直接在 args.gn
中定义替换项。这些替换项仅适用于主要产品程序集。
args.gn
示例:
import("//products/...")
import("//boards/...")
product_assembly_overrides_contents = {
kernel = {
command_line_args = [ "kernel.enable-debugging-syscalls=true" ]
}
}
该值使用的语法与 assembly_developer_overrides()
GN 模板相同,请参阅定义 assembly_developer_overrides
目标。
product_assembly_overrides
product_assembly_overrides
实参用于指定多个或非主程序集的替换项。它使用 GN 标签模式将替换目标与相应的程序集目标相匹配。
args.gn
示例:
import("//products/....")
import("//boards/....")
product_assembly_overrides = [
{
# zedboot
assembly = "//build/images/zedboot/*"
overrides = "//local:zedboot_overrides"
},
{
# For assemblies in Bazel, use their product label
assembly = "//products/minimal/*"
overrides = "//local:minimal_overrides"
},
{
# core or terminal products:
assembly = "//build/images/fuchsia/*"
overrides = "//local:enable_kernel_debug"
},
]
定义 assembly_developer_overrides
目标
如需定义一组开发者替换项,请在 BUILD.gn
文件中使用 assembly_developer_overrides()
模板。建议将这些定义放在 Fuchsia 代码库的 //local
目录中,因为该目录会被 Git 忽略。
//local/BUILD.gn
示例:
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("enable_kernel_debug") {
kernel = {
command_line_args = [
"foo",
]
}
}
# Multiple override sets can be defined in the same file.
assembly_developer_overrides("bar_debug") {
kernel = {
command_line_args = [ "bar" ]
}
}
可用的替换选项
以下部分介绍了可在 assembly_developer_overrides
目标中配置的可用选项:
仅限开发者的程序集选项
这些程序集选项只能通过开发者替换项启用,通常不允许在产品或主板配置中使用。
//local/BUILD.gn
示例:
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("netboot_with_all_packages") {
developer_only_options = {
all_packages_in_base = true
netboot_mode = true
}
}
all_packages_in_base
:将所有cache
和on_demand
软件包重定向到base
软件包集。当网络无法正常运行时,这有助于在设备上提供调试工具。netboot_mode
:创建包含 ramdisk 内的 FVM/Fxfs 映像的 Zircon 启动映像 (ZBI),从而允许产品进行网络启动。
平台配置
您可以替换产品组件配置的 platform
配置。如需了解详情,请参阅 PlatformSettings
参考文档。
您指定的值会与产品的平台配置逐个字段地合并。
//local/BUILD.gn
示例:
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("enable_sl4f") {
platform = {
development_support = {
include_sl4f = true
include_netsvc = true
}
}
}
如果您想附加到列表而不是替换列表,请参阅使用 __append_to_<key>
附加到列表。
内核命令行参数
您可以添加内核命令行实参。内核命令行实参的顺序不会保留。如需查看可用选项的列表,请参阅 Zircon 内核命令行选项文档。
//local/BUILD.gn
示例:
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("bar_debug") {
kernel = {
command_line_args = [ "bar" ]
}
}
其他软件包
您可以将开发者指定的软件包添加到 base
、cache
、bootfs
和 flexible
软件包集中。flexible
软件包集放置在 eng
build 类型的 cache
中,放置在 user
和 userdebug
build 类型的 base
中。
该模板需要针对软件包使用特定的 GN 标签,并且不使用 GN 元数据来遍历软件包组。
//local/BUILD.gn
示例:
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("my_custom_base_packages") {
base_packages = [
"//some/gn/target/for/a:package",
"//some/other/target/for/a:package",
"//third_party/sbase",
]
}
Shell 命令
如需将命令行工具添加到 Fuchsia shell,您必须同时添加包含该工具的软件包,并指示 assembly 为相应组件创建启动器桩。
//local/BUILD.gn
示例:
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("my_custom_shell_commands") {
shell_commands = [
{
package = "cp"
components = [ "cp" ]
}
]
}
如果通过软件包发现功能提供软件包还不够,您还可以将软件包添加到软件包集中。
//local/BUILD.gn
示例:
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("my_custom_shell_commands") {
shell_commands = [
{
package = "cp"
components = [ "cp" ]
}
]
# This GN target should define a package named "cp".
base_packages = [
"//some/gn/target/for/my/package:cp"
]
}
板级配置
您可以替换特定于主板的配置,以测试更改或新功能。
//local/BUILD.gn
示例:
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("add_new_feature") {
board = {
provided_features = [ "fuchsia::new_feature" ]
filesystems = {
gpt_all = true
}
}
}
如需附加到列表而不是替换列表,请参阅使用 __append_to_<key>
附加到列表。
已编译的软件包和组件
您可以向通过程序集编译的软件包和组件添加开发者指定的内容和 CML 分片。
//local/BUILD.gn
示例:
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("add_core_shard") {
core_shards = [ "//local/testing.core_shard.cml" ]
}
使用 __append_to_<key>
将内容附加到列表
默认情况下,开发者替换会用您指定的新内容替换列表。如需改为附加到列表,请使用 __append_to_<key>
语法,其中 <key>
是列表的名称。
例如,假设有以下主板配置:
board_configuration("bar") {
provided_features = [ "fuchsia::feature1", "fuchsia::feature2"]
}
您可以使用以下替换项附加新功能:
import("//build/assembly/developer_overrides.gni")
assembly_developer_overrides("foo") {
board = {
__append_to_provided_features = [ "fuchsia::new_feature" ]
}
}
生成的配置将如下所示:
board: {
provided_features: [
"fuchsia::feature1",
"fuchsia::feature2",
"fuchsia::new_feature",
]
}
重要细节
组装警告文本
具有替换项的程序集操作始终会生成一条警告,详细说明正在应用的替换项。例如:
WARNING!: Adding the following via developer overrides from: //local:enable_kernel_debug
Additional kernel command line arguments:
foo
商品标签模式
替换目标与商品套装之间的映射通过标签模式匹配完成。
//some/label/with/wildcard/*
:匹配相应路径中及其下的所有程序集。//some/label/with/wildcard:*
:仅匹配相应文件夹中的所有程序集。
不同的程序集位于 build 图中的不同路径。常见位置包括:
- GN 组装的产品:
bringup
个商品://build/images/bringup/*
core
个商品://build/images/fuchsia/*
zedboot
://build/images/zedboot/*
guest
://build/images/guest/*
- Bazel 组装的产品(
minimal
、terminal
、workbench
等):fuchsia.git
的登机时间://products/<name>/*