{% set rfcid = “RFC-0072” %} {% include “docs/contribute/governance/rfcs/_common/_rfc_header.md” %}
This document proposes a standalone tool, suitable for inclusion in a Fuchsia SDK, for assembling Fuchsia “system images” from packages and other compiled artifacts.
Product assembly, the process of creating a set of artifacts for delivering Fuchsia to a device out of the components and packages that are in the Fuchsia platform fuchsia.git and the product's own, and other repo(s), should be possible without using a complete fuchsia.git checkout and build.
This tool performs the final step of the product assembly process, the creation of the system artifacts, from previously built inputs.
This tool is also used as part of the fuchsia.git build itself, replacing many of the scripts and GN templates that are in //build/resources/BUILD.gn.
The creation of the final system output files that can be used to deliver Fuchsia to a device.
base PackageThe package in BlobFS, identified to pkgfs by its content identity, which contains the base system, (e.g. /system). This is called the system_image package in the current build. See this for more information.
BlobFS is Fuchsia's content-addressed filesystem.
These are the inputs that describe the low-level hardware details needed to perform the assembly process (e.g partition tables, flash-block sizes, device bootloader images for flashing onto the device or including in the update package, etc.).
Content-addressing is a way of identifying a thing based on a cryptographically-secure hash of its contents. On Fuchsia, this is used by BlobFS, pkgfs, and other parts of the system to identify files in a secure manner.
The FVM image is the block-device image for the Fuchsia Volume Manager.
The set of final output artifacts that are created by the build which contain Fuchsia. This is the larger set of artifacts which are used to deliver Fuchsia to devices via different means (OTA, flashing, paving, etc.)
update PackageThe package that contains files and rules for updating the system. See this for more information.
vbmeta ImageThe verified-boot metadata is used by the bootloader(s) running on the device to validate that the zbi is trusted for execution by the bootloader.
The ZBI is the Zircon Boot Image. This is the kernel and the ramdisk bootfs. This contains everyting needed to bootstrap Fuchsia.
This tool is primarily a replication of steps and processes that are currently performed by //build/resources/BUILD.gn and its associated scripts.
The tool is an ffx plug-in that allows it to be used both as part of the fuchsia build, as well as outside of it.
Operationally, the tool takes as input:
A set of options specifying which image files it should create:
base packageupdate packageThe following diagrams show which inputs (and outputs) are used to create the various final outputs:
┌─────────┐┌────────┐┌────────┐┌───────────┐┌─────────────────┐ │ Board ││ Kernel ││ Kernel ││ List of ││ List of │ │ Support ││ Image ││ Args ││ BootFS ││ packages │ └┬──┬─────┘└┬───────┘└┬───────┘│ Files │└┬───────────────┬┘ │ │ │ │ └┬──────────┘ │ │ │ │ │ │ ┌V───────┐ ┌V─────────────┐ │ │ │ │ │ │ BootFS │ │ base package │ │ │ │ │ │ └┬───────┘ └┬──┬──────────┘ │ │ │ ┌V─────────V─────────V────────────V┐ │ │ │ │ │ZBI │ │ │ │ │ └┬───────┬─────────────────────────┘ │ │ │ │ ┌V─────┐ │ │ │ │ │ │VBMeta│ │ │ │ │ │ └┬─────┘ │ │ │ │ ┌V───────V───────V───────────────────────────V────────────V┐ │ │ update package │ │ └┬──┬──────────────────────────────────────────────────────┘ │ │ ┌V───────┐ │ │ │ BlobFS │ │ │ └┬───────┘ ┌V──V──V┐ │ FVM │ └───────┘
Note: The update package itself is not placed in the FVM, but is a container which contains many of the inputs used to create BlobFS and FVM, which makes it a good intermediate from which to create the block-device image files
To create the base package, the tool needs:
To create the ZBI, the tool needs:
base package's “content identity”To create the vbmeta image, the tool needs:
To create the update package, the tool needs:
basebase packageTo create the flashable block device images, the tool needs:
update packageThe assembly tool generates the following outputs, depending on which it is instructed to create:
baseupdateThe following manifests are produced, when the tool is instructed to create the output files that are described within the manifests.
base and update)For build-tool compatibility, inputs will initially be what GN produces. For example, the results of the metadata walks that are used to describe all packages that are being built.
See:
The final tool will be constructed from:
ffx.To facilitate the transition for the fuchsia.git in-tree build, there will also be:
The above transitional tools will not be part of the permanent interface for the tool, but used to provide a transition path that minimizes risk to the fuchsia.git build.
To mitigate risks, the tool will be integrated into fuchsia.git carefully:
The addition of this tool to the SDK doesn't change any existing backwards compatibility concerns, as it is a different way of using existing tools that currently exist in the SDK. The restriction where the kernel and drivers used with the tool(s) should match the SDK tools (or be newer than the tooling) remains.
Use of the CLI tool has a neglible impact to the speed of the Fuchsia build. While it moves a number of operations from Python to Rust, it also adds itself as a compilation step that must be performed.
The existence of the tool allows for the re-assembly of a different set of components without performing a full build of Fuchsia itself.
The output manifests allow for auditing of the contents and provenance of the image artifacts produced.
No privacy concerns.
The core library will have unit tests which covers:
The ffx interface for this tool will need to be documented.