At its core, rust-analyzer is a library for semantic analysis of Rust code as it changes over time. This manual focuses on a specific usage of the library — running it as part of a server that implements the Language Server Protocol (LSP). The LSP allows various code editors, like VS Code, Emacs or Vim, to implement semantic features like completion or goto definition by talking to an external language server process.
|
Tip
|
To improve this document, send a pull request: |
If you have questions about using rust-analyzer, please ask them in the “IDEs and Editors” topic of Rust users forum.
In theory, one should be able to just install the rust-analyzer binary and have it automatically work with any editor.
We are not there yet, so some editor specific setup is required.
Additionally, rust-analyzer needs the sources of the standard library. If the source code is not present, rust-analyzer will attempt to install it automatically.
To add the sources manually, run the following command:
$ rustup component add rust-srcThis is the best supported editor at the moment. The rust-analyzer plugin for VS Code is maintained in tree.
You can install the latest release of the plugin from the marketplace.
Note that the plugin may cause conflicts with the official Rust plugin. It is recommended to disable the Rust plugin when using the rust-analyzer extension.
By default, the plugin will prompt you to download the matching version of the server as well:
|
Note
|
To disable this notification put the following to { "rust-analyzer.updates.askBeforeDownload": false } |
The server binary is stored in:
-
Linux:
~/.config/Code/User/globalStorage/matklad.rust-analyzer -
Linux (Remote, such as WSL):
~/.vscode-server/data/User/globalStorage/matklad.rust-analyzer -
macOS:
~/Library/Application\ Support/Code/User/globalStorage/matklad.rust-analyzer -
Windows:
%APPDATA%\Code\User\globalStorage\matklad.rust-analyzer
Note that we only support two most recent versions of VS Code.
The extension will be updated automatically as new versions become available. It will ask your permission to download the matching language server version binary if needed.
We ship nightly releases for VS Code. To help us out with testing the newest code and follow the bleeding edge of our master, please use the following config:
{ "rust-analyzer.updates.channel": "nightly" }You will be prompted to install the nightly extension version. Just click Download now and from that moment you will get automatic updates every 24 hours.
If you don’t want to be asked for Download now every day when the new nightly version is released add the following to your settings.json:
{ "rust-analyzer.updates.askBeforeDownload": false }|
Note
|
Nightly extension should only be installed via the Download now action from VS Code.
|
Alternatively, both the server and the plugin can be installed from source:
$ git clone https://github.com/rust-analyzer/rust-analyzer.git && cd rust-analyzer
$ cargo xtask installYou’ll need Cargo, nodejs and npm for this.
Note that installing via xtask install does not work for VS Code Remote, instead you’ll need to install the .vsix manually.
Here are some useful self-diagnostic commands:
-
Rust Analyzer: Show RA Version shows the version of
rust-analyzerbinary. -
Rust Analyzer: Status prints some statistics about the server, and dependency information for the current file.
-
To enable server-side logging, run with
env RA_LOG=infoand seeOutput > Rust Analyzer Language Serverin VS Code’s panel. -
To log project loading (sysroot &
cargo metadata), setRA_LOG=project_model=debug. -
To log all LSP requests, add
"rust-analyzer.trace.server": "verbose"to the settings and look forRust Analyzer Language Server Tracein the panel. -
To enable client-side logging, add
"rust-analyzer.trace.extension": trueto the settings and openOutput > Rust Analyzer Clientin the panel.
Other editors generally require the rust-analyzer binary to be in $PATH.
You can download the pre-built binary from the releases page.
Typically, you then need to rename the binary for your platform, e.g. rust-analyzer-mac if you’re on Mac OS, to rust-analyzer and make it executable in addition to moving it into a directory in your $PATH.
On Linux to install the rust-analyzer binary into ~/.local/bin, this commands could be used
$ curl -L https://github.com/rust-analyzer/rust-analyzer/releases/latest/download/rust-analyzer-linux -o ~/.local/bin/rust-analyzer
$ chmod +x ~/.local/bin/rust-analyzerEnsure ~/.local/bin is listed in the $PATH variable.
Alternatively, you can install it from source using the following command:
$ git clone https://github.com/rust-analyzer/rust-analyzer.git && cd rust-analyzer
$ cargo xtask install --serverIf your editor can’t find the binary even though the binary is on your $PATH, the likely explanation is that it doesn’t see the same $PATH as the shell, see this issue.
On Unix, running the editor from a shell or changing the .desktop file to set the environment should help.
The rust-analyzer binary can be installed from the repos or AUR (Arch User Repository):
-
rust-analyzer(built from latest tagged source) -
rust-analyzer-git(latest Git version)
Install it with pacman, for example:
$ pacman -S rust-analyzerPrerequisites: You have installed the rust-analyzer binary.
Emacs support is maintained as part of the Emacs-LSP package in lsp-rust.el.
-
Install the most recent version of
emacs-lsppackage by following the Emacs-LSP instructions. -
Set
lsp-rust-serverto'rust-analyzer. -
Run
lspin a Rust buffer. -
(Optionally) bind commands like
lsp-rust-analyzer-join-lines,lsp-extend-selectionandlsp-rust-analyzer-expand-macroto keys.
Prerequisites: You have installed the rust-analyzer binary. Not needed if the extension can install/update it on its own, coc-rust-analyzer is one example.
The are several LSP client implementations for vim or neovim:
-
Install coc.nvim by following the instructions at coc.nvim (Node.js required)
-
Run
:CocInstall coc-rust-analyzerto install coc-rust-analyzer, this extension implements most of the features supported in the VSCode extension:-
automatically install and upgrade stable/nightly releases
-
same configurations as VSCode extension,
rust-analyzer.serverPath,rust-analyzer.cargo.featuresetc. -
same commands too,
rust-analyzer.analyzerStatus,rust-analyzer.ssretc. -
inlay hints for method chaining support, Neovim Only
-
semantic highlighting is not implemented yet
-
-
Install LanguageClient-neovim by following the instructions here
-
The GitHub project wiki has extra tips on configuration
-
-
Configure by adding this to your vim/neovim config file (replacing the existing Rust-specific line if it exists):
let g:LanguageClient_serverCommands = { \ 'rust': ['rust-analyzer'], \ }
-
Install YouCompleteMe by following the instructions here
-
Configure by adding this to your vim/neovim config file (replacing the existing Rust-specific line if it exists):
let g:ycm_language_server = \ [ \ { \ 'name': 'rust', \ 'cmdline': ['rust-analyzer'], \ 'filetypes': ['rust'], \ 'project_root_files': ['Cargo.toml'] \ } \ ]
NeoVim 0.5 (not yet released) has built-in language server support.
For a quick start configuration of rust-analyzer, use neovim/nvim-lsp.
Once neovim/nvim-lsp is installed, use lua require'nvim_lsp'.rust_analyzer.setup({}) in your init.vim.
Prerequisites: You have installed the rust-analyzer binary.
You also need the LSP package. To install it:
-
If you’ve never installed a Sublime Text package, install Package Control:
-
Open the command palette (Win/Linux:
ctrl+shift+p, Mac:cmd+shift+p) -
Type
Install Package Control, press enter
-
-
In the command palette, run
Package control: Install package, and in the list that pops up, typeLSPand press enter.
Finally, with your Rust project open, in the command palette, run LSP: Enable Language Server In Project or LSP: Enable Language Server Globally, then select rust-analyzer in the list that pops up to enable the rust-analyzer LSP. The latter means that rust-analyzer is enabled by default in Rust projects.
If it worked, you should see "rust-analyzer, Line X, Column Y" on the left side of the bottom bar, and after waiting a bit, functionality like tooltips on hovering over variables should become available.
If you get an error saying No such file or directory: 'rust-analyzer', see the rust-analyzer binary section on installing the language server binary.
rust-analyzer does not require Cargo.
However, if you use some other build system, you’ll have to describe the structure of your project for rust-analyzer in the rust-project.json format:
interface JsonProject {
/// Path to the directory with *source code* of sysroot crates.
///
/// It should point to the directory where std, core, and friends can be found:
/// https://github.com/rust-lang/rust/tree/master/library.
///
/// If provided, rust-analyzer automatically adds dependencies on sysroot
/// crates. Conversely, if you omit this path, you can specify sysroot
/// dependencies yourself and, for example, have several different "sysroots" in
/// one graph of crates.
sysroot_src?: string;
/// The set of crates comprising the current project.
/// Must include all transitive dependencies as well as sysroot crate (libstd, libcore and such).
crates: Crate[];
}
interface Crate {
/// Optional crate name used for display purposes, without affecting semantics.
/// See the `deps` key for semantically-significant crate names.
display_name?: string;
/// Path to the root module of the crate.
root_module: string;
/// Edition of the crate.
edition: "2015" | "2018";
/// Dependencies
deps: Dep[];
/// Should this crate be treated as a member of current "workspace".
///
/// By default, inferred from the `root_module` (members are the crates which reside
/// inside the directory opened in the editor).
///
/// Set this to `false` for things like standard library and 3rd party crates to
/// enable performance optimizations (rust-analyzer assumes that non-member crates
/// don't change).
is_workspace_member?: boolean;
/// Optionally specify the (super)set of `.rs` files comprising this crate.
///
/// By default, rust-analyzer assumes that only files under `root_module.parent` can belong to a crate.
/// `include_dirs` are included recursively, unless a subdirectory is in `exclude_dirs`.
///
/// Different crates can share the same `source`.
///
/// If two crates share an `.rs` file in common, they *must* have the same `source`.
/// rust-analyzer assumes that files from one source can't refer to files in another source.
source?: {
include_dirs: string[],
exclude_dirs: string[],
},
/// The set of cfgs activated for a given crate, like `["unix", "feature=foo", "feature=bar"]`.
cfg: string[];
/// Target triple for this Crate.
///
/// Used when running `rustc --print cfg` to get target-specific cfgs.
target?: string;
/// Environment variables, used for the `env!` macro
env: : { [key: string]: string; },
/// For proc-macro crates, path to compiles proc-macro (.so file).
proc_macro_dylib_path?: string;
}
interface Dep {
/// Index of a crate in the `crates` array.
crate: number,
/// Name as should appear in the (implicit) `extern crate name` declaration.
name: string,
}This format is provisional and subject to change.
Specifically, the roots setup will be different eventually.
There are tree ways to feed rust-project.json to rust-analyzer:
-
Place
rust-project.jsonfile at the root of the project, and rust-anlayzer will discover it. -
Specify
"rust-analyzer.linkedProjects": [ "path/to/rust-project.json" ]in the settings (and make sure that your LSP client sends settings as a part of initialize request). -
Specify
"rust-analyzer.linkedProjects": [ { "roots": […], "crates": […] }]inline.
Relative paths are interpreted relative to rust-project.json file location or (for inline JSON) relative to rootUri.
See https://github.com/rust-analyzer/rust-project.json-example for a small example.
You can set RA_LOG environmental variable to rust_analyzer=info to inspect how rust-analyzer handles config and project loading.
Assists, or code actions, are small local refactorings, available in a particular context.
They are usually triggered by a shortcut or by clicking a light bulb icon in the editor.
Cursor position or selection is signified by ┃ character.
While most errors and warnings provided by rust-analyzer come from the cargo check integration, there’s a growing number of diagnostics implemented using rust-analyzer’s own analysis.
These diagnostics don’t respect [allow] or [deny] attributes yet, but can be turned off using the rust-analyzer.diagnostics.enable, rust-analyzer.diagnostics.enableExperimental or rust-analyzer.diagnostics.disabled settings.
It is possible to change the foreground/background color of inlay hints. Just add this to your
settings.json:
You can customize the look of different semantic elements in the source code. For example, mutable bindings are underlined by default and you can override this behavior by adding the following section to your settings.json:
{
"editor.semanticTokenColorCustomizations": {
"rules": {
"*.mutable": {
"fontStyle": "", // underline is the default
},
}
},
}You may use inRustProject context to configure keybindings for rust projects only. For example:
{
"key": "ctrl+i",
"command": "rust-analyzer.toggleInlayHints",
"when": "inRustProject"
}More about when clause contexts here.
You can use "rust-analyzer.runnableEnv" setting to define runnable environment-specific substitution variables. The simplest way for all runnables in a bunch:
"rust-analyzer.runnableEnv": {
"RUN_SLOW_TESTS": "1"
}Or it is possible to specify vars more granularly:
"rust-analyzer.runnableEnv": [
{
// "mask": null, // null mask means that this rule will be applied for all runnables
env: {
"APP_ID": "1",
"APP_DATA": "asdf"
}
},
{
"mask": "test_name",
"env": {
"APP_ID": "2", // overwrites only APP_ID
}
}
]You can use any valid RegExp as a mask. Also note that a full runnable name is something like run bin_or_example_name, test some::mod::test_name or test-mod some::mod, so it is possible to distinguish binaries, single tests, and test modules with this masks: "^run", "^test " (the trailing space matters!), and "^test-mod" respectively.
Instead of relying on the built-in cargo check, you can configure Code to run a command in the background and use the $rustc-watch problem matcher to generate inline error markers from its output.
To do this you need to create a new VS Code Task and set rust-analyzer.checkOnSave.enable: false in preferences.
For example, if you want to run cargo watch instead, you might add the following to .vscode/tasks.json:
{
"label": "Watch",
"group": "build",
"type": "shell",
"command": "cargo watch",
"problemMatcher": "$rustc-watch",
"isBackground": true
}
{ "workbench.colorCustomizations": { // Name of the theme you are currently using "[Default Dark+]": { "rust_analyzer.inlayHints.foreground": "#868686f0", "rust_analyzer.inlayHints.background": "#3d3d3d48", // Overrides for specific kinds of inlay hints "rust_analyzer.inlayHints.foreground.typeHints": "#fdb6fdf0", "rust_analyzer.inlayHints.foreground.paramHints": "#fdb6fdf0", "rust_analyzer.inlayHints.background.chainingHints": "#6b0c0c81" } } }