aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/dev/README.md11
-rw-r--r--docs/user/README.md78
2 files changed, 63 insertions, 26 deletions
diff --git a/docs/dev/README.md b/docs/dev/README.md
index 732e4bdd3..991deaf90 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -74,7 +74,7 @@ relevant test and execute it (VS Code includes an action for running a single
74test). 74test).
75 75
76However, launching a VS Code instance with locally build language server is 76However, launching a VS Code instance with locally build language server is
77possible. There's "Run Extension (Dev Server)" launch configuration for this. 77possible. There's **"Run Extension (Dev Server)"** launch configuration for this.
78 78
79In general, I use one of the following workflows for fixing bugs and 79In general, I use one of the following workflows for fixing bugs and
80implementing features. 80implementing features.
@@ -88,7 +88,14 @@ Code to sanity check that the thing works as I expect.
88 88
89If the problem concerns only the VS Code extension, I use **Run Extension** 89If the problem concerns only the VS Code extension, I use **Run Extension**
90launch configuration from `launch.json`. Notably, this uses the usual 90launch configuration from `launch.json`. Notably, this uses the usual
91`ra_lsp_server` binary from `PATH`. After I am done with the fix, I use `cargo 91`ra_lsp_server` binary from `PATH`. For this it is important to have the following
92in `setting.json` file:
93```json
94{
95 "rust-analyzer.raLspServerPath": "ra_lsp_server"
96}
97```
98After I am done with the fix, I use `cargo
92xtask install --client-code` to try the new extension for real. 99xtask install --client-code` to try the new extension for real.
93 100
94If I need to fix something in the `ra_lsp_server` crate, I feel sad because it's 101If I need to fix something in the `ra_lsp_server` crate, I feel sad because it's
diff --git a/docs/user/README.md b/docs/user/README.md
index 3da30a193..6afe51e8b 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,38 @@ 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
40In order to build the VS Code plugin from sources, you need to have node.js and npm with
41a minimum version of 12 installed. Please refer to
42[node.js and npm documentation](https://nodejs.org) for installation instructions.
43
34### Installation from prebuilt binaries 44### Installation from prebuilt binaries
35 45
36We ship prebuilt binaries for Linux, Mac and Windows via 46We ship prebuilt binaries for Linux, Mac and Windows via
37[GitHub releases](https://github.com/rust-analyzer/rust-analyzer/releases). 47[GitHub releases][github-releases].
38In order to use them you need to install the client VSCode extension. 48In order to use them you need to install the client VSCode extension.
39 49
40Publishing to VSCode marketplace is currently WIP. Thus, you need to clone the repository and install **only** the client extension via 50Publishing to VS Code marketplace is currently WIP. Thus, you need to manually download
51`rust-analyzer-0.1.0.vsix` file from latest [GitHub release][github-releases].
52
53After you downloaded the `.vsix` file you can install it from the terminal
54
41``` 55```
42$ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1 56$ code --install-extension rust-analyzer-0.1.0.vsix
43$ cd rust-analyzer
44$ cargo xtask install --client-code
45``` 57```
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 58
59Or open VS Code, press <kbd>Ctrl+Shift+P</kbd>, and search for the following command:
60
61<img width="500px" alt="Install from VSIX command" src="https://user-images.githubusercontent.com/36276403/74108225-c0c11d80-4b80-11ea-9b2a-0a43f09e29af.png">
62
63Press <kbd>Enter</kbd> and go to `rust-analyzer-0.1.0.vsix` file through the file explorer.
64
65Then open some Rust project and you should
66see an info message pop-up.
49 67
50<img height="140px" src="https://user-images.githubusercontent.com/36276403/74103174-a40df100-4b52-11ea-81f4-372c70797924.png" alt="Download now message"/> 68<img height="140px" src="https://user-images.githubusercontent.com/36276403/74103174-a40df100-4b52-11ea-81f4-372c70797924.png" alt="Download now message"/>
51 69
@@ -57,7 +75,7 @@ For updates you need to remove installed binary
57rm -rf ${HOME}/.config/Code/User/globalStorage/matklad.rust-analyzer 75rm -rf ${HOME}/.config/Code/User/globalStorage/matklad.rust-analyzer
58``` 76```
59 77
60`"Donwload latest language server"` command for VSCode and automatic updates detection is currently WIP. 78`"Download latest language server"` command for VSCode and automatic updates detection is currently WIP.
61 79
62 80
63### Installation from sources 81### Installation from sources
@@ -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