fds-os/docs/developer/tooling.md

FDS Rust tools

Development reference and historical context. For current operating instructions, use the user manual. Acceptance applies only to the source and artifacts identified in each record.

Documentation index · Implementation ledger

M3 introduces fds-common, the fds command, and the fds-stage0 diagnostic entry point. Both executables cross-build as static-musl AArch64 programs. The normal OS continues to use glibc; no target musl runtime package is added.

For native Linux software packaging and QEMU hotplug, use make workstation on Arch, or make workstation-binaries on other Linux distributions, and follow the current workstation guide. Those Clap tools are host binaries; make tooling below builds the static ARM runtime tools.

Build and test

After the workstation setup:

make tooling
make tooling-test

The outputs are out/fds, out/fds-stage0, out/fds-boottrace, out/fds-cartridged, out/fds-profile, out/fds-burn, out/fds-inspect, out/fds-eject, out/fds-power and out/fds-release, with hashes and source-input records under out/manifests/fds-tools*.sha256. The tests run shared Rust unit tests on x86_64, inspect the ARM ELF files, then execute those actual ARM binaries with the project-local QEMU userspace emulator. No physical monitor or disk is opened by this test.

The M3 workspace members reuse the already-locked serde, serde_json, and toml dependencies: typed configuration, machine-readable output, and the specified cartridge format. No asynchronous runtime, OpenSSL library, libudev binding, C compiler dependency, or additional native library is introduced.

All Rust command-line interfaces use Clap, with typed commands, generated help, and argument validation before execution. The workspace shares the Clap dependency already used by Dasung; Cargo.lock pins version 4.6.7 and its derive support. It adds no shared runtime library. The dependency-free smoketest has no command-line interface. Test helpers also use Clap and build through Cargo. The migration validation records parser, full-image, VM and startup comparison evidence.

M9 adds media creation and confirmed writes; see Media tools for its current validation state and the new SHA-256 dependency. M12 adds the base fds-release signature verifier and a workstation signer; see Release signatures for key handling, verification and the Ed25519 dependency rationale.

Find commands and options

Run these inside FDS (or prefix them with the emulator invocation below on the workstation):

fds --help
fds help format
fds format data --help
fds recovery repair --help
fds machine --help
fds-burn create --help
fds-release verify --help

Help is specific to the selected command. -h and --help print help without performing an operation; --version reports the executable version. Missing, unknown, duplicated, and conflicting arguments produce a usage error with exit status 2. Operational failures still come from the existing FDS safety checks.

fds --json bays and fds bays --json are equivalent. The installed aliases fds-inspect, fds-eject, and fds-power have their own generated help and accept the same relevant arguments as fds inspect, fds eject, and fds power. Bay selectors accept 1 through 12, including the BAY1 through BAY12 form.

Use -- to separate a managed program from FDS options:

fds run 2 -- editor --help

Here --help belongs to editor. Every argument after the separator is passed to the managed program unchanged, including --json and another --. Media writes still require the exact confirmation associated with the current cartridge insertion and image; accepting CLI syntax never authorizes a write.

Inspect identity and cartridge metadata

Run the ARM programs through the existing container:

./tools/in-void qemu-aarch64 "$PWD/out/fds" info
./tools/in-void qemu-aarch64 "$PWD/out/fds" --json info
./tools/in-void qemu-aarch64 "$PWD/out/fds" inspect \
  "$PWD/tests/fixtures/manifests/windowmaker.toml"

info reports tool version, build target, kernel and the visible PID 1. In userspace emulation those kernel/process values describe the execution environment, not a booted FDS machine. Full-system boot remains a separate test.

Manifest inspection reads at most 64 KiB and rejects unknown keys, unsupported format versions, unsafe identifiers, terminal control characters, writable SYSTEM/PROGRAM/ENVIRONMENT media, and activation actions outside ENVIRONMENT. A profile name is declarative; validation does not execute or activate it. DATA requires writable media. --json gives parsed, validated metadata.

Unknown commands and invalid data return nonzero. Bay state and eject now come from the base cartridge daemon; see Cartridge usage for available operations and remaining milestones.

Stage-0 diagnostics

./tools/in-void qemu-aarch64 "$PWD/out/fds-stage0" --help
./tools/in-void qemu-aarch64 "$PWD/out/fds-stage0" --check-cmdline /path/to/cmdline

Supported FDS kernel options are fds.boot=normal|recovery and fds.debug=0|1. Normal boot selects GPT PARTNAME=FDS_SYSTEM; recovery selects FDS_RECOVERY. Duplicate/unknown FDS options are rejected, while unrelated kernel options are left to the kernel. Read-only --probe SYSFS_ROOT [FDS_SYSTEM|FDS_RECOVERY] reports missing, unique, or ambiguous partitions from kernel-reported identities. It never chooses the first of multiple SYSTEMs and does not infer identity from sdX order.

With no arguments, stage0 now performs the M4 boot path as root PID 1 in the initramfs. It refuses that operation in an ordinary shell. The full-system boot matrix exercises root handoff; diagnostics alone do not establish a boot. M4 reuses the locked libc crate for direct Linux syscalls and adds no shared runtime dependency. The M2 VM remains a separate direct-root fixture.

Boot-event reporting

M5 adds fds boot-profile (or fds --json boot-profile) for the current boot. fds-boottrace adopts stage0 events into volatile runtime storage and records the first console readiness; a restarted shell does not replace that timestamp. Missing events remain absent. See Performance for event boundaries, saved-report comparison, and the greater-than-100 ms regression rule.

Desktop, applications, and Ethernet

M8 adds fds profiles, fds profile activate windowmaker, fds profile deactivate, fds network on|off, and PROGRAM launches with fds run N -- executable-name. The standalone fds-profile is also a static ARM executable. Its root-only s6 helpers create the authenticated X server and supervise the unprivileged desktop session; ordinary callers use the existing peer-checked control socket. See Desktop and programs for a complete usage walkthrough.