Getting Started

Prerequisites

Geblang is built from source. Choose a build path before you start:

You only need one of these, not both. The Go path gives the fastest build and development loop. The Docker path avoids installing Go on the host.

To build and install the VS Code extension you also need one of:

The Docker extension path requires no Node.js. If you already chose the Docker build path for Geblang itself, no additional tools are needed.

Getting The Source

git clone https://github.com/geblang/geblang.git
cd geblang

Building The Binary

With Go:

make build

This produces a geblang binary in the current directory.

With Docker:

make docker-build

This writes the binary and bundled stdlib to:

build/geblang
build/stdlib/

Use the Docker path when you do not want to install Go locally.

Adding Geblang To Your PATH

The geblang binary must be on your PATH for the VS Code extension, the REPL, and all other tooling to work.

Linux and macOS:

sudo cp geblang /usr/local/bin/

Or, without sudo, into a user-local directory:

mkdir -p ~/.local/bin
cp geblang ~/.local/bin/
# Add to your shell profile if ~/.local/bin is not already on PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc

Verify:

geblang --version

WSL (Windows Subsystem for Linux):

The same Linux instructions apply. Run them inside your WSL terminal. /usr/local/bin/geblang is a Linux path - VS Code's Remote WSL extension will call it from Linux automatically.

Windows (native):

With Go installed, build from PowerShell or Command Prompt:

go build -o geblang.exe ./cmd/geblang

Copy geblang.exe to a directory on your PATH (for example, a bin\ folder under your user profile that you have already added to %PATH%).

Alternatively, go install places the binary directly in %GOPATH%\bin:

go install ./cmd/geblang

If %GOPATH%\bin is on your PATH this is the simplest option on Windows.

VS Code IDE Setup

The VS Code extension lives in vscode-geblang/ inside the repository. It must be built and installed from source. It provides syntax highlighting, live error diagnostics, completion, and step debugging for .gb files.

Step 1 - Build the extension

Option A: Docker (no Node.js needed)

make vscode-build

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

build/vscode/out/extension.js   compiled extension
build/vscode/vsix/geblang.vsix  installable package

Option B: Local Node.js

cd vscode-geblang
npm install
npm run compile
npx @vscode/vsce package --no-dependencies --out geblang.vsix
cd ..

The geblang.vsix file is produced inside vscode-geblang/.

Step 2 - Install the extension

Linux and macOS:

make vscode-install

Or equivalently:

code --install-extension build/vscode/vsix/geblang.vsix

WSL:

Always install via make vscode-install from the WSL terminal:

make vscode-install

This copies the VSIX to C:\Windows\Temp\ and passes that path to code, avoiding the "UNC host 'wsl.localhost' access is not allowed" error that occurs when VS Code tries to open a VSIX from a \\wsl.localhost\ path directly. Never use the VS Code GUI's Extensions → Install from VSIX… dialog to navigate to a file inside WSL - use the command above instead.

Windows (native):

From PowerShell or Command Prompt, after building with Option B above:

code --install-extension vscode-geblang\geblang.vsix

Or use the VS Code GUI: open the Extensions panel, click the ... menu, choose Install from VSIX…, and browse to the file.

Step 3 - Configure VS Code

Open VS Code Settings (Ctrl+, / Cmd+,) and search for geblang.

WSL-specific: leave geblang.executablePath as a Linux path such as /usr/local/bin/geblang. The extension knows to call it through wsl.exe when needed. Do not point it at a Windows path.

Example settings.json snippet:

{
  "geblang.executablePath": "/usr/local/bin/geblang"
}

Step 4 - Verify the setup

1. Open a .gb file. The syntax should be highlighted immediately.
2. Introduce a deliberate error (delete a semicolon, reference an unknown identifier). A red underline should appear within a second or two.
3. Fix the error. Press F5 to start a debug session. Set a breakpoint and confirm execution pauses there.

If diagnostics are not appearing, open the Output panel (Ctrl+Shift+U / Cmd+Shift+U), select Geblang Language Server from the dropdown, and check for startup errors. The most common cause is geblang not being found - set geblang.executablePath to the full path.

Debugging features

Once the extension is active:

• Breakpoints: click in the editor gutter to set them, press F5 to start debugging.
• Variable inspection: the Variables panel shows local values when paused.
• Expression evaluation: open the Debug Console (Ctrl+Shift+Y) and type any Geblang expression while paused at a breakpoint. Hover over a variable in the editor to see its value inline.
• Watch expressions: add expressions in the Watch panel to re-evaluate them at each pause.

Running Scripts

geblang script.gb
geblang --disable-vm script.gb
geblang --vm-strict script.gb
geblang --trace-exec script.gb

By default Geblang compiles to bytecode and runs on the VM. --trace-exec prints which execution path was used:

geblang --trace-exec examples/core.gb

Run an executable module with -m. The module is resolved like any import and its exported main(args) function receives the remaining arguments:

geblang -m http.server 8080

REPL

geblang
geblang repl

The REPL supports declarations, imports, multi-line input, history, and completion. REPL commands:

:help       show available commands
:quit       exit
:reset      clear all bindings and imports
:load file  execute a .gb file into the session
:vars       list current bindings
:imports    list imported modules
:stdlib     list all standard-library modules
:mode       show current execution mode
:history    show command history

Expression results print automatically. Imported module names are constants for the session lifetime; use :reset to start fresh.

Checking Code

geblang check script.gb
geblang check src/
geblang check --json src/
geblang check --no-lint src/
geblang check --strict src/

check parses, semantically analyses, and lints without executing. It validates imports using the same path rules used at runtime. Lint warnings (unused imports, unreachable statements) are reported but do not fail the command unless --strict is used.

Static-analysis errors are also enforced by geblang run: a script that fails check because of a no-matching-overload call, a type mismatch, or any other hard error aborts before the first statement runs instead of executing partway through and crashing. Warnings print to stderr but do not block execution. check remains the place to discover all findings up front (CI / pre-commit hook).

Generate API documentation from docblocks:

geblang doc src/
geblang doc --format json src/
geblang doc --out build/api.md src/

Testing

geblang test examples/sample_test.gb
geblang test --tag fast examples

Test discovery scans for _test.gb files when the path is a directory.

import test;

class SampleTest extends test.Test {
    @test
    func addition(): void {
        this.assertEquals(4, 2 + 2);
    }
}

Cache And Diagnostics

Bytecode cache files are written under .geblang-cache/.

geblang cache stats
geblang cache clean
geblang doctor

doctor reports version, working directory, Go toolchain lookup, package manifest discovery, and cache status. Run it first when diagnosing an environment problem.