OxL for Visual Studio Code

Language support for OxL (docs/spec/oxl-standard.md): syntax highlighting, and, through the language server oxl lsp, diagnostics (with links to the diagnostic pages), hover, go to definition / type definition, find references, rename (across the packages of a workspace and through rpc), document outline, workspace symbols, completion, signature help, semantic highlighting (contextual keywords included), inlay hints (inferred types, chain errors, effects, where a pipeline step runs, call markers "in process" / "over network → role" / "scatter-gather"), the rpc hover (callers, policies, schema version, attributes with their final values), quick fixes and refactorings (handle all errors of a chain, extract constant, add a policy, generate a mock, move a pipeline step to another role) and formatting (document, selection, on type).

The extension is a thin client. Everything semantic is done by the compiler's own front end, so what the editor shows is what oxl check reports. See docs/lsp.md in the repository for the protocol surface.

Requirements#

• An oxl executable (build it with CMake, see the top-level docs/HANDOFF.md). It is found in PATH, or set the oxl.path setting to its absolute path (${workspaceFolder} and ~ are expanded).

Settings#

The inlay hint settings take effect without a restart. The extension turns semantic highlighting and editor.formatOnSave on for OxL files (the formatter is canonical, oxl fmt gives the same result); editor.formatOnType additionally reformats an item when } is typed.

Commands: OxL: Restart Language Server, OxL: Show Language Server Log.

Packages and single files#

A file below the src/ directory of a directory with an oxl.toml is analysed together with its package (all modules, unsaved buffers of the other open files included). Any other .oxl file is analysed on its own. Standard library symbols resolve exactly as in the compiler.

Building and packaging#

cd tools/vscode
npm install          # downloads vscode-languageclient and the build tools into node_modules (not committed)
npm run compile      # TypeScript -> out/extension.js
npm test             # compile + manifest/grammar checks + TextMate tokenization tests (no VS Code needed)
npx vsce package --allow-missing-repository --skip-license    # produces oxl-lang-0.1.0.vsix
code --install-extension oxl-lang-0.1.0.vsix

To try the extension without packaging, open tools/vscode in VS Code and press F5 (Extension Development Host), then set oxl.path to build/tools/oxl/oxl in the new window.

If vsce cannot be installed (no network), the extension can still be used from source: copy or symlink this directory to ~/.vscode/extensions/oxwaldlink.oxl-lang-0.1.0 after npm install --omit=dev && npm run compile.

Verifying in a live VS Code (manual checklist)#

Automated checks (npm test, npm run smoke) cover the manifest, the grammar, the compiled entry point, the contents of the .vsix, activate() against a stub of the vscode API and the real oxl lsp --stdio handshake. They cannot show the editor itself, so do this once per release in a real VS Code >= 1.75 (the machine needs a built oxl, see docs/HANDOFF.md):

1. Build and install the package: sh cd tools/vscode npm ci || npm install npm test && npm run smoke npx vsce package --allow-missing-repository --skip-license # -> oxl-lang-0.1.0.vsix code --install-extension oxl-lang-0.1.0.vsix --force (npm run package does the last vsce step; the smoke test builds a throw-away .vsix itself when no path is given.)
2. Open the repository's examples/shop folder (code examples/shop). In Settings (Ctrl+,) set OxL: Path to the absolute path of build/tools/oxl/oxl (or put it in PATH). Reload the window.
3. Open examples/shop/src/cart/cart.oxl (any .oxl file). Expect, within a second: the status bar shows the language OxL; keywords, durations (30s), string interpolation and attributes are coloured; View > Output > OxL Language Server shows the server starting and no error.
4. Diagnostics: type let x: i32 = "a" inside a function. A red squiggle appears with the code (for example type-mismatch) as a link to its page under docs/diagnostics; the Problems panel lists it. Undo: it disappears.
5. Hover a function call (signature and doc comment), F12 on a call (jumps to the declaration, also into std/), Shift+F12 (references), F2 (rename across the package), Ctrl+Space after a . (members), Ctrl+Shift+Space inside a call (signature help), Ctrl+Shift+O (outline lists the declarations).
6. Formatting: mis-indent a block and save. The file is reformatted (format on save is on for OxL); Shift+Alt+F does the same. build/tools/oxl/oxl fmt --check examples must agree with what the editor produced.
7. Commands (Ctrl+Shift+P): OxL: Restart Language Server (the Output panel shows the restart, diagnostics return) and OxL: Show Language Server Log. Set OxL: Path to a wrong path and reload: a message The OxL executable ... does not exist with an Open Settings button appears, and nothing crashes.
8. Debugging (needs lldb-dap-18): open examples/v1_hello.oxl (or any single file with fn main()), put a breakpoint, press F5 and pick OxL. The program is built with debug info, stops at the breakpoint, and Variables shows str, List and Map values through the pretty-printers. (Known gaps: no parked-task stacks, see docs/debugger.md.)
9. Uninstall: code --uninstall-extension oxwaldlink.oxl-lang.

Record the VS Code version and the result of each step in the release notes. If a step fails, Output > OxL Language Server with OxL > Trace: Server set to verbose has the protocol traffic.

Files#

Source: tools/vscode/README.md