---
type: workflow-guide
source: E07-S01 disk builder and E07-S02 launchers
---

# Editor and Compiler Workflow

Nova128 does not link the editor and compiler in memory. A development disk is
edited in one emulator session and compiled in another, strictly in sequence.
`scripts/prepare-disk.ps1` (E07-S01) copies `../vim/work.d81` to a disposable
image without ever writing the source; the launchers below add the two
sessions.

## Sequential rule

Never attach the same disk image writable to two emulators at once, and never
edit an image while a compiler session still has it open. VICE buffers DOS
writes, so a second session can read a half-written directory or overwrite the
first session's changes. The launchers enforce this with a session lock in the
image's folder (`.newlang-session.lock`); the lock holds the owning process and
its kind, and a lock left behind by a dead process is replaced automatically.

## Editor session

```text
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\launch-editor.ps1
```

- Copies `../vim/vim-improved.d81` to `build/newlang-edit.d81` first, so the
  editor never opens the source image, then writes `../vim/vim128.prg` into the
  copy as `vim128`.
- Starts `x128` in 80-column mode and autostarts `vim128` **from the session
  disk**, then attaches that disk as drive 8. Loading the editor from the disk
  is what gives it a write device: a host-loaded copy reports `written` and
  leaves the image unchanged, because it has no device number from the load.
  The 80-column session draws on the VDC, so an automated `-Screenshot` uses
  VICE's plain `-exitscreenshot`; the VIC-II option would capture a blank
  40-column screen.
- Waits for `x128` to exit, then waits until the image can be opened
  exclusively (the image has flushed) before returning.
- Verifies the source image's SHA-256 is unchanged.

Use `-EditorPrg` and `-SourceImage` to select another editor build or disk.
`-Emulator x64sc` selects the C64 build instead, but that program is on
`vim-improved.d81` rather than a standalone PRG, so pass `-EditorPrg` with the
extracted `vim` file. `-LimitCycles` and `-Screenshot` are for automated checks
only; they end the session early.

## Compiler session

```text
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\launch-compiler.ps1
```

- Rebuilds `build/newlang-dev.d81` from the clean source copy with
  `prepare-disk.ps1` (unless `-SkipPrepare` is given), injecting
  `build/n128c.prg`.
- Autostarts that compiler PRG in `x128` with the development image attached.
- Waits for `x128` to exit and for the image to flush before returning.

`-CompilerPrg` selects another compiler PRG. The launcher reports a missing
compiler program, source image, or VICE tool before starting anything.

### Using the compiler on the machine

`n128c` asks for one source name and compiles that file from the session disk:

```text
NOVA128 COMPILER
SOURCE: counter.n8
SOURCE COUNTER.N8
OUTPUT COUNTER.PRG
0 ERRORS
```

Type the name (letters and digits, up to 15 characters) and press RETURN. The
name may be typed in either case; the driver folds it to the disk's uppercase
form. It loads the SEQ file through the buffered PETSCII reader, so no host
conversion is involved, runs the lexer, parser and emitter, and writes
`NAME.PRG` and `NAME.MAP` next to the source. Diagnostics appear between the
prompt and the summary and are also written to `NAME.ERR`.

`-Keys` types into the session after `-KeyDelay` milliseconds (default 3000)
and exists for automated checks:

```text
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\launch-compiler.ps1 `
    -Keys "counter.n8\n" -LimitCycles 200000000 -Warp `
    -Screenshot build\driver-test\summary.png
```

`scripts/verify-driver-test.ps1` builds the driver, makes a fresh D81 with
`counter.n8` and a broken fixture, and checks the summary, `COUNTER.PRG`,
`COUNTER.MAP`, `BAD.ERR`, the refusal of a second compile, and that the
generated `COUNTER.PRG` reaches `MB_ST_PASS` in its own session.

`print` works in generated programs: the image carries a small
position-independent print runtime in a `PRINT` section ahead of `CODE`, so
text, byte and newline output call back into the PRG itself rather than into
the compiler. `hello.n8` prints its string from the built PRG; programs that
only compute, like `tests/compiler/counter.n8`, compile and run as before.

## Recovery

- **Lock reported as still owned**: close the named session's emulator window
  first; if the process is gone, the launcher replaces the stale lock.
- **Image still locked after the emulator exits**: wait for the DOS write to
  finish; the launcher retries for 30 seconds before failing.
- **Source image changed**: stop and inspect `../vim` with `git status`; the
  launchers only ever copy from it.
- **Wrong editor or compiler build**: pass `-EditorPrg`/`-CompilerPrg`
  explicitly rather than editing the defaults.
- **`OUTPUT EXISTS`**: `NAME.PRG` or `NAME.MAP` is already on the disk. Erase
  the old output (`SCRATCH "NAME.PRG"`, or `c1541 ... -delete`) and compile
  again; the driver never overwrites a previous build, so a failed compile
  cannot destroy the last good one.
- **`LOAD FAILED`**: the name is not on the session disk, or the file is not a
  SEQ source. Check the directory spelling and that the editor saved the file
  to the same disk the compiler is reading.
- **`COMPILE FAILED, n ERRORS`**: read `NAME.ERR` (or the screen) and fix the
  source in the editor session. No `NAME.PRG` is written for a failed compile.
- **`NO CODE GENERATED`**: the source parsed but produced no instructions; add
  a statement body rather than an empty `program`.
- **`NAME TOO LONG`**: shorten the source name so the base is at most 12
  characters, because `.PRG` and `.MAP` are appended.

## Limits

Autostart loads the compiler from the host file system, not from the disk; the
disk stays attached for the session's own file access. The compiler's inputs
and outputs are always on the session disk. Generated code is capped by the
256-byte code buffer (D130) and the section limits in `formats.inc`; a program
that exceeds either fails with a diagnostic instead of a partial PRG. Text
`print` needs the generated-program print runtime, so it reports E227 for now.
Physical C128 testing and the full edit/compile/run walkthrough belong to
E07-S04 and E08-S06.