aboutsummaryrefslogtreecommitdiff
path: root/docs/user/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/user/README.md')
-rw-r--r--docs/user/README.md78
1 files changed, 54 insertions, 24 deletions
diff --git a/docs/user/README.md b/docs/user/README.md
index 3da30a193..14ca6fd64 100644
--- a/docs/user/README.md
+++ b/docs/user/README.md
@@ -1,16 +1,26 @@
1[github-releases]: https://github.com/rust-analyzer/rust-analyzer/releases
2
1The main interface to rust-analyzer is the 3The main interface to rust-analyzer is the
2[LSP](https://microsoft.github.io/language-server-protocol/) implementation. To 4[LSP](https://microsoft.github.io/language-server-protocol/) implementation. To
3install lsp server, clone the repository and then run `cargo xtask install 5install lsp server, you have three options:
4--server` (which is shorthand for `cargo install --path 6
5./crates/ra_lsp_server`). This will produce a binary named `ra_lsp_server` which 7* **Preferred and default:** install the plugin/extension for your IDE and it will ask your permission to automatically download the latest lsp server for you from [GitHub releases][github-releases]. (See docs to find out whether this is implemented for your editor below).
6you should be able to use it with any LSP-compatible editor. We use custom 8* Manually download prebuilt binaries from [GitHub releases][github-releases]
7extensions to LSP, so special client-side support is required to take full 9 * `ra_lsp_server-linux` for Linux
8advantage of rust-analyzer. This repository contains support code for VS Code. 10 * `ra_lsp_server-mac` for Mac
9 11 * `ra_lsp_server-windows.exe` for Windows
10``` 12* Clone the repository and build from sources
13```bash
11$ git clone [email protected]:rust-analyzer/rust-analyzer && cd rust-analyzer 14$ git clone [email protected]:rust-analyzer/rust-analyzer && cd rust-analyzer
12$ cargo xtask install --server 15$ cargo xtask install --server # or cargo install --path ./crates/ra_lsp_server
13``` 16```
17
18This way you will get a binary named `ra_lsp_server` (with os suffix for prebuilt binaries)
19which you should be able to use with any LSP-compatible editor.
20
21We make use of custom extensions to LSP, so special client-side support is required to take full
22advantage of rust-analyzer. This repository contains support code for VS Code.
23
14Rust Analyzer needs sources of rust standard library to work, so 24Rust Analyzer needs sources of rust standard library to work, so
15you might also need to execute 25you might also need to execute
16 26
@@ -22,30 +32,34 @@ See [./features.md](./features.md) document for a list of features that are avai
22 32
23## VS Code 33## VS Code
24 34
25Prerequisites: 35### Prerequisites
26
27In order to build the VS Code plugin, you need to have node.js and npm with
28a minimum version of 10 installed. Please refer to
29[node.js and npm documentation](https://nodejs.org) for installation instructions.
30 36
31You will also need the most recent version of VS Code: we don't try to 37You will need the most recent version of VS Code: we don't try to
32maintain compatibility with older versions yet. 38maintain compatibility with older versions yet.
33 39
34### Installation from prebuilt binaries 40### Installation from prebuilt binaries
35 41
36We ship prebuilt binaries for Linux, Mac and Windows via 42We ship prebuilt binaries for Linux, Mac and Windows via
37[GitHub releases](https://github.com/rust-analyzer/rust-analyzer/releases). 43[GitHub releases][github-releases].
38In order to use them you need to install the client VSCode extension. 44In order to use them you need to install the client VSCode extension.
39 45
40Publishing to VSCode marketplace is currently WIP. Thus, you need to clone the repository and install **only** the client extension via 46Publishing to VS Code marketplace is currently WIP. Thus, you need to manually download
47`rust-analyzer-0.1.0.vsix` file from latest [GitHub release][github-releases].
48
49After you downloaded the `.vsix` file you can install it from the terminal
50
41``` 51```
42$ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1 52$ code --install-extension rust-analyzer-0.1.0.vsix
43$ cd rust-analyzer
44$ cargo xtask install --client-code
45``` 53```
46Then open VSCode (or reload the window if it was already running), open some Rust project and you should
47see an info message pop-up.
48 54
55Or open VS Code, press <kbd>Ctrl+Shift+P</kbd>, and search for the following command:
56
57<img width="500px" alt="Install from VSIX command" src="https://user-images.githubusercontent.com/36276403/74108225-c0c11d80-4b80-11ea-9b2a-0a43f09e29af.png">
58
59Press <kbd>Enter</kbd> and go to `rust-analyzer-0.1.0.vsix` file through the file explorer.
60
61Then open some Rust project and you should
62see an info message pop-up.
49 63
50<img height="140px" src="https://user-images.githubusercontent.com/36276403/74103174-a40df100-4b52-11ea-81f4-372c70797924.png" alt="Download now message"/> 64<img height="140px" src="https://user-images.githubusercontent.com/36276403/74103174-a40df100-4b52-11ea-81f4-372c70797924.png" alt="Download now message"/>
51 65
@@ -57,11 +71,15 @@ For updates you need to remove installed binary
57rm -rf ${HOME}/.config/Code/User/globalStorage/matklad.rust-analyzer 71rm -rf ${HOME}/.config/Code/User/globalStorage/matklad.rust-analyzer
58``` 72```
59 73
60`"Donwload latest language server"` command for VSCode and automatic updates detection is currently WIP. 74`"Download latest language server"` command for VSCode and automatic updates detection is currently WIP.
61 75
62 76
63### Installation from sources 77### Installation from sources
64 78
79In order to build the VS Code plugin from sources, you need to have node.js and npm with
80a minimum version of 12 installed. Please refer to
81[node.js and npm documentation](https://nodejs.org) for installation instructions.
82
65The experimental VS Code plugin can be built and installed by executing the 83The experimental VS Code plugin can be built and installed by executing the
66following commands: 84following commands:
67 85
@@ -71,6 +89,16 @@ $ cd rust-analyzer
71$ cargo xtask install 89$ cargo xtask install
72``` 90```
73 91
92After that you need to amend your `settings.json` file to explicitly specify the
93path to `ra_lsp_server` that you've just built.
94```json
95{
96 "rust-analyzer.raLspServerPath": "ra_lsp_server"
97}
98```
99This should work on all platforms, otherwise if installed `ra_lsp_server` is not available through your `$PATH` then see how to configure it [here](#setting-up-the-PATH-variable).
100
101
74The automatic installation is expected to *just work* for common cases, if it 102The automatic installation is expected to *just work* for common cases, if it
75doesn't, report bugs! 103doesn't, report bugs!
76 104
@@ -127,7 +155,7 @@ host.
127 As an example, [Pale Fire](https://github.com/matklad/pale-fire/) color scheme tweaks rust colors. 155 As an example, [Pale Fire](https://github.com/matklad/pale-fire/) color scheme tweaks rust colors.
128* `rust-analyzer.enableEnhancedTyping`: by default, rust-analyzer intercepts the 156* `rust-analyzer.enableEnhancedTyping`: by default, rust-analyzer intercepts the
129 `Enter` key to make it easier to continue comments. Note that it may conflict with VIM emulation plugin. 157 `Enter` key to make it easier to continue comments. Note that it may conflict with VIM emulation plugin.
130* `rust-analyzer.raLspServerPath`: path to `ra_lsp_server` executable 158* `rust-analyzer.raLspServerPath`: path to `ra_lsp_server` executable, when absent or `null` defaults to prebuilt binary path
131* `rust-analyzer.enableCargoWatchOnStartup`: prompt to install & enable `cargo 159* `rust-analyzer.enableCargoWatchOnStartup`: prompt to install & enable `cargo
132 watch` for live error highlighting (note, this **does not** use rust-analyzer) 160 watch` for live error highlighting (note, this **does not** use rust-analyzer)
133* `rust-analyzer.excludeGlobs`: a list of glob-patterns for exclusion (see globset [docs](https://docs.rs/globset) for syntax). 161* `rust-analyzer.excludeGlobs`: a list of glob-patterns for exclusion (see globset [docs](https://docs.rs/globset) for syntax).
@@ -232,6 +260,8 @@ Installation:
232 260
233* 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) 261* 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)
234 262
263
264<!-- Update links to this header when changing it! -->
235### Setting up the `PATH` variable 265### Setting up the `PATH` variable
236 266
237On Unix systems, `rustup` adds `~/.cargo/bin` to `PATH` by modifying the shell's 267On Unix systems, `rustup` adds `~/.cargo/bin` to `PATH` by modifying the shell's