TheBox Language Support for VS Code
This extension supports .in (Inner Realm) and .out (Outer Metal) source
files.
Development setup
- Build the TheBox CLI with
cargo build --locked from the repository root.
- Open
editors/vscode/ in VS Code and press F5 to launch the Extension
Development Host.
- If
thebox is not on PATH, set thebox.executablePath to the CLI
executable. The extension requires TheBox CLI 1.1.0 or later.
Diagnostics use thebox check on unsaved document contents and report the
first error returned by the compiler. When an error identifies a source name,
the extension highlights that name; otherwise it highlights the reported line.
The formatter currently normalizes block indentation and preserves comments,
strings, and the document's line endings; it does not rewrite expression or
declaration spacing.
Go to Definition supports local parameters and variables, top-level
declarations, .in bridge functions, and resolvable library API/manifest
files. Function names provided by external .in process libraries cannot be
resolved when their protocol has no static API description.
The .in debugger supports breakpoints, stepping, stack/local inspection,
pause, runtime-error output, actors, and callbacks through native bridges.
For .out, select Debug TheBox (.out) in Run and Debug. This configuration
builds the saved source with debug symbols, launches it through LLDB-DAP, and
maps breakpoints and user stack frames back to .out. It does not change the
optimized standalone build. Install LLVM/LLDB with lldb-dap available on
PATH, or set thebox.lldbDapPath. On Windows, if LLDB-DAP cannot load
python3.dll, set thebox.pythonHome to the Python installation root. Debug
builds support native #import packages and retain the generated Cargo project
until the debug session ends. Variables and stepping behavior depend on the
LLDB version and its Rust support. The .out debugger is currently supported
and validated only on Windows x64; it is not considered compatible with Linux
or macOS until tested there. Richer variable inspection remains to be tested.
See the feasibility report for the
prototype evidence and known limits.
Tests and packaging
From editors/vscode/:
npm test runs the fast language-feature unit tests.
npm run test:extension-host runs integration tests in a VS Code Extension
Host. It expects the repository CLI at target/debug/thebox (or
target/debug/thebox.exe on Windows). Set THEBOX_CLI_PATH to use another
executable and VSCODE_EXECUTABLE_PATH to use an installed VS Code binary.
Set THEBOX_LLDB_DAP_PATH (and, when needed, THEBOX_PYTHON_HOME) to also
run its .out debugger integration case.
npm run package builds a VSIX package.
Install a locally built package with:
code --install-extension thebox-language-support-0.1.0.vsix
CI runs the language-feature and Extension Host tests on Windows, Linux, and
macOS, and packages the VSIX on Ubuntu. The Extension Host requires a graphical
display server on Linux, so CI runs it through xvfb-run. The real .out
LLDB-DAP integration test runs only on Windows; other platforms are not yet
considered supported for .out debugging.
The manual Publish VS Code extension GitHub Actions workflow tests and
packages the current extension version before publishing it. Configure the
repository secret VSCE_PAT before running the workflow. The VS Code extension
uses its own version in package.json, independently of the TheBox CLI.
License
The VS Code extension is licensed under the MIT License; see LICENSE.
This license applies to the extension and does not set the license for the
rest of the TheBox repository.