Editor support
Axle ships a language server (axle-lsp) and an official VS Code
extension. Any editor that speaks the Language Server Protocol can drive axle-lsp directly; VS Code is the one with the polished client.
This page covers:
- installing the extension and reading the status-bar badge;
- what each language feature does;
- the settings, the colour overrides, the tasks, and the snippets;
- the rough edges worth knowing before you file a bug.
VS Code
Install
- Install the
axlecompiler — see Install the compiler. Theaxle-lspbinary ships in the same package, next toaxle. - Install the extension from the VS Code Marketplace (search for
“Axle”) or sideload a
.vsixbuilt from source.
Once both pieces are in place, opening any .axle file activates
the extension automatically. The status bar in the bottom-left
shows the server state:
| Badge | Meaning |
|---|---|
$(loading~spin) Axle | The language server is starting. |
$(check) Axle | Running — hover the badge for the version; click it for the log. |
$(warning) Axle | The server is older than the extension — rebuild or reinstall it. |
$(error) Axle | Stopped or crashed — click to restart. |
$(question) Axle | The client has not learned the server’s state yet. |
What you get
| Feature | What it does |
|---|---|
| Semantic highlighting | Per-identifier colouring driven by the language server. In Random::seed(42) it colours the Random namespace and the seed method, never the parens or the argument. Classes, traits, enums, enum members and namespaces each get their own scope so the theme can colour them distinctly. |
| Contextual completion | After . you only see fields and methods of the receiver type. After :: you see enum variants or module exports. After use std:: you walk the stdlib path tree. In a type position (let x :, fn f(x :) you only see types — never statement keywords like if or let. |
| Hover | The expression’s type plus a kind classification, the symbol’s doc-comment (yours or the stdlib’s), and — on locals and parameters — a memory-behaviour summary: which storage tier the compiler chose, the ownership contract, whether the binding is reassigned. |
| Goto definition | Lands on the declaration head — class Foo, fn bar, the original let x = … for a local, the Variant in an enum declaration — across project files. Go to Type Definition and Go to Implementations (trait → implementing classes) work too. |
| Find references | Locals, parameters, free functions, methods, fields, and types — across project files. |
| Rename | The same set: locals, parameters, functions, methods, fields, and types (class / struct / trait / enum), project-wide — the edit touches every file that references the symbol. |
| Document highlight | The other occurrences of the symbol under the cursor, in the current file. |
| Document outline | Tree of every class, struct, trait, enum, and free function in the current file — navigable through Outline: view and Ctrl+Shift+O. |
| Workspace symbols | Substring search via Ctrl+T — covers the whole project once any of its files is open. |
| Call hierarchy | Incoming and outgoing calls around the function under the cursor. |
| Type hierarchy | Super- and subtypes of a class or trait. |
| Code lens | An “N references” lens above each function and an “N implementors” lens above each class or trait, computed lazily as the lens scrolls into view. Clicking one lists the locations. Toggle with axle.codeLens.enable or the Axle: Toggle Code Lens command. |
| Document links | Clickable paths in use lines and import strings. |
| Formatting | Whole-document formatting through the same axle fmt the CLI runs — Shift+Alt+F. |
| Inline diagnostics | Lexing, parsing, and semantic errors with hint lines. Each error keeps its catalogue code (E0014, E0511, …) so you can cross-reference Reading compiler errors. |
| Editor lints | Unused variables and parameters are greyed out (tagged unnecessary). A let mut binding that is never written gets a hint (not greyed out) with a “Drop the mut” fix. Each unused name also has a one-click fix. |
| Signature help | The current call’s parameter list as you type, with the active parameter highlighted. |
| Code actions | Quick-fix lightbulbs. Replace with … offers a near match for an undefined name (E0002). Import … adds the use line for a stdlib type. Drop the mut removes an unneeded mut. Remove unused … and Prefix with _ deal with an unused name. |
| Folding & smart select | Fold functions, types and blocks; Shift+Alt+→ expands the selection through enclosing expressions. |
| Inlay hints | Inferred types beside let bindings without an explicit type annotation and beside lambda parameters whose type is inferred, and parameter names at call sites. Toggle them off with axle.inlayHints.enable if you find them noisy. |
| Snippets | fn main, class, try / catch, defer, spawn / await all, @vectorize / @unroll loops, extern "C" fn, struct literal, multi-arm match, generic class / function, doc-comment template, … |
| Tasks | axle: build, axle: run, axle: check, axle: bench, axle: profile are surfaced under “Tasks: Run Task”. Ctrl+Shift+B runs axle build ${file} by default. |
Settings
All keys live under the axle.* prefix in your settings.json.
Server lifecycle (changes restart the server) :
| Setting | Default | Effect |
|---|---|---|
axle.server.path | axle-lsp | Path to the binary. Accepts ~, ${workspaceFolder}, or a bare name resolved through PATH. |
axle.server.extraArgs | [] | Extra CLI args passed when spawning the server. |
axle.server.env | {} | Extra environment variables — useful for RUST_LOG. |
axle.trace.server | off | LSP-trace level (off / messages / verbose). |
Live filters (applied without restart) :
| Setting | Default | Effect |
|---|---|---|
axle.inlayHints.enable | true | Master switch for inlay hints. |
axle.inlayHints.typeAnnotations | true | Inferred types beside let. |
axle.inlayHints.parameterNames | true | Parameter names at call sites. |
axle.semanticHighlighting.enable | true | Use the server’s precise tokens. Disabling falls back to grammar-only highlighting. |
axle.completion.snippets | true | Include snippet items in completion proposals. |
axle.codeLens.enable | true | Show the server’s code lenses. Toggle at runtime with the Axle: Toggle Code Lens command. |
Toggled at extension start :
| Setting | Default | Effect |
|---|---|---|
axle.tasks.enable | true | Register the axle build / run / check / bench / profile tasks. |
axle.statusBar.enable | true | Show the Axle status-bar item. |
Customising colours
The extension ships defaults that work with VS Code’s built-in
Dark+ and Light+ themes. To override the colour of any token type
(in any theme), add to your settings.json:
"editor.semanticTokenColorCustomizations": {
"rules": {
"class:axle": { "foreground": "#FFD580", "bold": true },
"interface:axle": { "foreground": "#C9A0DC", "italic": true },
"enum:axle": { "foreground": "#A8E6CF" },
"enumMember:axle": { "foreground": "#FFB6C1" },
"namespace:axle": { "foreground": "#87CEEB" }
}
} Every token type you can target, scoped to Axle with :axle : namespace, class, interface, enum, enumMember, type, typeParameter, function, method, parameter, variable, property, keyword, string, number.
Tasks
Ctrl+Shift+P → "Tasks: Run Task" lists five tasks under the axle provider:
| Task | Command |
|---|---|
axle: build | axle build ${file} |
axle: run | axle run ${file} |
axle: check | axle check ${file} |
axle: bench | axle bench ${file} |
axle: profile | axle profile ${file} |
You can also write project-local tasks in tasks.json:
{
"type": "axle",
"command": "build",
"args": ["-O", "3"],
"file": "${workspaceFolder}/src/main.axle",
"label": "axle: release build"
} The axle binary is resolved as the sibling of axle.server.path (the apt / Docker packaging ships them
together) or falls back to bare axle on PATH.
Snippets
Type the prefix and hit Tab. The most-used ones:
| Prefix | Expands to |
|---|---|
main / mainv | fn main() : i32 { … return 0; } / fn main() : void { … } |
fn / fnt | fn name(args) : void { … } / the same with a ! E error set |
gfn | Generic free function |
class | Class with one field + constructor |
gclass | Generic class skeleton |
trait | Trait declaration |
method | Method body |
struct | Struct declaration |
slit | Struct literal Type { field: value } |
enum | Enum with three variants |
let / letmut / const | let name : i32 = 0; / let mut name : i32 = 0; / const NAME : i32 = 0; |
if / ife | if (cond) { … } / if … else … |
while / for | while (cond) { … } / for (i of 0..n) { … } |
match / matchm | Two-arm / multi-arm match |
try / throw / catche | try … catch, a throw, and the inline-catch expression |
defer | defer cleanup(); |
spawn / awaitall | A spawn + await pair / await all over Future<T>[] |
sync / share | synchronized (lock) { … } / share new T(…) |
vfor / ufor | @vectorize / @unroll(n) over a loop |
doc | Doc-comment skeleton |
extern | extern "C" fn under its own symbol name |
externas | @link(…) + extern "C" fn, when the names differ |
use | use std::…; |
println | Console::println(value); |
spread | [ ...a, ...b ] — concatenate two arrays |
Other editors
Any LSP-aware editor can drive axle-lsp directly. The general
recipe is:
- Make sure
axle-lspis on yourPATH(it ships withaxle). - Configure the editor to launch
axle-lspon stdio for files whose extension is.axleor whose language id isaxle.
The protocol speaks plain LSP — no custom extensions, no proprietary
methods. Semantic-token rendering depends on the editor mapping the
15 token types the server advertises (namespace, class, interface, enum, enumMember, type, typeParameter, function, method, parameter, variable, property, keyword, string, number) to its theme. The VS Code extension does this
through semanticTokenScopes; other editors typically need a few lines
of configuration to point each token type at the right theme colour.
A TextMate grammar ships with the VS Code extension as a syntax-only fallback for editors without an LSP client; it can be copied into any editor that consumes the TextMate format.
Limits / Uncabled
The language server is pre-1.0. These are the rough edges, and what to do about each:
| Feature | State | Detail / workaround |
|---|---|---|
| Rename of a stdlib symbol or import | Refused | Stdlib symbols live outside your source, which the rename pass does not rewrite. Everything you declare is a valid target |
| Unsaved change in another project file | Not seen yet | Other project files are read from disk, so a change in file B reaches file A only when B is saved. A file changed outside the editor refreshes the open documents the same way |
| Semantic token spanning several lines | Dropped from highlighting | LSP’s delta format cannot encode a multi-line token, so it is not split. Columns and lengths count UTF-16 code units, so a multi-byte character before a token shifts nothing |
See also
- Install the compiler — get
axle+axle-lspon your machine. - Reading compiler errors — what the inline diagnostics map to.
- Concept index — every keyword / type / annotation on one page.