# Theia-Modula-2: Short Tutorial

Modula-2 Studio is a GNU Modula-2 IDE built on Eclipse Theia (`modula2-ide/`).

It gives you: `.mod`/`.def` highlighting, snippets, auto-uppercasing, outline / hover / go-to-definition / rename, `gm2` Build-Run, GDB debug, and `modula2.json` projects.

## 1. Prerequisites

```bash
node --version  # >=24
yarn --version  # 1.x Classic
gm2 --version
gdb --version
```

Debian/Ubuntu: `sudo apt install gm2 gdb binutils`

## 2. Build and run

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

## 3. Open an example

1. Open folder `examples/hello/`
2. Look at:
   - `src/Main.mod` — sample program
   - `modula2.json` — project descriptor:

```json
{
  "name": "Hello",
  "compiler": {"type": "gnu-modula-2", "path": "gm2", "options": []},
  "sourceDirectories": ["src"],
  "main": "src/Main.mod"
}
```

## 4. Edit Modula-2

- Create `Foo.mod` / `Foo.def`. Keywords auto-uppercase (`begin` -> `BEGIN`, but `beginning` is left alone).
- Try: hover, `F12` go-to-definition, `Shift+F12` references, `F2` rename, `Ctrl+Shift+O` outline.
- Snippets: `mod`, `proc`, `if`, `defmod`.

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

- `Modula-2: New Modula-2 Project / New Module / New Definition Module`
- `Modula-2: Validate Project`
- `Modula-2: About Modula-2 IDE`

## 5. Build and run

With `modula2.json` open in workspace:

- `F1 > Modula-2: Build` — builds `bin/<name>`
- `Modula-2: Build File / Clean / Rebuild / Run`
- Or terminal: `gm2 -o bin/Hello src/Main.mod && ./bin/Hello`

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

## 6. Debug

1. Build with `Modula-2: Build` (passes `-g` by default, so breakpoints bind).
2. Set breakpoint in gutter.
3. `Run > Start Debugging`, type `modula2`. `program` defaults to `bin/<name>`.

The example `launch.json` sets `"preLaunchTask": "Modula-2: Build"`, so
debugging always builds first. You get: continue/step over/into/out, call
stack, Locals + Module scopes, hover/evaluate.

Right-click any file in the Modula-2 Project view for `New Module Here`,
`Build` and `Refresh` without leaving the explorer.

## 7. Troubleshooting

- Language features missing: check `plugins/modula2-language/` was synced by `yarn build:language`.
- `gm2 not found`: set `"compiler": {"path": "/usr/bin/gm2"}` in `modula2.json`.
- Debug `program not found`: run `Modula-2: Build` first.