# 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](workstation.md).
A prepared set of kernel, initramfs and SYSTEM images can be run on a Linux
workstation without building the OS locally.

For the physical computer, follow [Run FDS on a Raspberry Pi 5](hardware-setup.md).
It covers HDMI-plus-USB monitor wiring, both disks, EEPROM, first boot and recovery.

## 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](cleanup.md) between build batches.

From the checkout directory, install host prerequisites:

```sh
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.

```sh
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

```sh
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 [real-hardware setup](hardware-setup.md) when preparing a physical machine.

## Start the emulator

With the project-local QEMU tools:

```sh
./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`.
Use a new session directory for the first run; after `stop`, you can `start` the
same session again. Logs and DATA overlays are retained, and bays start empty.
At the `FDS>` prompt:

```sh
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:

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

Continue with [building and inserting software cartridges](workstation.md).
That guide also covers using copied boot images, DATA overlays and USB writing.