软件组装

软件组装 使开发者能够使用自定义操作系统快速构建产品。具体来说，软件组装是一组工具，可从输入（包括一组 Fuchsia 软件包、内核和配置文件）生成产品软件包 (PB)。

产品软件包

产品软件包 是一个包含明确指定工件的目录，可以运送到任何环境，并用于刷写、更新或模拟 Fuchsia 目标。开发者不应直接检查产品软件包的内容，而是可以依赖 Fuchsia 提供的工具。例如，ffx 工具用于使用产品软件包刷写或模拟设备：

# Flash a hardware target with the product bundle.
$ ffx target flash --product-bundle <PATH/TO/PRODUCT_BUNDLE>

# Start a new emulator instance with the product bundle.
$ ffx emu start <PATH/TO/PRODUCT_BUNDLE>

产品软件包可能包含主 产品和恢复 产品，它们是不同的可启动体验。通常，main 用于真实的产品体验，如果 main 出现故障且无法启动，则使用 recovery。recovery 通常是一种轻量级体验，能够使用出厂重置或无线下载 (OTA) 更新来解决 main 插槽中的问题。通常，最终用户可以在启动期间按住设备上的实体按钮，以切换要启动的产品。

软件组装提供用于构建产品软件包的构建工具，定义输入的格式（平台、产品配置、板级配置），并提供用于构建这些输入的构建规则。

包含主商品和恢复商品的商品套装

图 1. 产品软件包可能包含主产品和恢复产品。

平台、产品配置和板级配置

组装的三个输入（平台、产品配置、板级配置）是工件目录。内部格式可能会发生变化，不应依赖于此。开发者需要使用提供的 Bazel 或 GN 构建规则来构建和使用这些输入。

  • 平台 由 Fuchsia 团队制作。它包含任何 Fuchsia 产品可能想要使用的所有已编译平台代码。Fuchsia 团队将平台发布到 https://chrome-infra-packages.appspot.com/p/fuchsia/assembly/platform。 如需了解如何添加到平台，请参阅 Codelab：实现平台功能。 出于开发目的，您可以暂时替换平台配置值，请参阅 使用开发者替换项组装 Fuchsia 产品。

  • 产品配置 由开发者定义最终用户体验。它可能包含指示要包含哪些平台功能的标志。例如，产品配置可以设置 platform.fonts.enabled=true，从而使组装包含平台的相关字体支持。 如需查看所有可用标志，请参阅此参考文档。产品配置还可以包含用于构建用户体验的自定义代码。 如需了解详情，请参阅 Codelab：定义和构建产品软件包。

  • 板级配置 由支持特定硬件目标的开发者制作。它包含在该硬件上启动所需的所有驱动程序。 此外，板级配置还可以声明平台可以使用哪些硬件。例如，如果硬件具有实时时钟 (RTC)， 板级配置可以通过设置 provided_features=["fuchsia::real_time_clock"] 标志来指示这一点。组装会读取此标志，并包含平台中用于使用此硬件的必要代码。Fuchsia 团队维护一小部分板级配置，并将其发布到 https://chrome-infra-packages.appspot.com/p/fuchsia/assembly/boards。 如需了解详情，请参阅 Codelab：定义新的板级配置。

如何调用软件组装

Fuchsia 的软件组装本质上是一个 Rust 库，由多个不同的 CLI 工具用于生成产品软件包。以下描述了调用组装的最常见方式：

  • 构建系统集成（Bazel 和 GN）：Bazel 和 GN 等构建系统 提供简单的构建目标（例如 Bazel 中的 fuchsia_product_bundle），可 处理生成正确输入文件并为您调用 组装工具的复杂性。这是使用软件组装最常见且推荐的方式。

  • ffx product-bundle create：为测试生成一次性产品 软件包的最快方法是使用 ffx product-bundle create。此工具在处理预构建的平台、产品和板级配置时尤其有用，因为它允许非常快速的组装，而无需完整的构建系统集成。

Bazel

# A product bundle can contain both 'main' and 'recovery' products (systems/slots).
fuchsia_product_bundle(
    name = "my_product_bundle",
    main = ":main_product",
    recovery = "...",
)

# A product is a single bootable experience that is built by combining
# a platform, product configuration, and board configuration.
fuchsia_product(
    name = "main_product",
    platform = "//platform:x64",
    product = ":my_product",
    board = "//boards:x64",
)

# A product configuration defines the user experience by enabling
# platform features and including custom product code.
fuchsia_product_configuration(
    name = "my_product",
    product_config_json = {
        platform = {
            fonts = {
                enabled = True,
            },
        },
    },

    # The product code is included as packages.
    base_packages = [ ... ],
)

如需查看完整示例，请参阅 getting-started 代码库。

命令行界面

ffx product-bundle create --platform 28.20250718.3.1 \
                          --product-config <PATH/TO/MY_PRODUCT_CONFIG> \
                          --board-config cipd://fuchsia/assembly/boards/x64@version:28.20250718.3.1

可以运行 ffx product-bundle create 命令，以使用已构建的平台、板级和产品工件生成新的产品软件包。

静态分析工具

软件组装提供用于验证产品软件包质量的工具。

大小检查 工具会告知用户产品软件包是否符合目标硬件的分区大小限制。可以使用以下 Bazel 规则生成 产品大小 报告：

fuchsia_product_size_check(
    name = "main_product_size_report",
    product_image = ":main_product",
)

fuchsia_product(
    name = "main_product",
    ...
)

scrutiny 工具可确保产品软件包符合一组安全标准。如果开发者提供必要的 scrutiny 配置， scrutiny 会在构建产品软件包期间运行。请参阅以下 scrutiny 配置示例：

fuchsia_product_bundle(
    name = "my_product_bundle",
    main = ":main_product",
    main_scrutiny_config = ":main_scrutiny_config",
)

fuchsia_scrutiny_config(
    name = "main_scrutiny_config",
    base_packages = [ ... ],    # Allowlist of base packages to expect.
    kernel_cmdline = [ ... ],   # Allowlist of kernel arguments to expect.
    pre_signing_policy = "...", # File containing the policies to check before signing.
)

附录：开发者替换项

开发者通常希望通过添加新代码或翻转功能标志，在现有产品上本地测试某些内容。修改产品或板级 配置是不可取的，因为它会污染 git 树 (fuchsia.git)。 组装支持一种在本地修改现有产品的方法，而不会 使用 开发者替换项污染 git 树。