rust/docs/user/README.md

208 lines
8.5 KiB
Markdown
Raw Normal View History

2019-03-20 04:17:12 -05:00
The main interface to rust-analyzer is the
[LSP](https://microsoft.github.io/language-server-protocol/) implementation. To
install lsp server, clone the repository and then run `cargo xtask install
--server` (which is shorthand for `cargo install --path
./crates/ra_lsp_server`). This will produce a binary named `ra_lsp_server` which
you should be able to use it with any LSP-compatible editor. We use custom
extensions to LSP, so special client-side support is required to take full
advantage of rust-analyzer. This repository contains support code for VS Code
and Emacs.
```
$ git clone git@github.com:rust-analyzer/rust-analyzer && cd rust-analyzer
$ cargo xtask install --server
```
Rust Analyzer needs sources of rust standard library to work, so
you might also need to execute
2019-03-20 04:17:12 -05:00
```
$ rustup component add rust-src
```
2019-03-20 04:21:55 -05:00
See [./features.md](./features.md) document for a list of features that are available.
2019-03-20 04:17:12 -05:00
## VS Code
2019-02-10 15:09:33 -06:00
2019-03-13 09:23:22 -05:00
Prerequisites:
2019-02-10 15:09:33 -06:00
In order to build the VS Code plugin, you need to have node.js and npm with
a minimum version of 10 installed. Please refer to
[node.js and npm documentation](https://nodejs.org) for installation instructions.
2019-02-12 09:28:39 -06:00
You will also need the most recent version of VS Code: we don't try to
maintain compatibility with older versions yet.
2019-02-10 15:09:33 -06:00
The experimental VS Code plugin can then be built and installed by executing the
following commands:
2018-09-16 07:36:09 -05:00
```
$ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1
2018-12-27 08:56:07 -06:00
$ cd rust-analyzer
2019-10-17 11:36:55 -05:00
$ cargo xtask install
2018-09-16 07:36:09 -05:00
```
2019-05-11 06:22:44 -05:00
The automatic installation is expected to *just work* for common cases, if it
doesn't, report bugs!
2019-05-30 09:10:10 -05:00
If you have an unusual setup (for example, `code` is not in the `PATH`), you
2019-05-11 06:22:44 -05:00
should adapt these manual installation instructions:
```
$ git clone https://github.com/rust-analyzer/rust-analyzer.git --depth 1
$ cd rust-analyzer
2019-10-08 01:35:27 -05:00
$ cargo install --path ./crates/ra_lsp_server/ --force --locked
2019-05-11 06:22:44 -05:00
$ cd ./editors/code
$ npm install
$ ./node_modules/vsce/out/vsce package
$ code --install-extension ./ra-lsp-0.0.1.vsix
```
2018-09-16 07:36:09 -05:00
It's better to remove existing Rust plugins to avoid interference.
2019-03-20 04:17:12 -05:00
Beyond basic LSP features, there are some extension commands which you can
2019-03-20 04:21:55 -05:00
invoke via <kbd>Ctrl+Shift+P</kbd> or bind to a shortcut. See [./features.md](./features.md)
2019-03-20 04:17:12 -05:00
for details.
2019-01-13 06:04:05 -06:00
2019-10-17 11:36:55 -05:00
For updates, pull the latest changes from the master branch, run `cargo xtask install` again, and **restart** VS Code instance.
2019-09-18 09:01:56 -05:00
See [microsoft/vscode#72308](https://github.com/microsoft/vscode/issues/72308) for why a full restart is needed.
2019-07-29 04:14:11 -05:00
2019-10-21 14:19:26 -05:00
### VS Code Remote
You can also use `rust-analyzer` with the Visual Studio Code Remote extensions
(Remote SSH, Remote WSL, Remote Containers). In this case, however, you have to
manually install the `.vsix` package:
1. Build the extension on the remote host using the instructions above (ignore the
error if `code` cannot be found in your PATH: VSCode doesn't need to be installed
on the remote host).
2. In Visual Studio Code open a connection to the remote host.
3. Open the Extensions View (`View > Extensions`, keyboard shortcut: `Ctrl+Shift+X`).
4. From the top-right kebab menu (`···`) select `Install from VSIX...`
5. Inside the `rust-analyzer` directory find the `editors/code` subdirectory and choose
the `ra-lsp-0.0.1.vsix` file.
6. Restart Visual Studio Code and re-establish the connection to the remote host.
In case of errors please make sure that `~/.cargo/bin` is in your `PATH` on the remote
host.
2019-03-20 04:17:12 -05:00
### Settings
2019-01-13 06:04:05 -06:00
2019-03-20 04:17:12 -05:00
* `rust-analyzer.highlightingOn`: enables experimental syntax highlighting
* `rust-analyzer.enableEnhancedTyping`: by default, rust-analyzer intercepts
`Enter` key to make it easier to continue comments. Note that it may conflict with VIM emulation plugin.
2019-03-20 04:17:12 -05:00
* `rust-analyzer.raLspServerPath`: path to `ra_lsp_server` executable
* `rust-analyzer.enableCargoWatchOnStartup`: prompt to install & enable `cargo
watch` for live error highlighting (note, this **does not** use rust-analyzer)
* `rust-analyzer.excludeGlobs`: a list of glob-patterns for exclusion (see globset [docs](https://docs.rs/globset) for syntax).
Note: glob patterns are applied to all Cargo packages and a rooted at a package root.
This is not very intuitive and a limitation of a current implementation.
2019-09-06 08:25:24 -05:00
* `rust-analyzer.useClientWatching`: use client provided file watching instead
of notify watching.
* `rust-analyzer.cargo-watch.command`: `cargo-watch` command. (e.g: `clippy` will run as `cargo watch -x clippy` )
* `rust-analyzer.cargo-watch.arguments`: cargo-watch check arguments.
2019-05-11 06:22:44 -05:00
(e.g: `--features="shumway,pdf"` will run as `cargo watch -x "check --features="shumway,pdf""` )
* `rust-analyzer.cargo-watch.ignore`: list of patterns for cargo-watch to ignore (will be passed as `--ignore`)
2019-03-20 04:17:12 -05:00
* `rust-analyzer.trace.server`: enables internal logging
2019-04-02 00:07:40 -05:00
* `rust-analyzer.trace.cargo-watch`: enables cargo-watch logging
* `RUST_SRC_PATH`: environment variable that overwrites the sysroot
2019-10-25 01:00:30 -05:00
* `rust-analyzer.featureFlags` -- a JSON object to tweak fine-grained behavior:
```js
{
// Show diagnostics produced by rust-analyzer itself.
"lsp.diagnostics": true,
// Automatically insert `()` and `<>` when completing functions and types.
"completion.insertion.add-call-parenthesis": true,
// Enable completions like `.if`, `.match`, etc.
"completion.enable-postfix": true,
2019-10-25 01:00:30 -05:00
// Show notification when workspace is fully loaded
"notifications.workspace-loaded": true,
}
```
2019-01-13 06:04:05 -06:00
2019-03-20 04:17:12 -05:00
## Emacs
2018-09-16 07:36:09 -05:00
2019-03-20 04:17:12 -05:00
Prerequisites:
2019-01-13 08:13:54 -06:00
2019-03-20 04:17:12 -05:00
`emacs-lsp`, `dash` and `ht` packages.
2019-01-13 08:13:54 -06:00
2019-03-20 04:17:12 -05:00
Installation:
2019-01-13 08:13:54 -06:00
2019-03-20 04:17:12 -05:00
* add
2019-12-04 10:07:37 -06:00
[ra-emacs-lsp.el](../../editors/emacs/ra-emacs-lsp.el)
2019-03-20 04:17:12 -05:00
to load path and require it in `init.el`
* run `lsp` in a rust buffer
* (Optionally) bind commands like `rust-analyzer-join-lines`, `rust-analyzer-extend-selection` and `rust-analyzer-expand-macro` to keys, and enable `rust-analyzer-inlay-hints-mode` to get inline type hints
2019-05-25 14:24:47 -05:00
## Vim and NeoVim
Neovim 0.5 has a built in language server. For a quick start configuration of
rust-analyzer, use [neovim/nvim-lsp](https://github.com/neovim/nvim-lsp#rust_analyzer).
Once `neovim/nvim-lsp` is installed, you can use `call nvim_lsp#setup("rust_analyzer", {})`
or `lua require'nvim_lsp'.rust_analyzer.setup({})` to quickly get set up.
2019-05-25 14:24:47 -05:00
* Install coc.nvim by following the instructions at [coc.nvim]
2019-06-18 09:25:59 -05:00
- You will need nodejs installed.
- You may want to include some of the sample vim configurations [from here][coc-vim-conf]
- Note that if you use a plugin manager other than `vim-plug`, you may need to manually
checkout the `release` branch wherever your plugin manager cloned it. Otherwise you will
get errors about a missing javascript file.
* Run `:CocInstall coc-rust-analyzer` to install [coc-rust-analyzer], this extension implemented _most_ of the features supported in the VSCode extension:
2019-09-03 03:02:32 -05:00
- same configurations as VSCode extension, `rust-analyzer.raLspServerPath`, `rust-analyzer.enableCargoWatchOnStartup` etc.
- same commands too, `rust-analyzer.analyzerStatus`, `rust-analyzer.startCargoWatch` etc.
2019-09-08 23:58:44 -05:00
- highlighting and inlay_hints are not implemented yet
2019-05-25 14:24:47 -05:00
[coc.nvim]: https://github.com/neoclide/coc.nvim
2019-06-18 09:25:59 -05:00
[coc-vim-conf]: https://github.com/neoclide/coc.nvim/#example-vim-configuration
[coc-rust-analyzer]: https://github.com/fannheyward/coc-rust-analyzer
2019-05-25 14:24:47 -05:00
## Vim and NeoVim Alternative
* Install LanguageClient-neovim by following the instructions [here][lang-client-neovim]
- No extra run-time is required as this server is written in Rust
- The github project wiki has extra tips on configuration
* Configure by adding this to your vim/neovim config file (replacing the existing rust specific line if it exists):
```
let g:LanguageClient_serverCommands = {
\ 'rust': ['ra_lsp_server'],
\ }
```
[lang-client-neovim]: https://github.com/autozimu/LanguageClient-neovim
2019-05-25 14:24:47 -05:00
## Sublime Text 3
Prequisites:
`LSP` package.
Installation:
* Invoke the command palette with <kbd>Ctrl+Shift+P</kbd>
* Type `LSP Settings` to open the LSP preferences editor
* Add the following LSP client definition to your settings:
```json
"rust-analyzer": {
"command": ["ra_lsp_server"],
"languageId": "rust",
"scopes": ["source.rust"],
"syntaxes": [
"Packages/Rust/Rust.sublime-syntax",
"Packages/Rust Enhanced/RustEnhanced.sublime-syntax"
],
"initializationOptions": {
"featureFlags": {
}
},
}
```
* 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)
* 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`.