# Theia Modula-2/Pascal/Oberon: Short Tutorial

This is a Modula-2, Pascal and Oberon IDE built on Eclipse Theia (`modula2-ide/`).
All three languages get the same depth: syntax highlighting, snippets,
auto-uppercasing, outline / hover / go-to-definition / references / rename,
formatting, Build-Run tasks, GDB debug, and project wizards.

| Language | Files | Validators | Compiler | Debug type | Project file |
|---|---|---|---|---|---|
| Modula-2 | `.mod`/`.def` | Coco/R `gm2` grammar | `gm2` | `modula2` | `modula2.json` |
| Pascal | `.pas`/`.pp`/`.p` | 8 Coco/R dialects | `fpc`, Blaise | `pascal` | `pascal.json` |
| Oberon | `.Mod`/`.mod`/`.om` (`.def`/`.od`) | O07, Oberon-2, Ulm | `voc`, `ulmo` | `oberon` | `oberon.json` |

## 1. Prerequisites

```bash
node --version  # >=24
yarn --version  # 1.x Classic
gm2 --version
fpc -iV
voc         # prints its banner; ulmo likewise
gdb --version
```

Debian/Ubuntu: `sudo apt install gm2 gdb binutils fp-compiler`.
`voc`/`ulmo` come from their own distributions. Editing features
(hover, outline, rename, formatting) work without any compiler.

## 2. Build and run

```bash
cd modula2-ide
yarn
yarn build
yarn start:browser   # http://localhost:3000
# or
yarn start:electron
```

Standalone editor plugins (VS Code-compatible) ship as versioned zips:
`modula2-language-*.zip`, `pascal-language-*.zip`,
`oberon-language-*.zip`.

## 3. Open an example

| Example | Project file | Main file |
|---|---|---|
| `examples/hello/` | `modula2.json` | `src/Main.mod` |
| `examples/hello-pascal/` | `pascal.json` | `src/Main.pas` |
| `examples/hello-oberon/` | `oberon.json` | `src/Main.Mod` |

`pascal.json`:

```json
{
  "name": "Hello",
  "compiler": {"type": "fpc", "path": "fpc", "options": []},
  "sourceDirectories": ["src"],
  "main": "src/Main.pas"
}
```

`oberon.json` has the same shape with `"type": "voc"` (or `"ulm"`)
and `"main": "src/Main.Mod"`.

## 4. Edit

- Keywords auto-uppercase (`begin` -> `BEGIN`, but `beginning` is left
  alone). Oberon matching stays case-sensitive; Pascal is
  case-insensitive.
- Try: hover, `F12` go-to-definition, `Shift+F12` references, `F2`
  rename, `Ctrl+Shift+O` outline, `Shift+Alt+F` format.
- Cross-file jumps work through `USES` (Pascal), `IMPORT` (Oberon,
  alias-aware) and `IMPORT`/`FROM` (Modula-2 `.def` files).
- Snippets: Modula-2 `mod`/`proc`/`if`/`defmod`, Pascal
  `program`/`unit`/`proc`/`func`, Oberon `module`/`proc`/`func`.

Commands (via `F1` / Ctrl+Shift+P):

- `Pascal: New Pascal Project / New Unit`, `Oberon: New Oberon Project / New Module`,
  `Modula-2: New Modula-2 Project / New Module / New Definition Module`
- `Pascal` / `Oberon` / `Modula-2: Validate Project`, `About`, theme commands

Each language has its own Project explorer view (right-click for
`New Unit/Module Here`, `Build`, `Refresh`).

## 5. Build and run

With the project folder open in the workspace:

- `F1 > Pascal: Build` — builds `bin/<name>` (`fpc -M<dialect>`,
  dialect from `modula2.pascal.dialect`, default Free Pascal)
- `Oberon: Build` — runs `voc` (or `ulmo`) frontend check on the main module
- `Modula-2: Build` — `gm2 -fiso -g`
- Each also offers Build File / Clean / Rebuild / Run, or use the terminal:
  `fpc -o bin/Hello src/Main.pas`, `voc src/Main.Mod`,
  `gm2 -o bin/Hello src/Main.mod`

Build errors appear in Problems panel, click to jump to source.

## 6. Debug

1. Build first (passes debug info: `-g`/`-gl`).
2. Set breakpoint in gutter.
3. `Run > Start Debugging`, type `pascal`, `oberon` or `modula2`.
   `program` defaults to `bin/<name>`.

The example `launch.json` files set `"preLaunchTask": "<Lang>: Build"`,
so debugging always builds first. You get: continue/step over/into/out,
call stack, Locals + Module scopes, hover/evaluate.

## 7. Troubleshooting

- Language features missing: check `plugins/<lang>-language/` was synced
  by `yarn build:language`.
- No validator diagnostics: set `modula2.pascal.validators` /
  `modula2.oberon.validators` to the pilot binaries built by each
  `grammars/*/build.sh`. Unconfigured dialects stay silent by design.
- `fpc`/`voc` not found: set `"compiler": {"path": ...}` in
  `pascal.json` / `oberon.json` (or the `*.compiler.path` preference).
- Debug `program not found`: run `<Lang>: Build` first.