# FDS Rust tools

Development reference and historical context. For current operating instructions, use the [user manual](../README.md). Acceptance applies only to the source and artifacts identified in each record.


[Documentation index](README.md) · [Implementation ledger](implementation-status.md)

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`
and the [workstation guide](workstation.md). Those Clap tools are host binaries;
`make tooling` below builds the static ARM runtime tools.

## Build and test

After the [workstation setup](getting-started.md):

```sh
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](clap-validation.md) records parser, full-image, VM
and startup comparison evidence.

M9 adds media creation and confirmed writes; see [Media tools](media-tools.md)
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](releases.md) 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):

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

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

```sh
./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](cartridges.md) for available operations and remaining milestones.

## Stage-0 diagnostics

```sh
./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](boot.md) 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](init.md) 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](performance.md) 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](desktop.md) for a complete usage walkthrough.