Build Pipeline spk-compile

spk-compile (Project SmechDeployV2) is the sovereign build orchestrator for the entire Smech Labs OS stack. It is a single standalone Python 3 script with zero external dependencies — no pip, no venv, no external build system abstraction. Every build phase is implemented inline. SmechDeploy (the old collection of numbered shell/Python scripts) is retired; spk-compile is the build system.

Download

curl -fsSL https://github.com/Smech-Labs/spk-compile/releases/download/v2.2.0/spk-compile.py -o spk-compile.py
python3 spk-compile.py --version

Full release notes: github.com/Smech-Labs/spk-compile/releases/tag/v2.2.0

Getting spk-compile

git clone https://github.com/Smech-Labs/spk-compile.git
cd spk-compile

Or call it directly from inside spk (as spk build-image since spk v2.5.0 -- spk compile now means "build one package's source into a .spkg", see spk's README):

spk build-image smechos
spk build-image smechvisor --phase kde
spk build-image --list smechos

spk locates spk-compile.py at /usr/share/spk/spk-compile.py or /opt/smechdeploy/spk-compile.py.

What it builds

Prerequisites

• x86_64 Linux host with Docker or Podman
• Root / --privileged container access (kernel build, module installs)
• ~50 GB free disk space for source downloads and build artifacts
• Internet access (sources are downloaded on demand and cached)

Source tarballs are cached in spk-compile-sources/ (adjacent to --target, bind-mount this as a persistent volume). Re-runs skip already-cached files and already-completed phases via stamp files under spk-compile-sources/.stamps/.

Building in a container

# Build the compile image once (cached after the first run)
podman build -t ghcr.io/smech-labs/smechos-build:latest -f Dockerfile .
# docker build works identically if you have Docker instead of podman

# Run the full build
docker run --rm --privileged --cgroupns=host \
    -v /path/to/spk-compile-sources:/mnt/spk-compile-sources \
    -v /path/to/smechos_build_root:/mnt/smechos_build_root \
    -v /tmp/smechos_build:/tmp/smechos_build \
    ghcr.io/smech-labs/smechos-build:latest smechos-plasma-live

mkdir -p /path/to/smechos-iso-output
docker run --rm --privileged --cgroupns=host \
    -v /path/to/spk-compile-sources:/mnt/spk-compile-sources \
    -v /path/to/smechos_build_root:/mnt/smechos_build_root \
    -v /tmp/smechos_build:/tmp/smechos_build \
    -v /path/to/smechos-iso-output:/mnt/smechos-iso-output \
    ghcr.io/smech-labs/smechos-build:latest smechos-plasma-live --iso live

The finished ISO lands at smechos-iso-output/smechos-plasma-live.iso.

The container runs as root, so the ISO output directory ends up root-owned on the host. Hashing/signing as a regular user afterward needs a chown first, or sha256sum ... | tee and gpg fail to write their output files silently:

sudo chown -R $(whoami):$(whoami) /path/to/smechos-iso-output
cd /path/to/smechos-iso-output
sha256sum smechos-plasma-live.iso > smechos-plasma-live.iso.sha256
gpg --detach-sign --armor smechos-plasma-live.iso

If a phase fails on a missing package, that's normal — it's a one-line Dockerfile fix, not a real bug. Find the Ubuntu -dev package providing the missing CMake/Meson dependency, add it to the relevant apt-get install block, and rebuild — Docker layer caching keeps this to seconds, and completed phases/packages are skipped via the stamp files, so you only re-pay for the phase that failed. A handful of dependencies aren't in apt at all (KDE-adjacent projects on their own release schedule, or small third-party libraries) — those get built from source inline in phase_kde(); copy the existing pattern there for a new one.

Build Profiles

SmechOS

# Full build
sudo python3 spk-compile.py smechos

# Single phase
sudo python3 spk-compile.py smechos --phase kde

# Custom target path
sudo python3 spk-compile.py smechos --target /mnt/my_build_root

# Build install ISO
sudo python3 spk-compile.py smechos --iso install

SmechVisor

# Full build
sudo python3 spk-compile.py smechvisor

# Deploy shim ISO only
sudo python3 spk-compile.py smechvisor --iso shim

List phases

python3 spk-compile.py --list smechos
python3 spk-compile.py --list smechvisor

Phase Reference

SmechOS phases (24, profile smechos-plasma-live)

SmechVisor phases (8)

Source versions pinned

SmechOS builds against glibc + systemd, not musl/OpenRC — the leaner musl/OpenRC stack is used only by the headless smechos-bitcoin profile (see spk-compile.py's SMECHOS_BITCOIN_PHASES), not the desktop smechos-plasma-live profile this page documents.

Adding a new phase

1. Write a Python function def phase_myfeature(target): ... in spk-compile.py. Use download(), extract(), cmake_install(), or meson_install() helpers.
2. Add a tuple ("myfeature", phase_myfeature, "Description") to the relevant phase list — SMECHOS_PLASMA_LIVE_PHASES for the desktop build, or SMECHOS_PHASES / SMECHVISOR_PHASES / SMECHOS_BITCOIN_PHASES for the other profiles — at the correct position.
3. Run with --phase myfeature to test in isolation before committing to the full build.