fds-os/docs/getting-started.md

Build and start FDS

This guide creates a bootable FDS SYSTEM image and starts it in QEMU. Use an x86_64 Arch Linux workstation for the complete OS build. To build application cartridges on another Linux distribution, use the workstation guide. A prepared set of kernel, initramfs and SYSTEM images can be run on a Linux workstation without building the OS locally.

Prepare the workstation

Use a normal user account, a Git checkout with its submodule metadata, and a checkout path without spaces. Initial preparation needs Internet access. The host must support unprivileged user namespaces and namespaced binfmt_misc (Linux 6.7 or newer). Full builds and VM tests use tens of GiB per build tree; check free space with df -h . and use cleanup between build batches.

From the checkout directory, install host prerequisites:

sudo pacman -S --needed bash coreutils binutils git curl make file tar xz gzip zstd \
  bubblewrap rustup ca-certificates findutils diffutils grep sed gawk util-linux \
  python e2fsprogs libarchive lz4
bwrap --ro-bind / / --unshare-user --uid 0 --gid 0 true

Python must be 3.14 or newer. The namespace check exits successfully without output. Build commands below run as your normal user, sequentially; they share one project-local Void build container.

make bootstrap
make smoke-test
make check

Bootstrap prepares pinned Rust and XBPS tools and the Void build container. The smoke test checks the AArch64 build toolchains; make check validates the build guardrails. Stop and resolve any failed command before continuing. Logs are in out/logs/. Repeated preparation reuses verified downloads and caches.

Build the images

make rootfs PROFILE=cli
make system-card PROFILE=cli
make initramfs
make workstation

The rootfs build includes the kernel and base packages. These are the three inputs needed by the emulator:

File	Purpose
out/kernel/boot/kernel_2712.img	ARM kernel
out/fds-initramfs.img	Early startup and SYSTEM discovery
out/fds-system-cli.img	Read-only operating system cartridge

make rootfs PROFILE=development followed by make system-card PROFILE=development builds a SYSTEM with compilers, Git, Vim, debuggers and display diagnostics. Both profiles include WindowMaker and the Dasung daemon. The desktop starts on request. make all also assembles recovery, boot and internal-storage images; see internal installation when preparing a physical machine.

Start the emulator

With the project-local QEMU tools:

./tools/in-void xbps-install -y qemu-img
out/workstation/fds-emulator --session out/my-emulator start --qemu-runner tools/in-void
out/workstation/fds-emulator --session out/my-emulator console

If QEMU is installed directly on the workstation, omit --qemu-runner. The session directory must be new. At the FDS> prompt:

fds info
fds bays
fds --help

The shell runs as the ordinary fds user. Press Ctrl-] to detach from the console; the VM remains running. Stop it from the workstation:

out/workstation/fds-emulator --session out/my-emulator stop

Continue with building and inserting software cartridges. That guide also covers using copied boot images, DATA overlays and USB writing.