使用开发者替换项组装 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 args 或 args.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：将所有 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>/*