Maxon Language Support (VS Code Extension)

Visual Studio Code extension that provides syntax highlighting and Language Server Protocol (LSP) support for the Maxon programming language.

Features

• Syntax highlighting for .maxon sources, .maxproj project files, .maxtasks task files and .maxtest test files using a TextMate grammar
• Language Server Protocol support (completion, diagnostics, go-to-definition, etc.) from the compiler's own maxon lsp-server
• Go to definition and hover across files, and into their members: F12 on a name declared in another file of your project, or in the standard library, opens that file, and hovering one renders its declaration, whether top-level or a field or method of such a type. The project is the nearest directory above the file that holds a .maxproj file, searched up to the workspace folder that contains the file; failing that, the file is a single file, resolved against the standard library and itself. A file of the standard library's stdlib/ or runtime/ belongs to that directory's project. In a multi-root window every folder caps the search for its own files, and a folder added to the window does so at once. Hover and completion also resolve a receiver typed by self, by a call, by a try … otherwise, by a field of the enclosing type, by a for … in loop variable, by a chain of any of these (a.b.c, a.m().n()), by a generic-instance type alias, by an element taken out of a generic container, or by a service handle, which offers its service's messages plus shutdown and clone.
• Diagnostics that know about your other files: a name a sibling file of the project declares counts as declared. Each buffer is checked on its own at once; in a project with a .maxproj, the whole project is then compiled with your unsaved text, a moment after you stop typing, and the file shows the errors maxon build's checks report on it. Outside stdlib/ and runtime/, a file with no .maxproj in or above its directory is checked alone. Each project check writes an outcome line to the Maxon Language Server output channel.
• Language configuration: comment support, bracket pairing, and auto-closing pairs
• Code formatting: the language server's formatter, applied on save by default
• Compiler Explorer: View the Target IR the compiler lowers a program to
• Test Explorer: Discover the test declarations in your *.maxtest files and run them with maxon test
• Debugging (x64-windows, x64-linux, arm64-linux, arm64-macos): F5 on a .maxon file, breakpoints in the gutter, the Variables and Call Stack panes, stepping and Pause, through the compiler's own maxon dap-server

The language features come from the Maxon compiler itself, which serves the Language Server Protocol (maxon lsp-server). This extension is its client.

Requirements

• Visual Studio Code 1.107.0 or later, or an editor built on it
• The Maxon compiler. If the extension cannot find one it offers to install it, using the same one-line installer as the installation page.

Installation

Install Maxon from the Visual Studio Marketplace or Open VSX.

Finding the compiler

The extension looks in this order:

1. The maxon.serverPath setting, if you set one.
2. The build in a workspace folder that is a Maxon source checkout (a folder holding specs/, stdlib/, runtime/ and maxon-bin/), at maxon-bin/.maxon/maxon. The compiler reads stdlib/ and runtime/ from beside its own executable, so a checkout is served by the compiler built from it. With several checkouts open, the first in folder order is used. A checkout with no build yet is noted in the output channel ("build it with maxon run build") and the search goes on.
3. maxon on your PATH.
4. ~/.maxon/bin (%USERPROFILE%\.maxon\bin on Windows), or $MAXON_INSTALL/bin — where the install script puts it. Searched directly, because a VS Code started from the dock or the Start menu gets the desktop's PATH, without your shell profile's additions.
5. The build in the checkout the extension itself is part of, when you run the extension from source.

If none of those finds one, it offers Install, which runs the installer for your account, and Locate…, which lets you pick a compiler you already have.

The language server is the compiler it finds, run as maxon lsp-server. The extension searches again each time the server restarts, when a workspace folder is added or removed, and when maxon.serverPath changes, and moves the server to the compiler that search finds. When the compiler in use, or the build of any open checkout, is rebuilt, the extension restarts the server, so it answers from the new compiler.

From source (for working on the extension)

1. Build the compiler in the repository root (see the repository README); the extension finds maxon-bin/.maxon/maxon in the workspace.

2. Install extension dependencies and compile the extension:

cd vscode-extension
npm install
npm run compile

3. Package and install it, from the repository root:

./maxon-bin/.maxon/maxon run build-extension     # vscode-extension/maxon-lsp-client.vsix
./maxon-bin/.maxon/maxon run install-extension   # packages it, then installs it into VS Code

Both are tasks of the repository root's maxon.maxtasks, and both run npm install first. install-extension installs with the code command, replacing any installed copy; VS Code puts code on PATH (on macOS, through Shell Command: Install 'code' command in PATH).

Usage

• Open a .maxon file in VS Code. If the LSP server binary is available and runs correctly, you should get diagnostics, code completion, and basic navigation features.
• .maxproj, .maxtasks and .maxtest files are Maxon documents too. A .maxtest file is checked with its project's other test files in view, and a .maxon file with the production sources only.
• A .test file (a spec fragment in the Maxon checkout) is highlighted as Maxon and sent to the language server whole, exactly like a .maxon file.
• If you only want syntax highlighting, no LSP server is required.

Development

• Use the watch script during development to compile TypeScript and auto-emit changes:

cd vscode-extension
npm run watch

• In VS Code, open the vscode-extension folder and launch the extension host via the Run/Debug panel to test and iterate quickly.

Extension build and packaging

• npm run compile — compile TypeScript to JavaScript (output is out/)
• npm run package — build a .vsix package using vsce
• maxon run build-extension and maxon run install-extension, at the repository root — package the extension, and package then install it into VS Code

Testing

• The extension uses @vscode/test-electron for integration tests and mocha for unit testing.
• To run tests:

cd vscode-extension
npm test

• npm run test:unit compiles the extension and runs the unit tests that need no VS Code instance (src/test/unit/), such as how a maxon test --json report maps onto Test Explorer results.
• npm run test:grammar checks the TextMate grammar against the snapshots in test-fixtures/.

Code Formatting

The extension has no formatter of its own. Format Document (Shift+Alt+F, or Shift+Option+F on Mac) sends textDocument/formatting to the language server, which re-prints the whole document with the compiler's formatter and answers with one edit replacing all of it — or with nothing when the document is already formatted.

The extension sets editor.formatOnSave to true for Maxon files, so saving formats. Turn it off in your settings to format only on request:

{
  "[maxon]": {
    "editor.formatOnSave": false
  }
}

Indentation

Maxon indents with tabs. Two settings choose what the server is asked for:

• maxon.formatting.insertSpaces (default false): indent with spaces instead.
• maxon.formatting.tabSize (default 2): how many spaces make one indent. The server reads it only when insertSpaces is true; with tabs it is ignored.

These settings replace the editor's own editor.insertSpaces and editor.tabSize for the formatting request.

Compiler Explorer

The Compiler Explorer panel shows the Target IR the compiler lowers a program to — the same text maxon build --emit-ir writes, for your program's own functions. It compiles for the machine VS Code runs on, and nothing is written to disk.

Opening the Compiler Explorer

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run Maxon: Open Compiler Explorer

Using the Panel

Type or paste a whole program into the Source pane. The Target IR pane updates shortly after you stop typing. If the program does not compile, the pane lists each error with its line and column instead.

Test Explorer

The extension contributes a Maxon Tests controller to VS Code's Test Explorer. It lists every test '<name>' declaration in the workspace's *.maxtest files, one node per file with its tests beneath it, and runs them with maxon test — the same compiler the language server uses (see Finding the compiler). The tests are listed even when no compiler is found; running them then reports that none was.

Discovery

Test files are read from disk, and the tree follows them as they are created, saved and deleted. A file beneath a directory holding a .maxonignore is not listed, because no maxon test run compiles it. The refresh button in the Test Explorer re-reads every test file.

Which project a test runs in

A test file's project is the nearest directory holding a .maxproj, from the file's own directory up to the workspace folder, and the test runs as maxon test <that directory>, which compiles every .maxon file beneath it together with its tests as one program. A test file with no .maxproj there runs alone, as maxon test <file>: it is compiled with the library tiers and nothing else, as the language server checks it. So lib/math.maxtest runs with the whole project when an app.maxproj sits at the root, and by itself when nothing marks a project.

The compiler runs in the workspace folder, so a relative path inside a test means what it means in a terminal opened there.

Running

Each project, or lone test file, the selection touches is one invocation:

maxon test <project or file> --json [--filter=<patterns>]

Running every test of a project or file passes no filter. Otherwise the filter names each file whose tests are all selected by its path, and each other selected test by its name. The compiler matches a pattern as a case-insensitive substring, so the run may include more tests than you selected; only the selected ones are reported.

Results

--json prints one report, which the extension matches to the tree by file and test name:

A test that threw an error nothing caught names the error, and points at where it was thrown when that file exists. Anything a test printed goes to the run's output.

When maxon test exits with code 2 it could not run at all — a compile error, most often — and every test in that project is errored with what it printed. A selected test missing from the report is errored too, with the report's reason when it ran nothing: the compiler reads saved files, so a test that is not saved yet is not in it.

The spec suite

When the workspace folder is the Maxon compiler checkout — it holds both specs/ and maxon-bin/ — a second controller, Maxon Spec Suite, lists the <!-- test: name --> markers in specs/*.md under one node per spec, and runs them with the tree's own build, maxon-bin/.maxon/maxon spec-test, in one process per run. A run of every spec passes no filter; otherwise each whole spec adds --filter=<spec>/ and each single test --filter=<spec>/<test>. Verdicts are read from the PASS, FAIL, SKIP and NOTRUN lines on stdout; a selected test with no verdict is skipped when the run reached its <n> passed, <m> failed summary, and errored with the runner's stderr when it did not. A filter that selects nothing on this host refuses the whole run, so every selected test is then errored with the runner's message.

Debugging

The extension contributes a Maxon debugger. The debug adapter is the compiler it finds (see Finding the compiler), run as maxon dap-server, so the compiler is the whole debugger.

⚠ Native programs. The debugger debugs a program built for the host's own native target — x64-windows, x64-linux, arm64-linux or arm64-macos — and maxon dap-server refuses a program built for a target other than the host's, naming both. On arm64-macos it drives the program through Apple's debugserver, so a host without the Xcode command line tools is refused.

Starting a session

Press F5 with a .maxon file in the active editor to debug it. A configuration without a program, or none at all, debugs the active editor's .maxon file, or else the workspace folder when it holds a .maxproj file. With neither, the session is refused with a message saying so.

A source file or a project directory is built with debug info before it runs. The executable goes to the host's Maxon cache, and maxon cache clear removes it once its session has ended. program can also name an executable already built with debug info (its .mxdbg sidecar beside it). A build that fails refuses the session with the compiler's diagnostics.

Run and Debug → create a launch.json file writes a configuration for the current file, and the Add Configuration… button offers one for the current file and one for the project. A launch configuration takes:

{
  "type": "maxon",
  "request": "launch",
  "name": "Debug the server",
  "program": "${workspaceFolder}",
  "args": ["--port=8080"],
  "env": { "LOG_LEVEL": "debug" },
  "stopOnEntry": false
}

While it runs

• Breakpoints: click in the gutter of a .maxon file. A breakpoint on a line without code is shown unverified, with the reason. Edit Condition gives a breakpoint a condition, which the debugger checks before it stops; a condition beyond what the debugger evaluates leaves the breakpoint unverified, with the reason. Function breakpoints (+ in the Breakpoints pane) stop at a function's entry. Breakpoints can be added and removed while the program runs.
• Call Stack: every green thread is a thread of its own. Frames of inlined functions are listed, dimmed.
• Variables: the stopped frame's locals; a value with fields or elements expands into them. A value unreadable at that point shows the reason in its place: <optimized out>, <not live here>, <read failed> or <layout not described>.
• Hover and Watch evaluate an expression in the stopped frame, and the Debug Console takes any command maxon debug takes (help lists them — gt-park and gt-resume hold and release one green thread, trace reads the DebugStream ring).
• Stepping: Step Over, Step Into and Step Out, by source line. Pause stops every thread wherever it is.
• A hardware fault or a trap stops the session as an exception, saying what faulted. The program's stdout and stderr appear in the Debug Console, and its exit code ends the session.

Debugging a test

The Test Explorer has a Debug Test action beside Run Test. It debugs the selected tests under the same test binary maxon test runs. Each project, or lone test file, the selection touches is built once:

maxon test <project or file> --list --build --json [--filter=<the selection>]

builds its tests with debug info without running them, and names the binary and, for each listed test, the value that selects it alone. The extension copies the binary and its .mxdbg sidecar into a temporary directory, then debugs each selected test in turn as a session of <copy> --select=<value> in the workspace folder, where maxon test runs it too. Debugging the copy leaves the original free, so Run Test can rebuild and run the project while a session is live. The copy is deleted when the project's last session ends. Breakpoints in the test, and in the code it calls, stop as in any other session. Cancelling the test run stops the session in progress and ends the run there.

The test is marked passed when the binary exits 0 and failed when it exits 3 (or 101, when the test leaked); what it printed, including the failed assertion, is in the Debug Console. Any other exit code (1 is a panic), a build that fails, or a session that ends before the binary exits marks the test errored, saying why.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Notes and Troubleshooting

• Language server errors are written to the Maxon Language Server output channel, and the status bar item turns red while the server is stopped. If the server fails to start, that channel says which compiler it found, or that it found none. See Finding the compiler.
• The status bar item turns yellow while the server loads a project, which happens when a document of that project opens. A project is a directory holding a .maxproj, stdlib/ or runtime/. Its tooltip shows the compiler's version (as maxon version prints it, reported by the server when it starts) and its location, lists the projects loading and loaded, and ends with Restart and Show Output links (also the commands Maxon: Restart Language Server and Maxon: Show Language Server Output).
• For LSP server issues, the embedded server code is in maxon-bin/Compiler/Lsp/.

If you need help with building or testing the extension, open an issue on the repository with your platform, VS Code version, and steps to reproduce the problem.