Axle v0.22.0

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

  1. Install the axle compiler — see Install the compiler. The axle-lsp binary ships in the same package, next to axle.
  2. Install the extension from the VS Code Marketplace (search for “Axle”) or sideload a .vsix built 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:

BadgeMeaning
$(loading~spin) AxleThe language server is starting.
$(check) AxleRunning — hover the badge for the version; click it for the log.
$(warning) AxleThe server is older than the extension — rebuild or reinstall it.
$(error) AxleStopped or crashed — click to restart.
$(question) AxleThe client has not learned the server’s state yet.

What you get

FeatureWhat it does
Semantic highlightingPer-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 completionAfter . 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.
HoverThe 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 definitionLands 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 referencesLocals, parameters, free functions, methods, fields, and types — across project files.
RenameThe 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 highlightThe other occurrences of the symbol under the cursor, in the current file.
Document outlineTree of every class, struct, trait, enum, and free function in the current file — navigable through Outline: view and Ctrl+Shift+O.
Workspace symbolsSubstring search via Ctrl+T — covers the whole project once any of its files is open.
Call hierarchyIncoming and outgoing calls around the function under the cursor.
Type hierarchySuper- and subtypes of a class or trait.
Code lensAn “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 linksClickable paths in use lines and import strings.
FormattingWhole-document formatting through the same axle fmt the CLI runs — Shift+Alt+F.
Inline diagnosticsLexing, parsing, and semantic errors with hint lines. Each error keeps its catalogue code (E0014, E0511, …) so you can cross-reference Reading compiler errors.
Editor lintsUnused 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 helpThe current call’s parameter list as you type, with the active parameter highlighted.
Code actionsQuick-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 selectFold functions, types and blocks; Shift+Alt+→ expands the selection through enclosing expressions.
Inlay hintsInferred 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.
Snippetsfn 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, …
Tasksaxle: 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) :

SettingDefaultEffect
axle.server.pathaxle-lspPath 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.serveroffLSP-trace level (off / messages / verbose).

Live filters (applied without restart) :

SettingDefaultEffect
axle.inlayHints.enabletrueMaster switch for inlay hints.
axle.inlayHints.typeAnnotationstrueInferred types beside let.
axle.inlayHints.parameterNamestrueParameter names at call sites.
axle.semanticHighlighting.enabletrueUse the server’s precise tokens. Disabling falls back to grammar-only highlighting.
axle.completion.snippetstrueInclude snippet items in completion proposals.
axle.codeLens.enabletrueShow the server’s code lenses. Toggle at runtime with the Axle: Toggle Code Lens command.

Toggled at extension start :

SettingDefaultEffect
axle.tasks.enabletrueRegister the axle build / run / check / bench / profile tasks.
axle.statusBar.enabletrueShow 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:

TaskCommand
axle: buildaxle build ${file}
axle: runaxle run ${file}
axle: checkaxle check ${file}
axle: benchaxle bench ${file}
axle: profileaxle 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:

PrefixExpands to
main / mainvfn main() : i32 { … return 0; } / fn main() : void { … }
fn / fntfn name(args) : void { … } / the same with a ! E error set
gfnGeneric free function
classClass with one field + constructor
gclassGeneric class skeleton
traitTrait declaration
methodMethod body
structStruct declaration
slitStruct literal Type { field: value }
enumEnum with three variants
let / letmut / constlet name : i32 = 0; / let mut name : i32 = 0; / const NAME : i32 = 0;
if / ifeif (cond) { … } / if … else …
while / forwhile (cond) { … } / for (i of 0..n) { … }
match / matchmTwo-arm / multi-arm match
try / throw / catchetry … catch, a throw, and the inline-catch expression
deferdefer cleanup();
spawn / awaitallA spawn + await pair / await all over Future<T>[]
sync / sharesynchronized (lock) { … } / share new T(…)
vfor / ufor@vectorize / @unroll(n) over a loop
docDoc-comment skeleton
externextern "C" fn under its own symbol name
externas@link(…) + extern "C" fn, when the names differ
useuse std::…;
printlnConsole::println(value);
spread[ ...a, ...b ] — concatenate two arrays

Other editors

Any LSP-aware editor can drive axle-lsp directly. The general recipe is:

  1. Make sure axle-lsp is on your PATH (it ships with axle).
  2. Configure the editor to launch axle-lsp on stdio for files whose extension is .axle or whose language id is axle.

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:

FeatureStateDetail / workaround
Rename of a stdlib symbol or importRefusedStdlib symbols live outside your source, which the rename pass does not rewrite. Everything you declare is a valid target
Unsaved change in another project fileNot seen yetOther 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 linesDropped from highlightingLSP’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

lspeditorvscodetooling