# V3 tutorial — build and run Modula-2

This is a short hands-on tour.  It assumes a Linux shell, `gcc`/`gm2`,
Coco/R `CR`, and `qbe` as described in `README.md`.

## 1. Build the compiler

From the repository root:

```sh
cd compiler
./build.sh          # M2.atg -> scanner/parser/driver -> ./M2
./run_tests.sh      # 303/303
```

`M2` reads Modula-2 sources and writes QBE IR to `gen_ssa/`.

## 2. Hello, world (one-shot)

The one-shot mode compiles every unit named on the command line into one
image.  The program module comes last.

```sh
cd compiler
./M2 tests/hello.mod                 # -> gen_ssa/Hello.ssa
qbe -o gen_ssa/Hello.s gen_ssa/Hello.ssa
cc gen_ssa/Hello.s ../runtime/syslib/shim.c -o /tmp/hello -lm
/tmp/hello
```

Expected output:

```text
Hello, Modula-2!
```

A global `VAR ExitCode : INTEGER` becomes the process exit code; without
one, the program returns 0.

## 3. A library and a program (one-shot)

A definition/implementation pair plus a program can still be compiled in
one invocation:

```sh
./M2 tests/sep_lib.def tests/sep_lib.mod tests/sep_prog.mod
qbe -o gen_ssa/SepProg.s gen_ssa/SepProg.ssa
cc gen_ssa/SepProg.s ../runtime/syslib/shim.c -o /tmp/sep -lm
/tmp/sep
```

This produces one image and is the mode used by the test suite and the
corpus harness.

## 4. Separate compilation

Separate compilation reads only the imported `.def` files when compiling a
unit.  The library object and the program object are linked with `cc`; a
`.def` is never passed to the linker.

### Direct `M2 -c`

From `compiler/`:

```sh
# Library: Lib.def is found beside Lib.mod automatically.
./M2 -c tests/sep_lib.mod

# Program: pass the imported interface explicitly.
./M2 -c tests/sep_lib.def tests/sep_prog.mod

qbe -o gen_ssa/SepLib.s   gen_ssa/SepLib.ssa
qbe -o gen_ssa/SepProg.s  gen_ssa/SepProg.ssa
cc -c gen_ssa/SepLib.s  -o gen_ssa/SepLib.o
cc -c gen_ssa/SepProg.s -o gen_ssa/SepProg.o
cc gen_ssa/SepProg.o gen_ssa/SepLib.o ../runtime/syslib/shim.c \
   -o /tmp/sep -lm
/tmp/sep
```

`M2 -c` requires imported interfaces on the command line.  The target’s own
`.def` is found automatically.

### `M2make --separate`

`M2make` is the convenient transitive-interface resolver.  Build it once:

```sh
cd tools/m2make
./build_m2.sh
cd ../..
```

Then, from the repository root:

```sh
tools/m2make/b_v3/M2make --separate --dialect iso \
    --m2bin ./compiler/M2 \
    --shim runtime/syslib/shim.c \
    -o /tmp/hello compiler/tests/hello.mod
/tmp/hello
```

`M2make` scans imports transitively, passes the ordered `.def` files to each
`M2 -c`, writes `gen_ssa/<Module>.o`, and links.  The one-shot default is
still:

```sh
M2make -o /tmp/sep compiler/tests/sep_prog.mod
```

### What the object model guarantees

- Library objects have **no `main`**.
- The program object has the only `main`.
- Every object exports `<Module>_init`; the program calls imported inits in
  dependency order, then its own init.
- Exported globals are `export data`; module procedures use
  `<Module>__<name>`; vtables use `<Module>__<Class>__vt`.

## 5. Dialect library folders

Libraries are split by dialect:

```text
lib/pim/     classic PIM modules (InOut, RealInOut, …)
lib/iso/     ISO 10514-1 modules (TextIO, IOChan, Files, …)
lib/common/  shared Strings, Math, Storage, SysIO, CharClass
lib/gm2/     optional gm2 compatibility modules
runtime/syslib/  shared runtime/shim
```

Select one dialect per session:

```sh
M2make --dialect iso ... main.mod
```

or add the folders explicitly with `-I lib/iso -I lib/common -I
runtime/syslib`.  Do not mix `lib/pim` and `lib/iso` in one session.

## 6. Useful checks

```sh
cd compiler && ./run_tests.sh
cd .. && TMP="$PWD/.scratch/fixpoint" ./bootstrap/fixpoint.sh
tools/v3-corpus/corpus.sh
```

Current gates: suite **303/303**, fixpoint **OK (3,717,887 bytes)**,
corpus **519/612 compile-OK, 0 crashes**.

## 7. Current limits

- `M2 -c` does not scan `-I` paths itself; use `M2make --separate`.
- `M2make --separate` rebuilds all objects; there is no incremental object
  or ABI-version cache.
- Generic instance objects are not emitted separately yet.
- The fixpoint gate still compares the one-shot compiler image.

For details, see `docs/separate-compilation.md` and
`docs/plan-separate-compilation.md`.