Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AnimatedGTVR/abora-os/llms.txt

Use this file to discover all available pages before exploring further.

The Abora OS build system combines Nix flakes with a set of shell scripts, all exposed through a single Makefile entrypoint. Running make iso invokes scripts/build-iso.sh, which calls nix build against the flake’s packages.x86_64-linux.iso output and copies the finished image into out/iso/. Everything else — TinyPM packaging, release metadata, QEMU testing — follows the same pattern of thin make targets delegating to dedicated scripts.

​
Requirements

Before running any build target, you need:
  • Nix with the nix-command and flakes experimental features enabled
  • QEMU for local VM testing (make qemu and related targets)
If your Nix installation does not have flakes enabled system-wide, the build scripts set NIX_CONFIG automatically before calling nix build:
export NIX_CONFIG="experimental-features = nix-command flakes"
You can also set this in your shell profile or in /etc/nix/nix.conf to avoid it being set on every build invocation.

​
Flake Outputs

The flake.nix exposes the following outputs:
OutputTypeDescription
packages.x86_64-linux.isoPackageThe live ISO image
packages.x86_64-linux.modularityPackageModularity game engine package
packages.x86_64-linux.mangoPackageMango package
nixosModules.installed-baseModuleInstalled Abora base module
nixosModules.anixModuleANIX NixOS module
overlays.defaultOverlaynixpkgs overlay adding modularity and mango packages

​
Build Targets

​
ISO and Release

Builds the ISO and writes it to out/iso/. Use this for fast live-image and installer iteration.
make iso

​
QEMU Testing

All QEMU targets delegate to scripts/run-qemu.sh with different environment variables controlling the boot mode.

make qemu

Boot the latest ISO in a QEMU graphical window. make qmec and make qemc are aliases for this target.
make qemu

make qemu-fresh

Delete the old QEMU disk image and boot the ISO — the standard clean install test.
make qemu-fresh

make qemu-disk

Boot the installed QEMU virtual hard drive without attaching the ISO. Use this after completing a qemu-fresh install to verify the installed system.
make qemu-disk

make qemu-serial

Boot in headless mode — all QEMU output goes to the current terminal instead of a graphical window.
make qemu-serial

make qemu-fresh-serial

Combines a fresh disk wipe with headless output. Useful for CI-style unattended install testing.
make qemu-fresh-serial

​
Checks and Preflight

1

Run script checks

Validates syntax, executability, and runtime behaviour of every shell script in the repo, verifies required files are tracked by git, and evaluates the Nix flake.
make check
2

Evaluate all desktop profiles

Runs nix-instantiate against all 21 supported desktop profiles to catch configuration regressions before building the ISO.
make check-desktops
3

Run full release preflight

Executes scripts/preflight.sh, which combines script checks, desktop evaluation, and additional release readiness assertions.
make preflight

​
Vendoring Modularity

The Modularity game engine is not bundled in the repo. Use make setup-modularity to extract it from an official Linux zip into vendor/modularity/: 
make setup-modularity ZIP=/path/to/Modularity-1.0.0-Linux.zip
The ZIP variable is required. Running make setup-modularity without it will print a usage message and exit with an error.
setup-modularity is not declared in the .PHONY list in the Makefile. It is a real Makefile target and works correctly, but it is not protected against a file named setup-modularity existing in the repo root. In practice this is not an issue, but it is worth knowing if you are working on the Makefile itself.

​
ISO Naming Convention

The build script names the output ISO using the build date and the version read from the VERSION file: 
abora-YYYY.MM.DD-x86_64-v3.1.4.iso
For example, a build run on 2025-07-15 at version 3.1.4 produces: 
out/iso/abora-2025.07.15-x86_64-v3.1.4.iso
Any previously built ISO at that version tag is removed before the new file is copied in, so out/iso/ always holds at most one ISO per version.

​
Build Output Structure

All generated artifacts land under out/. This directory is not treated as source and should not be committed. 
out/
├── iso/          # Built ISO files
├── packages/     # TinyPM release tarballs and other generated packages
├── release/      # Checksum files, release manifests, and generated release notes
├── qemu/         # QEMU disk images and firmware state
├── logs/         # QEMU serial logs and build logs
└── nix/          # Nix build result symlinks (e.g. iso-result)
A complete make release run populates out/iso/, out/packages/, and out/release/ with everything needed to publish a GitHub release: 
out/release/
├── SHA256SUMS-v3.1.4.txt
├── RELEASE_MANIFEST-v3.1.4.txt
└── RELEASE_NOTES-v3.1.4.md

​
Project Layout Reference

The following table summarises the top-level directories that are relevant to the build system. See the full layout guide in docs/project-layout.md for the complete picture.
PathPurpose
MakefileCommand entrypoint for all build, check, QEMU, and release targets
flake.nix / flake.lockNix flake entrypoint and pinned nixpkgs dependency
VERSIONVersion string consumed by build-iso.sh and release-metadata.sh
scripts/build-iso.shISO-only build path
scripts/release-metadata.shChecksums, manifest, and release notes generation
scripts/package-tinypm.shTinyPM release package path
scripts/run-qemu.shQEMU ISO, fresh-disk, disk-only, and serial helpers
scripts/check-scripts.shRepo script and runtime sanity checks
scripts/check-desktops.shEvaluates every supported desktop profile
nix/profiles/live.nixLive ISO profile and bundled installer assets
nix/modules/installed-base.nixInstalled Abora base module
nix/modules/anix.nixANIX NixOS module
out/Generated build output — do not treat as source

Build docs developers (and LLMs) love

Get started for freeTalk to us