diff options
Diffstat (limited to 'docs/user/README.md')
-rw-r--r-- | docs/user/README.md | 78 |
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 | |||
1 | The main interface to rust-analyzer is the | 3 | The 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 |
3 | install lsp server, clone the repository and then run `cargo xtask install | 5 | install 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). |
6 | you should be able to use it with any LSP-compatible editor. We use custom | 8 | * Manually download prebuilt binaries from [GitHub releases][github-releases] |
7 | extensions to LSP, so special client-side support is required to take full | 9 | * `ra_lsp_server-linux` for Linux |
8 | advantage 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 | |||
18 | This way you will get a binary named `ra_lsp_server` (with os suffix for prebuilt binaries) | ||
19 | which you should be able to use with any LSP-compatible editor. | ||
20 | |||
21 | We make use of custom extensions to LSP, so special client-side support is required to take full | ||
22 | advantage of rust-analyzer. This repository contains support code for VS Code. | ||
23 | |||
14 | Rust Analyzer needs sources of rust standard library to work, so | 24 | Rust Analyzer needs sources of rust standard library to work, so |
15 | you might also need to execute | 25 | you 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 | ||
25 | Prerequisites: | 35 | ### Prerequisites |
26 | |||
27 | In order to build the VS Code plugin, you need to have node.js and npm with | ||
28 | a minimum version of 10 installed. Please refer to | ||
29 | [node.js and npm documentation](https://nodejs.org) for installation instructions. | ||
30 | 36 | ||
31 | You will also need the most recent version of VS Code: we don't try to | 37 | You will need the most recent version of VS Code: we don't try to |
32 | maintain compatibility with older versions yet. | 38 | maintain compatibility with older versions yet. |
33 | 39 | ||
34 | ### Installation from prebuilt binaries | 40 | ### Installation from prebuilt binaries |
35 | 41 | ||
36 | We ship prebuilt binaries for Linux, Mac and Windows via | 42 | We 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]. |
38 | In order to use them you need to install the client VSCode extension. | 44 | In order to use them you need to install the client VSCode extension. |
39 | 45 | ||
40 | Publishing to VSCode marketplace is currently WIP. Thus, you need to clone the repository and install **only** the client extension via | 46 | Publishing 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 | |||
49 | After 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 | ``` |
46 | Then open VSCode (or reload the window if it was already running), open some Rust project and you should | ||
47 | see an info message pop-up. | ||
48 | 54 | ||
55 | Or 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 | |||
59 | Press <kbd>Enter</kbd> and go to `rust-analyzer-0.1.0.vsix` file through the file explorer. | ||
60 | |||
61 | Then open some Rust project and you should | ||
62 | see 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 | |||
57 | rm -rf ${HOME}/.config/Code/User/globalStorage/matklad.rust-analyzer | 71 | rm -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 | ||
79 | In order to build the VS Code plugin from sources, you need to have node.js and npm with | ||
80 | a minimum version of 12 installed. Please refer to | ||
81 | [node.js and npm documentation](https://nodejs.org) for installation instructions. | ||
82 | |||
65 | The experimental VS Code plugin can be built and installed by executing the | 83 | The experimental VS Code plugin can be built and installed by executing the |
66 | following commands: | 84 | following commands: |
67 | 85 | ||
@@ -71,6 +89,16 @@ $ cd rust-analyzer | |||
71 | $ cargo xtask install | 89 | $ cargo xtask install |
72 | ``` | 90 | ``` |
73 | 91 | ||
92 | After that you need to amend your `settings.json` file to explicitly specify the | ||
93 | path to `ra_lsp_server` that you've just built. | ||
94 | ```json | ||
95 | { | ||
96 | "rust-analyzer.raLspServerPath": "ra_lsp_server" | ||
97 | } | ||
98 | ``` | ||
99 | This 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 | |||
74 | The automatic installation is expected to *just work* for common cases, if it | 102 | The automatic installation is expected to *just work* for common cases, if it |
75 | doesn't, report bugs! | 103 | doesn'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 | ||
237 | On Unix systems, `rustup` adds `~/.cargo/bin` to `PATH` by modifying the shell's | 267 | On Unix systems, `rustup` adds `~/.cargo/bin` to `PATH` by modifying the shell's |