144 lines
6.6 KiB
Markdown
144 lines
6.6 KiB
Markdown
# FDS Rust tools
|
|
|
|
[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.
|