diff options
Diffstat (limited to 'docs/user/readme.adoc')
-rw-r--r-- | docs/user/readme.adoc | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/docs/user/readme.adoc b/docs/user/readme.adoc new file mode 100644 index 000000000..b9ecc7055 --- /dev/null +++ b/docs/user/readme.adoc | |||
@@ -0,0 +1,152 @@ | |||
1 | = User Manual | ||
2 | :toc: preamble | ||
3 | :sectanchors: | ||
4 | :page-layout: post | ||
5 | |||
6 | |||
7 | // Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository | ||
8 | |||
9 | At it's core, rust-analyzer is a *library* for semantic analysis of the Rust code as it changes over time. | ||
10 | This manual focuses on a specific usage of the library -- the implementation of | ||
11 | https://microsoft.github.io/language-server-protocol/[Language Server Protocol]. | ||
12 | LSP allows various code editors, like VS Code, Emacs or Vim, to implement semantic feature like completion or goto definition by talking to an external language server process. | ||
13 | |||
14 | == Installation | ||
15 | |||
16 | In theory, one should be able to just install the server binary and have it automatically work with any editor. | ||
17 | We are not there yet, so some editor specific setup is required. | ||
18 | |||
19 | === VS Code | ||
20 | |||
21 | This the best supported editor at the moment. | ||
22 | rust-analyzer plugin for VS Code is maintained | ||
23 | https://github.com/rust-analyzer/rust-analyzer/tree/master/editors/code[in tree]. | ||
24 | |||
25 | You can install the latest release of the plugin from | ||
26 | https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer[the marketplace]. | ||
27 | By default, the plugin will download the latest version of the server as well. | ||
28 | |||
29 | image::https://user-images.githubusercontent.com/36276403/74103174-a40df100-4b52-11ea-81f4-372c70797924.png[] | ||
30 | |||
31 | The server binary is stored in `~/.config/Code/User/globalStorage/matklad.rust-analyzer`. | ||
32 | |||
33 | Note that we only support the latest version of VS Code. | ||
34 | |||
35 | ==== Updates | ||
36 | |||
37 | The extension will be updated automatically as new versions become available. | ||
38 | The server update functionality is in progress. | ||
39 | For the time being, the workaround is to remove the binary from `globalStorage` and to restart the extension. | ||
40 | |||
41 | ==== Building From Source | ||
42 | |||
43 | Alternatively, both the server and the plugin can be installed from source: | ||
44 | |||
45 | [source] | ||
46 | ---- | ||
47 | $ git clone https://github.com/rust-analyzer/rust-analyzer.git && cs rust-analyzer | ||
48 | $ cargo xtask install | ||
49 | ---- | ||
50 | |||
51 | You'll need Cargo, nodejs and npm for this. | ||
52 | To make VS Code use the freshly build server, add this to the settings: | ||
53 | |||
54 | [source,json] | ||
55 | ---- | ||
56 | { "rust-analyzer.raLspServerPath": "ra_lsp_server" } | ||
57 | ---- | ||
58 | |||
59 | Note that installing via `xtask install` does not work for VS Code Remote, instead you'll need to install the `.vsix` manually. | ||
60 | |||
61 | === Language Server Binary | ||
62 | |||
63 | Other editors generally require `ra_lsp_server` binary to be in `$PATH`. | ||
64 | You can download pre-build binary from | ||
65 | https://github.com/rust-analyzer/rust-analyzer/releases[relases] | ||
66 | page, or you can install it from source using the following command: | ||
67 | |||
68 | [source,bash] | ||
69 | ---- | ||
70 | $ cargo xtask install --server | ||
71 | ---- | ||
72 | |||
73 | === Emacs | ||
74 | |||
75 | Emacs support is maintained https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-rust.el[upstream]. | ||
76 | |||
77 | 1. Install recent version of `emacs-lsp` package by following the instructions https://github.com/emacs-lsp/lsp-mode[here]. | ||
78 | 2. Set `lsp-rust-server` to `'rust-analyzer`. | ||
79 | 3. Run `lsp` in a Rust buffer. | ||
80 | 4. (Optionally) bind commands like `lsp-rust-analyzer-join-lines`, `lsp-extend-selection` and `lsp-rust-analyzer-expand-macro` to keys. | ||
81 | |||
82 | === Vim | ||
83 | |||
84 | The are several LSP client implementations for vim: | ||
85 | |||
86 | ==== coc-rust-analyzer | ||
87 | |||
88 | 1. Install coc.nvim by following the instructions at | ||
89 | https://github.com/neoclide/coc.nvim[coc.nvim] | ||
90 | (nodejs required) | ||
91 | 2. Run `:CocInstall coc-rust-analyzer` to install | ||
92 | https://github.com/fannheyward/coc-rust-analyzer[coc-rust-analyzer], | ||
93 | this extension implements _most_ of the features supported in the VSCode extension: | ||
94 | * same configurations as VSCode extension, `rust-analyzer.raLspServerPath`, `rust-analyzer.enableCargoWatchOnStartup` etc. | ||
95 | * same commands too, `rust-analyzer.analyzerStatus`, `rust-analyzer.startCargoWatch` etc. | ||
96 | * highlighting and inlay_hints are not implemented yet | ||
97 | |||
98 | ==== LanguageClient-neovim | ||
99 | |||
100 | 1. Install LanguageClient-neovim by following the instructions | ||
101 | https://github.com/autozimu/LanguageClient-neovim[here] | ||
102 | * The github project wiki has extra tips on configuration | ||
103 | |||
104 | 2. Configure by adding this to your vim/neovim config file (replacing the existing rust specific line if it exists): | ||
105 | + | ||
106 | [source,vim] | ||
107 | ---- | ||
108 | let g:LanguageClient_serverCommands = { | ||
109 | \ 'rust': ['ra_lsp_server'], | ||
110 | \ } | ||
111 | ---- | ||
112 | |||
113 | ==== nvim-lsp | ||
114 | |||
115 | NeoVim 0.5 (not yet released) has built in language server support. | ||
116 | For a quick start configuration of rust-analyzer, use https://github.com/neovim/nvim-lsp#rust_analyzer[neovim/nvim-lsp]. | ||
117 | Once `neovim/nvim-lsp` is installed, use `lua require'nvim_lsp'.rust_analyzer.setup({})` in your `init.vim`. | ||
118 | |||
119 | === Sublime Text 3 | ||
120 | |||
121 | Prerequisites: | ||
122 | |||
123 | `LSP` package. | ||
124 | |||
125 | Installation: | ||
126 | |||
127 | 1. Invoke the command palette with <kbd>Ctrl+Shift+P</kbd> | ||
128 | 2. Type `LSP Settings` to open the LSP preferences editor | ||
129 | 3. Add the following LSP client definition to your settings: | ||
130 | + | ||
131 | [source,json] | ||
132 | ---- | ||
133 | "rust-analyzer": { | ||
134 | "command": ["ra_lsp_server"], | ||
135 | "languageId": "rust", | ||
136 | "scopes": ["source.rust"], | ||
137 | "syntaxes": [ | ||
138 | "Packages/Rust/Rust.sublime-syntax", | ||
139 | "Packages/Rust Enhanced/RustEnhanced.sublime-syntax" | ||
140 | ], | ||
141 | "initializationOptions": { | ||
142 | "featureFlags": { | ||
143 | } | ||
144 | }, | ||
145 | } | ||
146 | ---- | ||
147 | |||
148 | 4. You can now invoke the command palette and type LSP enable to locally/globally enable the rust-analyzer LSP (type LSP enable, then choose either locally or globally, then select rust-analyzer) | ||
149 | |||
150 | == Usage | ||
151 | |||
152 | See https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/features.md[features.md]. | ||