VS Code Extension

Geblang ships a VS Code extension in the vscode-geblang/ directory of the repository. It provides:

• Syntax highlighting for .gb files.
• Live diagnostics - parse and semantic errors appear as you type, via the built-in language server (geblang lsp).
• Completion and signature help for standard-library modules, functions, classes, and common language keywords.
• Step debugging - breakpoints, step over/into/out, call stack, and variable inspection, via the built-in debug adapter (geblang dap).

Building The Extension

You need the geblang binary on your PATH before installing the extension. See Getting Started for build instructions.

Option A - Docker (no Node.js required)

make vscode-build

This builds the extension inside a Docker container and writes the compiled output to:

build/vscode/out/extension.js   compiled extension entry point
build/vscode/vsix/geblang.vsix  installable package (if vsce succeeded)

Install the VSIX from the terminal:

make vscode-install
# equivalent to:
code --install-extension build/vscode/vsix/geblang.vsix

WSL users: do not use the VS Code GUI's Install from VSIX… dialog to install from a WSL path. VS Code on Windows cannot open VSIX files via \\wsl.localhost\ UNC paths and will error with "UNC host 'wsl.localhost' access is not allowed". Always install via make vscode-install, which copies the VSIX to the Windows temp directory before invoking code, so the path translation is handled automatically.

Option B - Local Node.js

cd vscode-geblang
npm install
npm run compile

To also produce a VSIX package:

npx @vscode/vsce package --no-dependencies --out geblang.vsix
code --install-extension geblang.vsix

Option C - Extension Development Host (no install needed)

Open the vscode-geblang/ folder in VS Code, then press F5. VS Code launches a second window with the extension already loaded. This is the fastest path for iterating on the extension itself.

Prerequisite: run npm install && npm run compile first (or make vscode-build to ensure out/extension.js exists).

Requirements

If geblang is installed to a non-standard location, set the path in VS Code settings (see Settings below).

Features

Syntax Highlighting

.gb files are highlighted automatically once the extension is active. Keywords, types, string interpolation, operators, and comments are all distinguished.

Diagnostics

Open any .gb file and errors appear as red underlines immediately. Hover over an underline to read the message. The Problems panel (Ctrl+Shift+M / Cmd+Shift+M) lists all diagnostics across open files.

The language server runs geblang lsp as a subprocess. It re-analyses the file on every change and sends results back to VS Code without touching the file on disk.

Completion And Signature Help

The language server exposes the bundled standard library to VS Code:

• Type import to complete module names such as io, http, db, web, collections, reflect, and websocket.
• Type a module member access such as io. or db. to complete exported functions and classes.
• Type a function call such as http.listen( or db.query( to see the expected parameters and return shape.

Completion metadata is provided by the geblang lsp process, so it works with the same executable configured for diagnostics and debugging.

Step Debugging

Quick start

1. Open a .gb file.
2. Click in the gutter to set a breakpoint (red dot).
3. Press F5 - VS Code picks up the default launch configuration and starts the debug adapter.
4. Execution pauses at the breakpoint. Use the debug toolbar or keyboard shortcuts to step:

The Variables panel shows all local variables at the current scope. The Call Stack panel shows the active call frames.

launch.json

For more control, add a .vscode/launch.json to your workspace:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "geblang",
      "request": "launch",
      "name": "Run current file",
      "program": "${file}",
      "cwd": "${workspaceFolder}",
      "stopOnEntry": false
    },
    {
      "type": "geblang",
      "request": "launch",
      "name": "Run with args",
      "program": "${workspaceFolder}/src/main.gb",
      "cwd": "${workspaceFolder}",
      "args": ["--verbose"],
      "stopOnEntry": true
    }
  ]
}

Known limitations

• The debug adapter runs scripts on the evaluator path. Scripts that require --vm-strict mode may behave differently under the debugger.
• Only the main script file has source-mapped breakpoints. Breakpoints set in imported modules are not yet supported.
• Variable inspection shows the local scope only. Module-level and outer-scope variables are not currently exposed.

These limitations are expected to be lifted in a post-1.0.0 release.

Settings

Open File → Preferences → Settings (or Cmd+, on macOS) and search for geblang.

Example settings.json entry:

{
  "geblang.executablePath": "/usr/local/bin/geblang",
  "geblang.executionMode": "auto"
}

On native Windows, point geblang.executablePath at geblang.exe or leave it as geblang if the executable is on PATH. On Windows with WSL, set the path to a Linux path such as /home/me/bin/geblang and leave geblang.executionMode as auto, or set it explicitly to wsl.

Troubleshooting

"UNC host 'wsl.localhost' access is not allowed" when installing VSIX You are on Windows with WSL and used the GUI's Install from VSIX… dialog to navigate to a file under \\wsl.localhost\. VS Code cannot install VSIXs via UNC paths. Run make vscode-install from your WSL terminal instead - it copies the VSIX to C:\Windows\Temp\ before calling code, so the Windows process gets a native path it can read.

Syntax highlighting not working Confirm the extension is active: open the Extensions panel and check that Geblang is listed and enabled.

No diagnostics appearing Check the Output panel (Ctrl+Shift+U / Cmd+Shift+U), select Geblang Language Server from the dropdown, and look for startup errors. The most common cause is geblang not being found on PATH. Set geblang.executablePath to the full binary path.

Breakpoints not binding Ensure the file is saved before starting a debug session. Breakpoints in unsaved buffers are shown as grey (unverified) and will not pause execution.

Debug session exits immediately The script may have a parse error. Check the Debug Console for the error message, fix it, and re-launch.