• Rhai LSP
  • Requirements
  • Project Structure
    • crates/rhai-rowan
    • crates/rhai-lsp
    • crates/rhai-sourcegen
    • editors/vscode
  • Tests
  • Benchmarks
  • Profiling
  • Contributing
    • Development Process
      • Building and Installing the VSCode Extension
      • Building the Rhai CLI
      • Debugging the Language Server
      • Building the VSCode Extension
        • Requirements
        • Build Steps

Rhai LSP

Experimental Rhai LSP Server and IDE support.

It's incomplete and not recommended for general use yet, everything can be subject to changes.

Quick Start (VS Code)

1. Install the extension:

   code --install-extension rhaiscript.vscode-rhai

2. Install the Rhai CLI:

   cargo install --path crates/rhai-cli

3. Configure VS Code (.vscode/settings.json):

   {
       "rhai.useLanguageServer": true,
       "rhai.executable.bundled": false
   }

4. Create Rhai.toml in your project root:

   [source]
   include = ["**/*.rhai"]

5. Add type definitions (see Type Definition Files)

Type Definition Files

Type definition files (.d.rhai) allow you to declare types and functions that the LSP will recognize for autocompletion and error checking.

Creating Definition Files

Definition files must start with module followed by a name or static:

/// Type definitions for my custom types
module static;

// Opaque type declaration
type MyHandle;

// Type with known structure  
type Options = #{
    name: String,
    count: int,
};

// Function declaration
fn my_function(arg: String) -> int;

// Method declaration
fn MyHandle.do_something(options: Options) -> ();

Where to Place Definition Files

• Place .d.rhai files anywhere in your workspace
• The LSP auto-discovers files starting with module keyword
• They're indexed based on patterns in Rhai.toml

How Detection Works

The LSP uses is_rhai_def() function (crates/rhai-rowan/src/util.rs) which calls parse_def_header() to check if a file starts with module.

Key parser code is in:

• crates/rhai-rowan/src/parser/parsers/def.rs - Definition file parser
• parse_def_module() - Handles module static;, module name;, module "path";
• parse_def_fn() - Handles fn Type.method() syntax

Requirements

• Stable Rust toolchain is required (e.g. via rustup)
• ... other required tools are described in the appropriate sections

Project Structure

crates/rowan

Rhai syntax and a recursive descent parser based on Rowan.

The high-level syntax (ungrammar) definition is found in crates/rowan/src/ast/rhai.ungram. The parser mimics the structure and produces a fitting CST.

crates/lsp

The LSP server implementation backed up by lsp-async-stub.

It can be compiled to WASM only right now, but native binaries with stdio or TCP communication can be easily implemented.

crates/sourcegen

Crate for source generation.

Currently only some node types and helper macros are generated from the ungrammar definition. Later the AST will also be generated from it.

editors/vscode

VS Code extension that uses the LSP.

If all the tools are available from the Requirements, it can be built and installed with task ide:vscode:dev.

Tests

Run all tests with cargo test.

Parser tests are based on scripts found in testdata, and also in the upstream rhai submodule.

Benchmarks

Run benchmarks with cargo bench.

Current parser results:

We can only go up from here. (although it is 3 times faster than a similar LALR generated parser)

Profiling

To profile the parser, run cargo bench --bench parse -- --profile-time 5.

The flame graph outputs can be found in target/criterion/profile afterwards.

Contributing

The documentation is still pretty much WIP (as everything else). All contributions are welcome!

Development Process

Currently the following steps are used to develop the project via vscode:

Building the Rhai CLI

cargo install --path crates/rhai-cli --debug

This will build and install the rhai executable globally that the vscode extension can also use.

Debugging the Language Server

The debugging process can consist of either strategically placed tracing::info statements that are visible in the VSCode debug console under Rhai LSP, or attaching a debugger to the running rhai process via LLDB VSCode. Both approaches deemed sufficient so far.

Building the VSCode Extension

The vscode extension relies on rhai-lsp compiled to WebAssembly via rhai-wasm. There are several related js libraries that are built on top of it.

Requirements

• The usual Rust tools along with the wasm32-unknown-unknown target, (rustup target add wasm32-unknown-unknown).
• NodeJs with proper PATH variables set up.
• Yarn (npm i -g yarn)
• vsce (npm i -g vsce)

Build Steps

You'll need to build all local js libraries in dependency order:

First the core js library with common utilities:

# from js/core

yarn install --force
yarn build

Then the LSP wrapper, it will also build the WASM library:

# from js/lsp

yarn install --force
yarn build

Finally the extension itself:

# from editors/vscode

yarn install --force
vsce package --no-yarn

Then you can use vscode to install the packaged extension via the UI or the following command:

code --install-extension rhai-0.0.0.vsix --force

After this the Rhai extension will be available in vscode.

If you modify any of the packages, unfortunately you will have to build all dependent packages manually, e.g. if you modify js/core, you will have to repeat all the above steps.

Unless you wish to develop any of the javascript parts (the libraries or the extension itself), instead of rebuilding the extension, it is enough to install the Rhai CLI, and setting "rhai.executable.bundled": false in vscode. This way the extension will use the language server from the rhai executable which is easier to debug, rebuild and develop in general.