update docs
This commit is contained in:
@@ -0,0 +1,131 @@
|
||||
# Clap command-line migration validation
|
||||
|
||||
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) · [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).
|
||||
Reference in New Issue
Block a user