# Modula-2 IDE

A starting point for a dedicated GNU Modula-2 IDE built on Eclipse Theia.

## Included

- Browser and Electron Theia applications
- Native Theia `modula2-workbench` extension
- VS Code-compatible `modula2-language` extension
- `.mod` and `.def` support
- TextMate syntax highlighting
- Modula-2 comments, brackets and indentation
- Modula-2 snippets
- Keyword-only automatic uppercasing
- AST-backed document outline, completion, hover, go-to-definition,
  find references and rename
  (lenient declaration parser with cross-file `.def` resolution)
- GNU Modula-2 compiler service: async Build/Build File/Clean/Rebuild/Run
  plus compiler detection, driven by the workspace `modula2.json`
- GDB-backed debugger: breakpoints (+ conditions), continue/step,
  call stack, Locals + Module scopes with structure expansion,
  evaluate/hover (debug type `modula2`, program defaults to `bin/<name>`)
- Project wizards: New Module/Definition Module/Project plus Validate Project,
  with a `modula2.json` JSON schema for editor completions and validation
- Modula-2 Project side view: Sources/Definitions/Project groups, main-file
  marker, click-to-open, live refresh
- Initial Modula-2 commands/menu
- Example/grammar placeholders

## Requirements

The current project targets Eclipse Theia 1.75.0, whose current stable release uses Node.js 24 as its minimum. Use Yarn Classic (1.x).

```bash
node --version
yarn --version
yarn
yarn build
```

Run browser:

```bash
yarn start:browser
```

Run Electron:

```bash
yarn start:electron
```

The language extension is intentionally a VS Code-compatible extension because Theia recommends VS Code extensions for language support. Native Theia extensions are used for product-specific workbench features.

## Release packaging (AppImage + Debian package)

The Electron app packages to a self-contained AppImage and a Debian
package with everything except the compiler toolchain (see host
prerequisites below):

```bash
cd apps/electron
yarn package   # production bundle + plugin staging + dist/*.AppImage, dist/*.deb
```

This runs `bundle:prod` (native rebuild + production esbuild), stages the
`modula2-language` plugin with its runtime dependencies into
`apps/electron/plugins/`, and builds the artifacts via electron-builder.
The packaged launcher (`electron-launcher.js`) points the backend at the
bundled plugins through the `THEIA_PLUGINS` environment variable, so no
`--plugins` flag is needed.

Debian users install with:

```bash
sudo apt install ./modula2-ide-electron_0.15.0_amd64.deb
```

then launch `Modula-2 IDE` from the applications menu (Development
section). The package ships its icon and desktop entry; uninstall with
`sudo apt remove modula2-ide-electron`.

This runs `bundle:prod` (native rebuild + production esbuild), stages the
`modula2-language` plugin with its runtime dependencies into
`apps/electron/plugins/`, and builds
`dist/Modula-2 IDE-<version>.AppImage` via electron-builder. The packaged
launcher (`electron-launcher.js`) points the backend at the bundled
`resources/plugins` through the `THEIA_PLUGINS` environment variable, so no
`--plugins` flag is needed.

Host prerequisites (not bundled): GNU Modula-2 (`gm2`), `gdb` and `readelf`
for build/run/debug. On Debian/Ubuntu the IDE itself needs only FUSE (or
`APPIMAGE_EXTRACT_AND_RUN=1`) to launch the AppImage.

## Standalone language plugin (`modula2-language-0.1.5.zip`)

For editors other than the packaged IDE, the VS Code-compatible language
extension ships as a self-contained zip (compiled server, grammars,
snippets, docs, plus its runtime dependencies — no dev files, no
`gm2`/`gdb` required for editing features):

```bash
unzip modula2-language-0.1.5.zip -d /tmp/m2plugin   # yields modula2-language/
```

- **VS Code / VSCodium**: copy (not the zip itself) into the extensions
  folder and restart:
  ```bash
  cp -r /tmp/m2plugin/modula2-language ~/.vscode/extensions/
  # VSCodium: ~/.vscode-oss/extensions/
  ```
- **Any Theia application**: point it at the *parent* folder:
  ```bash
  THEIA_PLUGINS=local-dir:/tmp/m2plugin <theia-launch-command>
  ```

You get `.mod`/`.def` highlighting, outline, completion, hover,
go-to-definition, references, rename, formatting (document + selection),
semantic highlighting and zero-false-positive diagnostics. Building,
running and debugging Modula-2 programs additionally need `gm2`
(and `gdb` for debugging) on `PATH`; the optional external validator
(`modula2.cocoR.validatorCommand`) stays off unless configured.

## Roadmap

1. Stabilize the GNU Modula-2/Coco/R grammar against `gm2` (see `GNU-grammar`).
2. ~~Add AST, symbols and semantic analysis~~ AST/symbols done (lenient parser); semantic analysis pending.
3. ~~Add LSP~~ LSP live (diagnostics bridge + outline/completion/hover/definition).
4. ~~Add `modula2.json` project support~~ wizards, validation and schema done.
5. ~~Add GNU Modula-2 build/run/diagnostics~~ done via the compiler service.
6. ~~Add debugger integration~~ GDB/MI adapter done (breakpoints, stack, scopes, evaluate).


## Local VS Code language extension

The Modula-2 language extension is a VS Code-compatible extension. The build synchronizes it into `plugins/modula2-language`, and the Browser/Electron applications start Theia with `--plugins=local-dir:../../plugins`. The plugin directory must contain the extension folder; pointing `--plugins` directly at the extension folder does not provide the expected container layout.

## Coco/R language-server bridge (0.1.7)

The language extension now contains a real LSP client/server pair. The server
can invoke a GNU Modula-2 executable generated from a Coco/R grammar and turn
its editor-oriented diagnostics into LSP diagnostics. See
`extensions/modula2-language/COCOR-LSP.md`.