101 lines
3.8 KiB
Markdown
101 lines
3.8 KiB
Markdown
# 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.
|