Quickstart

By the end of this page you will have SlopOS built from source and running in a QEMU window on your machine.

SlopOS can boot in two ways. The live ISO is a CD image that runs the whole system from memory and keeps nothing when you close it. The development machine is a virtual machine with a disk that keeps what you write, and carries a compiler and a copy of the source so you can build SlopOS inside SlopOS. Start with the live ISO: it builds faster and needs nothing from you.

What you need

A Linux or macOS machine with QEMU (the emulator SlopOS runs in), rustup, just (a command runner: just boot runs the recipe named boot in the repository's justfile), Go 1.22 or later, an LLVM toolchain of version 18 or later, and a handful of disk-image tools. One command per platform installs them:

brew install rustup qemu xorriso e2fsprogs just go python git curl zstd \
  dosfstools mtools util-linux llvm lld cmake ninja openssl

The build looks every tool up on PATH, so add Homebrew's e2fsprogs, util-linux and llvm directories to it if brew tells you they are not linked.

sudo apt install qemu-system-x86 xorriso e2fsprogs python3 git curl zstd \
  dosfstools mtools fdisk golang-go clang lld llvm cmake ninja-build openssl
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install just

sudo pacman -S rustup qemu-full xorriso e2fsprogs python git curl zstd \
  dosfstools mtools util-linux just go clang lld llvm cmake ninja openssl

Not every recipe needs every tool. Booting needs QEMU, xorriso, e2fsprogs and Python; the development machine adds dosfstools, mtools, sfdisk and zstd; the test suite adds Go and LLVM. Building and testing says which recipe needs what.

1. Get the source

git clone https://github.com/SlopLabs/slopos.git
cd slopos

The repository has no submodules. The bootloader (Limine), the virtual machine's firmware (OVMF) and a few other pinned inputs download on first use into third_party/.

2. Install the toolchain

just setup

This installs the exact Rust nightly the repository pins, then builds a copy of it named slopos whose standard library carries SlopOS's own changes. Both the kernel and the programs that run on it build with that copy. The command also checks your Go version and fetches the Go modules of the test runner. When everything is already in place it does nothing, so it is safe to rerun after every pull.

just setup does not install Go for you. If Go is missing or too old it stops and says how to install it. Toolchain explains the slopos toolchain.

3. Boot the live ISO

just boot-live

The first run compiles the kernel and every program, packs them into builddir/slop.iso, and opens a QEMU window.

The first thing you see is the Wheel of Fate: a roulette wheel that decides whether this boot may continue. An odd number lets the system boot. An even number reboots the machine and the wheel spins again. It is a joke that the project keeps, and it is harmless, but you will usually want to skip it:

ROULETTE=0 just boot-live

After the wheel (or without it) the kernel starts the first program, /sbin/init, which brings up the desktop. Everything runs from memory, so nothing you change survives closing the window.

If you have no display, or you are on SSH, add VIDEO=0: QEMU then opens no window and the system's console appears in your terminal.

4. Boot the development machine

just boot-fast

This is just boot with the wheel skipped. It boots an optimised kernel from its own boot disk, with 4 GB of memory and a persistent root filesystem at fs/assets/ext2-persist.img. That disk holds the compiler at /usr/local and a clone of your checkout at /src/slopos, and what you write to it is still there next time. The first run takes longer, because it builds that disk. Development machine covers working inside it.

Check that it worked

For a check that needs no window, boot the live ISO headless:

just boot-log

It boots for 15 seconds, saves everything the kernel printed to test_output.log, and exits non-zero unless the log shows that /sbin/init started.

If something goes wrong

Missing tools, firmware downloads and a disk the build refuses to touch are covered in Troubleshooting. SlopOS also needs a particular kind of virtual (or real) machine; Hardware lists it, and QEMU options lists what the wrapper gives QEMU.

Next, read Building and testing to run the test suite, or the Overview to see how the system fits together.