aboutsummaryrefslogtreecommitdiff
path: root/docs/user/manual.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'docs/user/manual.adoc')
-rw-r--r--docs/user/manual.adoc282
1 files changed, 282 insertions, 0 deletions
diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc
new file mode 100644
index 000000000..f40139804
--- /dev/null
+++ b/docs/user/manual.adoc
@@ -0,0 +1,282 @@
1= User Manual
2:toc: preamble
3:sectanchors:
4:page-layout: post
5// https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74#admonitions
6:tip-caption: :bulb:
7:note-caption: :information_source:
8:important-caption: :heavy_exclamation_mark:
9:caution-caption: :fire:
10:warning-caption: :warning:
11:source-highlighter: rouge
12:experimental:
13
14// Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository
15
16At its core, rust-analyzer is a *library* for semantic analysis of Rust code as it changes over time.
17This manual focuses on a specific usage of the library -- running it as part of a server that implements the
18https://microsoft.github.io/language-server-protocol/[Language Server Protocol] (LSP).
19The 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.
20
21To improve this document, send a pull request against
22https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/manual.adoc[this file].
23
24If you have questions about using rust-analyzer, please ask them in the https://users.rust-lang.org/c/ide/14["`IDEs and Editors`"] topic of Rust users forum.
25
26== Installation
27
28In theory, one should be able to just install the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>> and have it automatically work with any editor.
29We are not there yet, so some editor specific setup is required.
30
31Additionally, rust-analyzer needs the sources of the standard library.
32If the source code is not present, rust-analyzer will attempt to install it automatically.
33
34To add the sources manually, run the following command:
35
36```bash
37$ rustup component add rust-src
38```
39
40=== VS Code
41
42This is the best supported editor at the moment.
43The rust-analyzer plugin for VS Code is maintained
44https://github.com/rust-analyzer/rust-analyzer/tree/master/editors/code[in tree].
45
46You can install the latest release of the plugin from
47https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer[the marketplace].
48By default, the plugin will prompt you to download the matching version of the server as well:
49
50image::https://user-images.githubusercontent.com/9021944/75067008-17502500-54ba-11ea-835a-f92aac50e866.png[]
51
52[NOTE]
53====
54To disable this notification put the following to `settings.json`
55
56[source,json]
57----
58{ "rust-analyzer.updates.askBeforeDownload": false }
59----
60====
61
62The server binary is stored in:
63
64* Linux: `~/.config/Code/User/globalStorage/matklad.rust-analyzer`
65* macOS: `~/Library/Application Support/Code/User/globalStorage/matklad.rust-analyzer`
66* Windows: `%APPDATA%\Code\User\globalStorage\matklad.rust-analyzer`
67
68Note that we only support two most recent versions of VS Code.
69
70==== Special `when` clause context for keybindings.
71You may use `inRustProject` context to configure keybindings for rust projects only. For example:
72[source,json]
73----
74{ "key": "ctrl+shift+f5", "command": "workbench.action.debug.restart", "when": "inDebugMode && !inRustProject"},
75{ "key": "ctrl+shift+f5", "command": "rust-analyzer.debug", "when": "inRustProject"},
76{ "key": "ctrl+i", "command": "rust-analyzer.toggleInlayHints", "when": "inRustProject" }
77----
78More about `when` clause contexts https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[here].
79
80==== Updates
81
82The 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.
83
84===== Nightly
85
86We 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:
87
88[source,json]
89----
90{ "rust-analyzer.updates.channel": "nightly" }
91----
92
93You 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.
94
95If 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`:
96[source,json]
97----
98{ "rust-analyzer.updates.askBeforeDownload": false }
99----
100
101NOTE: Nightly extension should **only** be installed via the `Download now` action from VS Code.
102
103==== Building From Source
104
105Alternatively, both the server and the plugin can be installed from source:
106
107[source]
108----
109$ git clone https://github.com/rust-analyzer/rust-analyzer.git && cd rust-analyzer
110$ cargo xtask install
111----
112
113You'll need Cargo, nodejs and npm for this.
114
115Note that installing via `xtask install` does not work for VS Code Remote, instead you'll need to install the `.vsix` manually.
116
117==== Troubleshooting
118
119Here are some useful self-diagnostic commands:
120
121* **Rust Analyzer: Show RA Version** shows the version of `rust-analyzer` binary
122* **Rust Analyzer: Status** prints some statistics about the server, like the few latest LSP requests
123* To enable server-side logging, run with `env RA_LOG=info` and see `Output > Rust Analyzer Language Server` in VS Code's panel.
124* To log all LSP requests, add `"rust-analyzer.trace.server": "verbose"` to the settings and look for `Server Trace` in the panel.
125* To enable client-side logging, add `"rust-analyzer.trace.extension": true` to the settings and open the `Console` tab of VS Code developer tools.
126
127=== rust-analyzer Language Server Binary
128
129Other editors generally require the `rust-analyzer` binary to be in `$PATH`.
130You 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-analyzer` and make it executable in addition to moving it into a directory in your `$PATH`.
131
132On Linux to install the `rust-analyzer` binary into `~/.local/bin`, this commands could be used
133
134[source,bash]
135----
136$ curl -L https://github.com/rust-analyzer/rust-analyzer/releases/latest/download/rust-analyzer-linux -o ~/.local/bin/rust-analyzer
137$ chmod +x ~/.local/bin/rust-analyzer
138----
139
140Ensure `~/.local/bin` is listed in the `$PATH` variable.
141
142Alternatively, you can install it from source using the following command:
143
144[source,bash]
145----
146$ git clone https://github.com/rust-analyzer/rust-analyzer.git && cd rust-analyzer
147$ cargo xtask install --server
148----
149
150If 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 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.
151
152==== Arch Linux
153
154The `rust-analyzer` binary can be installed from the repos or AUR (Arch User Repository):
155
156- https://www.archlinux.org/packages/community/x86_64/rust-analyzer/[`rust-analyzer`] (built from latest tagged source)
157- https://aur.archlinux.org/packages/rust-analyzer-git[`rust-analyzer-git`] (latest Git version)
158
159Install it with pacman, for example:
160
161[source,bash]
162----
163$ pacman -S rust-analyzer
164----
165
166=== Emacs
167
168Prerequisites: You have installed the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>>.
169
170Emacs support is maintained as part of the https://github.com/emacs-lsp/lsp-mode[Emacs-LSP] package in https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-rust.el[lsp-rust.el].
171
1721. Install the most recent version of `emacs-lsp` package by following the https://github.com/emacs-lsp/lsp-mode[Emacs-LSP instructions].
1732. Set `lsp-rust-server` to `'rust-analyzer`.
1743. Run `lsp` in a Rust buffer.
1754. (Optionally) bind commands like `lsp-rust-analyzer-join-lines`, `lsp-extend-selection` and `lsp-rust-analyzer-expand-macro` to keys.
176
177=== Vim/NeoVim
178
179Prerequisites: You have installed the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>>. Not needed if the extension can install/update it on its own, coc-rust-analyzer is one example.
180
181The are several LSP client implementations for vim or neovim:
182
183==== coc-rust-analyzer
184
1851. Install coc.nvim by following the instructions at
186 https://github.com/neoclide/coc.nvim[coc.nvim]
187 (Node.js required)
1882. Run `:CocInstall coc-rust-analyzer` to install
189 https://github.com/fannheyward/coc-rust-analyzer[coc-rust-analyzer],
190 this extension implements _most_ of the features supported in the VSCode extension:
191 * automatically install and upgrade stable/nightly releases
192 * same configurations as VSCode extension, `rust-analyzer.serverPath`, `rust-analyzer.cargo.features` etc.
193 * same commands too, `rust-analyzer.analyzerStatus`, `rust-analyzer.ssr` etc.
194 * inlay hints for method chaining support, _Neovim Only_
195 * semantic highlighting is not implemented yet
196
197==== LanguageClient-neovim
198
1991. Install LanguageClient-neovim by following the instructions
200 https://github.com/autozimu/LanguageClient-neovim[here]
201 * The GitHub project wiki has extra tips on configuration
202
2032. Configure by adding this to your vim/neovim config file (replacing the existing Rust-specific line if it exists):
204+
205[source,vim]
206----
207let g:LanguageClient_serverCommands = {
208\ 'rust': ['rust-analyzer'],
209\ }
210----
211
212==== YouCompleteMe
213
2141. Install YouCompleteMe by following the instructions
215 https://github.com/ycm-core/lsp-examples#rust-rust-analyzer[here]
216
2172. Configure by adding this to your vim/neovim config file (replacing the existing Rust-specific line if it exists):
218+
219[source,vim]
220----
221let g:ycm_language_server =
222\ [
223\ {
224\ 'name': 'rust',
225\ 'cmdline': ['rust-analyzer'],
226\ 'filetypes': ['rust'],
227\ 'project_root_files': ['Cargo.toml']
228\ }
229\ ]
230----
231
232==== ALE
233
234To use the LSP server in https://github.com/dense-analysis/ale[ale]:
235
236[source,vim]
237----
238let g:ale_linters = {'rust': ['analyzer']}
239----
240
241==== nvim-lsp
242
243NeoVim 0.5 (not yet released) has built-in language server support.
244For a quick start configuration of rust-analyzer, use https://github.com/neovim/nvim-lsp#rust_analyzer[neovim/nvim-lsp].
245Once `neovim/nvim-lsp` is installed, use `+lua require'nvim_lsp'.rust_analyzer.setup({})+` in your `init.vim`.
246
247=== Sublime Text 3
248
249Prerequisites: You have installed the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>>.
250
251You also need the `LSP` package. To install it:
252
2531. If you've never installed a Sublime Text package, install Package Control:
254 * Open the command palette (Win/Linux: `ctrl+shift+p`, Mac: `cmd+shift+p`)
255 * Type `Install Package Control`, press enter
2562. In the command palette, run `Package control: Install package`, and in the list that pops up, type `LSP` and press enter.
257
258Finally, 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.
259
260If 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.
261
262If you get an error saying `No such file or directory: 'rust-analyzer'`, see the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>> section on installing the language server binary.
263
264=== GNOME Builder
265
266Prerequisites: You have installed the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>>.
267
268Gnome Builder currently has support for RLS, and there's no way to configure the language server executable. A future version might support `rust-analyzer` out of the box.
269
2701. Rename, symlink or copy the `rust-analyzer` binary to `rls` and place it somewhere Builder can find (in `PATH`, or under `~/.cargo/bin`).
2712. Enable the Rust Builder plugin.
272
273== Features
274
275include::./generated_features.adoc[]
276
277== Assists (Code Actions)
278
279Assists, or code actions, are small local refactorings, available in a particular context.
280They are usually triggered by a shortcut or by clicking a light bulb icon in the editor.
281
282See [assists.md](./assists.md) for the list of available assists.