使用开发者替换项组装 Fuchsia 产品

Fuchsia 构建系统会结合使用平台、产品和主板配置来创建最终产品软件包。虽然这些配置定义了产品的规范版本,但您可能需要进行临时修改以进行测试或调试。如需详细了解软件组装的概念,请参阅软件组装

开发者替换项提供了一种机制,用于对产品的配置进行仅限本地的修改,而无需更改 Fuchsia 树中的源文件。

本文档介绍了如何使用开发者替换项来修改产品的配置。

使用程序集替换项

如需使用程序集的开发者替换项,您需要:

  1. 在 GN 目标(通常在 //local/BUILD.gn 中)定义替换项
  2. 将替换项应用到 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'

如需了解详情,请参阅以下部分:

使用 fx argsargs.gn

您可以通过修改 args.gn 文件或使用 fx args 来应用替换。以下 GN 实参可供使用:

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:将所有 cacheon_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" ]
  }
}

其他软件包

您可以将开发者指定的软件包添加到 basecachebootfsflexible 软件包集中。flexible 软件包集放置在 eng build 类型的 cache 中,放置在 useruserdebug 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 组装的产品minimalterminalworkbench 等):
    • fuchsia.git 的登机时间://products/<name>/*