ImageBuilder

Brought to you by OERV team.

Overview

It is driven by GNU Makefile for target management.

It will produce:

• RootFS tarball
  • rpm-based package manager
    • yum
  • dpkg-based package manager
  • Archiving method
    • tar.zst
• Embedded system images for SBC-like devices
  • Single disk image with all partitions inside
    • GUID partition table
      • Partition UUID
      • Partition GUID type and attributes
      • Partition name
    • msdos parition table
    • MTD
  • Separated files for each filesystem
  • Filesystems
    • vfat
    • ext4
• Post-process for specific usage
  • qcow2 format
  • Vendor-defined package format

It can be interrupted at any time, without harming your host OS.

Prerequirements

• GNU Make 4 or newer
• rsync, curl, and unzip for staging recipes and downloading blobs
• RISC-V user-mode emulation and binfmt registration: qemu-riscv64-static and binfmt; registration is a one-time system setup step
• Docker or Podman; rootless operation is supported

Dependencies

The Makefile uses these host commands before a build script runs:

Command	Debian package	Fedora package	Used for
make	make	make	Makefile target management
rsync	rsync	rsync	Recipe staging
curl	curl	curl	Remote blob downloads
unzip	unzip	unzip	Extracting blob archives
qemu-riscv64-static	qemu-user-static	qemu-user-static	Running RISC-V binaries on the build host
binfmt registration	binfmt-support	systemd (systemd-binfmt)	Dispatching RISC-V binaries to QEMU

The build scripts and the recipe post-processing scripts use the following commands. The package names are the packages to install on the build host; some commands are also supplied by the default base image in Docker.

Command or tool	Debian package	Fedora package	Used for
setfattr	attr	attr	Removing the SELinux attribute from /boot
bash	bash	bash	Running recipe scripts
column	bsdextrautils	util-linux	Formatting generated fstab
coreutils (basename, cat, chmod, cp, cut, dd, du, head, ln, mkdir, mktemp, mv, readlink, rm, sha256sum, sort, stat, tee, tr, truncate)	coreutils	coreutils	File, stream, and image operations
dosfstools (mkfs.vfat)	dosfstools	dosfstools	Creating VFAT filesystems
e2fsprogs (mkfs.ext4, tune2fs, e2fsck, resize2fs)	e2fsprogs	e2fsprogs	Creating and shrinking ext4 filesystems
find	findutils	findutils	Finding and copying filesystem contents
grep	grep	grep	Validation and command detection
hexdump	bsdextrautils	util-linux	Generating VFAT UUIDs
mcopy, mlabel	mtools	mtools	Writing and labeling VFAT images
blockdev, mount, umount, rev, seq, uuidgen	fdisk, util-linux, uuid-runtime	util-linux	Mounting, partitioning, iteration, and UUIDs
policycoreutils (setfiles)	policycoreutils	policycoreutils	Applying SELinux labels
rpm/dnf (yum)	rpm, dnf	rpm, dnf	Installing packages into the rootfs
sed	sed	sed	Parsing configuration and command output
tar	tar	tar	Rootfs archive creation and extraction
zstd	zstd	zstd	Rootfs compression
pseudo, pseudodb, pseudolog	Build from source	Build from source	Rootfs ownership and metadata emulation
img2simg	Build from source	Build from source	Optional sparse-image post-processing

For CI environments that invoke the scripts directly, install the dependencies with Debian:

sudo apt-get update
sudo apt-get install --no-install-recommends \
    attr bash bsdextrautils coreutils curl dosfstools e2fsprogs fdisk findutils \
    grep make mtools policycoreutils qemu-user-static binfmt-support rsync rpm \
    sed tar unzip util-linux uuid-runtime zstd
sudo update-binfmts --enable qemu-riscv64

The corresponding Fedora setup is:

sudo dnf install \
    attr bash coreutils curl dosfstools e2fsprogs findutils grep make mtools \
    policycoreutils qemu-user-static rsync rpm sed tar unzip util-linux zstd
sudo systemctl enable --now systemd-binfmt

pseudo and img2simg are built in the Dockerfile and are not standard runtime packages on Debian or Fedora. They must also be available in PATH when scripts are invoked directly.

The current Dockerfile does not need bzip2, gzip, xz-utils, gdisk, or rsync: the scripts use Zstandard only, partitioning is done by sfdisk, and recipe staging, downloading, and extraction happen on the host. zlib1g remains required by the custom img2simg binary.

Usage

Build New Images

Bash tab completition will print all available targets

Firstly, let it build a container image for later use:

make container

It will be tagged and managed by the configured container runtime.

Listing all available targets:

make list

Build a single rootfs target:

make openEuler-24.03-LTS-SP1-base-rootfs

Build all rootfs targets one by one, under a different directory /tmp/build:

make O=/tmp/build openEuler-24.03-LTS-SP1-base-rootfs

Build all available BSP targets, parallelly:

make -j$(nproc) all_bsp

For CI jobs that invoke build_rootfs.sh and build_bsp.sh directly instead of through a container, clear CONTAINER_CMD:

make CONTAINER_CMD= openEuler-24.03-LTS-SP4-RVA23-base-OLK-generic

Normal builds use the configured container runtime. Set CONTAINER_CMD=podman to use Podman instead of Docker:

make CONTAINER_CMD=podman container
make CONTAINER_CMD=podman openEuler-24.03-LTS-SP4-RVA23-base-OLK-generic

BSP target will be rebuilt each time even if no configuration is changed

Cleanup:

make clean

Add New Targets

Add RootFS Targets

1. Creating a directory for your distro under receipes
2. Filling receipes/${DISTRO_NAME}/distro.mk, taking existing ones as reference
3. Creating a directory for the distro release, under receipes/${DISTRO_NAME}
4. Filling receipes/${DISTRO_NAME}/${DISTRO_RELEASE}/release.mk
5. Creating a directory for rootfs receipe (such as minimal, base or desktop), under receipes/${DISTRO_NAME}/${DISTRO_RELEASE}/userspace
6. Filling receipes/${DISTRO_NAME}/${DISTRO_RELEASE}/userspace/${receipe}/receipe.mk
7. Listing required packages under receipes/${DISTRO_NAME}/${DISTRO_RELEASE}/userspace/${receipe}/packages.d
8. Listing repo URLs required to install those packages under receipes/${DISTRO_NAME}/${DISTRO_RELEASE}/userspace/${receipe}/repos.d
9. Listing scripts to be run after all package installation under receipes/${DISTRO_NAME}/${DISTRO_RELEASE}/userspace/${receipe}/post.d

Add BSP Targets

TBD

Common Usage

packages.d

post.d

repos.d