docs/user/README.md

   1 The main interface to rust-analyzer is the
   2 [LSP](https://microsoft.github.io/language-server-protocol/) implementation. To
   3 install lsp server, use `cargo install-ra --server`, which is a shorthand for `cargo
   4 install --package ra_lsp_server`. The binary is named `ra_lsp_server`, you
   5 should be able to use it with any LSP-compatible editor. We use custom
   6 extensions to LSP, so special client-side support is required to take full
   7 advantage of rust-analyzer. This repository contains support code for VS Code
   8 and Emacs.
   9
  10 Rust Analyzer needs sources of rust standard library to work, so you might need
  11 to execute
  12
  13 ```
  14 $ rustup component add rust-src
  15 ```
  16
  17 See [./features.md](./features.md) document for a list of features that are available.
  18
  19 ## VS Code
  20
  21 Prerequisites:
  22
  23 In order to build the VS Code plugin, you need to have node.js and npm with
  24 a minimum version of 10 installed. Please refer to
  25 [node.js and npm documentation](https://nodejs.org) for installation instructions.
  26
  27 You will also need the most recent version of VS Code: we don't try to
  28 maintain compatibility with older versions yet.
  29
  30 The experimental VS Code plugin can then be built and installed by executing the
  31 following commands:
  32
  33 ```
  34 $ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1
  35 $ cd rust-analyzer
  36 $ cargo install-ra
  37 ```
  38
  39 The automatic installation is expected to *just work* for common cases, if it
  40 doesn't, report bugs!
  41
  42 If you have an unusual setup (for example, `code` is not in the `PATH`), you
  43 should adapt these manual installation instructions:
  44
  45 ```
  46 $ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1
  47 $ cd rust-analyzer
  48 $ cargo install --path ./crates/ra_lsp_server/ --force --locked
  49 $ cd ./editors/code
  50 $ npm install
  51 $ ./node_modules/vsce/out/vsce package
  52 $ code --install-extension ./ra-lsp-0.0.1.vsix
  53 ```
  54
  55 It's better to remove existing Rust plugins to avoid interference.
  56
  57 Beyond basic LSP features, there are some extension commands which you can
  58 invoke via <kbd>Ctrl+Shift+P</kbd> or bind to a shortcut. See [./features.md](./features.md)
  59 for details.
  60
  61 For updates, pull the latest changes from the master branch, run `cargo install-ra` again, and **restart** VS Code instance.
  62 See [microsoft/vscode#72308](https://github.com/microsoft/vscode/issues/72308) for why a full restart is needed.
  63
  64 ### Settings
  65
  66 * `rust-analyzer.highlightingOn`: enables experimental syntax highlighting
  67 * `rust-analyzer.showWorkspaceLoadedNotification`: to ease troubleshooting, a
  68   notification is shown by default when a workspace is loaded
  69 * `rust-analyzer.enableEnhancedTyping`: by default, rust-analyzer intercepts
  70   `Enter` key to make it easier to continue comments. Note that it may conflict with VIM emulation plugin.
  71 * `rust-analyzer.raLspServerPath`: path to `ra_lsp_server` executable
  72 * `rust-analyzer.enableCargoWatchOnStartup`: prompt to install & enable `cargo
  73   watch` for live error highlighting (note, this **does not** use rust-analyzer)
  74 * `rust-analyzer.excludeGlobs`: a list of glob-patterns for exclusion (see globset [docs](https://docs.rs/globset) for syntax).
  75   Note: glob patterns are applied to all Cargo packages and a rooted at a package root.
  76   This is not very intuitive and a limitation of a current implementation.
  77 * `rust-analyzer.useClientWatching`: use client provided file watching instead
  78   of notify watching.
  79 * `rust-analyzer.cargo-watch.command`: `cargo-watch` command. (e.g: `clippy` will run as `cargo watch -x clippy` )
  80 * `rust-analyzer.cargo-watch.arguments`: cargo-watch check arguments.
  81   (e.g: `--features="shumway,pdf"` will run as `cargo watch -x "check --features="shumway,pdf""` )
  82 * `rust-analyzer.cargo-watch.ignore`: list of patterns for cargo-watch to ignore (will be passed as `--ignore`)
  83 * `rust-analyzer.trace.server`: enables internal logging
  84 * `rust-analyzer.trace.cargo-watch`: enables cargo-watch logging
  85 * `RUST_SRC_PATH`: environment variable that overwrites the sysroot
  86
  87
  88 ## Emacs
  89
  90 Prerequisites:
  91
  92 `emacs-lsp`, `dash` and `ht` packages.
  93
  94 Installation:
  95
  96 * add
  97 [ra-emacs-lsp.el](https://github.com/rust-analyzer/rust-analyzer/blob/69ee5c9c5ef212f7911028c9ddf581559e6565c3/editors/emacs/ra-emacs-lsp.el)
  98 to load path and require it in `init.el`
  99 * run `lsp` in a rust buffer
 100 * (Optionally) bind commands like `rust-analyzer-join-lines` or `rust-analyzer-extend-selection` to keys, and enable `rust-analyzer-inlay-hints-mode` to get inline type hints
 101
 102
 103 ## Vim and NeoVim
 104
 105 * Install coc.nvim by following the instructions at [coc.nvim]
 106   - You will need nodejs installed.
 107   - You may want to include some of the sample vim configurations [from here][coc-vim-conf]
 108   - Note that if you use a plugin manager other than `vim-plug`, you may need to manually
 109     checkout the `release` branch wherever your plugin manager cloned it. Otherwise you will
 110     get errors about a missing javascript file.
 111 * Run `:CocInstall coc-rust-analyzer` to install [coc-rust-analyzer], this extension implemented _most_ of the features supported in the VSCode extension:
 112   - same configurations as VSCode extension, `rust-analyzer.raLspServerPath`, `rust-analyzer.enableCargoWatchOnStartup` etc.
 113   - same commands too, `rust-analyzer.analyzerStatus`, `rust-analyzer.startCargoWatch` etc.
 114   - highlighting and inlay_hints are not implemented yet
 115
 116 [coc.nvim]: https://github.com/neoclide/coc.nvim
 117 [coc-vim-conf]: https://github.com/neoclide/coc.nvim/#example-vim-configuration
 118 [coc-rust-analyzer]: https://github.com/fannheyward/coc-rust-analyzer
 119
 120 ## Vim and NeoVim Alternative
 121
 122 * Install LanguageClient-neovim by following the instructions [here][lang-client-neovim]
 123   - No extra run-time is required as this server is written in Rust
 124   - The github project wiki has extra tips on configuration
 125
 126 * Configure by adding this to your vim/neovim config file (replacing the existing rust specific line if it exists):
 127
 128 ```
 129 let g:LanguageClient_serverCommands = {
 130 \ 'rust': ['ra_lsp_server'],
 131 \ }
 132 ```
 133
 134 [lang-client-neovim]: https://github.com/autozimu/LanguageClient-neovim
 135
 136
 137 ## Sublime Text 3
 138
 139 Prequisites:
 140
 141 `LSP` package.
 142
 143 Installation:
 144
 145 * Invoke the command palette with <kbd>Ctrl+Shift+P</kbd>
 146 * Type `LSP Settings` to open the LSP preferences editor
 147 * Add the following LSP client definition to your settings:
 148
 149 ```json
 150 "rust-analyzer": {
 151     "command": ["ra_lsp_server"],
 152     "languageId": "rust",
 153     "scopes": ["source.rust"],
 154     "syntaxes": [
 155         "Packages/Rust/Rust.sublime-syntax",
 156         "Packages/Rust Enhanced/RustEnhanced.sublime-syntax"
 157     ]
 158 }
 159 ```
 160
 161 * 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)
 162
 163 * Note that `ra_lsp_server` binary must be in `$PATH` for this to work. If it's not the case, you can specify full path to the binary, which is typically `.cargo/bin/ra_lsp_server`.