Skip to content

install: add --target-arch for cross-architecture installs - #2655

Closed
mattmoor wants to merge 1 commit into
bootc-dev:mainfrom
mattmoor:target-arch
Closed

mattmoor wants to merge 1 commit into
bootc-dev:mainfrom
mattmoor:target-arch

Conversation

@mattmoor

Copy link
Copy Markdown

Draft to show the objective; not ready for review. It depends on unreleased changes to composefs-rs and ocidir, consumed here through [patch.crates-io] git branches.

Objective

Build a bootc disk image for one architecture on a host of another, for example an aarch64 cloud image from an x86_64 builder, without emulating the target. Nothing in bootc install to-disk needs to run target code; it only makes decisions that today follow the host instead of the image.

Where the host architecture is assumed

  1. Partition layout (install/baseline.rs): the BIOS boot / PReP partition and the root partition type come from cfg!(target_arch) and dps::this_arch_root().
  2. EFI (ARCH_USES_EFI).
  3. systemd-boot: bootctl install copies only host-arch EFI binaries, so a foreign-arch install gets no bootloader.
  4. Image resolution: the composefs pull resolves an image index to the host platform, inside composefs-oci → ocidir (open_image_this_platform).

Change

--target-arch on the install config options, defaulting to the host, so existing behaviour is unchanged. When it names another architecture:

  • sfdisk layout, root-type check and EFI use follow the target;
  • bootctl install gets --all-architectures --install-source=image (systemd ≥ 252), so the target's systemd-boot comes from the image;
  • the composefs pull requests the target's manifest via a new PullOptions::platform.

Cross installs are refused outside what was exercised: systemd-repart/aboot layouts, unified storage, and bootloaders other than systemd-boot.

Dependencies (branches only; no PRs yet)

Testing

On an x86_64 host, with this branch and the same dependency changes:

  • Before: an arm64 bootc image (Wolfi, composefs backend, oci-archive) fails with No manifest found for platform linux/amd64. bootc 1.17.4 had already written a BIOS boot partition and an x86-64 root partition type for it.
  • After, with install to-disk --composefs-backend --target-arch aarch64: the GPT is ESP + Linux root (ARM-64) with no BIOS boot partition, and the ESP holds EFI/systemd/systemd-bootaa64.efi and EFI/BOOT/BOOTAA64.EFI, both PE32+ ARM64.
  • Boot: the disk boots under qemu-system-aarch64 (TCG, edk2 UEFI) through systemd-boot and the arm64 kernel to Reached target Multi-User System and a login prompt on ttyAMA0.
  • No flag, or a mismatched one: without the flag the arm64 image fails exactly as upstream does. --target-arch x86_64 for the arm64 image is refused. A native amd64 install produces the same layout (BIOS boot, x86-64 root, BOOTX64.EFI) as upstream main.
  • Unit tests: pass for install, baseline, bootloader and the new target_arch module, and for the ocidir and composefs-oci tests touching the changed paths.

Not covered: registry pulls of multi-arch indexes via the skopeo proxy (only the oci-archive path was exercised), ostree-backend installs, and the integration suites.

Generated-by: AI

bootc install assumes the image's architecture is the host's at four
sites: the sfdisk layout (BIOS boot partition, root partition type),
the EFI decision, the systemd-boot copy (bootctl installs only
host-arch binaries), and composefs image-index resolution.

--target-arch defaults to the host, so existing installs are
unchanged. When it names another architecture:
- the partition layout, root type check and EFI use follow the target;
- bootctl runs with --all-architectures --install-source=image
  (systemd >= 252) so the target's systemd-boot comes from the image;
- the composefs pull asks for the target's manifest through
  composefs-oci's PullOptions::platform.

Cross installs are limited to the sfdisk layout, the composefs backend
without unified storage, and systemd-boot; anything else is refused.

The platform selection is not yet in released composefs-rs or ocidir,
so Cargo.toml patches both to branches that add it.

Generated-by: AI
Copilot AI balanced review requested due to automatic review settings November 15, 2026 15:23
@github-actions github-actions Bot added area/install Issues related to `bootc install` area/documentation Updates to the documentation labels Nov 15, 2026
@bootc-bot
bootc-bot Bot requested a review from gursewak1997 November 15, 2026 15:23

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Critical cross-architecture image-selection and bootloader errors can produce invalid installations, while late compatibility checks can wipe disk signatures before rejecting unsupported options.

7 open issues
What changed in this PR

Adds --target-arch to support building disk images for another architecture without emulation, focusing on composefs installs with systemd-boot while preserving host-native defaults.

Changes:

  • Makes partition layout and EFI decisions follow the selected target architecture.
  • Passes target-platform information to composefs pulls and enables cross-architecture systemd-boot installation.
  • Documents the option and pins unreleased dependency branches providing platform-selection APIs.
File Description
docs/​src/​man/​bootc-install-to-filesystem.8.md Documents the target option and supported scope.
docs/​src/​man/​bootc-install-to-existing-root.8.md Documents the target option and supported scope.
docs/​src/​man/​bootc-install-to-disk.8.md Documents cross-architecture disk installation.
crates/​lib/​src/​install/​target_arch.rs Adds architecture mappings, layout helpers, and unit tests.
crates/​lib/​src/​install/​baseline.rs Uses target-specific partition types and layout checks.
crates/​lib/​src/​install.rs Adds target configuration with host defaults.
crates/​lib/​src/​bootloader.rs Adds cross-architecture bootctl flags and version validation.
crates/​lib/​src/​bootc_composefs/​repo.rs Passes target-platform information to direct pulls.
crates/​lib/​src/​bootc_composefs/​boot.rs Restricts cross-architecture bootloader selection.
Cargo.toml Adds temporary dependency branch overrides.
Cargo.lock Pins the overridden dependencies to Git revisions.

Review effort: Balanced

Comment thread Cargo.toml
Comment on lines +139 to +140
[patch.crates-io]
composefs = { git = "https://github.com/mattmoor/composefs-rs", branch = "pull-platform" }
// paths name or run the host's.
let target_arch = state.config_opts.target_arch();
ensure!(
target_arch.is_host() || (bootloader == Bootloader::Systemd && target_arch.uses_efi()),
PullOptions {
img_proxy_config: Some(config),
progress: Some(reporter),
platform,
Comment thread crates/lib/src/install.rs
Comment on lines +405 to +407
#[clap(long)]
#[serde(default)]
pub(crate) target_arch: Option<TargetArch>,
Comment on lines +1059 to +1063
anyhow::ensure!(
target_arch.is_host() || (state.aboot_disk_layout.is_none() && !use_systemd_repart),
"Installing for {target_arch} from {} is not supported with systemd-repart partitioning",
super::TargetArch::host()
);
"Installing for {} does not support unified storage",
state.config_opts.target_arch()
);
Some(state.config_opts.target_arch().oci_platform()?)
Comment thread crates/lib/src/install.rs
Comment on lines +412 to +413
pub(crate) fn target_arch(&self) -> TargetArch {
self.target_arch.unwrap_or_else(TargetArch::host)
@mattmoor mattmoor closed this Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/documentation Updates to the documentation area/install Issues related to `bootc install`

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants