77 lines
3.0 KiB
Markdown
77 lines
3.0 KiB
Markdown
# Development tools
|
|
|
|
## Host support
|
|
|
|
Automation currently supports **Windows 10/11 only**. The fast development loop
|
|
requires only `uv`; it downloads pinned DOSBox-X and Open Watcom DOS releases.
|
|
The final milestone gate additionally requires QEMU with WHPX support and
|
|
`ffmpeg.exe` on `PATH`. Other hosts are not supported yet.
|
|
|
|
## Getting started
|
|
|
|
```powershell
|
|
uv run ferro-test setup --accept-watcom-license
|
|
uv run ferro-test run --through m6 -v
|
|
```
|
|
|
|
`setup` reads `tools/toolchains/dosboxx.lock.json`, downloads the exact official
|
|
archives, verifies their SHA-256 hashes, and extracts them under ignored
|
|
`.dosboxx/`. Review the Open Watcom license referenced by the lock file before
|
|
accepting it. Archives and installed tools are deliberately not committed.
|
|
|
|
Each `run` creates a disposable DOS drive, copies the current compiler, standard
|
|
library, and fixtures, then builds `FEC.EXE` once inside DOS with Open Watcom.
|
|
All selected milestone commands execute sequentially in that same DOSBox-X
|
|
instance, while pytest reports every emit, Watcom build, runtime, and rejection
|
|
check separately. Thus stale QEMU binaries cannot make the test pass.
|
|
|
|
`--through m6` runs cumulatively from M1; `--only m6` selects one milestone.
|
|
Use `--keep-failed` to preserve a failed drive under `.dosboxx/runs/`,
|
|
`--dos-log` to print the captured DOS console, `--trace-dos` to disable command
|
|
output redirection, and `--show-dos` to keep the GUI open until a key is pressed.
|
|
|
|
This is the quick development smoke test. Run the QEMU/FreeDOS workflow below
|
|
for the authoritative milestone completion gate.
|
|
|
|
```powershell
|
|
uv run ferro-vm start
|
|
uv run ferro-vm status
|
|
```
|
|
|
|
The command list lives in the CLI itself, not in this file:
|
|
|
|
```powershell
|
|
uv run ferro-vm --help
|
|
uv run ferro-vm <command> --help
|
|
uv run ferro-test --help
|
|
```
|
|
|
|
Working rules, verification gates, and DOS build traps are in `AGENTS.md`.
|
|
|
|
## How it fits together
|
|
|
|
`TCPAGENT.EXE` runs inside FreeDOS and dials out to `127.0.0.1:5558`; its wire
|
|
protocol is documented in `tcpagent/README.md`. The `ferro-vm` daemon owns that
|
|
connection and the QEMU monitor. Local commands reach the daemon over the
|
|
Windows named pipe `\\.\pipe\ferrolang-vm` — there is no controller or observer
|
|
TCP port.
|
|
|
|
The daemon writes an append-only structured log (`uv run ferro-vm logs`, which
|
|
uses `lnav` when installed and otherwise falls back to PowerShell `Get-Content
|
|
-Wait`). It records command metadata, DOS output, exit status, transfers, and
|
|
agent lifecycle events as UTF-8 lines, and deliberately never logs raw binary
|
|
payloads or protocol hex.
|
|
|
|
`reset` quits QEMU cleanly, restarts it, waits for FreeDOS to boot, submits the
|
|
default boot-menu Enter, and requires a TCPAGENT `PING`/`PONG` before returning.
|
|
QEMU `system_reset` is intentionally unsupported: repeated soft resets leave the
|
|
FreeDOS NE2000 packet driver stuck during initialization.
|
|
|
|
## Standalone OCR
|
|
|
|
`tools/qemu_ocr.py` remains available for OCRing an existing image:
|
|
|
|
```powershell
|
|
uv run python tools/qemu_ocr.py --image .qemu/qemu-screen.png
|
|
```
|