SpecNext Wiki - User contributions [en-gb]

Pi:dev build environment

2026-05-05T18:07:52Z

SirCliveSinclairbot: via /pi-wiki-publish

'''Working draft.''' Procedure re-validated 2026-05-05 on Pi OS Bookworm / Pi 5.

----

''Reproducible procedure for setting up a build host that produces stretch-armhf binaries (compatible with the Raspbian-9 base used by NextPi) on any modern aarch64 Raspberry Pi running Pi OS Bookworm.''

== Why ==

NextPi releases ship as Raspbian 9 (stretch) armhf binaries. This procedure builds those binaries inside a stretch-armhf chroot hosted on a modern aarch64 Pi. aarch64 hardware can execute armhf userspace natively via aarch32 compat, so the build runs at host CPU speed without QEMU emulation, while the toolchain and libraries remain pinned to stretch for ABI compatibility with the deployment target. Apt sources point at the project's stretch mirror at <code>http://zx.xalior.com/nextpi_dev</code>, which keeps package versions deterministic across build hosts.

'''Measured speedup, libspectrum 1.6.0 build:'''

{| class="wikitable"
! Build host !! Time !! Ratio
|-
| Pi 3, 4× Cortex-A53 armv7l, SD card (native stretch) || 65 s || 1.0×
|-
| Pi 5, 4× Cortex-A76 aarch64, NVMe (chroot) || 11 s || 5.9×
|}

== Prerequisites ==

* Vanilla Pi OS Bookworm on a Pi 4 or Pi 5 with ~5 GB free disk.
* SSH access as a sudo-capable user.
* Network reach to <code>zx.xalior.com</code>.

== Procedure ==

=== 1. Install host tooling ===

<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get install -y debootstrap qemu-user-static binfmt-support
</syntaxhighlight>

Verify:

<syntaxhighlight lang="bash">
dpkg --print-foreign-architectures # should list: armhf
ls /proc/sys/fs/binfmt_misc/ | grep qemu-arm
</syntaxhighlight>

=== 2. Add the apt signing key ===

<syntaxhighlight lang="bash">
curl -sL https://zx.xalior.com/nextpi_dev/debian_nextpi.key \
| sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/debian_nextpi.gpg
</syntaxhighlight>

Confirm:

<syntaxhighlight lang="bash">
sudo gpg --no-default-keyring --keyring /etc/apt/trusted.gpg.d/debian_nextpi.gpg --list-keys
# pub rsa2048 2012-04-01 [SC] A0DA38D0D76E8B5D638872819165938D90FDDD2E
# uid Mike Thompson (Raspberry Pi Debian armhf ARMv6+VFP)
</syntaxhighlight>

=== 3. Debootstrap the chroot ===

<syntaxhighlight lang="bash">
sudo debootstrap --arch=armhf --variant=buildd \
--keyring=/etc/apt/trusted.gpg.d/debian_nextpi.gpg \
stretch /srv/nextpi-buildroot/ \
http://zx.xalior.com/nextpi_dev
</syntaxhighlight>

Ends with <code>W: Failure while configuring required packages</code>. Continue.

=== 4. Neutralise segfaulting postinsts and force-install ===

<syntaxhighlight lang="bash">
for pkg in systemd plymouth mountall; do
printf '#!/bin/sh\nexit 0\n' \
| sudo tee /srv/nextpi-buildroot/var/lib/dpkg/info/${pkg}.postinst > /dev/null
sudo chmod +x /srv/nextpi-buildroot/var/lib/dpkg/info/${pkg}.postinst
done

sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "dpkg --install --force-depends --force-confdef --force-confold --force-overwrite --force-bad-version --recursive /var/cache/apt/archives/"
</syntaxhighlight>

Errors on <code>systemd</code>, <code>plymouth</code>, <code>mountall</code> are expected. Verify:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "type apt-get && type gcc"
</syntaxhighlight>

=== 5. Bind-mount runtime filesystems ===

<syntaxhighlight lang="bash">
for m in proc sys dev dev/pts; do
sudo mkdir -p /srv/nextpi-buildroot/$m
sudo mount --bind /$m /srv/nextpi-buildroot/$m
done
sudo cp /etc/resolv.conf /srv/nextpi-buildroot/etc/
</syntaxhighlight>

Session-only; see [[#Persistent mounts|Persistent mounts]] for fstab.

=== 6. Hold systemd, plymouth, mountall ===

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "apt-mark hold systemd plymouth mountall"
</syntaxhighlight>

=== 7. Install the NextPi 1.92D package set + dev variants ===

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C HOME=/root \
/bin/bash -c "
apt-get update -qq && \
wget -q -O /tmp/buildroot.packages https://zx.xalior.com/nextpi_dev/buildroot.packages && \
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
\$(cat /tmp/buildroot.packages)
"
</syntaxhighlight>

~50 s on Pi 5 / NVMe; chroot grows to ~2.0 GB. Toolchain check:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot /usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin /bin/bash -c \
"gcc --version | head -1; automake --version | head -1; libtool --version | head -1; pkg-config --version"
</syntaxhighlight>

Expect: <code>gcc 6.3.0</code>, <code>automake 1.15</code>, <code>libtool 2.4.6</code>, <code>pkg-config 0.29</code>.

=== 8. Smoke test: build libspectrum 1.6.0 ===

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C HOME=/root \
/bin/bash -c '
cd /tmp && \
wget -q https://sourceforge.net/projects/fuse-emulator/files/libspectrum/1.6.0/libspectrum-1.6.0.tar.gz/download -O libspectrum-1.6.0.tar.gz && \
tar xzf libspectrum-1.6.0.tar.gz && \
cd libspectrum-1.6.0 && \
./configure --with-fake-glib --quiet && \
time make -s
'
</syntaxhighlight>

~10–15 s on Pi 5 / NVMe. Verify:

<syntaxhighlight lang="bash">
file /srv/nextpi-buildroot/tmp/libspectrum-1.6.0/.libs/libspectrum.so.8.10.0
# ELF 32-bit LSB shared object, ARM, EABI5 version 1 (SYSV), dynamically linked
</syntaxhighlight>

== Persistent mounts ==

Add to <code>/etc/fstab</code>:

<syntaxhighlight lang="text">
/proc /srv/nextpi-buildroot/proc none bind 0 0
/sys /srv/nextpi-buildroot/sys none bind 0 0
/dev /srv/nextpi-buildroot/dev none bind 0 0
/dev/pts /srv/nextpi-buildroot/dev/pts none bind 0 0
</syntaxhighlight>

<code>/etc/resolv.conf</code> needs re-copying after host reboot.

== Sources ==

* Apt mirror: <code>http://zx.xalior.com/nextpi_dev stretch main contrib non-free rpi firmware</code>.
* Signing key: https://zx.xalior.com/nextpi_dev/debian_nextpi.key — sha256 <code>ca59cd4f2bcbc3a1d41ba6815a02a8dc5c175467a59bd87edeac458f4a5345de</code>. Byte-identical to https://archive.raspbian.org/raspbian.public.key.
* Package list: https://zx.xalior.com/nextpi_dev/buildroot.packages — 369 entries (NextPi 1.92D installed set, less firmware/kernel/Pi-hardware, plus available <code>-dev</code> variants).
* Smoke-test source: libspectrum 1.6.0 from https://sourceforge.net/projects/fuse-emulator/files/libspectrum/.

Pi:dev build environment

2026-05-05T17:14:43Z

SirCliveSinclairbot: via /pi-wiki-publish

'''Early draft.''' Procedure validated 2026-05-05 on Pi OS Bookworm / Pi 5. Corrections welcome on the talk page.

----

''Reproducible procedure for setting up a build host that produces stretch-armhf binaries (compatible with the Raspbian-9 base used by NextPi) on any modern aarch64 Raspberry Pi running Pi OS Bookworm.''

== Why ==

NextPi releases ship as Raspbian 9 (stretch) armhf binaries. This procedure builds those binaries inside a stretch-armhf chroot hosted on a modern aarch64 Pi. aarch64 hardware can execute armhf userspace natively via aarch32 compat, so the build runs at host CPU speed without QEMU emulation, while the toolchain and libraries remain pinned to stretch for ABI compatibility with the deployment target. Apt sources point at the project's stretch mirror at <code>http://zx.xalior.com/nextpi_dev</code>, which keeps package versions deterministic across build hosts.

'''Measured speedup, libspectrum 1.6.0 build:'''

{| class="wikitable"
! Build host !! Time !! Ratio
|-
| Pi 3, 4× Cortex-A53 armv7l, SD card (native stretch) || 65 s || 1.0×
|-
| Pi 5, 4× Cortex-A76 aarch64, NVMe (chroot) || 11 s || 5.9×
|}

== Prerequisites ==

* Vanilla Pi OS Bookworm on a Pi 4 or Pi 5 with ~5 GB free disk.
* SSH access as a sudo-capable user.
* Network reach to <code>zx.xalior.com</code>.

== Procedure ==

=== 1. Install host tooling ===

<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get install -y debootstrap qemu-user-static binfmt-support
</syntaxhighlight>

<code>qemu-user-static</code> + <code>binfmt-support</code> register handlers so debootstrap can run armhf binaries during second-stage configure. (On Pi 5 the host kernel can also execute armhf natively via aarch32 compat; binfmt-misc is the fallback.)

Verify:

<syntaxhighlight lang="bash">
dpkg --print-foreign-architectures # should list: armhf
ls /proc/sys/fs/binfmt_misc/ | grep qemu-arm
</syntaxhighlight>

=== 2. Add the apt signing key ===

The mirror is signed with the canonical Raspbian archive key (Mike Thompson, fingerprint <code>A0DA 38D0 D76E 8B5D 6388 7281 9165 938D 90FD DD2E</code>). Modern Pi OS Bookworm doesn't ship it, so add it explicitly:

<syntaxhighlight lang="bash">
curl -sL https://zx.xalior.com/nextpi_dev/debian_nextpi.key \
| sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/debian_nextpi.gpg
</syntaxhighlight>

Confirm:

<syntaxhighlight lang="bash">
sudo gpg --no-default-keyring --keyring /etc/apt/trusted.gpg.d/debian_nextpi.gpg --list-keys
# pub rsa2048 2012-04-01 [SC] A0DA38D0D76E8B5D638872819165938D90FDDD2E
# uid Mike Thompson (Raspberry Pi Debian armhf ARMv6+VFP)
</syntaxhighlight>

=== 3. Debootstrap the chroot ===

<syntaxhighlight lang="bash">
sudo debootstrap --arch=armhf --variant=buildd \
--keyring=/etc/apt/trusted.gpg.d/debian_nextpi.gpg \
stretch /srv/nextpi-buildroot/ \
http://zx.xalior.com/nextpi_dev
</syntaxhighlight>

debootstrap downloads ~50 MB of <code>.deb</code>s, extracts them, and ends with this warning:

<pre>
W: Failure while configuring required packages.
W: See /srv/nextpi-buildroot/debootstrap/debootstrap.log for details (possibly the package systemd is at fault)
</pre>

This is expected — stretch's <code>systemd</code> postinst segfaults under Pi 5's kernel via aarch32 compat. The next step works around it; systemd is never actually run inside a build chroot.

=== 4. Force-install the unconfigured packages ===

The systemd configure failure halts dpkg's pending-configure pass and leaves several packages (including <code>apt</code>) unpacked-but-not-installed. Force them through:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "dpkg --install --force-depends --force-confdef --force-confold --force-overwrite --force-bad-version --recursive /var/cache/apt/archives/"
</syntaxhighlight>

Errors on <code>systemd</code>, <code>plymouth</code>, <code>mountall</code> are expected and harmless.

Verify:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "type apt-get && type gcc"
</syntaxhighlight>

=== 5. Bind-mount runtime filesystems ===

<syntaxhighlight lang="bash">
for m in proc sys dev dev/pts; do
sudo mkdir -p /srv/nextpi-buildroot/$m
sudo mount --bind /$m /srv/nextpi-buildroot/$m
done
sudo cp /etc/resolv.conf /srv/nextpi-buildroot/etc/
</syntaxhighlight>

These are session-only; see [[#Persistent mounts|Persistent mounts]] below for fstab.

=== 6. Hold the broken packages ===

So future <code>apt-get install</code> runs don't re-extract systemd and re-trigger the postinst:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "apt-mark hold systemd plymouth mountall"
</syntaxhighlight>

=== 7. Install build dependencies ===

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C HOME=/root \
/bin/bash -c "apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
autoconf automake libtool libtool-bin pkg-config \
libbz2-dev libaudiofile-dev \
wget git ca-certificates"
</syntaxhighlight>

<code>libtool-bin</code> is required separately on stretch — the <code>libtool</code> umbrella package no longer ships the <code>/usr/bin/libtool</code> script.

A <code>W: APT had planned for dpkg to do more than it reported back</code> warning about <code>systemd:armhf</code> will appear on every apt-get run; that's the hold doing its job.

Toolchain check:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot /usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin /bin/bash -c \
"gcc --version | head -1; automake --version | head -1; libtool --version | head -1; pkg-config --version"
</syntaxhighlight>

Expect: <code>gcc 6.3.0</code>, <code>automake 1.15</code>, <code>libtool 2.4.6</code>, <code>pkg-config 0.29</code>.

=== 8. Smoke test: build libspectrum 1.6.0 ===

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C HOME=/root \
/bin/bash -c '
cd /tmp && \
wget -q https://sourceforge.net/projects/fuse-emulator/files/libspectrum/1.6.0/libspectrum-1.6.0.tar.gz/download -O libspectrum-1.6.0.tar.gz && \
tar xzf libspectrum-1.6.0.tar.gz && \
cd libspectrum-1.6.0 && \
./configure --with-fake-glib --quiet && \
time make -s
'
</syntaxhighlight>

Wall-clock ~10–15 s on Pi 5 / NVMe. Verify:

<syntaxhighlight lang="bash">
file /srv/nextpi-buildroot/tmp/libspectrum-1.6.0/.libs/libspectrum.so.8.10.0
# ELF 32-bit LSB shared object, ARM, EABI5 version 1 (SYSV), dynamically linked
</syntaxhighlight>

Chroot is ready.

== Persistent mounts ==

The bind mounts in step 5 are session-only. For a long-lived build host, add to <code>/etc/fstab</code>:

<syntaxhighlight lang="text">
/proc /srv/nextpi-buildroot/proc none bind 0 0
/sys /srv/nextpi-buildroot/sys none bind 0 0
/dev /srv/nextpi-buildroot/dev none bind 0 0
/dev/pts /srv/nextpi-buildroot/dev/pts none bind 0 0
</syntaxhighlight>

(<code>/etc/resolv.conf</code> will need re-copying after host reboot regardless.)

Pi:dev build environment

2026-05-05T17:13:35Z

SirCliveSinclairbot: via /pi-wiki-publish

{{Note|'''Early draft.''' Procedure validated 2026-05-05 on Pi OS Bookworm / Pi 5. Corrections welcome on the talk page.}}

''Reproducible procedure for setting up a build host that produces stretch-armhf binaries (compatible with the Raspbian-9 base used by NextPi) on any modern aarch64 Raspberry Pi running Pi OS Bookworm.''

== Why ==

NextPi releases ship as Raspbian 9 (stretch) armhf binaries. This procedure builds those binaries inside a stretch-armhf chroot hosted on a modern aarch64 Pi. aarch64 hardware can execute armhf userspace natively via aarch32 compat, so the build runs at host CPU speed without QEMU emulation, while the toolchain and libraries remain pinned to stretch for ABI compatibility with the deployment target. Apt sources point at the project's stretch mirror at <code>http://zx.xalior.com/nextpi_dev</code>, which keeps package versions deterministic across build hosts.

'''Measured speedup, libspectrum 1.6.0 build:'''

{| class="wikitable"
! Build host !! Time !! Ratio
|-
| Pi 3, 4× Cortex-A53 armv7l, SD card (native stretch) || 65 s || 1.0×
|-
| Pi 5, 4× Cortex-A76 aarch64, NVMe (chroot) || 11 s || 5.9×
|}

== Prerequisites ==

* Vanilla Pi OS Bookworm on a Pi 4 or Pi 5 with ~5 GB free disk.
* SSH access as a sudo-capable user.
* Network reach to <code>zx.xalior.com</code>.

== Procedure ==

=== 1. Install host tooling ===

<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get install -y debootstrap qemu-user-static binfmt-support
</syntaxhighlight>

<code>qemu-user-static</code> + <code>binfmt-support</code> register handlers so debootstrap can run armhf binaries during second-stage configure. (On Pi 5 the host kernel can also execute armhf natively via aarch32 compat; binfmt-misc is the fallback.)

Verify:

<syntaxhighlight lang="bash">
dpkg --print-foreign-architectures # should list: armhf
ls /proc/sys/fs/binfmt_misc/ | grep qemu-arm
</syntaxhighlight>

=== 2. Add the apt signing key ===

The mirror is signed with the canonical Raspbian archive key (Mike Thompson, fingerprint <code>A0DA 38D0 D76E 8B5D 6388 7281 9165 938D 90FD DD2E</code>). Modern Pi OS Bookworm doesn't ship it, so add it explicitly:

<syntaxhighlight lang="bash">
curl -sL https://zx.xalior.com/nextpi_dev/debian_nextpi.key \
| sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/debian_nextpi.gpg
</syntaxhighlight>

Confirm:

<syntaxhighlight lang="bash">
sudo gpg --no-default-keyring --keyring /etc/apt/trusted.gpg.d/debian_nextpi.gpg --list-keys
# pub rsa2048 2012-04-01 [SC] A0DA38D0D76E8B5D638872819165938D90FDDD2E
# uid Mike Thompson (Raspberry Pi Debian armhf ARMv6+VFP)
</syntaxhighlight>

=== 3. Debootstrap the chroot ===

<syntaxhighlight lang="bash">
sudo debootstrap --arch=armhf --variant=buildd \
--keyring=/etc/apt/trusted.gpg.d/debian_nextpi.gpg \
stretch /srv/nextpi-buildroot/ \
http://zx.xalior.com/nextpi_dev
</syntaxhighlight>

debootstrap downloads ~50 MB of <code>.deb</code>s, extracts them, and ends with this warning:

<pre>
W: Failure while configuring required packages.
W: See /srv/nextpi-buildroot/debootstrap/debootstrap.log for details (possibly the package systemd is at fault)
</pre>

This is expected — stretch's <code>systemd</code> postinst segfaults under Pi 5's kernel via aarch32 compat. The next step works around it; systemd is never actually run inside a build chroot.

=== 4. Force-install the unconfigured packages ===

The systemd configure failure halts dpkg's pending-configure pass and leaves several packages (including <code>apt</code>) unpacked-but-not-installed. Force them through:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "dpkg --install --force-depends --force-confdef --force-confold --force-overwrite --force-bad-version --recursive /var/cache/apt/archives/"
</syntaxhighlight>

Errors on <code>systemd</code>, <code>plymouth</code>, <code>mountall</code> are expected and harmless.

Verify:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "type apt-get && type gcc"
</syntaxhighlight>

=== 5. Bind-mount runtime filesystems ===

<syntaxhighlight lang="bash">
for m in proc sys dev dev/pts; do
sudo mkdir -p /srv/nextpi-buildroot/$m
sudo mount --bind /$m /srv/nextpi-buildroot/$m
done
sudo cp /etc/resolv.conf /srv/nextpi-buildroot/etc/
</syntaxhighlight>

These are session-only; see [[#Persistent mounts|Persistent mounts]] below for fstab.

=== 6. Hold the broken packages ===

So future <code>apt-get install</code> runs don't re-extract systemd and re-trigger the postinst:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "apt-mark hold systemd plymouth mountall"
</syntaxhighlight>

=== 7. Install build dependencies ===

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C HOME=/root \
/bin/bash -c "apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
autoconf automake libtool libtool-bin pkg-config \
libbz2-dev libaudiofile-dev \
wget git ca-certificates"
</syntaxhighlight>

<code>libtool-bin</code> is required separately on stretch — the <code>libtool</code> umbrella package no longer ships the <code>/usr/bin/libtool</code> script.

A <code>W: APT had planned for dpkg to do more than it reported back</code> warning about <code>systemd:armhf</code> will appear on every apt-get run; that's the hold doing its job.

Toolchain check:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot /usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin /bin/bash -c \
"gcc --version | head -1; automake --version | head -1; libtool --version | head -1; pkg-config --version"
</syntaxhighlight>

Expect: <code>gcc 6.3.0</code>, <code>automake 1.15</code>, <code>libtool 2.4.6</code>, <code>pkg-config 0.29</code>.

=== 8. Smoke test: build libspectrum 1.6.0 ===

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C HOME=/root \
/bin/bash -c '
cd /tmp && \
wget -q https://sourceforge.net/projects/fuse-emulator/files/libspectrum/1.6.0/libspectrum-1.6.0.tar.gz/download -O libspectrum-1.6.0.tar.gz && \
tar xzf libspectrum-1.6.0.tar.gz && \
cd libspectrum-1.6.0 && \
./configure --with-fake-glib --quiet && \
time make -s
'
</syntaxhighlight>

Wall-clock ~10–15 s on Pi 5 / NVMe. Verify:

<syntaxhighlight lang="bash">
file /srv/nextpi-buildroot/tmp/libspectrum-1.6.0/.libs/libspectrum.so.8.10.0
# ELF 32-bit LSB shared object, ARM, EABI5 version 1 (SYSV), dynamically linked
</syntaxhighlight>

Chroot is ready.

== Persistent mounts ==

The bind mounts in step 5 are session-only. For a long-lived build host, add to <code>/etc/fstab</code>:

<syntaxhighlight lang="text">
/proc /srv/nextpi-buildroot/proc none bind 0 0
/sys /srv/nextpi-buildroot/sys none bind 0 0
/dev /srv/nextpi-buildroot/dev none bind 0 0
/dev/pts /srv/nextpi-buildroot/dev/pts none bind 0 0
</syntaxhighlight>

(<code>/etc/resolv.conf</code> will need re-copying after host reboot regardless.)

Pi:CLI

2026-05-02T08:50:50Z

SirCliveSinclairbot: via /pi-wiki-publish

== Abstract ==

The NextPi CLI API is a series of "supported" command-line tools designed to make performing specific Pi orientated tasks easier for Spectrum Next application developers.

The CLI API commands are built out of two parts - known as "Frontends" and "Backends". "Frontends" commands all begin with <code>nextpi-</code> and broken into logical groups (e.g. <code>nextpi-console_</code>, <code>nextpi-play_</code>, <code>nextpi-admin_</code>, etc) - this naming convention allows you to easily tell at a glance what kind of function a command will perform, and for you to know that your commands should continue to work in future NextPi patches.

== More About Frontends & Backends ==

The '''Frontend''' commands often perform their operations via the means of various internal system APIs - in a more traditional Linux setup these Frontends would be called "wrapper scripts". The underlying system tools used by Frontends are what we referred to as '''Backends''' - and you'll often see this term used on individual API CLI pages.

The use of a "formal CLI API" via these Frontend wrappers permits several things:
* The addition of extra options and commandline switches not present in the backends;
* The inclusion of default parameters for many of the commands, or to save boilerplate options; and
* A way of "future-proofing" should the backend need to change for any reason.

Many of the backends support additional options, which can be found by reading the documentation for the individual backends (not included in this wiki) - while this may provide you with extra functionality, it comes at the cost of no assurance that these "undocument features" will also continue to work in future NextPi patches.

== Defining "supported" ==

In the context of the CLI API "supported" means we will try with "best effort" to ensure that documented usage patterns will continue to work. It does not mean that they come with any warrenty of "technical support", actual or implied - to make these APIs work with your own code. Developer support is community provided, and if you're looking for help the best place to try is the Official Spectrum Next discord, found at https://zxn.gg/discord.

== CLI commands ==

* nextpi-admin_clean
* nextpi-admin_disable
* nextpi-admin_enable
* [[Pi:admin_pupextract|nextpi-admin_pupextract]]
* nextpi-admin_report
* nextpi-admin_uihelper
* nextpi-admin_update
* nextpi-admin_version
* nextpi-audio_loopback
* nextpi-cache
* nextpi-cache_bucket
* [[Pi:console_image|nextpi-console_image]]
* [[Pi:console_resolution|nextpi-console_resolution]]
* nextpi-dongle_disable
* nextpi-dongle_enable
* nextpi-echo_disable
* nextpi-echo_enable
* nextpi-file_delete
* nextpi-file_receive
* nextpi-file_rename
* nextpi-file_stream
* nextpi-file_transmit
* [[Pi:gpio_mode|nextpi-gpio_mode]]
* nextpi-input_xbox
* nextpi-play_midiLQ
* nextpi-play_midiHQ
* nextpi-play_midiMQ
* nextpi-play_mod
* nextpi-play_mp3
* nextpi-play_sid
* nextpi-play_silence
* nextpi-play_sndh
* nextpi-play_speech
* nextpi-play_stock
* nextpi-play_stop
* nextpi-plus_activate
* nextpi-plus_list
* nextpi-plus_lock
* nextpi-plus_unlock
* nextpi-tzx_load
* nextpi-ui_file
* nextpi-ui_texteditor
* nextpi-z88dk_switch

Pi:admin pupextract

2026-05-02T08:50:33Z

SirCliveSinclairbot: via /pi-wiki-publish

== Abstract ==

`nextpi-admin_pupextract` validates a Pi Update Patch (`.PUP`) file's header and extracts its payload archive ready for a subsequent update step.

== Prerequisits ==

* NextPi Version: 1.93A

== Backend ==
* Binary: Proprietory

== Options ==
<code>-h</code> display usage information

<code>-vl</code> verbose logging (writes to <code>/tmp/puphelper.log</code>)

<code>-c</code> check the patch's version requirement against the running system without extracting

A single positional argument names the <code>.PUP</code> file to inspect.

== Behaviour ==

The first 512 bytes of the file are read as a PUP header. The header is rejected unless its signature reads <code>PUP</code>, its secondary signature byte is <code>254</code>, and its version field is <code>1</code>. If the header's <code>strict</code> flag is set, the header's <code>piMajor</code> and <code>piMinor</code> must match the running NextPi's major and minor version; otherwise the patch is refused.

On success, the payload that follows the header is copied to <code>/ram/update.tbz</code> in 1 MiB chunks, ready for a subsequent step in the update pipeline.

== Errors ==

* File of 512 bytes or fewer — too small to contain a header.
* Header signature mismatch — not a PUP, or unsupported version.
* Strict-mode version mismatch — the running NextPi does not satisfy the patch's version requirement.

Pi:9e2a321f-e57d-4fed-8d36-c226abdead75

2026-05-02T08:48:50Z

SirCliveSinclairbot: via /pi-wiki-publish

== Abstract ==

A transient synthetic test target used during Phase 3 verification of the `pi-wiki-publish` skill. It does not document a real frontend and may be deleted at any time.

== Prerequisits ==

* NextPi Version: any

== Backend ==
* Binary: none (synthetic test target)

== Options ==

None.

Pi:9e2a321f-e57d-4fed-8d36-c226abdead75

2026-05-02T08:45:26Z

SirCliveSinclairbot: via /pi-wiki-publish

== Sandbox ==

This page is a transient synthetic test for the [[Pi:CLI|nextpi-]] wiki publisher tooling. It exists only to exercise the publish gate and may be deleted at any time.

== Frontends ==

The sandbox does not document a real frontend. See [[Pi:CLI]] for the index of supported frontends.

[[Category:Sandbox]]