|
|
@@ -0,0 +1,248 @@
|
|
|
+# TP3-comp tutorial
|
|
|
+
|
|
|
+This is a hands-on path from a clean checkout to a running shell, a compiled
|
|
|
+Pascal program, and the test suite. It assumes the repository root is
|
|
|
+`TP3-comp/`.
|
|
|
+
|
|
|
+The short version:
|
|
|
+
|
|
|
+```sh
|
|
|
+cd TP3-comp/shell
|
|
|
+make
|
|
|
+./tpshell
|
|
|
+```
|
|
|
+
|
|
|
+Then press `W` to name a work file, `E` to edit it, `C` to compile, and `R`
|
|
|
+to run it. The rest of this page explains each step and the command-line
|
|
|
+alternatives.
|
|
|
+
|
|
|
+## 1. What you need
|
|
|
+
|
|
|
+- GNU Modula-2 (`gm2`, tested with 16.0.1)
|
|
|
+- a C compiler for the `DEFINITION MODULE FOR "C"` bridge
|
|
|
+- `qemu-system-i386` for the execution tests
|
|
|
+- `make`
|
|
|
+- a real ANSI terminal for the interactive shell
|
|
|
+
|
|
|
+The build itself only needs `gm2`, `cc` and `make`. qemu is needed by
|
|
|
+`tests/run_all.sh`, `tests/run_com_exec.py`, `tests/run_exec86.py` and
|
|
|
+`tests/calc_cli.py`.
|
|
|
+
|
|
|
+## 2. Build the shell
|
|
|
+
|
|
|
+From the repository root:
|
|
|
+
|
|
|
+```sh
|
|
|
+cd shell
|
|
|
+make
|
|
|
+```
|
|
|
+
|
|
|
+This builds `tpshell` (and `tp3cfg`, the terminal configurator). The
|
|
|
+authoritative recipe is `shell/Makefile`; it uses GNU Modula-2's two-phase
|
|
|
+link because a single whole-program `gm2 -o` pass trips the compiler's
|
|
|
+pass-3 limit on a compiler-sized program.
|
|
|
+
|
|
|
+A clean build should end with `tpshell` and no real compile errors. The one
|
|
|
+line that mentions `ParseExpr: too many errors in pass 3` is the expected
|
|
|
+phase-1 generation rollup and is tolerated by the recipe.
|
|
|
+
|
|
|
+## 3. Start the shell
|
|
|
+
|
|
|
+```sh
|
|
|
+./tpshell
|
|
|
+```
|
|
|
+
|
|
|
+The shell uses raw terminal mode and draws the TP3.0 main menu:
|
|
|
+
|
|
|
+- `L` — logged drive / directory
|
|
|
+- `A` — active directory
|
|
|
+- `W` — work file
|
|
|
+- `M` — main file
|
|
|
+- `E` — edit
|
|
|
+- `C` — compile
|
|
|
+- `R` — run
|
|
|
+- `S` — save
|
|
|
+- `D` — directory listing
|
|
|
+- `O` — options
|
|
|
+- `Q` — quit
|
|
|
+
|
|
|
+`R` runs the linked image in the in-process Exec86 interpreter. It is no
|
|
|
+longer a stub.
|
|
|
+
|
|
|
+## 4. Your first program
|
|
|
+
|
|
|
+Inside `tpshell`:
|
|
|
+
|
|
|
+1. Press `W` and enter `hello` (or `hello.pas`). The shell adds `.PAS` when
|
|
|
+ needed.
|
|
|
+2. Press `E` to open the editor.
|
|
|
+3. Enter:
|
|
|
+
|
|
|
+ ```pascal
|
|
|
+ program hello;
|
|
|
+ begin
|
|
|
+ writeln('Hello from TP3-comp')
|
|
|
+ end.
|
|
|
+ ```
|
|
|
+
|
|
|
+4. Press `^K-D` to return to the shell.
|
|
|
+5. Press `S` to save. The previous version, if any, becomes `.BAK`.
|
|
|
+6. Press `C` to compile.
|
|
|
+7. Press `R` to run the image.
|
|
|
+
|
|
|
+If compilation fails, the shell reports the TP3-style error number and jumps
|
|
|
+the editor to the error position. The menu's status line shows the current
|
|
|
+work file and free space.
|
|
|
+
|
|
|
+### Editor essentials
|
|
|
+
|
|
|
+- `^K-D` — leave the editor and return to the shell (then `S` saves)
|
|
|
+- `^S` / `^D` / `^E` / `^X` — move by character or line
|
|
|
+- `^Q-F` — search
|
|
|
+- `^Q-A` — replace
|
|
|
+- `^K-B` / `^K-K` — mark a block
|
|
|
+- `^K-C` / `^K-V` / `^K-Y` — copy / move / delete block
|
|
|
+
|
|
|
+The complete key list is in `README.md` and `TP3-EDITOR.md`.
|
|
|
+
|
|
|
+## 5. Compile without the interactive shell
|
|
|
+
|
|
|
+The fast compiler loop is `tests/CompileTest.mod`, built as `compiletest`.
|
|
|
+Build it once, then feed it paths (one per line):
|
|
|
+
|
|
|
+```sh
|
|
|
+cd shell
|
|
|
+tests/run_compile_tests.sh --build-only
|
|
|
+
|
|
|
+printf '%s\n' tests/fixtures/t01_minimal.pas | ./compiletest
|
|
|
+```
|
|
|
+
|
|
|
+You should see a line like:
|
|
|
+
|
|
|
+```text
|
|
|
+tests/fixtures/t01_minimal.pas OK code=34 data=5
|
|
|
+```
|
|
|
+
|
|
|
+`compiletest` loads the file exactly as the shell does (LF to CR, `^Z` ends
|
|
|
+the text), calls `Compiler.Compile`, and prints the error position and a
|
|
|
+caret on failure. It is much faster than driving the editor.
|
|
|
+
|
|
|
+To compile the whole fixture matrix:
|
|
|
+
|
|
|
+```sh
|
|
|
+tests/run_compile_tests.sh
|
|
|
+```
|
|
|
+
|
|
|
+The expected verdicts are in `tests/fixtures/expected.tsv`, including error
|
|
|
+numbers and positions.
|
|
|
+
|
|
|
+## 6. Run a compiled image
|
|
|
+
|
|
|
+The normal test path builds a floppy image, boots the `.COM` under
|
|
|
+`qemu-system-i386`, captures the serial output, and compares it byte for byte
|
|
|
+with a fixture `.out` file:
|
|
|
+
|
|
|
+```sh
|
|
|
+cd shell
|
|
|
+python3 tests/run_com_exec.py t01_minimal
|
|
|
+```
|
|
|
+
|
|
|
+Every executed fixture is also checked by the independent Exec86 interpreter:
|
|
|
+
|
|
|
+```sh
|
|
|
+python3 tests/run_exec86.py t01_minimal
|
|
|
+```
|
|
|
+
|
|
|
+For a larger, interactive example, build and boot CALC:
|
|
|
+
|
|
|
+```sh
|
|
|
+python3 tests/calc_cli.py
|
|
|
+python3 tests/calc_smoke.py
|
|
|
+```
|
|
|
+
|
|
|
+CALC needs its `CALC.INC` include file; `calc_cli.py` stages the source in a
|
|
|
+temporary directory for you. See `FREEDOS-CALC.md` for a manual FreeDOS/qemu
|
|
|
+setup.
|
|
|
+
|
|
|
+## 7. Run the whole check suite
|
|
|
+
|
|
|
+```sh
|
|
|
+cd shell
|
|
|
+bash tests/run_all.sh
|
|
|
+```
|
|
|
+
|
|
|
+This runs the compiler matrix, the shell/editor UI tests, frame and encoding
|
|
|
+checks, runtime entry tests, the `.COM` linker checks, the corpus census,
|
|
|
+CALC, and the execution harnesses.
|
|
|
+
|
|
|
+Then run the mutation suite:
|
|
|
+
|
|
|
+```sh
|
|
|
+bash tests/nonvacuity.sh
|
|
|
+```
|
|
|
+
|
|
|
+It deliberately breaks a check's subject and requires the check to go red.
|
|
|
+A green `nonvacuity.sh` is what proves that the other checks are not merely
|
|
|
+passing by accident.
|
|
|
+
|
|
|
+Current expected totals are kept in `SUMMARY.md`; do not copy them into every
|
|
|
+document, because they expire. At the `v-TP3-EXPR-IO` checkpoint they were:
|
|
|
+
|
|
|
+- compile matrix: **154/154**
|
|
|
+- non-vacuity: **121 ok, 0 failed**
|
|
|
+- corpus: **71/71**
|
|
|
+- runtime: **10,975 bytes / 82 entries**
|
|
|
+- CALC: **38,497-byte `.COM`**
|
|
|
+
|
|
|
+## 8. Where the compiler lives
|
|
|
+
|
|
|
+The compiler used to be one large `Compiler.mod`. It is now split into:
|
|
|
+
|
|
|
+| Module | Responsibility |
|
|
|
+|---|---|
|
|
|
+| `CompilerShared.def` | compiler-wide constants, state and types |
|
|
|
+| `CompilerUtil.def/.mod` | pure character, word, bit and string helpers |
|
|
|
+| `CompilerSource.def/.mod` | source cursor and `{$I}` include expansion |
|
|
|
+| `CompilerSymbols.def/.mod` | symbol table and scope lookup |
|
|
|
+| `CompilerLex.def/.mod` | keyword table, scanning, constants, string pool |
|
|
|
+| `CompilerExpr.def/.mod` | expression parser and value construction |
|
|
|
+| `CompilerIO.def/.mod` | standard-procedure dispatch |
|
|
|
+| `CompilerEmit.def/.mod` | primitive 8086 emitters and patch machinery |
|
|
|
+| `Compiler.def/.mod` | public API plus statements, declarations and driver |
|
|
|
+
|
|
|
+`Compiler.def` currently exposes a deliberately broad internal interface so
|
|
|
+the mutually recursive parser modules can call each other. Finishing the
|
|
|
+modularization means shrinking that interface and extracting the statement
|
|
|
+and declaration groups.
|
|
|
+
|
|
|
+## 9. Common problems
|
|
|
+
|
|
|
+**`./tpshell` draws nothing or behaves strangely.** It needs a real ANSI
|
|
|
+terminal in raw mode. Run it directly in a terminal, not through a wrapper
|
|
|
+that strips escape sequences.
|
|
|
+
|
|
|
+**`make` reports `too many errors in pass 3`.** This is expected for the
|
|
|
+phase-1 module-list generation. The actual link is the following
|
|
|
+`-fuse-list` command in `shell/Makefile`.
|
|
|
+
|
|
|
+**`compiletest` is missing.** It is a test harness, not part of `make`.
|
|
|
+Run `tests/run_compile_tests.sh --build-only`.
|
|
|
+
|
|
|
+**Execution tests cannot find qemu.** Install `qemu-system-i386`; the tests
|
|
|
+invoke it by path and will report the missing binary.
|
|
|
+
|
|
|
+**A `.COM` test says “comtest wrote no .COM”.** Build the harness first with
|
|
|
+`tests/run_com_tests.sh`, or let `run_all.sh` build it.
|
|
|
+
|
|
|
+## 10. What to work on next
|
|
|
+
|
|
|
+The corpus target is met. The remaining work is TP3 conformance and proof:
|
|
|
+
|
|
|
+1. `v-TP3-DIRECTIVES` — conformance matrix, `$K`/`$V`, unsupported directives
|
|
|
+2. `v-TP3-DOSFILES` — file I/O under a real DOS filesystem
|
|
|
+3. `v-TP3-CALCHELP` — full CALC Help and heap path
|
|
|
+4. `v-TP3-ARGS` — raise or document the 16-argument limit
|
|
|
+5. `v-TP3-CORE` — finish the statement/declaration split
|
|
|
+
|
|
|
+`SUMMARY.md` is the authoritative status document and carries the detailed
|
|
|
+roadmap.
|
