Cutting an ISO Release

Cutting an ISO Release

The whole pipeline lives in archiso/. CI (.github/workflows/build.yml) only compile-checks — it does not build or publish ISOs. Releases are cut by hand.

---

The steps

1. Pre-flight the tree. Check for untracked source files, not just modified ones — a git commit -a can otherwise push a tree that doesn't build:

git status --short --untracked=all -- synui synapd synguard synsh synnet synapse_kmod

2. Bump iso_version in archiso/profiledef.sh — and nothing else. Do not touch SYNAPSEOS_VERSION in build.sh; see the version model. Bump the pkgrel of any component whose code changed.

3. Build (~20–30 min: compiles llama.cpp, downloads a ~4 GB GGUF, runs mkarchiso):

sudo ./archiso/build.sh --no-clean

Flag	Effect
(none)	CPU-only llama.cpp — this is the release default
--gpu=vulkan	AMD/Intel; portable, safe to ship broadly (needs glslc)
--gpu=cuda	NVIDIA; will not start on a machine without the driver
--no-gpu	Same as the default; kept for compatibility
--no-model	slim ISO (~4 GB smaller); model fetched on first boot by syn-firstboot
--no-clean	reuse the previous llama.cpp build — safe, and saves the most time

Output: archiso/out/SynapseOS-<ver>-x86_64.iso.

The ISO ships a CPU llama build on purpose, and the default flags give you that. A CUDA or ROCm build links the shipped libggml against the build host's driver stack, so synapd exits 127 on any machine without it — including every VM. --gpu=vulkan is the exception: it links only the Vulkan loader and runs on any AMD/Intel card.

Regardless of the ISO's own backend, the build also packages synapse-llama-cuda into the repo if nvcc is on the host, and synapse-llama-vulkan if glslc is — so an installed machine can switch onto its GPU later. Those go in the repo, never into packages.x86_64.

4. Verify the right packages actually made it in. This is the step that catches a silently stale build:

grep '^synui ' archiso/work/iso/arch/pkglist.x86_64.txt   # → synui 0.1.0-<pkgrel>

If that pkgrel isn't the one you just bumped, the ISO is stale — do not ship it.

5. Publish. GitHub caps release assets at 2 GiB, so the ISO is split:

./archiso/publish-release.sh <ver>

This splits the image into 1900 MiB .part* files and runs gh release create v<ver>. Recent ISOs are ~6.5 GB → 4 parts.

---

--no-clean is safe (it wasn't always)

Two stale-artifact bugs used to make builds silently "succeed" on old output. Both are fixed (3b6b747), but they're worth knowing because they're the shape of failure to expect here:

1. --no-clean used to preserve mkarchiso's work/ too, not just the expensive build/ (llama.cpp). mkarchiso's per-stage stamp files then made it skip straight to "Done!" in about two minutes — reusing the previous ISO and its old pacstrapped packages, including an unbumped synui. A false-positive exit 0. Now build.sh always wipes work/ and gates only build/ on --clean.

2. Git-sourced packages left a stale src/<pkg> that broke the next build. See the src collision hazard.

Two earlier ones (ec361d2, bf5d733): create_source_tarball omitted data/ so synui's install_data(data/wallpaper.png) failed; and build.sh chowned the ISO files but not the out/ directory (mkarchiso creates it root-owned), so publish-release.sh — which runs as your user — couldn't write the split parts.

The collector drift, and why it is now deduped

create_source_tarball existed in two places — build-all.sh and archiso/build.sh — and every single fix to it landed in one and not the other. Four times out of four. The symptom was always the same shape: a file missing from the tarball, a build that fails later and somewhere else, and a fix that "was already applied".

Both collectors now delegate to the component's own <pkg>/mktarball.sh when one exists (8629c32), and build.sh treats a failing mktarball.sh as fatal rather than falling through to a stale tarball. When you add a package that needs particular files, write it a mktarball.sh — do not teach the two collectors about it.

---

Testing without hardware

QEMU_RAM=8G ./archiso/build_scripts/qemu-test.sh   # auto-detects the newest ISO

Uses KVM when available, boots UEFI via OVMF (falling back to BIOS), and attaches a persistent 20 GB test disk. Give it 8 GB+ of RAM when the model is embedded. Kernel and boot output are mirrored to the serial console — View → serial0 in the QEMU window.

The default CPU build is already the right one for QEMU — and for release.

---

Release history

Version	Date	Notes
(unreleased)	—	wlroots 0.20 / scenefx 0.5 port, glass halo + shadow_spread + CSD clipping, HDR-from-EDID, desktop icon persistence, event sounds, the widget manager. Effects off by default
0.1.9	2026-07-24	The desktop release: quickshell bar replaces waybar, start button and menu move into it, desktop widgets, cursor theme manager, six riced themes, LUKS2 full-disk encryption + syn-crypt, per-app window geometry
0.1.8	2026-07-19	AMD/Vulkan + glass. Portable Vulkan llama.cpp backend, dual-boot install, scenefx glass migration, theme manager
0.1.7	2026-07-18	Greeter, clock/calendar panel, Software Manager, Samsung M2020W driver
0.1.6	2026-07-17	Native lock screen, night light, clipboard history, screen recording, laptop support, Bluetooth, CUPS, Alt+Tab MRU
0.1.5	2026-07-13	Titlebars with min/max/close, drag-to-edge snapping, window animations, the synctl control socket, virtual desktops
0.1.4	2026-07-12	Task manager, control panel, tray, game mode, worm/keylogger detection, Secure Boot enroll fix
0.1.3	2026-07-11	synui pkgrel 59 — control panel (Super+C), Super-tap start menu, waybar tray. 6.5 GB / 4 parts
0.1.2	2026-07-10	synui pkgrel 42 — lock screen (Super+L). 5.7 GB / 4 parts
0.1.1	2026-07-08	First release with the wallpaper selector + dock. 5.5 GB / 3 parts
0.1.0	—	Initial

See also: Building and Packaging.