PengyOS / Docs / Build PengyOS

Building PengyOS from source

This is the whole process that produces the published images: the build host, every command, and where each file ends up. Follow it from top to bottom on a fresh machine. The first time takes the better part of a day, most of it waiting for compilers.

The source is public. Everything this guide uses is at github.com/patw/pengyos, MIT licensed. This is the same process the published images come from, so you can follow it end to end and end up with your own signed releases.

1How a build fits together

PengyOS is built with Buildroot 2026.08. Buildroot builds a cross toolchain, then the kernel and every package from pinned source tarballs, and assembles a root filesystem. PengyOS's part is a BR2_EXTERNAL tree (buildroot-external/) with these pieces:

The exception is the COSMIC desktop. Its Rust components, along with the PengyOS installer and updates apps, are built with cargo directly on the build host for now. The Desktop's post-build script copies them into the image. So a Desktop build has two halves:

scripts/build-cosmic.sh: ~/cosmic-src/<component> ──cargo build──▶ ~/cosmic-build/release/* ─┐ tools/pengyos-install-gui ──cargo build──▶ ~/cosmic-build/install-gui ─┤ tools/pengyos-updates ──cargo build──▶ " ─┤ copied in by │ post-build.sh Buildroot 2026.08 + buildroot-external/ ──make──▶ output/<target>/target ◀─┘ │ post-image.sh ▼ output/<target>/images/*.img, *.iso (disk image, installer stick, installer ISO)

Core and Server don't need the COSMIC half.

TargetEditionImages it writes (output/<target>/images/)
pengyos-coreCorepengyos-core-x86_64.img
pengyos-serverServerpengyos-server-x86_64.img, pengyos-server-x86_64.iso, pengyos-server-x86_64-installer.img (legacy)
pengyos-desktopDesktoppengyos-desktop-x86_64.img, pengyos-desktop-x86_64.iso, pengyos-desktop-x86_64-installer.img (legacy)
pengyos-server-nvidiaServer NVIDIAthe Server's file names, in its own output directory
pengyos-desktop-nvidiaDesktop NVIDIAthe Desktop's file names, in its own output directory

2The build host

MinimumReference host
CPUx86-64, 8 threads16 threads
RAM16 GB64 GB
Disk200 GB free for Desktop alonesee below
OSUbuntu 26.04 LTS, x86-64
Virtualization/dev/kvm usable by your user (for testing images)

Disk use on the reference host after a clean build of every edition:

PathSizeWhat
~/build/pengyos/buildroot-2026.08~8 GBBuildroot itself, plus dl/: every source tarball, shared by all targets
~/build/pengyos/output/pengyos-core~24 GBtoolchain, build tree, images
~/build/pengyos/output/pengyos-server~36 GB
~/build/pengyos/output/pengyos-desktop~100 GBadds Mesa + LLVM/Clang, Qt 6, GStreamer, the Wayland stack
~/build/pengyos/output/pengyos-server-nvidia~40 GBa second Server tree, plus Go for the container toolkit
~/build/pengyos/output/pengyos-desktop-nvidia~100 GBa full second Desktop tree
~/cosmic-build~28 GBcargo's target directory for all of COSMIC

Why the host distribution matters

Buildroot builds everything inside the image with its own toolchain, so for Core and Server the host distribution barely matters. The host-built COSMIC binaries are different: they link against the host's libraries. Two rules follow from that.

Another distribution can work, but only Ubuntu 26.04 is tested. If you try another, check the post-build log for missing libraries and boot the Desktop before trusting it.

3Host packages and Rust

One script installs everything with apt, idempotently (it calls sudo itself): Buildroot's requirements, QEMU with UEFI firmware and a software TPM for testing, and with --desktop the headers the COSMIC crates link against, the packages post-build copies libraries from, and Rust through rustup (COSMIC's epoch-1.9 apps need Rust 1.95, newer than Ubuntu's):

git clone https://github.com/patw/pengyos ~/src/pengyos     # see step 4
~/src/pengyos/scripts/provision-build-host.sh --desktop     # or without --desktop for Core/Server only
sudo usermod -aG kvm "$USER"                                # then log out and in again

The package list is at the top of the script. If a COSMIC crate's build script stops on a missing .pc file, apt-file search names the package to add.

Building on PengyOS itself works the same way inside an Ubuntu 26.04 container: distrobox create -n pengyos-build -i docker.io/library/ubuntu:26.04, then run everything in distrobox enter pengyos-build. (Testing images in a VM needs KVM, which PengyOS's kernel doesn't enable yet.)

Two host gotchas.

4Get the source

git clone https://github.com/patw/pengyos ~/src/pengyos
cd ~/src/pengyos

What's where:

VERSIONThe release number, YY.MM.N, written into every image's /etc/os-release
targets.tomlThe buildable targets: name → Buildroot version + defconfig
buildroot-external/The external tree: configs/layers/, board/, package/, external.mk
tools/About 75 small tools, each with its own tests: pengyos-build, pengyos-qemu-verify, pengyos-release, the installer, the updater…
scripts/Host helpers: provision-build-host.sh, build-cosmic.sh, release.sh, flash-usb.sh, compose-defconfigs.py, the repo gate

The images record the git commit they were built from as BUILD_ID (with -dirty if there were uncommitted changes), so build from a clean checkout when the result matters.

5Build COSMIC on the host

Desktop and Desktop NVIDIA only.

~/src/pengyos/scripts/build-cosmic.sh

The script clones every COSMIC component pinned in scripts/cosmic-components.tsv (repository, exact commit, cargo arguments), applies the fixes PengyOS carries (buildroot-external/board/desktop/cosmic-patches/), builds them, and builds the two PengyOS libcosmic apps, the graphical installer and PengyOS Updates. It is idempotent: run it again after changing a pin or a patch, or pass component names (build-cosmic.sh cosmic-settings pengyos-updates) to rebuild just those.

Without COSMIC the image still builds, but post-build only logs a warning: you get a Desktop image with no desktop, a stick with no graphical installer. Check the post-build lines in the build log (next step).

6Build an image

pengyos-build drives Buildroot. Run it from its directory; it needs only Python 3.11+:

cd ~/src/pengyos/tools/pengyos-build
B="python3 -m pengyos_build"
T="--targets ../../targets.toml"

$B list $T                                        # what can be built
$B acquire   pengyos-desktop $T          # clone Buildroot 2026.08 (once, shared by targets)
$B configure pengyos-desktop $T          # apply the edition's defconfig
$B build     pengyos-desktop $T          # the long part
$B sbom      pengyos-desktop $T --embed  # bill of materials, baked into the image
$B status    pengyos-desktop $T          # fetching / building / images / done / error

Optional: build in your SSH key

To log into a test image as root over SSH, export your public key before build. Core's post-build writes it to /root/.ssh/authorized_keys:

export PENGYOS_AUTHORIZED_KEYS_FILE=~/.ssh/id_ed25519.pub

Leave it unset for images you'll give to anyone else.

Every edition, checked: release.sh

~/src/pengyos/scripts/release.sh            # all five images
~/src/pengyos/scripts/release.sh pengyos-server pengyos-core

For each target it configures, builds, generates and embeds the SBOM, checks the image says the right version, and boots it under QEMU: the Core and Server images run their smoke matrices (the boot, every service, no failed units, the firewall, the embedded SBOM), the Desktops must reach a working console login and a running COSMIC session (compositor, panel and the installer, under virgl in Xvfb) with no failed units. It builds COSMIC first when a Desktop is on the list. It refuses to build from uncommitted changes unless you pass --allow-dirty.

Each target has its own output directory and toolchain, so they share downloads but not build time. The NVIDIA targets download NVIDIA's driver bundle (about 420 MB) from download.nvidia.com.

7Test it in a VM

The smoke matrix for an edition (UEFI, with and without a TPM, KVM, throwaway snapshot):

cd ~/src/pengyos/tools/pengyos-qemu-verify
python3 -m pengyos_qemu_verify smoke                                 # Core
python3 -m pengyos_qemu_verify smoke --matrix smoke/server.toml      # Server

Or just a headless boot to a login prompt:

cd ~/src/pengyos/tools/pengyos-qemu-verify
python3 -m pengyos_qemu_verify boot \
  ~/build/pengyos/output/pengyos-server/images/pengyos-server-x86_64.img --uefi

A window you can use:

~/src/pengyos/scripts/run-qemu-disk.sh          # offers every image you have built

Or by hand, with SSH forwarded to port 2222 (use an image built with your key):

cp /usr/share/OVMF/OVMF_VARS_4M.fd /tmp/vars.fd
qemu-system-x86_64 -M q35 -m 4096 -smp 4 -enable-kvm -cpu host \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.fd \
  -drive if=pflash,format=raw,file=/tmp/vars.fd \
  -drive file=pengyos-server-x86_64.img,if=virtio,format=raw,snapshot=on \
  -netdev user,id=n0,hostfwd=tcp:127.0.0.1:2222-:22 -device virtio-net-pci,netdev=n0 \
  -display none -serial file:serial.log &
ssh -p 2222 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null root@127.0.0.1

To test the installer, boot the .iso as a CD (-cdrom pengyos-server-x86_64.iso, with the OVMF lines above) with a second, empty disk (truncate -s 40G target.raw, then another -drive), install onto it, and boot the target disk alone. A VM proves the build boots. Real hardware is still the test for drivers, firmware and the boot splash.

8Write a USB stick

Server and Desktop install from the .iso, a hybrid ISO: write it as it is. Core runs from pengyos-core-x86_64.img.

lsblk                                        # find the stick: the whole disk, e.g. /dev/sdb
sudo dd if=~/build/pengyos/output/pengyos-desktop/images/pengyos-desktop-x86_64.iso \
  of=/dev/sdX bs=4M oflag=direct status=progress

oflag=direct makes the progress line follow what reaches the stick, so the stick is ready when dd returns. The same ISO is what a VM attaches as a CD; how it boots is in docs/iso-installer.md.

Legacy, for one more release: the -installer.img is a raw disk image and needs scripts/flash-usb.sh, which wipes the stick, writes the image, then repairs the partition table for the stick's real size and adds a hybrid MBR (without that, some firmware won't list the stick).

9Make changes

To change…EditThen
Which packages are in an editionbuildroot-external/configs/layers/<layer>.config, in the lowest layer that needs itscripts/compose-defconfigs.py, then configure + build
A file in the image (/etc/…, a unit, a script)board/<layer>/rootfs-overlay/ (core, server or desktop)build
Kernel optionsboard/<layer>/linux.fragmentconfigure + build; check with scripts/check-kernel-fragments.py
A package Buildroot lacksa recipe in buildroot-external/package/<name>/, sourced from Config.inenable it in a layer, as above
A COSMIC componenta patch under board/desktop/cosmic-patches/<component>/, or its pin in scripts/cosmic-components.tsvbuild-cosmic.sh <component>, then build the image
The release numberVERSION (commit it before building)build

10Publish your own updates

Installed machines update from a feed: static files on any web server, signed with an ed25519 key. The image trusts the public keys in /usr/share/pengyos/keys/ and reads the feed URL from /etc/pengyos/update.conf.

A self-built image still trusts the official feed. Unless you change both settings, a machine running your build offers to replace it with the next official release of the same edition.

1. A signing key

cd ~/src/pengyos/tools/pengyos-sign && cargo build --release
./target/release/pengyos-sign keygen --out ~/keys/my-release.key --pub ~/keys/my-release.pub

Keep the private key off the build machine's shared disks and out of the repository.

2. Point the image at your feed

OVL=~/src/pengyos/buildroot-external/board/server/rootfs-overlay
cp ~/keys/my-release.pub $OVL/usr/share/pengyos/keys/
git rm $OVL/usr/share/pengyos/keys/release-2026.pub          # stop trusting official releases
sed -i 's|^feed = .*|feed = https://updates.example.org/update/feed.xml|' $OVL/etc/pengyos/update.conf

Commit, bump VERSION, and build. The Server overlay is part of Desktop too, so this covers both.

3. Publish a release

cd ~/src/pengyos/tools/pengyos-release
R="env -u LD_LIBRARY_PATH python3 -m pengyos_release"
SITE=~/build/pengyos/site                     # a local copy of your web root

# one per edition that installs (Server, Server NVIDIA, Desktop, Desktop NVIDIA)
$R update-publish --build ~/build/pengyos/output/pengyos-desktop \
  --site $SITE --key ~/keys/my-release.key --channel testing \
  --base-url https://updates.example.org/update/ --notes @notes.txt

# later: promote it to stable
$R update-promote --site $SITE --image pengyos-desktop --release 26.10.0 --channel stable \
  --base-url https://updates.example.org/update/

# compressed, checksummed, signed install images under download/
$R download-publish --site $SITE --key ~/keys/my-release.key \
  --build ~/build/pengyos/output/pengyos-desktop --build ~/build/pengyos/output/pengyos-server

rsync -a $SITE/ webhost:/var/www/updates/      # any static web server will do

Or let release.sh do it after the checks pass: PENGYOS_RELEASE_KEY=~/keys/my-release.key scripts/release.sh --publish signs every edition into ~/build/pengyos/site, and --push with PENGYOS_SITE_REMOTE=webhost:/var/www/updates/ uploads it. It won't publish images that weren't boot-checked.

update-publish writes update/<IMAGE_ID>/<version>/ (the root filesystem, the kernel, a signed manifest and release notes) and regenerates update/feed.xml. Machines refuse a release whose signature, edition or version doesn't check out, and they never take a downgrade.

11How reproducible is it?

Pinned today:

Checked: 26.10.3 was built on two machines, the reference Ubuntu 26.04 host and an Ubuntu 26.04 distrobox on a PengyOS Desktop (an Intel N100), at the same paths. The Core and Server images came out byte for byte identical: kernel, root filesystem, ESP, disk image, installer stick and both bills of materials. The Desktop matched too, apart from the host-built COSMIC set.

Not yet:

12Troubleshooting

SymptomCause and fix
Buildroot stops at once, complaining about LD_LIBRARY_PATHAn empty entry in the variable. Use pengyos-build, or env -u LD_LIBRARY_PATH.
A host-tool check fails on install or cpuutils coreutils. Use pengyos-build, which puts the GNU tools first.
Random compiler errors that change between runsA parallel-build race. Use build --jobs 8 and run it again.
The Desktop boots to a black screenThe COSMIC binaries weren't found. Look for post-build: … absent in the build log and check the paths.
The USB stick boots without an installerpengyos-install-gui wasn't built (post-build says so). Wrong file: install from the .iso (or the legacy -installer.img), not the plain .img.
A kernel option from a fragment is silently missingKconfig dropped it (an unmet dependency or a renamed symbol). scripts/check-kernel-fragments.py --kernel-src <linux build dir> lists every dropped line.
The firmware doesn't list the stickA stale partition table on the stick. Clear it (sudo wipefs -a /dev/sdX) and write the ISO again; the legacy -installer.img needs flash-usb.sh.
The build fails at the end of post-build, with libraries the image needs but doesn't containcheck-needed-libs.py found a program needing a shared library the image doesn't have (26.10.3 shipped a compositor without libinput that way). Add the package to the right layer, or (for a host-built COSMIC binary, as a stopgap) to the copy list in the Desktop post-build.sh.
← DocsRecipes →