Skip to content
DOCUMENTATION

Building

UFLinux builds real Alpine packages and then assembles them into images with Alpine’s mkimage. Everything runs from one entry point, scripts/build.sh.

A disposable Linux host with Python 3.11+, GNU tar, gzip, coreutils, util-linux, network access, root privileges, and at least 10 GiB free — more if you keep several builds around.

Non-native architectures need QEMU user emulation and binfmt_misc with the F flag. On Ubuntu runners:

Terminal window
# qeme-user-binfmt binfmt-support
python3 scripts/preflight.py --arch ppc64le

x86 uses the x86_64 kernel’s 32-bit compatibility support. aarch64 and armv7 builds use ARM64 runners; armv7 stays emulated there, because AArch32 support is optional in ARM64 kernels and the runner map treats only an identical host architecture as native.

Run privileged builds on a machine you are willing to destroy. The build chroot exposes proc and selected device nodes but not host sysfs — it is a build environment, not a security boundary for hostile source.

Terminal window
export APK_REPOSITORY_URL=https://repo.uflinux.org/apk/v3.24/uflinux
sudo --preserve-env=APK_REPOSITORY_URL bash scripts/build.sh --arch x86_64

APK_REPOSITORY_URL is optional: builds from the distribution repository default to https://repo.uflinux.org/apk/v3.24/uflinux, and other repositories derive https://OWNER.github.io/REPO/apk/v3.24/uflinux from GITHUB_REPOSITORY.

--stage accepts bootstrap, packages, sign, image, device, verify or all. Stages share --workdir (default .state) and --outdir (default out); download, APK, Cargo and compiler caches use --cache (default .cache/build). A lockfile change requires a fresh work directory, though verified downloads can be reused. After each compile the Cargo and compiler caches are made world-readable, because abuild leaves them owned by uid 1000 with mode 640 and the host user that archives or restores a cache directory could not read them otherwise.

With --device BOARD, the device (or all) stage assembles an installed board disk image instead of an ISO — see Device images.

config/sources.lock.json pins minirootfs hashes, commit archive hashes for the vendored sources (aports, ConnMan, gnome-backgrounds, gpu-screen-recorder, the labwc themes and ReGreet), feature choices, and the default source epoch. Downloaded files are re-checked on every reuse.

The apps section pins UFLinux’s own apps repository, which publishes uflinux-files: its URL, signing key, key hash and indexed architectures. The index itself is not pinned by hash — the repository is republished whenever its packages are rebuilt, so the URL is the pin, the same policy as the Nura suite used by the QCS6490 image. scripts/check.py verifies the pins and that aports/uflinux/uflinux3.ec384.pub matches the published key, and scripts/check-packages.py re-checks the live indexes. Architectures the apps repository does not index never list it, because apk fails on an unreachable repository line.

Alpine’s official repositories remain on the named stable branch so security revisions can be picked up. Resolved package versions and hashes are recorded, but a pinned minirootfs does not freeze those repositories.

Thirty-one custom APKs are built, in five origins:

Origin APKs
connman patched ConnMan: runtime, OpenRC, dev, docs, debug (seven)
uflinux-regreet ReGreet (one)
gpu-screen-recorder patched recorder: runtime, dev, docs, debug (four)
uflinux-settings GUI, desktop shell, screencapture tool, installer UI, daemon/CLI, system helper, OpenRC, documentation, debug symbols (nine)
uflinux distribution packages (ten)

ConnMan’s pinned upstream source and Alpine compatibility patches are retained with the build inputs.

Stage What it does
bootstrap Prepares the root and toolchain.
packages Root installs recipe dependencies with SUDO_APK=apk abuild -F deps; the unprivileged builder runs plain abuild — dependency validation, locked Cargo fetch, frozen release build and tests, development signing. Root removes temporary dependencies afterwards, including after a failure. This avoids target setuid helpers, which cannot elevate under QEMU user emulation.
sign Verifies incoming development signatures, replaces only the APK v2 signature stream, signs indexes, and verifies the results.
image Alpine mkimage with a custom profile, an APK cache, and a reproducible configuration overlay. See Boot-image compression.
device With --device: installs the board’s package set into a separate chroot, configures an installed system, regenerates the initramfs without a modloop, and writes a raw GPT image without loop devices or mounts. The assembled disk is re-read and checked for geometry, identifiers, boot files and initramfs compression before compression.
verify Installs the custom packages through apk, tests a headless desktop and toplevel controls against the resident desktop shell (quick-settings panels, Start menu and wallpaper drawing), checks every shipped executable’s architecture and library linkage, and exercises the installer safeguards. Firmware boot and disk installation are separate VM jobs.

Use the same entry point, and repeat independently for each of the five origins:

Terminal window
sudo --preserve-env=APK_REPOSITORY_URL bash scripts/build.sh --arch x86_64 \
--stage packages --package uflinux-settings
sudo --preserve-env=APK_REPOSITORY_URL python3 scripts/reproducibility.py \
--arch x86_64 --version 0.1.0 --package uflinux-settings

--package automatically uses .state/ORIGIN and .cache/build/ORIGIN, writing below out/package-shards/ARCH/ORIGIN. Shard work and cache directories must stay distinct for concurrent builds. Shards support only packages and bootstrap and never receive release keys.

After every origin succeeds, collect the outputs before sign, image and verify:

Terminal window
python3 scripts/merge-packages.py --arch x86_64 --version 0.1.0

Collection rejects missing APKs, stale hashes, mixed source commits, differing build settings and incomplete native reproducibility proofs. Each native origin must have its clean-rebuild report first. Parallel builds retain build APKs, Cargo inputs and sources separately under out/inputs/ARCH/ORIGIN, with the origin in the release asset name; sequential builds keep the original four-archive format.

GitHub compiles the five origins independently: a pull request or main push schedules five compile jobs (x86_64 only), and a release tag or full-matrix manual run schedules thirty — one per architecture and origin — with at most eight compile jobs at a time. Each origin gets its own VM, development signing key, timeout and cache.

Directory Contents
out/images/ARCH ISO and SHA-256/SHA-512 sidecars
out/devices/ARCH Board disk images (img.zst) and SHA-256 sidecars
out/package-shards/ARCH/ORIGIN Isolated compile outputs before collection
out/packages/ARCH Build-signed APKs and their public key
out/repository/ARCH Final signed APKs and APKINDEX
out/metadata/ARCH Source and build records, hashes, package lists, SPDX inventory
out/checks/ARCH Headless desktop logs, screenshot, memory, validation result
out/vm/ARCH/MODE ISO, install and reboot console logs and result
out/inputs/ARCH Compressed package, source and Cargo inputs for rebuilding

To preserve an older development ISO, choose a separate --outdir and a fresh --workdir. Do not reuse results after changing inputs.

The build sets SOURCE_DATE_EPOCH, UTC, stable paths, normalised tar metadata, and gzip without timestamps; GitHub uses the source commit time. The Rust origins build with opt-level=s, eight codegen units, abort-on-panic, and dynamically linked Alpine libraries. The Settings origin additionally forces fat LTO in its APKBUILD, overriding the workspace’s lto = "thin"; ReGreet only sets the optimization level. Release builds use Cargo’s default debug-info level, and Alpine still splits any available debug symbols into the debug APKs. There is no target-cpu=native or host instruction-set tuning.

These controls help reproducibility, but byte-for-byte reproducibility is not claimed until two clean builds with identical resolved packages have been compared. Clean-build comparisons cover unsigned APK control and data payloads, not whole ISOs. The native CI jobs rebuild each origin with a fresh compiler target directory and compare every custom APK’s control and data streams excluding signatures; publication requires that report to match the exact native package set being published.

To reconstruct an older build, use its source commit and recorded epoch, unpack the input caches, and resolve the recorded APK revisions from the saved packages. If mirrors have dropped those revisions, create a local signed repository from the retained APKs and use it explicitly. The default command resolves current packages from the stable branch — it is not an offline replay mode.

The SPDX file inventories APKs physically bundled in the ISO, including packages available for installation but not installed at live boot. It is not a claim that every cached package is running. Publication requires every custom package that is not a -dbg, -doc or -dev subpackage to appear in that inventory with the same checksum as the published APK. The exception is the device-only set in ISO_EXCLUDED_PACKAGES (scripts/builder.py), currently uflinux-device: those APKs are built, signed and published so device disk images can install them from the release repository, but the live system never pulls them in, so requiring them in the ISO would block every release. Original APK licence annotations are retained in licenseComments; licenseDeclared and licenseConcluded use NOASSERTION, because Alpine annotations can contain non-SPDX strings and the inventory does not guess how to reinterpret them.

Settings, the desktop shell and the screencapture tool share settings/Cargo.lock. Their UIs link GTK4; the session service and privileged helper do not. cargo auditable records dependency data. The Start menu is not a separate crate: its sources live in settings/start-menu/src and are compiled into uflinux-desktop with #[path] module declarations, so the taskbar, its panels and the Start menu are one process.

Terminal window
cargo fmt --manifest-path settings/Cargo.toml --all
python3 scripts/check.py

Run python3 scripts/settings-source.py --update when changing the Settings version. Build preparation removes only project-crate compiler artifacts, so normalised source timestamps do not stale the Cargo fingerprint and dependency caches survive.

Derived from docs/building.md inUFlinux-project/uflinux3(b4f4817). Report documentation problems inUFlinux-project/docs.