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:
- Defconfig layers.
core,server,desktop,nvidia-computeandnvidiaare stacked to make each edition's configuration. A Desktop is literally core + server + desktop; a Server NVIDIA is core + server + nvidia-compute. - Boards. There's one per layer: a root-filesystem overlay, a kernel config fragment, and a post-build script. Each edition's post-image script lays out its disk image, installer stick and installer ISO.
- Recipes for the packages Buildroot doesn't ship, such as greetd, Plymouth, the portals and NVIDIA's driver, plus a few overrides of stock recipes.
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:
Core and Server don't need the COSMIC half.
| Target | Edition | Images it writes (output/<target>/images/) |
|---|---|---|
pengyos-core | Core | pengyos-core-x86_64.img |
pengyos-server | Server | pengyos-server-x86_64.img, pengyos-server-x86_64.iso, pengyos-server-x86_64-installer.img (legacy) |
pengyos-desktop | Desktop | pengyos-desktop-x86_64.img, pengyos-desktop-x86_64.iso, pengyos-desktop-x86_64-installer.img (legacy) |
pengyos-server-nvidia | Server NVIDIA | the Server's file names, in its own output directory |
pengyos-desktop-nvidia | Desktop NVIDIA | the Desktop's file names, in its own output directory |
2The build host
| Minimum | Reference host | |
|---|---|---|
| CPU | x86-64, 8 threads | 16 threads |
| RAM | 16 GB | 64 GB |
| Disk | 200 GB free for Desktop alone | see below |
| OS | Ubuntu 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:
| Path | Size | What |
|---|---|---|
~/build/pengyos/buildroot-2026.08 | ~8 GB | Buildroot itself, plus dl/: every source tarball, shared by all targets |
~/build/pengyos/output/pengyos-core | ~24 GB | toolchain, build tree, images |
~/build/pengyos/output/pengyos-server | ~36 GB | |
~/build/pengyos/output/pengyos-desktop | ~100 GB | adds Mesa + LLVM/Clang, Qt 6, GStreamer, the Wayland stack |
~/build/pengyos/output/pengyos-server-nvidia | ~40 GB | a second Server tree, plus Go for the container toolkit |
~/build/pengyos/output/pengyos-desktop-nvidia | ~100 GB | a full second Desktop tree |
~/cosmic-build | ~28 GB | cargo'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.
- The host's glibc must be no newer than the image's. Ubuntu 26.04 has 2.43 and PengyOS 26.09 has 2.44.
- The shared libraries those binaries need must exist in the image under the same names. The
Desktop build provides most of them (Flatpak, ostree and AppStream are built from source), and
post-build copies the few the image lacks from the host (
libdisplay-info.so.3,libwacom.so.9,libdav1d.so.7, some GStreamer libraries, and an OpenSSL/curl pair for COSMIC Store).
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.
LD_LIBRARY_PATHwith an empty entry (a trailing:, as some CUDA setups leave) makes Buildroot refuse to start.pengyos-buildstrips the variable for you. If you runmakeor the tools yourself, prefix them withenv -u LD_LIBRARY_PATH.- uutils coreutils. Ubuntu 26.04 ships the Rust coreutils as
/usr/bin/install,cpand friends, and Buildroot needs the GNU ones.pengyos-builddetects this and puts the GNU binaries (gnuinstall, …) first onPATHfor the build. Don't call Buildroot'smakedirectly on such a host unless you do the same.
4Get the source
git clone https://github.com/patw/pengyos ~/src/pengyos
cd ~/src/pengyos
What's where:
VERSION | The release number, YY.MM.N, written into every image's /etc/os-release |
targets.toml | The 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.
- Sources go to
~/cosmic-src, binaries to cargo's target directory~/cosmic-build. ExportPENGYOS_COSMIC_SRCandPENGYOS_COSMIC_BUILDto use other directories; the image build reads the same variables. - Keep the source checkouts. Post-build reads data from them as well as binaries: the panel
layout, settings resources, applet icons and
.desktopfiles. - On a machine with little RAM,
CARGO_BUILD_JOBS=2keeps the link steps from swapping.
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
- Everything goes under
~/build/pengyos. SetPENGYOS_BUILD_ROOTor pass--build-rootto use another disk. - The log is
~/build/pengyos/output/<target>/logs/build.log.tail -fit. Grep forpost-build:to see what the board scripts did, COSMIC included. builduses every CPU. If you hit a parallel-build race, pass--jobs 8and run it again. Buildroot resumes where it stopped.--dry-runonconfigureorbuildprints the exactmakecommand without running it.- The first build downloads every source (about 7.5 GB into
buildroot-2026.08/dl/) and compiles a toolchain, the kernel and the whole userspace. Expect hours for the first Desktop. Core and Server are much quicker, and later builds of the same target only redo what changed.
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… | Edit | Then |
|---|---|---|
| Which packages are in an edition | buildroot-external/configs/layers/<layer>.config, in the lowest layer that needs it | scripts/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 options | board/<layer>/linux.fragment | configure + build; check with scripts/check-kernel-fragments.py |
| A package Buildroot lacks | a recipe in buildroot-external/package/<name>/, sourced from Config.in | enable it in a layer, as above |
| A COSMIC component | a patch under board/desktop/cosmic-patches/<component>/, or its pin in scripts/cosmic-components.tsv | build-cosmic.sh <component>, then build the image |
| The release number | VERSION (commit it before building) | build |
- Never edit the generated
configs/pengyos_*_defconfigfiles.compose-defconfigs.py --checkfails when they're out of date. - Re-running
configurecompares the old and new configuration and cleans every package whose options changed, so the nextbuildrebuilds it. Buildroot alone wouldn't. To force one package to rebuild, use Buildroot's own targets, e.g.env -u LD_LIBRARY_PATH make -C ~/build/pengyos/buildroot-2026.08 O=~/build/pengyos/output/pengyos-server podman-dirclean, thenbuild. - Before committing, run the repository's checks: each tool's tests
(
python3 -m pytest -qorcargo testintools/<tool>) and the integration gate,python3 scripts/pengyos_gate.py run --repo . --mode full, which runs every tool's tests (the same check runs on every push).
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:
- Buildroot itself (the
2026.08tag) and, through it, every package's version and tarball hash; every PengyOS recipe's version and.hash, the defconfig layers, the kernel fragments and the overlays - every COSMIC component's commit (
scripts/cosmic-components.tsv) and itsCargo.lock - Buildroot's reproducible mode is on: UTC and the C locale, a fixed kernel build user, host
and time, and
SOURCE_DATE_EPOCHset to the commit's date - each image's
/etc/os-releaserecords the release and the git commit it came from, and/etc/pengyos/holds its SPDX and CycloneDX bill of materials
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:
- The COSMIC components are built on the host, so the host's compiler and libraries leak into the Desktop. Moving them into Buildroot recipes with vendored crates is the next step.
- A release isn't yet gated on that comparison; for 26.10.3 it was done by hand. Buildroot only
promises identical output for builds in the same output directory, so build at the same paths
(the repository and
~/build/pengyos) and compare.pengyos-repro comparelists every file that differs.
12Troubleshooting
| Symptom | Cause and fix |
|---|---|
Buildroot stops at once, complaining about LD_LIBRARY_PATH | An empty entry in the variable. Use pengyos-build, or env -u LD_LIBRARY_PATH. |
A host-tool check fails on install or cp | uutils coreutils. Use pengyos-build, which puts the GNU tools first. |
| Random compiler errors that change between runs | A parallel-build race. Use build --jobs 8 and run it again. |
| The Desktop boots to a black screen | The COSMIC binaries weren't found. Look for post-build: … absent in the build log and check the paths. |
| The USB stick boots without an installer | pengyos-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 missing | Kconfig 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 stick | A 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 contain | check-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. |