129 lines
6.5 KiB
Markdown
129 lines
6.5 KiB
Markdown
# Clap command-line migration validation
|
||
|
||
[Documentation index](README.md) · [Command usage](tooling.md) · [M12 evidence](m12-validation.md)
|
||
|
||
Software acceptance completed on 2026-09-21. Every Rust command-line interface
|
||
uses the shared, locked Clap 4.6.7 dependency. The migration adds no third-party
|
||
crate versions or shared runtime libraries. Dasung already used Clap; its
|
||
workspace dependency now shares the same definition. The dependency-free
|
||
smoketest has no argument interface.
|
||
|
||
## Implemented behavior
|
||
|
||
- Typed commands cover `fds`, its inspect/eject/power aliases, stage0, boottrace,
|
||
cartridge/profile services, media creation/writing, and release signing.
|
||
- `fds burn` and `fds-burn` share one grammar. Format options are specific to
|
||
the selected class, with duplicate and conflicting options rejected.
|
||
- Clap generates command-specific help, versions, required-option errors and
|
||
typed bay/size validation. Global `--json` works around nested commands.
|
||
- `fds run BAY -- EXECUTABLE ARGS...` preserves every child argument, including
|
||
`--help`, `--json`, empty strings, spaces and an additional `--`.
|
||
- Private s6 flags and default daemon/PID-1 behavior are preserved. Stage0
|
||
enters its emergency path on argument errors as PID 1 instead of exiting.
|
||
- VM client and write/stress helpers now build through Cargo and use Clap.
|
||
No project-owned Rust source reads or slices a raw process argument vector.
|
||
Kernel command-line files and metadata remain separate domain parsers.
|
||
|
||
A regression test caught that Clap's broad argument/subcommand conflict rule
|
||
also rejected `fds-inspect --json image IMAGE`. The final implementation uses
|
||
Clap's typed conversion hook to reject only simultaneous target/image forms;
|
||
it accepts global options before or after the image subcommand. This behavior
|
||
passed host parser tests and execution of the actual ARM binary.
|
||
|
||
## Build and runtime evidence
|
||
|
||
The final tooling run passed **48 Rust unit tests**, ELF checks for every ARM
|
||
executable/alias, real ARM help/version/invalid-input tests, strict metadata
|
||
checks and stage0 diagnostic fixtures. Evidence: `out/logs/clap-tooling-test.log`.
|
||
The independent Dasung simulator/service and host/ARM/OpenSSL signing suites
|
||
passed in `out/logs/clap-dasung-test.log` and
|
||
`out/logs/clap-signing-test.log` (`out/m12-signing.9xgbool5/`).
|
||
|
||
`make bootstrap`, `make smoke-test`, and `make check` passed. The complete
|
||
`make all` build passed in `out/logs/clap-all-final.log`; the earlier
|
||
`clap-all.log` attempt was intentionally stopped before fixing the inspection
|
||
option-placement regression. The final `make check` also passed in
|
||
`out/logs/clap-check-final.log`.
|
||
|
||
All suites below passed against the rebuilt images. Each has its own
|
||
`out/logs/clap-<make-target>.log` and retained VM/image evidence:
|
||
|
||
| Make target | Evidence directory |
|
||
| --- | --- |
|
||
| `init-test` | `out/m2-vm.lsptD3/` |
|
||
| `boot-test` | `out/m4-vm.4VJHfm/` |
|
||
| `console-test` | `out/m5-vm.ktln7za0/` |
|
||
| `cartridge-test` | `out/m6-vm.nv3oq41q/` |
|
||
| `data-test` | `out/m7-vm.yv53pjkk/` |
|
||
| `desktop-test` | `out/m8-vm.q8nwbhgc/` |
|
||
| `media-image-test` | `out/m9-images.9ts4w_qb/` |
|
||
| `media-test` | `out/m9-vm.06yddrko/`, `out/m9-system.a9n8xxb_/` |
|
||
| `power-test` | `out/m10-vm.yk62sod6/` |
|
||
| `stress-test` | `out/m11-vm.vg5dicrw/`, `out/m11-faults.pd52oxs7/` |
|
||
| `recovery-test` | `out/m12-recovery.0604mqgm/` |
|
||
| `internal-test` | `out/m12-internal.uj0rbf4i/` |
|
||
| `clock-test` | `out/m12-clock.f54asrop/` |
|
||
| `development-test` | `out/m12-development.mu29x4mr/` |
|
||
|
||
These checks include actual SYSTEM creation/write/readback/boot, confirmed DATA
|
||
repair, interrupted-checker quarantine, persistent settings across reboot,
|
||
window manager and DHCP control, sustained writes, all twelve overlapping I/O
|
||
intervals, and injected write/flush/readback/worker/daemon failures. They use
|
||
regular-file images and isolated ARM VMs. No physical media was written.
|
||
|
||
## Executable size and startup measurements
|
||
|
||
Clap increases executable sizes. All eight production Rust programs (including
|
||
Dasung) remain statically linked and contain no personal build-path prefix.
|
||
`out/clap-binary-sizes.json` records the final hashes and these sizes:
|
||
|
||
| Executable | Before, bytes | After, bytes |
|
||
| --- | ---: | ---: |
|
||
| `fds` | 900,720 | 1,097,960 |
|
||
| `fds-burn` | 821,344 | 990,312 |
|
||
| `fds-stage0` | 474,336 | 633,880 |
|
||
| `fds-boottrace` | 442,152 | 606,672 |
|
||
| `fds-cartridged` | 917,328 | 1,064,832 |
|
||
| `fds-profile` | 527,880 | 687,904 |
|
||
| `fds-release` | 434,720 | 595,776 |
|
||
|
||
Five alternating QEMU TCG boot pairs compare the previous complete image set
|
||
with the rebuilt images, using the same Pi kernel. The previous images also
|
||
precede Rust source-path normalization; this is an image-level comparison,
|
||
not an isolated microbenchmark of the parser. Each measurement uses Linux
|
||
CLOCK_BOOTTIME from kernel start to the first ordinary-user console.
|
||
|
||
| Image set | Five samples, ms | Median, ms |
|
||
| --- | --- | ---: |
|
||
| before | 1958.754852, 2031.634456, 1998.790409, 1951.843302, 1961.052514 | 1961.052514 |
|
||
| clap | 1917.447815, 1909.301394, 1923.776234, 1955.579658, 2053.676925 | 1923.776234 |
|
||
|
||
The median change was **−37.276280 ms**, below the +100 ms regression threshold.
|
||
This does not establish a speedup on the Pi. Input hashes, all sample reports
|
||
and serial logs are in `out/clap-console-pairs.qyyoppcj/`; the replay script is
|
||
`out/clap-boot-comparison.py`.
|
||
|
||
The updated stage0 was also built at all three optimization levels and booted
|
||
three times per level (`out/rust-profiles.8hnnusn8/comparison.json`):
|
||
|
||
| Optimization | Stage0 bytes | Median kernel-to-console, ms |
|
||
| --- | ---: | ---: |
|
||
| `z` | 633,880 | 1922.658965 |
|
||
| `2` | 730,568 | 1938.769685 |
|
||
| `3` | 757,168 | 1950.010662 |
|
||
|
||
Retain `z`; these VM samples do not establish a physical-hardware winner. The
|
||
separate twelve-device test observed a +180.457 ms median versus empty bays.
|
||
That comparison adds twelve emulated USB devices and is not the before/after
|
||
Clap comparison. Its readiness-gate test still proved that cartridge service
|
||
readiness does not block the console. Physical Pi boot and shutdown targets,
|
||
USB electrical behavior, display recovery and flash durability remain deferred.
|
||
|
||
## Release status
|
||
|
||
The requested CLI migration is complete and included in the signed local
|
||
0.1.0 release. Fresh v5 offline builds produced 27 byte-identical artifacts,
|
||
which also match the normal images used by every runtime suite above. The old
|
||
v4 candidate was stopped before acceptance. See [final M12 evidence](m12-validation.md#final-local-release-acceptance)
|
||
and the [67-section implementation ledger](implementation-status.md).
|