From 082dd87b328e8cdf1b99999f9332e056a8bc916b Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Fri, 14 Feb 2020 18:30:52 +0100 Subject: Start manual --- docs/user/readme.adoc | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 docs/user/readme.adoc (limited to 'docs/user/readme.adoc') diff --git a/docs/user/readme.adoc b/docs/user/readme.adoc new file mode 100644 index 000000000..b9ecc7055 --- /dev/null +++ b/docs/user/readme.adoc @@ -0,0 +1,152 @@ += User Manual +:toc: preamble +:sectanchors: +:page-layout: post + + +// Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository + +At it's core, rust-analyzer is a *library* for semantic analysis of the Rust code as it changes over time. +This manual focuses on a specific usage of the library -- the implementation of +https://microsoft.github.io/language-server-protocol/[Language Server Protocol]. +LSP allows various code editors, like VS Code, Emacs or Vim, to implement semantic feature like completion or goto definition by talking to an external language server process. + +== Installation + +In theory, one should be able to just install the server binary and have it automatically work with any editor. +We are not there yet, so some editor specific setup is required. + +=== VS Code + +This the best supported editor at the moment. +rust-analyzer plugin for VS Code is maintained +https://github.com/rust-analyzer/rust-analyzer/tree/master/editors/code[in tree]. + +You can install the latest release of the plugin from +https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer[the marketplace]. +By default, the plugin will download the latest version of the server as well. + +image::https://user-images.githubusercontent.com/36276403/74103174-a40df100-4b52-11ea-81f4-372c70797924.png[] + +The server binary is stored in `~/.config/Code/User/globalStorage/matklad.rust-analyzer`. + +Note that we only support the latest version of VS Code. + +==== Updates + +The extension will be updated automatically as new versions become available. +The server update functionality is in progress. +For the time being, the workaround is to remove the binary from `globalStorage` and to restart the extension. + +==== Building From Source + +Alternatively, both the server and the plugin can be installed from source: + +[source] +---- +$ git clone https://github.com/rust-analyzer/rust-analyzer.git && cs rust-analyzer +$ cargo xtask install +---- + +You'll need Cargo, nodejs and npm for this. +To make VS Code use the freshly build server, add this to the settings: + +[source,json] +---- +{ "rust-analyzer.raLspServerPath": "ra_lsp_server" } +---- + +Note that installing via `xtask install` does not work for VS Code Remote, instead you'll need to install the `.vsix` manually. + +=== Language Server Binary + +Other editors generally require `ra_lsp_server` binary to be in `$PATH`. +You can download pre-build binary from +https://github.com/rust-analyzer/rust-analyzer/releases[relases] +page, or you can install it from source using the following command: + +[source,bash] +---- +$ cargo xtask install --server +---- + +=== Emacs + +Emacs support is maintained https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-rust.el[upstream]. + +1. Install recent version of `emacs-lsp` package by following the instructions https://github.com/emacs-lsp/lsp-mode[here]. +2. Set `lsp-rust-server` to `'rust-analyzer`. +3. Run `lsp` in a Rust buffer. +4. (Optionally) bind commands like `lsp-rust-analyzer-join-lines`, `lsp-extend-selection` and `lsp-rust-analyzer-expand-macro` to keys. + +=== Vim + +The are several LSP client implementations for vim: + +==== coc-rust-analyzer + +1. Install coc.nvim by following the instructions at + https://github.com/neoclide/coc.nvim[coc.nvim] + (nodejs required) +2. Run `:CocInstall coc-rust-analyzer` to install + https://github.com/fannheyward/coc-rust-analyzer[coc-rust-analyzer], + this extension implements _most_ of the features supported in the VSCode extension: + * same configurations as VSCode extension, `rust-analyzer.raLspServerPath`, `rust-analyzer.enableCargoWatchOnStartup` etc. + * same commands too, `rust-analyzer.analyzerStatus`, `rust-analyzer.startCargoWatch` etc. + * highlighting and inlay_hints are not implemented yet + +==== LanguageClient-neovim + +1. Install LanguageClient-neovim by following the instructions + https://github.com/autozimu/LanguageClient-neovim[here] + * The github project wiki has extra tips on configuration + +2. Configure by adding this to your vim/neovim config file (replacing the existing rust specific line if it exists): ++ +[source,vim] +---- +let g:LanguageClient_serverCommands = { +\ 'rust': ['ra_lsp_server'], +\ } +---- + +==== nvim-lsp + +NeoVim 0.5 (not yet released) has built in language server support. +For a quick start configuration of rust-analyzer, use https://github.com/neovim/nvim-lsp#rust_analyzer[neovim/nvim-lsp]. +Once `neovim/nvim-lsp` is installed, use `lua require'nvim_lsp'.rust_analyzer.setup({})` in your `init.vim`. + +=== Sublime Text 3 + +Prerequisites: + +`LSP` package. + +Installation: + +1. Invoke the command palette with Ctrl+Shift+P +2. Type `LSP Settings` to open the LSP preferences editor +3. Add the following LSP client definition to your settings: ++ +[source,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": { + } + }, +} +---- + +4. 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) + +== Usage + +See https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/features.md[features.md]. -- cgit v1.2.3