Building
Tato stránka zatím není přeložená, zobrazuje se anglická verze.
UFLinux builds real Alpine packages and then assembles them into images with Alpine’s
mkimage. Everything runs from one entry point, scripts/build.sh.
What you need
Section titled “What you need”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:
# qeme-user-binfmt binfmt-supportpython3 scripts/preflight.py --arch ppc64lex86 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.
The basic command
Section titled “The basic command”export APK_REPOSITORY_URL=https://repo.uflinux.org/apk/v3.24/uflinuxsudo --preserve-env=APK_REPOSITORY_URL bash scripts/build.sh --arch x86_64APK_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.
What the lockfile pins
Section titled “What the lockfile pins”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.
The stages
Section titled “The stages”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. |
Building one package
Section titled “Building one package”Use the same entry point, and repeat independently for each of the five origins:
sudo --preserve-env=APK_REPOSITORY_URL bash scripts/build.sh --arch x86_64 \ --stage packages --package uflinux-settingssudo --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:
python3 scripts/merge-packages.py --arch x86_64 --version 0.1.0Collection 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.
Outputs
Section titled “Outputs”| 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.
Reproducibility
Section titled “Reproducibility”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 inventory
Section titled “The SPDX inventory”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.
The Settings workspace
Section titled “The Settings workspace”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.
After editing Settings
Section titled “After editing Settings”cargo fmt --manifest-path settings/Cargo.toml --allpython3 scripts/check.pyRun 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.