3.5 KiB
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 upstream reference stays clean in vendor/void-packages/. Generated package
copies, build configuration and caches live in .host/void-packages/; edit
FDS package sources in packages/, not in either generated checkout.
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.