:style wave))`.
## Enabling / Disabling
- `rustowl-enable-cursor` โ enable cursor-based highlighting for current buffer (adds post-command-hook).
- `rustowl-disable-cursor` โ disable cursor-based highlighting (removes hook, cancels timer and clears overlays).
- Cursor highlighting is automatically enabled for Rust buffers via `rust-mode-hook`, `rust-ts-mode-hook`, and `rustic-mode-hook`.
- Obsolete aliases `enable-rustowl-cursor` / `disable-rustowl-cursor` remain for backward compatibility.
## Examples
To disable analyze-on-save globally, remove the hooks or call:
```elisp
(remove-hook 'rust-mode-hook #'rustowl-enable-cursor)
```
To customize the timeout in your config:
```elisp
(setq rustowl-cursor-timeout 1.0) ; 1 second
```
## Troubleshooting
- If overlays don't appear, ensure `lsp-mode` is active and `rustowl` server is reachable.
- Use `M-x rustowl-clear-overlays` to clear overlays if they persist.
See `docs/lsp-spec.md` for the LSP request/response shapes.
---
### Installation (`docs/installation.md`)
# Installation
## Table Of Contents
- [Installation](#installation)
- [Table Of Contents](#table-of-contents)
- [Quick Start](#quick-start)
- [cargo-binstall (recommended)](#cargo-binstall)
- [Windows (winget)](#windows-winget)
- [Arch Linux (AUR)](#arch-linux-aur)
- [Nix flake](#nix-flake)
- [GitHub Releases](#github-releases)
- [Docker](#docker)
- [Build manually](#build-manually)
## Quick Start
- Install using our script (recommended):
```
curl -L https://raw.githubusercontent.com/cordx56/rustowl/refs/heads/main/scripts/installer | sh
```
## cargo-binstall
Install the prebuilt binary using cargo-binstall:
```bash
cargo binstall rustowl
```
This automatically downloads and unpacks a Rust toolchain if required.
## Windows (winget)
Install with:
```sh
winget install rustowl
```
## Arch Linux (AUR)
We provide AUR packages that either install prebuilt binaries or build from source.
Prebuilt binaries (recommended):
```sh
yay -S rustowl-bin
```
Build from AUR (cargo build):
```sh
yay -S rustowl
```
Git (build from latest source):
```sh
yay -S rustowl-git
```
Replace `yay` with your AUR helper of choice.
## Nix flake
There is a [third-party Nix flake repository](https://github.com/nix-community/rustowl-flake) in the Nix community.
## GitHub Releases
Download the `rustowl` executable from the release page:
https://github.com/cordx56/rustowl/releases/latest
Place the executable into a directory on your PATH.
## Docker
Run the prebuilt image from GitHub Container Registry:
```sh
docker pull ghcr.io/cordx56/rustowl:latest
```
Run it against a project directory:
```sh
docker run --rm -v /path/to/project:/app ghcr.io/cordx56/rustowl:latest
```
Use an alias to act like a local CLI:
```sh
alias rustowl='docker run --rm -v $(pwd):/app ghcr.io/cordx56/rustowl:latest'
```
## Build manually
See `docs/build.md` for detailed build instructions and how to build editor extensions.
---
### Lsp Spec (`docs/lsp-spec.md`)
# The RustOwl LSP specification
## Table of Contents
- [The RustOwl LSP specification](#the-rustowl-lsp-specification)
- [Table of Contents](#table-of-contents)
- [Types](#types)
- [`OprType`](#oprtype)
- [`Decoration`](#decoration)
- [Methods](#methods)
- [`rustowl/cursor`](#rustowlcursor)
- [Request payload](#request-payload)
- [Response payload](#response-payload)
`rustowl`, is an LSP server which provides RustOwl information.
To display various types of decorations, RustOwl supports some custom methods from the client.
Here, we describe the specifications of those custom methods.
## Types
Here, we describe the types we will use in this document.
### `OprType`
```typescript
"lifetime" | "definitely_live" | "maybe_initialized"
| "imm_borrow" | "mut_borrow" | "move" | "call"
| "outlive" | "shared_mut"
```
`definitely_live` and `maybe_initialized` are derived from a CFG-based liveness analysis:
- `definitely_live` covers ranges where the local is provably initialized on every path that reaches the location (state is exactly `{Initialized}`).
- `maybe_initialized` covers ranges where the local is initialized on at least one path but may also have been moved, dropped, or be uninitialized on others (state contains `Initialized` together with other variants). Useful for spotting conditional drops and other resource-management ambiguity.
`lifetime` is retained for backward compatibility; clients should treat `definitely_live` as the replacement for the previous "actual lifetime" decoration.
### `Decoration`
{
"type": OprType,
"range": Range,
"hover_text": Option<String>,
"overlapped": bool
}
`overlapped` field indicates that the decoration is overlapped and should be hidden.
## Methods
We describe the custom methods used in RustOwl.
### `rustowl/cursor`
#### Request payload
{
"position": Position,
"document": {
"uri": DocumentUri
}
}
#### Response payload
{
"is_analyzed": bool,
"decorations": [Decoration]
}
---
### Neovim Configuration (`docs/neovim-configuration.md`)
# RustOwl Configuration (Neovim)
## Quick Start
1. Install RustOwl (see docs/installation.md) and the Neovim plugin via your plugin manager.
2. Add the minimal setup to your lazy.nvim config and open a Rust Cargo workspace.
3. Hover the cursor over a variable and wait ~500ms to see visualizations.
This document describes all available configuration options for the RustOwl Neovim plugin.
## Table of Contents
- [RustOwl Configuration (Neovim)](#rustowl-configuration-neovim)
- [Quick Start](#quick-start)
- [Table of Contents](#table-of-contents)
- [Basic Setup](#basic-setup)
- [Configuration Options](#configuration-options)
- [`auto_attach` (boolean)](#autoattach-boolean)
- [`auto_enable` (boolean)](#autoenable-boolean)
- [`idle_time` (number)](#idletime-number)
- [`highlight_style` (string)](#highlightstyle-string)
- [`colors` (table)](#colors-table)
- [Available Color Options:](#available-color-options)
- [`client` (table)](#client-table)
- [Customizing Highlight Colors](#customizing-highlight-colors)
- [Default Highlight Style](#default-highlight-style)
- [Default Colors](#default-colors)
- [Custom Colors](#custom-colors)
- [Color Format](#color-format)
- [Partial Color Customization](#partial-color-customization)
- [Examples](#examples)
- [Example 1: Minimal Configuration](#example-1-minimal-configuration)
- [Example 2: Auto-enable with Custom Colors](#example-2-auto-enable-with-custom-colors)
- [Example 3: Custom Key Binding and Styling](#example-3-custom-key-binding-and-styling)
- [Example 4: Dark Theme Optimized Colors](#example-4-dark-theme-optimized-colors)
- [Example 5: For init.vim Users](#example-5-for-initvim-users)
- [Usage Commands](#usage-commands)
## Basic Setup
The minimal configuration for RustOwl using [lazy.nvim](https://github.com/folke/lazy.nvim):
```lua
{
'cordx56/rustowl',
version = '*', -- Latest stable version
build = 'cargo install rustowl',
lazy = false, -- This plugin is already lazy
opts = {},
}
```
## Configuration Options
All configuration options are optional and have sensible defaults:
### `auto_attach` (boolean)
- **Default**: `true`
- **Description**: Automatically attach the RustOwl LSP client when opening a Rust file.
### `auto_enable` (boolean)
- **Default**: `false`
- **Description**: Enable RustOwl highlighting immediately when the LSP client attaches. When `false`, you need to manually enable highlighting using `:Rustowl enable` or `require('rustowl').enable()`.
### `idle_time` (number)
- **Default**: `500`
- **Description**: Time in milliseconds to hover with the cursor before triggering RustOwl analysis and highlighting.
### `highlight_style` (table)
- **Description**: The style of underline for different highlight types. `'undercurl'` or `'underline'`.
### `colors` (table)
- **Description**: Custom colors for different highlight types. Each color should be a hex color string (e.g., `'#ff0000'`).
#### Available Color Options:
- `lifetime`: Color for variable lifetime highlights (default: `'#00cc00'` - green)
- `imm_borrow`: Color for immutable borrow highlights (default: `'#0000cc'` - blue)
- `mut_borrow`: Color for mutable borrow highlights (default: `'#cc00cc'` - purple)
- `move`: Color for value move highlights (default: `'#cccc00'` - yellow)
- `call`: Color for function call highlights (default: `'#cccc00'` - yellow)
- `outlive`: Color for lifetime error highlights (default: `'#cc0000'` - red)
### `client` (table)
- **Description**: LSP client configuration that gets passed to `vim.lsp.start`. This follows the same structure as Neovim's LSP client configuration.
## Customizing Highlight Colors
### Default Highlight Style
Default highlight style is straight underline except for maybe live and errors.
### Default Colors
The default color scheme uses the following colors that correspond to the visual legend:
- ๐ฉ **Green** (`#00cc00`): Variable's lifetime
- ๐ฆ **Blue** (`#0000cc`): Immutable borrowing
- ๐ช **Purple** (`#cc00cc`): Mutable borrowing
- ๐ง **Yellow** (`#cccc00`): Value moved / function call
- ๐ฅ **Red** (`#cc0000`): Lifetime errors
### Custom Colors
To customize colors, specify them in the `colors` table:
```lua
opts = {
colors = {
lifetime = '#32cd32', -- Lime green
imm_borrow = '#4169e1', -- Royal blue
mut_borrow = '#ff69b4', -- Hot pink
move = '#ffa500', -- Orange
call = '#ffd700', -- Gold
outlive = '#dc143c', -- Crimson
},
}
```
#### Color Format
Colors must be specified as hex color strings:
- โ
Valid: `'#ff0000'`, `'#00ff00'`, `'#0000ff'`
- โ Invalid: `'red'`, `'rgb(255,0,0)'`, `'#f00'`
### Partial Color Customization
You can customize only specific colors while keeping the defaults for others:
```lua
opts = {
colors = {
lifetime = '#90ee90', -- Light green for better visibility
outlive = '#ff4500', -- Orange red for errors
-- Other colors will use defaults
},
}
```
## Examples
### Example 1: Minimal Configuration
```lua
{
'cordx56/rustowl',
version = '*',
build = 'cargo install rustowl',
lazy = false,
opts = {},
}
```
### Example 2: Auto-enable with Custom Colors
```lua
{
'cordx56/rustowl',
version = '*',
build = 'cargo install rustowl',
lazy = false,
opts = {
auto_enable = true,
colors = {
lifetime = '#90ee90', -- Light green
imm_borrow = '#87ceeb', -- Sky blue
mut_borrow = '#dda0dd', -- Plum
move = '#f0e68c', -- Khaki
call = '#ffd700', -- Gold
outlive = '#ff6347', -- Tomato
},
},
}
```
### Example 3: Custom Key Binding and Styling
```lua
{
'cordx56/rustowl',
version = '*',
build = 'cargo install rustowl',
lazy = false,
opts = {
auto_enable = false,
idle_time = 300,
highlight_style = {
definitely_live = 'underline',
maybe_initialized = 'undercurl',
},
colors = {
outlive = '#ff0000', -- Bright red for errors
},
client = {
on_attach = function(_, buffer)
vim.keymap.set('n', 'ro', function()
require('rustowl').toggle(buffer)
end, { buffer = buffer, desc = 'Toggle RustOwl' })
vim.keymap.set('n', 're', function()
require('rustowl').enable(buffer)
end, { buffer = buffer, desc = 'Enable RustOwl' })
vim.keymap.set('n', 'rd', function()
require('rustowl').disable(buffer)
end, { buffer = buffer, desc = 'Disable RustOwl' })
end
},
},
}
```
### Example 4: Dark Theme Optimized Colors
```lua
{
'cordx56/rustowl',
version = '*',
build = 'cargo install rustowl',
lazy = false,
opts = {
colors = {
lifetime = '#50fa7b', -- Dracula green
imm_borrow = '#8be9fd', -- Dracula cyan
mut_borrow = '#ff79c6', -- Dracula pink
move = '#f1fa8c', -- Dracula yellow
call = '#ffb86c', -- Dracula orange
outlive = '#ff5555', -- Dracula red
},
},
}
```
### Example 5: For init.vim Users
If you're using `init.vim` instead of `init.lua`, you can configure RustOwl using Vim script:
```vim
lua << EOF
require('lazy').setup({
{
'cordx56/rustowl',
version = '*',
build = 'cargo install rustowl',
lazy = false,
opts = {
colors = {
lifetime = '#00ff00',
imm_borrow = '#0080ff',
mut_borrow = '#ff00ff',
move = '#ffff00',
call = '#ffa500',
outlive = '#ff0000',
},
},
},
})
EOF
```
## Usage Commands
When opening a Rust file, the following commands become available:
- `:Rustowl start_client` - Start the RustOwl LSP client
- `:Rustowl stop_client` - Stop the RustOwl LSP client
- `:Rustowl restart_client` - Restart the RustOwl LSP client
- `:Rustowl enable` - Enable RustOwl highlighting
- `:Rustowl disable` - Disable RustOwl highlighting
- `:Rustowl toggle` - Toggle RustOwl highlighting
You can also use the Lua API:
```lua
require('rustowl').enable() -- Enable highlighting
require('rustowl').disable() -- Disable highlighting
require('rustowl').toggle() -- Toggle highlighting
require('rustowl').is_enabled() -- Check if enabled
```
---
### Usage (`docs/usage.md`)
# RustOwl usage
## Table of Contents
- [RustOwl usage](#rustowl-usage)
- [Table of Contents](#table-of-contents)
- [Quick Start](#quick-start)
- [Getting started](#getting-started)
- [Basic usage](#basic-usage)
- [Advanced usage](#advanced-usage)
## Quick Start
1. Install RustOwl (docs/installation.md) and the editor extension for your editor.
2. Open a Rust Cargo workspace and save a Rust file to trigger analysis.
3. Place the cursor on a variable or function call and wait a short idle time to see visualizations.
Here, I describe how to use RustOwl in your workflow.
## Getting started
First, please install the RustOwl LSP server and extension for your editor.
Installation guide is on [installation](/docs/installation.md) file.
Then, please open a Rust source code file (`.rs`) in the editor.
RustOwl only works with a Cargo workspace, so you need to open the source code that is part of a Cargo workspace.
I recommend you try RustOwl with a small, simple workspace first.
RustOwl's analysis may take a long time for a large workspace.
VS Code extension will automatically start analyzing the workspace.
For other editors, you may need to enable RustOwl manually, but you can enable automatic loading in your configuration file.
The progress of analysis will be shown in your editor.
After the analysis started, RustOwl waits for your request.
Please place the text cursor on a variable or function call you would like to inspect.
RustOwl works for the analyzed portion, even if the entire analysis has not finished.
If your program has some fatal errors (e.g., syntax errors or unrecoverable type errors), RustOwl cannot work for the part where the analysis failed.
Wait for a few seconds, and then the ownership-related operations and lifetimes of the variable to which the `unwrap()` method call assigns a value will appear.
## Basic usage
Basically, RustOwl can be used to resolve ownership and lifetime errors.
What RustOwl visualizes is:
- Lifetime of variables, split into two precisions:
- **Definitely live** range: the variable is provably initialized on every path that reaches the location.
- **Maybe live** range: the variable is initialized on at least one path but may have been moved, dropped, or be uninitialized on others.
- Shared (immutable) borrowing of variables
- Mutable borrowing of variables
- Value movement
- Function call
- Ownership and lifetime errors
You can see which color is assigned to them on the top page of this repository.
RustOwl can be used to see where a variable lives, where it dies, and where it is borrowed or moved.
For VS Code, you can see the message that explains the meaning of the underline by hovering your mouse cursor over it.
This is the basic usage of RustOwl!
Now you have a master's degree in RustOwl.
## Advanced usage
The lifetime that RustOwl visualizes is the range of these variables:
- Where the variable _lives_
- For the meaning of _NLL_
- Until the variable is _dropped_ or _moved_
- For the meaning of _RAII_
Based on this, we can use RustOwl as listed below:
- To resolve _dead lock_ that is caused by some data structures like `Mutex`
- Because these _locks_ are freed where the lock object is dropped
- To manage resources
- Like memories, files, and anything which is managed by _RAII_ respective
### Definitely live vs. maybe live
The lifetime visualization is split by a CFG-based liveness analysis into two precisions, which is useful when ownership depends on control flow.
```rust
fn f(cond: bool) {
let v: Vec<_> = (0..100).collect();
if cond {
drop(v); // v is dropped only on the `cond == true` branch
}
// After the `if`, v is "maybe live": still owned on the `false`
// branch, but already dropped on the `true` branch.
}
```
- A **definitely live** range marks code where the variable is owned on every path. Dropping or freeing a resource here is safe.
- A **maybe live** range marks code where the variable is owned on some paths only. Reading from or moving the variable here would not compile, and it is a hint that resource cleanup is happening conditionally.
When auditing resource management (file handles, locks, allocations), the boundary between the two ranges is typically the location to inspect.
Did you get a Ph.D. in lifetimes?
So let's try managing resources with RustOwl.
You will get a Ph.D. in RustOwl and computer resource management.
---
### Vscode Configuration (`docs/vscode-configuration.md`)
# RustOwl Configuration (VS Code)
## Table Of Contents
- [RustOwl Configuration (VS Code)](#rustowl-configuration-vs-code)
- [Table Of Contents](#table-of-contents)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Settings (configuration keys)](#settings-configuration-keys)
- [Commands](#commands)
- [Behavior](#behavior)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)
This document describes configuration options for the RustOwl VS Code extension.
## Quick Start
Install the extension from the Marketplace or Open VSX. The extension will download and run the rustowl binary automatically when activated.
1. Install the extension in VS Code.
2. Open a Rust Cargo workspace.
3. Save a Rust file and hover over a variable after a short idle time to see decorations.
## Configuration
The VS Code extension exposes configurable settings and commands. Here are the concrete settings and behavior derived from code.
## Settings (configuration keys)
- `rustowl.underlineThickness` (string) โ The stroke thickness of the underline line. Allowed values: "1", "2", "3", "4".
- `rustowl.lifetimeColor` (string) โ The color of the lifetime (definitely live).
- `rustowl.maybeInitColor` (string) โ The color of the lifetime (maybe initialized).
- `rustowl.moveCallColor` (string) โ The color of the move/call.
- `rustowl.immutableBorrowColor` (string) โ The color of the immutable borrow.
- `rustowl.mutableBorrowColor` (string) โ The color of the mutable borrow.
- `rustowl.outliveColor` (string) โ The color of the outlive.
- `rustowl.displayDelay` (number) โ Delay in displaying underlines (ms).
- `rustowl.highlightBackground` (boolean) โ Highlight text background instead of underline.
- `rustowl.defaultEnabled` (boolean) โ Enabled by default.
## Commands
- `rustowl.hover` โ manually request hover/decorations for current selection.
- `rustowl.toggle` โ toggle decorations on/off (status bar changes accordingly).
## Behavior
- The extension bootstraps the `rustowl` binary using `bootstrap.ts` and starts an LSP client pointing at the executable.
- On save of Rust files the extension sends `rustowl/analyze` to the server (if enabled).
- On cursor selection changes, after `displayDelay` ms the extension sends `rustowl/cursor` and applies decorations returned by server.
- Decorations ignore overlapped ranges and map LSP response types to decorations (lifetime, imm_borrow, mut_borrow, move/call, outlive/shared_mut).
## Examples
Add settings to `.vscode/settings.json`:
```json
{
"rustowl.displayDelay": 2000,
"rustowl.defaultEnabled": true,
"rustowl.lifetimeColor": "#00cc00",
"rustowl.maybeInitColor": "#00cc00",
"rustowl.immutableBorrowColor": "#0000cc",
"rustowl.mutableBorrowColor": "#cc00cc",
"rustowl.moveCallColor": "#cccc00",
"rustowl.outliveColor": "#cc0000",
"rustowl.highlightBackground": false,
"rustowl.underlineThickness": 2
}
```
## Troubleshooting
- Check Output -> RustOwl for logs. If the server failed to start, the extension shows an error message.
- Ensure the `rustowl` executable is in PATH or let the extension download it (bootstrap).
---
--- METRICS ---
- Files Extracted: 14
- Estimated Token Budget: ~15000 tokens
- Canonical Reference: https://codewiki.google/github.com/cordx56/rustowl
