Building from source

Everything joe Linux publishes can be built on one Linux machine, without root.

What the build machine needs

Zig 0.17.1, a C toolchain, QEMU with KVM, OVMF firmware, btrfs-progs 6.12 or newer, bubblewrap, zstd, Python 3, OpenSSL, and a build directory on btrfs. Nothing needs root: root-owned trees are made in user namespaces, build chroots with bubblewrap, and disk images without mounting anything. What truly needs root runs inside a virtual machine.

$ git clone https://github.com/theJoeLinuxFoundation/joe-linux
$ cd joe-linux

Tests that take minutes

make test                  unit tests and command-line tests, in seconds
make test-boot-contract    what the design assumes about systemd-boot, in a VM
make test-deployments      upgrade, rollback, power loss and recovery, in a VM

The two VM tests use a scaffold: a throwaway image made from the build machine’s kernel and a stock Arch userspace, so the deployment mechanics can be tested without building a distribution first. Nothing from it ships.

The distribution

make bootstrap             cross toolchain and temporary tools
make packages              every recipe in packages/, into build/repo
make image                 a bootable console image, build/images/joe.img
make run                   boot it in QEMU on this terminal (leave with Ctrl-A X)
make test-joe              the deployment tests on that image
make test-security         the security module's three rules
make audit-security        the seal and declaration audit

The bootstrap follows Linux From Scratch. Building the desktop packages takes several hours the first time; LLVM, Rust, Firefox, Node.js and SpiderMonkey are the long ones.

The desktop and the medium

make desktop-image         a GNOME image, build/images/joe-desktop.img
make run-desktop           boot it in a QEMU window (user joe, password joe)
make test-desktop          the session, every application, a web page; logging and enforcing
make release-image         the desktop as a person gets it, build/images/joe-release.img
make test-release          its first boot: disk growth, first-run setup, sound, shared folder
make iso                   build/images/joe-live.iso, the installation medium
make run-iso               boot the newest medium in a window, beside an empty disk
make test-live             boot it as a CD and as a USB stick
make test-install          install from it onto an empty disk, then boot that

The desktop image is a test image, with a ready-made user. The release image has none, and neither has a system installed from the medium: the first start asks who you are.

The container image

make container             build/images/joe-container.tar, an OCI image

Load it with docker load -i or podman load -i. The published one, ghcr.io/thejoelinuxfoundation/joe, is built from the published repository by a GitHub workflow after each release.

Living in it

make vm                    a virtual machine with a 64G disk of its own, in build/vm
make run-vm                boot it; what you do in it is still there next time
make serve-repo            offer build/repo to that machine

To change the system you are running, as its developer: edit packages/NAME, bump .release in its package.zon, build it with bootstrap/build-packages.sh NAME, leave make serve-repo running, and run sudo dave upgrade and restart in the virtual machine.

The repository’s README and the recipe reference go further.