Introduction

boot2deb turns a laptop, SBC, tablet, or other device into a Debian device. It is a Rust-native, typed, testable builder that resolves a build from layered TOML config — an arch ← soc ← boot-method ← device hardware stack plus an orthogonal kernel axis — and drives the whole pipeline: kernel, u-boot, media-accel userspace, ffmpeg, the Debian rootfs, and a bootable disk image, all from a single committed lockfile.

The image assembly is pure Rust: GPT partitioning, ext4 formatting, and .xz or .gz compression with no C dependencies and no sudo. The Debian bootstrap, every compile, and every .deb archiving run in rootless, in-process user-namespace roots, so an x86_64 host builds an arm64 image without root and without fakeroot at all.

Your host supplies no compiler and no packaging tool. Both are packages of a provisioned Debian root, resolved from the build’s own mirror list and sha256-pinned in that root’s manifest — so what compiled and archived an image is stated by its lock rather than by whichever gcc and dpkg your distribution happens to ship. What is left on the host is git, unprivileged user namespaces, an unprivileged overlay for a build that compiles, and qemu-user for one that assembles a foreign-architecture image. boot2deb does not need to run on a Debian-family machine.

Not every board needs every stage. A build compiles a kernel only if the board needs one of its own, and builds a bootloader only if the board’s firmware is ours to make. The Turing RK1 does both — a patched mainline kernel, and u-boot written into the disk’s raw gap. The ASUS C201 Chromebook does neither: Debian’s own kernel runs it, its firmware lives in an SPI chip, and what boot2deb produces for it is a signed kernel in a ChromeOS partition. Its lock, correspondingly, pins nothing from git. The model states what is true of each board rather than making them look alike.

Where to start

• Getting started — install the prerequisites and build your first image.
• Adapting a shipped recipe — change the suite, the features, or the localization of an image that already builds.
• Moving a board to a newer kernel — measure whether a patch series survives a kernel you have not adopted, then adopt it.
• Authoring a recipe — name a build point of your own, and say what it has been taken through.
• Turing RK1 — the shipped RK3588 configuration, and how to flash it.
• ASUS Chromebook C201 — the shipped RK3288 Chromebook: a ChromeOS-firmware board, and a kernel that comes from Debian. Its two siblings, the C100P and the Chromebit CS10, are each a device file and nothing else.
• Config model — how a build is described across its axes, and how the layers resolve.
• CLI — the command reference.
• Overlays — keep your own boards and retunings out-of-tree.
• Adding a board — bring up a new device.
• Adding a patch — get a patch into a build.