Source: rpi-image-gen
Section: devel
Priority: optional
Maintainer: Richard Oliver <richard.oliver@raspberrypi.com>
Build-Depends:
 debhelper-compat (= 13),
# For genimage and erofs-utils, from the supplementary orig tarballs. Neither
# GitHub archive ships a configure script, hence autoreconf. libconfuse is
# genimage's. The rest are erofs-utils': libuuid, because the ab_userdata
# layout passes mkfs.erofs -U to fix the filesystem UUID, and the compression
# libraries Debian's own erofs-utils builds against, so that mkfs.erofs here
# is no narrower than the archive binary - see debian/rules.
 autoconf,
 automake,
 libtool,
 pkgconf,
 libconfuse-dev,
 libdeflate-dev,
 liblz4-dev,
 liblzma-dev,
 libxxhash-dev,
 libzstd-dev,
 uuid-dev,
 zlib1g-dev,
Standards-Version: 4.7.2
Rules-Requires-Root: no
Homepage: https://github.com/raspberrypi/rpi-image-gen

Package: rpi-image-gen
Architecture: all
Multi-Arch: foreign
# Upstream's "depends" manifest is neither an upper nor a lower bound on this
# list, so diff it with care on a new release. dependencies_check --category
# all aborts a build on any manifest entry being absent, so all of them are
# here; patch 0007 drops its "pkg buildsys" block. cpio, openssl and whois
# are reached for at run time without appearing in the manifest at all - see
# README.Debian.
Depends:
 ${misc:Depends},
 python3,
 python3-debian,
 python3-jsonschema,
 python3-yaml,
# bdebstrap's only import beyond the standard library. Upstream's runtime pip
# install pulls it from PyPI; we ship bdebstrap, so we owe the dependency.
 python3-ruamel.yaml,
 btrfs-progs,
 ca-certificates,
 cpio,
# veritysetup, which the manifest attributes to cryptsetup. It is in
# cryptsetup-bin; cryptsetup itself is the boot integration - cryptdisks init
# scripts, /etc/default/cryptdisks, debconf - which no image build touches.
# dependencies_check looks for the command first, so this satisfies it.
 cryptsetup-bin,
 curl,
 dctrl-tools,
 debian-archive-keyring,
 dosfstools,
# dpkg-architecture is in dpkg-dev, which Recommends build-essential; patch
# 0010 uses Dpkg::Arch from here instead, which needs only perl and dpkg.
 libdpkg-perl,
 e2fsprogs,
 fdisk,
 mmdebstrap,
 mtools,
 openssl,
 pv,
 rsync,
 uidmap,
 whois,
# envsubst, for bin/generators/envcp and the provisionmap hooks. Patch 0013
# adds it to upstream's manifest.
 gettext-base,
 xz-utils,
 zip,
# The compiled helper, built here rather than on the user's machine. Version
# bound because the two travel together; not binary:Version, which differs
# between an arch:all and an arch:any package under a binNMU.
 rpi-image-gen-host (>= ${source:Version}),
# The compressor patch 0007 points at, in place of the one upstream builds
# for itself: Debian's is the pinned 1.5.7 exactly. Not in the manifest, so
# the dependency check will not look for it.
 zstd,
Recommends:
 rpi-image-gen-doc,
Suggests:
 arch-test,
 binfmt-support,
 qemu-user-static,
Description: build custom OS images for Raspberry Pi devices
 rpi-image-gen assembles bootable disk images, partitioned media layouts and
 device-agnostic filesystem tarballs for Raspberry Pi devices from declarative
 YAML configuration. It composes a root filesystem from pre-built Debian and
 Raspberry Pi OS packages rather than building from source, so an image can
 use exactly the library versions shipped to production devices.
 .
 Builds are described as a stack of layers: modular, composable units that
 declare their own variables, validation policy and documentation. Hooks run
 shell at defined points in the pipeline, and external directories can supply
 custom configurations and layers without modifying the installed tree.
 .
 The tool runs as an ordinary user, using mmdebstrap and bdebstrap for
 filesystem construction, genimage for disk image layout and user
 namespaces to get file ownership right without root. It can emit a Software
 Bill of Materials and CVE report alongside the image, and supports
 reproducible builds from Debian snapshot archives.
 .
 This is not the tool used to build the Raspberry Pi OS distribution itself;
 see pi-gen for that.

Package: rpi-image-gen-host
Architecture: any
Multi-Arch: foreign
Depends:
 ${shlibs:Depends},
 ${misc:Depends},
Description: compiled helper tools for rpi-image-gen
 rpi-image-gen builds disk images with genimage, and erofs root filesystems
 with mkfs.erofs. Upstream fetches and compiles its own copy of each when a
 build first calls for it; this package carries those builds instead, so the
 tool needs no compiler, no network and no wait.
 .
 Neither is the copy Debian ships. genimage is pinned to a version newer than
 Debian's, with a local fix applied. erofs-utils is built to accept a 16K
 block size, which the archive build does not: a 2712 device runs a 16K page
 size kernel, and an erofs root filesystem has to match it.
 .
 The tools here are private to rpi-image-gen, under
 /usr/lib/rpi-image-gen/host, and are not on the PATH of anything else.

Package: rpi-image-gen-doc
Architecture: all
Section: doc
Multi-Arch: foreign
Depends:
 ${misc:Depends},
 libjs-bootstrap4,
 libjs-jquery,
 python3:any,
Recommends:
 rpi-image-gen,
# Two examples import a built filesystem into a container (docker_export,
# oci_create) and one README walks through a podman kernel-build chroot.
# Nothing on the build path needs it: patch 0008 replaced "podman unshare"
# with util-linux unshare.
Suggests:
 podman,
Description: build custom OS images for Raspberry Pi devices (documentation)
 rpi-image-gen assembles bootable disk images, partitioned media layouts and
 device-agnostic filesystem tarballs for Raspberry Pi devices from declarative
 YAML configuration.
 .
 This package contains the extended documentation that is not needed to run
 the tool:
 .
  * the technical reference manual, in AsciiDoc and rendered HTML, covering
    the configuration system, layer and metadata formats, variable validation,
    traits, provisioning and execution flow;
  * generated reference pages for every layer in the built-in layer library,
    and JSON schemas for the metadata, image and provisioning map formats;
  * worked examples, each a self-contained source tree that can be passed
    straight to "rpi-image-gen build -S", covering reproducible filesystems,
    OTA and signed OTA, encrypted roots, custom kernels, nested images, OCI
    and Docker export, mass storage gadgets, kiosk systems and splash screens;
  * contrib, holding community-maintained extensions outside the supported
    core;
  * the upstream test suite, installed so it can be run against the installed
    tool.
 .
 Installing this package also enables the "rpi-image-gen docs" subcommand,
 which serves the documentation over HTTP for local browsing.
