diff --git a/newLang/planning/claims/E07-S05.md b/newLang/planning/claims/E07-S05.md new file mode 100644 index 0000000..06ae28c --- /dev/null +++ b/newLang/planning/claims/E07-S05.md @@ -0,0 +1,111 @@ +--- +story: E07-S05 +owner: codebuff +status: in-progress +started: 2026-11-10 +depends-on: [E07-S01, E04-S01, E04-S06, E02-S04] +--- + +# E07-S05 Claim + +## Intended change + +A `n128c` PRG that runs on `x128` and is the compiler the launcher and disk +builder already assume: it takes a source name from the keyboard, loads that SEQ +file from drive 8 through the buffered PETSCII reader, runs lexer, parser and +pass-2 emission, writes `NAME.PRG` and `NAME.MAP` through `output.s`, and prints +a one-screen summary with the source name, the output name and the diagnostic +count. Failures print a stable message, write diagnostics to `NAME.ERR`, and +leave any previous output untouched. + +## File area + +- `src/compiler/driver.s` (new): prompt, load, compile, output, summary +- `cfg/driver.cfg` (new, or `cfg/compiler.cfg` plus `output.s` if the extra + section fits): link layout for the whole compiler +- `scripts/build-driver.ps1` (new): builds `build/n128c.prg` +- `tests/driver/driver.n8`, `tests/driver/fail.n8` (new fixtures) +- `scripts/verify-driver-test.ps1` (new): drives the PRG through `x128` + `keybuf` on a copied image and checks the PRG, ERR, MAP and summary +- `docs/editor-workflow.md`, `docs/architecture.md`, `docs/decisions.md` +- `planning/claims/E07-S05.md` +- generated files under `build/driver-test/` + +## Acceptance criteria (from the story) + +- [ ] `build/n128c.prg` is built by a documented script and is the file + `prepare-disk.ps1` injects and `launch-compiler.ps1` autostarts. +- [ ] The driver takes one source name, loads it from the session disk with no + host conversion, compiles, and writes the PRG named after the source. +- [ ] ERR and MAP outputs are written for the same run, with a one-screen + summary naming source, output and diagnostic count. +- [ ] A clean source produces a PRG that runs on `x128`; a failing source + produces the catalogued diagnostics, a non-zero count, and no PRG. +- [ ] Missing source, unreadable source and an existing output each end with + the documented message and leave the previous output intact. +- [ ] A test drives the driver through `scripts/launch-compiler.ps1` on a copied + development image and checks the artifacts. +- [ ] `docs/editor-workflow.md` documents the command and the recovery steps, + and E07-S04 can be completed with no undocumented command. + +## Coordination notes + +- The pieces exist and are individually proven: `src_load`, `names_init`, + `diag_init`/`diag_finish`, `parse_file` and `sizing`; `output.s` already + implements `out_begin` (refuses an existing `NAME.PRG`/`NAME.MAP`), + `out_startup`, `out_section`, `out_byte`, `out_finish` and `out_abort`. + `tests/parser/parser-test.s` shows the exact compiler initialisation order: + `mmu_init`, `mmu_bank0`, then per file `src_load`, `names_init`, `diag_init`, + `parse_file`, `diag_finish`. +- `scripts/build-parser-test.ps1` links every compiler module against + `cfg/compiler.cfg`, so the driver's link set is that list plus `output.s` and + the runtime startup/print modules. The map has `MAIN` to `$B7FF` + (about 40 KB) and `BANK1` to `$BFFF`; `output.s` keeps its section, class, + method and table records in BSS, so the remaining budget must be measured + after the first link, not assumed. +- `out_begin` derives `NAME.PRG`/`NAME.MAP`/`NAME.ERR` by stripping a trailing + `.N8` from the source name and caps the base at 12 characters, which matches + the 16-character limit VICE's directory allows; the driver must validate the + typed name before calling it. +- `parse_file` only emits when `em_on` is set; the fixture path sets it, so the + driver has to set it for pass 2 and must call `parse_file_base` (not + `parse_file`) when pass-3 absolute addresses are known. That decision is part + of the driver, not the parser. +- Launching the PRG needs the same rule the editor learned in D151: it must be + started from the session disk (`n128c`), not from a host path, so its file + naming and drive device are the ones the session uses. + +## Work log + +- Read `output.s`, the parser initialisation path, `cfg/compiler.cfg` and the + parser fixture's link and startup code to fix the driver's contract and the + module set it must link. +- Confirmed `output.s` already refuses to overwrite and scratches only files it + created, so the story's "leave the previous output intact" criterion is a + matter of aborting on `out_err` rather than adding new file logic. +- No driver source, config, build script or fixture has been written yet, so no + behaviour exists to verify. + +## Completion + +- Tests run: none. The claim records the design and the discovered contracts; + nothing has landed, so it stays `in-progress`. +- Results: not applicable. +- Remaining risks: the whole compiler plus `output.s` plus the runtime print + module may not fit `MAIN`/`BANK1`; if it does not, the driver needs a section + split or `output.s` record limits reduced, which is a decision, not a tweak. + The summary must not use the compiler's own zero page while a compile is in + progress, and a source name longer than 12 base characters has to be rejected + before `out_begin` builds both names. + +## Next steps + +1. Write `src/compiler/driver.s` with the initialisation order above, a + `source:` prompt, name validation, `parse_file`/`parse_file_base`, and the + `out_*` calls; build it with a copy of `cfg/compiler.cfg`. +2. Measure the link (`MAIN`/`BANK1` free bytes) and record the result; adjust or + raise a decision if it does not fit. +3. Add `scripts/build-driver.ps1` producing `build/n128c.prg`, then the + verifier that copies a disk, injects the driver, types a fixture name, and + checks `NAME.PRG`, `NAME.MAP`, `NAME.ERR` and the summary. +4. Update `docs/editor-workflow.md` and unblock E07-S04.