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