tools/lsp/README.md

The Objeck LSP server brings code intelligence to the Objeck programming language — diagnostics, completion, hover docs, go-to-definition, rename, formatting, and more. It runs on Windows, Linux, and macOS (AMD64 and ARM64).

Quick Start

1. Install Objeck from github.com/objeck/objeck-lang

On Linux, the Objeck runtime dynamically links mbedTLS for crypto/TLS; HTTP/2 and HTTP/3 are linked into it. Install mbedTLS first — the install script checks for it and stops with the same hint if it's missing. macOS and Windows releases need nothing extra:

# Debian / Ubuntu
sudo apt-get install libmbedtls-dev

2. Run the install script from the extracted release directory:

# Windows - user install (no admin required)
scripts\install.cmd C:\Users\you\objeck vscode

# Windows - system-wide install
scripts\install.cmd "C:\Program Files\Objeck" vscode

# Linux / macOS - user install
./scripts/install.sh ~/objeck vscode

# Linux / macOS - system-wide install
./scripts/install.sh /usr/local/objeck vscode

This creates a self-contained deployment at ~/.objeck-lsp/ and configures your editor. Replace vscode with sublime, neovim, emacs, or all. The first argument is wherever you installed Objeck.

3. Or configure manually — pick your editor below, then see the Install Guide for step-by-step instructions. Set environment variables (required for STDIO transport):

export OBJECK_LIB_PATH=<objeck_install_dir>/lib
export OBJECK_STDIO=binary

4. Create a workspace — add a build.json to your project root for multi-file projects:

{
  "files": ["main.obs", "helper.obs"],
  "libs": ["gen_collect.obl", "net.obl", "json.obl"],
  "flags": ""
}

Open the folder in your editor and the LSP server handles the rest.

5. To debug — compile with debug symbols first, or no breakpoint will bind:

obc -src myprog.obs --debug -dest myprog.obe

Then add a launch configuration. In VS Code the extension contributes an objeck debug type, so Run > Add Configuration... writes a launch.json entry for you. In Sublime put a debugger_configurations block in a .sublime-project, or a global_debugger_configurations block in Packages/User/Debugger.sublime-settings to debug without a project at all — see clients/sublime/README.md for both routes and their example files. The .obe is what runs, so recompile after every edit.

Supported Editors

Editor	Transport	Setup
VS Code	STDIO (one server per window)	Install the .vsix extension, set install path in settings
Sublime Text	STDIO	Add config from clients/sublime/ to LSP settings
Kate	STDIO	Add server entry in LSP Client settings (instructions)
ecode	STDIO	Add server to lspclient.json
Neovim (0.11+)	STDIO	Copy objeck.lua + objeck.vim to nvim config
Emacs (29+)	STDIO	Copy objeck-mode.el to your load-path (includes syntax highlighting)
Helix	STDIO	Merge clients/helix/languages.toml into your config

Install scripts (scripts/install.cmd and scripts/install.sh) automate setup for VS Code, Sublime, Neovim, and Emacs. Use scripts/update_lsp to refresh the runtime after rebuilding Objeck.

Features

• Diagnostics — Real-time error and warning reporting
• Code Completion — Variables, methods, and functions with trigger characters (@, ., >)
• Signature Help — Method/function parameter hints
• Hover — Bundle documentation on hover
• Go to Definition / Declaration — Navigate to variables, classes, and methods
• Find References — Locate all usages of a symbol
• Rename — Project-wide variable and method renaming
• Document & Workspace Symbols — Outline and cross-file search
• Code Actions — Quick fixes (add use statements, qualify references)
• Formatting — Document and range formatting
• Multi-root Workspaces — JSON-configured project support via build.json

Debugging Features

The debug adapter (obd --dap) is shared by every editor that speaks DAP.

• Structured variable inspection — objects expand into their instance fields, arrays into indexed elements, and Vector, Map and Hash into their contents. A Map shows key → value in key order rather than an address, and each child expands recursively
• Readable values — strings show their text, boxed scalars (IntRef, FloatRef, …) show their value, and collections show Vector(size=3). These are deliberately terminal: drilling into them would only expose backing storage
• Watch and hover — expressions resolving to an object or collection expand exactly like the Variables pane
• Variable paging — large arrays and collections report indexedVariables and honour start/count, so a client can page instead of pulling everything
• Breakpoint validation — breakpointLocations reports only lines that carry an instruction, so editors stop offering breakpoints that cannot bind
• Data breakpoints — break when a value changes rather than when a line is reached, which is how you find the one write among many that corrupts a field. Right-click a variable and choose "Break on Value Change"; the stop names the watch and reports the old → new transition. Write/change only: the watch compares values after each instruction, so a read that leaves the value alone cannot be seen
• Debug console completion — completions suggests the variables visible in the selected frame
• Also supported — conditional breakpoints, function breakpoints, logpoints, exception breakpoints with exceptionInfo, setVariable/setExpression, restart, terminate, modules and loadedSources

Not supported: stepping backwards, and goto/restartFrame — the last two would need the VM's interpreter loop to expose its program counter, which it currently passes to the debugger by value.

Architecture

graph LR
    subgraph Editors
        VSCode[VS Code]
        Sublime[Sublime Text]
        Kate[Kate]
        ecode[ecode]
        Neovim[Neovim]
        Emacs[Emacs]
        Helix[Helix]
    end

    subgraph Transport
        STDIO[STDIO]
        Pipe[Named Pipe]
        Socket[TCP Socket]
    end

    subgraph Runtime["Objeck Runtime"]
        Workspace[In-Memory Workspace]
        Compiler[Analysis Compiler]
        Detection[Issue Detection]
        Navigation[Code Navigation & Refactoring]
        Docs[API Documentation]

        Workspace --> Compiler
        Compiler --> Detection
        Compiler --> Navigation
        Compiler --> Docs
    end

    VSCode --> STDIO
    Sublime --> STDIO
    Kate --> STDIO
    ecode --> STDIO
    Neovim --> STDIO
    Emacs --> STDIO
    Helix --> STDIO

    STDIO --> Workspace
    Pipe --> Workspace
    Socket --> Workspace

Notifications

Event	Method
Initialized	initialized
Cancel Request	$/cancelRequest
File Open	textDocument/didOpen
File Changed	textDocument/didChange
File Save	textDocument/didSave
File Close	textDocument/didClose
Exit	exit

Requests

Feature	Method
Initialize	initialize
Shutdown	shutdown
Completion	textDocument/completion, completionItem/resolve
Hover	textDocument/hover (MarkupContent)
Signature Help	textDocument/signatureHelp
Definition	textDocument/definition
Declaration	textDocument/declaration
Type Definition	textDocument/typeDefinition
Implementation	textDocument/implementation
References	textDocument/references
Document Highlight	textDocument/documentHighlight
Document Symbol	textDocument/documentSymbol (a tree for clients that take one)
Rename	textDocument/prepareRename, textDocument/rename
Code Action	textDocument/codeAction (quick fixes, source.organizeImports)
Diagnostics (pull)	textDocument/diagnostic, for clients that pull
Code Lens	textDocument/codeLens (Run on Main)
Document Link	textDocument/documentLink (use bundles to the API reference)
Format Document	textDocument/formatting
Format Selection	textDocument/rangeFormatting
Folding Range	textDocument/foldingRange
Selection Range	textDocument/selectionRange
Inlay Hint	textDocument/inlayHint
Semantic Tokens	textDocument/semanticTokens/full, /full/delta, /range
Call Hierarchy	textDocument/prepareCallHierarchy, callHierarchy/incomingCalls, callHierarchy/outgoingCalls
Type Hierarchy	textDocument/prepareTypeHierarchy, typeHierarchy/supertypes, typeHierarchy/subtypes

Server to client

Feature	Method
Diagnostics	textDocument/publishDiagnostics (push clients), workspace/diagnostic/refresh (pull clients)
Log	window/logMessage
Progress	window/workDoneProgress/create, $/progress
Watch build.json	client/registerCapability

Workspace

Feature	Method
Watch File Changes	workspace/didChangeWatchedFiles
Workspace Folder Changes	workspace/didChangeWorkspaceFolders
Find Symbol	workspace/symbol

Development

Building the VS Code extension:

npm install -g yo generator-code typescript @vscode/vsce
cd clients/vscode && npm run compile

Building the LSP server (requires Objeck):

cd server
obc -src frameworks.obs,proxy.obs,server.obs,format_code/scanner.obs,format_code/formatter.obs \
    -lib diags,net,json,regex,cipher -dest objeck_lsp.obe

Testing the server: python tests/run_lsp_tests.py <objeck>/bin [server_dir]. The server keeps each parsed and analyzed program until a document changes; set OBJECK_LSP_NO_CACHE=1 to parse afresh for every request instead, and compare the two when a result looks wrong.

Resources

• Install Guide — detailed setup for all editors
• README.txt — quick-reference setup instructions
• Objeck Language — compiler, runtime, and documentation
• Issues — bug reports and feature requests