editors/README.md

   1
   2 Preqrequisites:
   3
   4 In order to build the VS Code plugin, you need to have node.js and npm with
   5 a minimum version of 10 installed. Please refer to
   6 [node.js and npm documentation](https://nodejs.org) for installation instructions.
   7
   8 You will also need the most recent version of VS Code: we don't try to
   9 maintain compatibility with older versions yet.
  10
  11 The experimental VS Code plugin can then be built and installed by executing the
  12 following commands:
  13
  14 ```
  15 $ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1
  16 $ cd rust-analyzer
  17 $ cargo install-code
  18
  19 # for stdlib support
  20 $ rustup component add rust-src
  21 ```
  22
  23 This will run `cargo install --package ra_lsp_server` to install the server
  24 binary into `~/.cargo/bin`, and then will build and install plugin from
  25 `editors/code`. See
  26 [this](https://github.com/rust-analyzer/rust-analyzer/blob/0199572a3d06ff66eeae85a2d2c9762996f0d2d8/crates/tools/src/main.rs#L150)
  27 for details. The installation is expected to *just work*, if it doesn't, report
  28 bugs!
  29
  30 It's better to remove existing Rust plugins to avoid interference.
  31
  32 ## Rust Analyzer Specific Features
  33
  34 These features are implemented as extensions to the language server protocol.
  35 They are more experimental in nature and work only with VS Code.
  36
  37 ### Syntax highlighting
  38
  39 It overrides built-in highlighting, and works only with a specific theme
  40 (zenburn). `rust-analyzer.highlightingOn` setting can be used to disable it.
  41
  42 ### Go to symbol in workspace <kbd>ctrl+t</kbd>
  43
  44 It mostly works on top of the built-in LSP functionality, however `#` and `*`
  45 symbols can be used to narrow down the search. Specifically,
  46
  47 - `#Foo` searches for `Foo` type in the current workspace
  48 - `#foo#` searches for `foo` function in the current workspace
  49 - `#Foo*` searches for `Foo` type among dependencies, excluding `stdlib`
  50 - `#foo#*` searches for `foo` function among dependencies.
  51
  52 That is, `#` switches from "types" to all symbols, `*` switches from the current
  53 workspace to dependencies.
  54
  55 ### Commands <kbd>ctrl+shift+p</kbd>
  56
  57 #### Show Rust Syntax Tree
  58
  59 Shows the parse tree of the current file. It exists mostly for debugging
  60 rust-analyzer itself.
  61
  62 #### Extend Selection
  63
  64 Extends the current selection to the encompassing syntactic construct
  65 (expression, statement, item, module, etc). It works with multiple cursors. Do
  66 bind this command to a key, its super-useful! Expected to be upstreamed to LSP soonish:
  67 https://github.com/Microsoft/language-server-protocol/issues/613
  68
  69 #### Matching Brace
  70
  71 If the cursor is on any brace (`<>(){}[]`) which is a part of a brace-pair,
  72 moves cursor to the matching brace. It uses the actual parser to determine
  73 braces, so it won't confuse generics with comparisons.
  74
  75 #### Parent Module
  76
  77 Navigates to the parent module of the current module.
  78
  79 #### Join Lines
  80
  81 Join selected lines into one, smartly fixing up whitespace and trailing commas.
  82
  83 #### Run
  84
  85 Shows popup suggesting to run a test/benchmark/binary **at the current cursor
  86 location**. Super useful for repeatedly running just a single test. Do bind this
  87 to a shortcut!
  88
  89
  90 ### On Typing Assists
  91
  92 Some features trigger on typing certain characters:
  93
  94 - typing `let =` tries to smartly add `;` if `=` is followed by an existing expression.
  95 - Enter inside comments automatically inserts `///`
  96 - typing `.` in a chain method call auto-indents
  97
  98
  99 ### Code Actions (Assists)
 100
 101 These are triggered in a particular context via light bulb. We use custom code on
 102 the VS Code side to be able to position cursor.
 103
 104
 105 - Flip `,`
 106
 107 ```rust
 108 // before:
 109 fn foo(x: usize,<|> dim: (usize, usize))
 110 // after:
 111 fn foo(dim: (usize, usize), x: usize)
 112 ```
 113
 114 - Add `#[derive]`
 115
 116 ```rust
 117 // before:
 118 struct Foo {
 119     <|>x: i32
 120 }
 121 // after:
 122 #[derive(<|>)]
 123 struct Foo {
 124     x: i32
 125 }
 126 ```
 127
 128 - Add `impl`
 129
 130 ```rust
 131 // before:
 132 struct Foo<'a, T: Debug> {
 133     <|>t: T
 134 }
 135 // after:
 136 struct Foo<'a, T: Debug> {
 137     t: T
 138 }
 139
 140 impl<'a, T: Debug> Foo<'a, T> {
 141     <|>
 142 }
 143 ```
 144
 145 - Change visibility
 146
 147 ```rust
 148 // before:
 149 fn<|> foo() {}
 150
 151 // after
 152 pub(crate) fn foo() {}
 153 ```
 154
 155 - Introduce variable:
 156
 157 ```rust
 158 // before:
 159 fn foo() {
 160     foo(<|>1 + 1<|>);
 161 }
 162
 163 // after:
 164 fn foo() {
 165     let var_name = 1 + 1;
 166     foo(var_name);
 167 }
 168 ```
 169
 170 - Replace if-let with match:
 171
 172 ```rust
 173 // before:
 174 impl VariantData {
 175     pub fn is_struct(&self) -> bool {
 176         if <|>let VariantData::Struct(..) = *self {
 177             true
 178         } else {
 179             false
 180         }
 181     }
 182 }
 183
 184 // after:
 185 impl VariantData {
 186     pub fn is_struct(&self) -> bool {
 187         <|>match *self {
 188             VariantData::Struct(..) => true,
 189             _ => false,
 190         }
 191     }
 192 }
 193 ```
 194
 195 - Split import
 196
 197 ```rust
 198 // before:
 199 use algo:<|>:visitor::{Visitor, visit};
 200 //after:
 201 use algo::{<|>visitor::{Visitor, visit}};
 202 ```
 203
 204 ## LSP features
 205
 206 * **Go to definition**: works correctly for local variables and some paths,
 207   falls back to heuristic name matching for other things for the time being.
 208
 209 * **Completion**: completes paths, including dependencies and standard library.
 210   Does not handle glob imports and macros. Completes fields and inherent
 211   methods.
 212
 213 * **Outline** <kbd>alt+shift+o</kbd>
 214
 215 * **Signature Info**
 216
 217 * **Format document**. Formats the current file with rustfmt. Rustfmt must be
 218   installed separately with `rustup component add rustfmt`.
 219
 220 * **Hover** shows types of expressions and docstings
 221
 222 * **Rename** works for local variables
 223
 224 * **Code Lens** for running tests
 225
 226 * **Folding**
 227
 228 * **Diagnostics**
 229   - missing module for `mod foo;` with a fix to create `foo.rs`.
 230   - struct field shorthand
 231   - unnecessary braces in use item
 232
 233
 234 ## Performance
 235
 236 Rust Analyzer is expected to be pretty fast. Specifically, the initial analysis
 237 of the project (i.e, when you first invoke completion or symbols) typically
 238 takes dozen of seconds at most. After that, everything is supposed to be more or
 239 less instant. However currently all analysis results are kept in memory, so
 240 memory usage is pretty high. Working with `rust-lang/rust` repo, for example,
 241 needs about 5 gigabytes of ram.