Merge #3140

3140: Start manual r=matklad a=matklad



Co-authored-by: Aleksey Kladov <[email protected]>

1 files changed, 152 insertions, 0 deletions

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 <kbd>Ctrl+Shift+P</kbd>
+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].