204 lines
8.8 KiB
Plaintext
204 lines
8.8 KiB
Plaintext
= User Manual
|
|
:toc: preamble
|
|
:sectanchors:
|
|
:page-layout: post
|
|
// https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74#admonitions
|
|
:tip-caption: :bulb:
|
|
:note-caption: :information_source:
|
|
:important-caption: :heavy_exclamation_mark:
|
|
:caution-caption: :fire:
|
|
:warning-caption: :warning:
|
|
|
|
|
|
|
|
// Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository
|
|
|
|
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
|
|
https://microsoft.github.io/language-server-protocol/[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.
|
|
|
|
To improve this document, send a pull request against
|
|
https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/readme.adoc[this file].
|
|
|
|
== Installation
|
|
|
|
In theory, one should be able to just install the server 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:
|
|
|
|
```bash
|
|
$ rustup component add rust-src
|
|
```
|
|
|
|
=== VS Code
|
|
|
|
This is the best supported editor at the moment.
|
|
The rust-analyzer plugin for VS Code is maintained
|
|
https://github.com/rust-analyzer/rust-analyzer/tree/master/editors/code[in tree].
|
|
|
|
You can install the latest release of the plugin from
|
|
https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer[the marketplace].
|
|
By default, the plugin will prompt you to download the matching version of the server as well:
|
|
|
|
image::https://user-images.githubusercontent.com/9021944/75067008-17502500-54ba-11ea-835a-f92aac50e866.png[]
|
|
|
|
[NOTE]
|
|
====
|
|
To disable this notification put the following to `settings.json`
|
|
|
|
[source,json]
|
|
----
|
|
{ "rust-analyzer.updates.askBeforeDownload": false }
|
|
----
|
|
====
|
|
|
|
The server binary is stored in `~/.config/Code/User/globalStorage/matklad.rust-analyzer` (Linux) or in `~/.Library/Application Support/Code/User/globalStorage/matklad.rust-analyzer` (macOS) or in `%APPDATA%\Code\User\globalStorage` (Windows).
|
|
|
|
Note that we only support the latest version of VS Code.
|
|
|
|
==== Updates
|
|
|
|
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.
|
|
|
|
===== Nightly
|
|
|
|
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:
|
|
|
|
[source,json]
|
|
----
|
|
{ "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`:
|
|
[source,json]
|
|
----
|
|
{ "rust-analyzer.updates.askBeforeDownload": false }
|
|
----
|
|
|
|
NOTE: Nightly extension should **only** be installed via the `Download now` action from VS Code.
|
|
|
|
==== Building From Source
|
|
|
|
Alternatively, both the server and the plugin can be installed from source:
|
|
|
|
[source]
|
|
----
|
|
$ git clone https://github.com/rust-analyzer/rust-analyzer.git && cd rust-analyzer
|
|
$ cargo xtask install
|
|
----
|
|
|
|
You'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.
|
|
|
|
==== Troubleshooting
|
|
|
|
Here are some useful self-diagnostic commands:
|
|
|
|
* **Rust Analyzer: Show RA Version** shows the version of `rust-analyzer` binary
|
|
* **Rust Analyzer: Status** prints some statistics about the server, like the few latest LSP requests
|
|
* To enable server-side logging, run with `env RUST_LOG=info` and see `Output > Rust Analyzer Language Server` in VS Code's panel.
|
|
* To log all LSP requests, add `"rust-analyzer.trace.server": "verbose"` to the settings and look for `Server Trace` in the panel.
|
|
* To enable client-side logging, add `"rust-analyzer.trace.extension": true` to the settings and open the `Console` tab of VS Code developer tools.
|
|
|
|
=== Language Server Binary
|
|
|
|
Other editors generally require the `rust-analyzer` binary to be in `$PATH`.
|
|
You can download the pre-built binary from the https://github.com/rust-analyzer/rust-analyzer/releases[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-analzyer` and make it executable in addition to moving it into a directory in your `$PATH`.
|
|
|
|
Alternatively, you can install it from source using the following command:
|
|
|
|
[source,bash]
|
|
----
|
|
$ cargo xtask install --server
|
|
----
|
|
|
|
==== Arch Linux
|
|
|
|
The `rust-analyzer` binary can be installed from AUR (Arch User Repository):
|
|
|
|
- https://aur.archlinux.org/packages/rust-analyzer-bin[`rust-analyzer-bin`] (binary from GitHub releases)
|
|
- https://aur.archlinux.org/packages/rust-analyzer[`rust-analyzer`] (built from latest tagged source)
|
|
- https://aur.archlinux.org/packages/rust-analyzer-git[`rust-analyzer-git`] (latest git version)
|
|
|
|
Install it with AUR helper of your choice, for example:
|
|
|
|
[source,bash]
|
|
----
|
|
$ yay -S rust-analyzer-bin
|
|
----
|
|
|
|
=== Emacs
|
|
|
|
Emacs support is maintained https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-rust.el[upstream].
|
|
|
|
1. Install the most recent version of `emacs-lsp` package by following the instructions https://github.com/emacs-lsp/lsp-mode[here].
|
|
2. Set `lsp-rust-server` to `'rust-analyzer`.
|
|
3. Run `lsp` in a Rust buffer.
|
|
4. (Optionally) bind commands like `lsp-rust-analyzer-join-lines`, `lsp-extend-selection` and `lsp-rust-analyzer-expand-macro` to keys.
|
|
|
|
=== Vim
|
|
|
|
The are several LSP client implementations for vim:
|
|
|
|
==== coc-rust-analyzer
|
|
|
|
1. Install coc.nvim by following the instructions at
|
|
https://github.com/neoclide/coc.nvim[coc.nvim]
|
|
(nodejs required)
|
|
2. Run `:CocInstall coc-rust-analyzer` to install
|
|
https://github.com/fannheyward/coc-rust-analyzer[coc-rust-analyzer],
|
|
this extension implements _most_ of the features supported in the VSCode extension:
|
|
* same configurations as VSCode extension, `rust-analyzer.serverPath`, `rust-analyzer.enableCargoWatchOnStartup` etc.
|
|
* same commands too, `rust-analyzer.analyzerStatus`, `rust-analyzer.startCargoWatch` etc.
|
|
* highlighting and inlay_hints are not implemented yet
|
|
|
|
==== LanguageClient-neovim
|
|
|
|
1. Install LanguageClient-neovim by following the instructions
|
|
https://github.com/autozimu/LanguageClient-neovim[here]
|
|
* The github project wiki has extra tips on configuration
|
|
|
|
2. Configure by adding this to your vim/neovim config file (replacing the existing Rust-specific line if it exists):
|
|
+
|
|
[source,vim]
|
|
----
|
|
let g:LanguageClient_serverCommands = {
|
|
\ 'rust': ['rust-analyzer'],
|
|
\ }
|
|
----
|
|
|
|
==== nvim-lsp
|
|
|
|
NeoVim 0.5 (not yet released) has built-in language server support.
|
|
For a quick start configuration of rust-analyzer, use https://github.com/neovim/nvim-lsp#rust_analyzer[neovim/nvim-lsp].
|
|
Once `neovim/nvim-lsp` is installed, use `+lua require'nvim_lsp'.rust_analyzer.setup({})+` in your `init.vim`.
|
|
|
|
=== Sublime Text 3
|
|
|
|
Prerequisites: You have installed the <<language-server-binary,`rust-analyzer` binary>>.
|
|
|
|
You also need the `LSP` package. To install it:
|
|
|
|
1. 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
|
|
2. In the command palette, run `Package control: Install package`, and in the list that pops up, type `LSP` and 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-analzyer is enabled by default in Rust projects.
|
|
|
|
If it worked, you should see "rust-analzyer, 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'` even though the binary is on your `$PATH`, the likely explanation is that Sublime doesn't see the same `$PATH` as the shell, see https://github.com/rust-analyzer/rust-analyzer/issues/1811[this issue]. On Unix, running the editor from a shell or changing the `.desktop` file to set the environment, should help.
|
|
|
|
== Usage
|
|
|
|
See https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/features.md[features.md].
|