pi-gen

# pi-gen

Tool used to create Raspberry Pi OS images, and custom images based on Raspberry Pi OS,
which was in turn derived from the Raspbian project.

**Note**: Raspberry Pi OS 32 bit images are based primarily on Raspbian, while
Raspberry Pi OS 64 bit images are based primarily on Debian.

**Note**: 32 bit images should be built from the `master` branch.
64 bit images should be built from the `arm64` branch.

## Dependencies

pi-gen runs on Debian-based operating systems released after 2017, and we
always advise you use the latest OS for security reasons.

On other Linux distributions it may be possible to use the Docker build described
below.

To install the required dependencies for `pi-gen` you should run:

```bash
apt install coreutils quilt parted qemu-user-binfmt debootstrap zerofree zip \
dosfstools e2fsprogs libcap2-bin grep rsync xz-utils file git curl bc \
gpg pigz xxd arch-test bmap-tools kmod
```

The file `depends` contains a list of tools needed.  The format of this
package is `<tool>[:<debian-package>]`.

qemu is only used outside a native build environment, which is not supported. If
you do build that way on a distribution whose `qemu-user` binaries are still
dynamically linked, install `qemu-user-static` instead of `qemu-user-binfmt`, or
the chroot will fail.

## Getting started with building your images

Getting started is as simple as cloning this repository on your build machine. You
can do so with:

```bash
git clone https://github.com/RPI-Distro/pi-gen.git
```

`--depth 1` can be added after `git clone` to create a shallow clone, only containing
the latest revision of the repository. Do not do this on your development machine.

Also, be careful to clone the repository to a base path **NOT** containing spaces.
This configuration is not supported by debootstrap and will lead to `pi-gen` not
running.

After cloning the repository, you can move to the next step and start configuring
your build.

## Config

Upon execution, `build.sh` will source the file `config` in the current
working directory.  This bash shell fragment is intended to set needed
environment variables.

The following environment variables are supported:

 * `IMG_NAME` (Default: `raspios-$RELEASE-$ARCH`, for example: `raspios-trixie-armhf`)

   The name of the image to build with the current stage directories. Use this
   variable to set the root name of your OS, eg `IMG_NAME=Frobulator`.
   Export files in stages may add suffixes to `IMG_NAME`.

 * `PI_GEN_RELEASE` (Default: `Raspberry Pi reference`)

   The release name to use in `/etc/issue.txt`. The default should only be used
   for official Raspberry Pi builds.

* `RELEASE` (Default: `trixie`)

   The release version to build images against. Valid values are any supported
   Debian release. However, since different releases will have different sets of
   packages available, you'll need to either modify your stages accordingly, or
   checkout the appropriate branch. For example, if you'd like to build a