felis/fds-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Package workstation tools, reuse emulator sessions, and derive build versions

Browse Source
This commit is contained in:
felis
2026-09-23 03:45:48 +08:00
parent 6bfcce8070
commit f5d9f96409
79 changed files with 878 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/workstation.md
+45 -5
View File
@@ -7,15 +7,42 @@ as guest commands.
## Prepare the tools
The native tools are `fds-cartridge` and `fds-emulator`. Build them with Rust,
a C linker and Make; the repository selects its pinned Rust toolchain:
The native tools are `fds-cartridge` and `fds-emulator`. On Arch Linux, build
and install their `fds-tools` package from the checkout:
```sh
sudo pacman -S --needed base-devel rustup python git
make workstation
mkdir -p out
make workstation-install
```
`make workstation` produces `out/workstation/fds-tools-VERSION-1-ARCH.pkg.tar.zst`
with both commands, documentation, examples and license notices. It does not
install packages. `make workstation-install` builds that package and invokes
`sudo pacman -U` to install it into `/usr/bin`. Pacman tracks upgrades and removal;
remove it later with `sudo pacman -R fds-tools`. The exact latest package path is
recorded in `out/workstation/package-path.txt`.
The package requires glibc, GCC runtime libraries and xz. EROFS, bubblewrap and
QEMU are optional package dependencies because the tools can use the project-local
Void runners instead. For all features using native Arch utilities, install:
```sh
sudo pacman -S --needed bubblewrap erofs-utils qemu-system-aarch64 qemu-img
```
On other Linux distributions, install Rust, a C linker, Make, Python 3 and Git,
then build the same native commands without Arch packaging:
```sh
make workstation-binaries
export PATH="$PWD/out/workstation:$PATH"
```
Python and Git resolve the build version; neither is needed to run the installed
Rust commands. The repository selects its pinned Rust toolchain. XBPS and a
prepared Void checkout are still separate source-build prerequisites.
| Prerequisite | Used for |
| --- | --- |
| Prepared writable Void `void-packages` checkout and native XBPS utilities | Build source packages and install their AArch64 runtime dependencies |
@@ -138,7 +165,9 @@ fds-emulator --session out/my-emulator start \
--system /path/to/fds-system-cli.img
```
The session directory must be new and private. Keep its absolute path short
The session directory is created private (0700). After stopping, reuse the same
directory with the same `start` command; an existing directory must contain a
valid stopped FDS session owned by you. Keep its absolute path short
(under 90 bytes) for Unix sockets. Start waits for the FDS prompt and uses two
emulated CPUs and 1024 MiB RAM; `--memory-mib 2048` increases memory. SYSTEM and
PROGRAM images are read-only. The session holds logs and any DATA overlays.
@@ -181,7 +210,18 @@ fds-emulator --session out/my-emulator stop
Eject asks FDS to stop programs and release storage before removing the virtual
USB device. If FDS refuses, the cartridge stays attached. `stop` performs native
FDS shutdown. Session logs remain available; create a new session to boot again.
FDS shutdown and waits for QEMU to exit. Start the same session again:
```sh
fds-emulator --session out/my-emulator start --qemu-runner tools/in-void
```
Pass any custom boot-image or memory options again. This is a fresh boot with
empty cartridge bays. Console and QEMU logs are appended, DATA overlay files
remain in place, and `previous-*.json` preserves the previous session's image
and overlay mapping. Insert cartridges again as needed. A running session,
unknown directory, insecure permissions, or an outstanding control operation
prevents restart; the tool never clears a live session to make room.
`unplug BAY` simulates a physical pull, and `stop --force` cuts virtual power.
Use these only for deliberate failure simulation; DATA writes can be lost.