WLAN Pi OS builder

Tools to build WLAN Pi OS images, based on upstream pi-gen.

Get the images

You do not need to build anything. Download ready-made images from Releases: choose the newest non-pre-release for stable use, and verify your download against the release's wlanpi-os-<version>-SHA256SUMS file (SHA256SUMS in releases up to 26.10-rc.2-DeadEye).

Build images yourself

Prerequisites:

• A Debian-based Linux host with root privileges. The reference build environment is an ubuntu-24.04-arm runner (see CI).
• Host packages from depends (or depends-arm64 on arm64 hosts).
• For native builds, apt-cacher-ng running on localhost:3142 (the checked-in config routes apt through it). To use another proxy, set APT_PROXY=<url>; to build without a proxy, set APT_PROXY= (empty).

The repo ships a checked-in config that builds both images (STAGE_LIST="wlanpi1-lite wlanpi2-full").

Native build (requires an arm64 host, such as an arm64 Linux machine or the ubuntu-24.04-arm CI runner):

sudo -E ./build.sh

-E preserves your environment so overrides such as WLANPI_CODENAME reach the build (CI uses the same form). build.sh verifies native arm64 execution with arch-test and exits with an error on other hosts.

Docker build (works on other host architectures, such as x86_64, through qemu-user-static emulation in the build container; slower than a native build):

./build-docker.sh

Verify success: finished images appear in deploy/ as .img.gz files with matching .sha256 checksums.

Builds are incremental: stage state persists under work/wlanpi-os/ and re-runs reuse it. If a stage edit appears to do nothing, remove the work/ directory to force a full rebuild.

On Fedora hosts, export-image prints SELinux and lowercase-label mount warnings; both are benign.

How this repo works

• Branches: trixie64 is the default branch, the living builder for the current Debian release, continuing the bullseye64 and bookworm64 line. When WLAN Pi OS moves to the next Debian release, trixie64 freezes (it stays so you can rebuild old images) and a new distro branch becomes the default. PRs target the default branch; there is no main.
• Releases: every build publishes a GitHub pre-release tagged with its full version. Releases are immutable tag artifacts, and promoting a build to a stable, latest release is a manual step. See Releasing.
• Versioning: image versions (YY.MM plus codename) are build inputs, not branch properties.
• CI: the build and release pipeline.
• Releasing: cut and promote a release.
• Local debs: inject locally built packages.
• Partitions: A/B partition layout.
• Product requirements.
• Upstream README: reference for the base tool. Its stage layout (stage0-5) differs from this repo (wlanpi1-lite, wlanpi2-full).