# 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
    - [x] yum
  - [ ] ~~dpkg-based package manager~~
  - Archiving method
    - [x] tar.zst
- Embedded system images for SBC-like devices
  - Single disk image with all partitions inside
    - [x] GUID partition table
      - [x] Partition UUID
      - [x] Partition GUID type and attributes
      - [x] Partition name
    - [ ] msdos parition table
    - [ ] MTD
  - [ ] Separated files for each filesystem
  - Filesystems
    - [x] vfat
    - [x] 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:

```shell
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:

```shell
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:

```shell
make container
```

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

Listing all available targets:

```shell
make list
```

Build a single rootfs target:

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

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

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

Build all available BSP targets, parallelly:

```shell
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`:

```shell
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:

```shell
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:

```shell
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`