From 5a2f4548e59981871fe4db2b9ee591b9bf39a46e Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sun, 31 May 2020 13:22:02 +0200 Subject: Rename user/readme.adoc -> user/manual.adoc --- docs/user/manual.adoc | 282 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/user/readme.adoc | 282 -------------------------------------------------- xtask/src/lib.rs | 6 +- 3 files changed, 287 insertions(+), 283 deletions(-) create mode 100644 docs/user/manual.adoc delete mode 100644 docs/user/readme.adoc diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc new file mode 100644 index 000000000..f40139804 --- /dev/null +++ b/docs/user/manual.adoc @@ -0,0 +1,282 @@ += User Manual +:toc: preamble +:sectanchors: +:page-layout: post +// https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74#admonitions +:tip-caption: :bulb: +:note-caption: :information_source: +:important-caption: :heavy_exclamation_mark: +:caution-caption: :fire: +:warning-caption: :warning: +:source-highlighter: rouge +:experimental: + +// Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository + +At its core, rust-analyzer is a *library* for semantic analysis of Rust code as it changes over time. +This manual focuses on a specific usage of the library -- running it as part of a server that implements the +https://microsoft.github.io/language-server-protocol/[Language Server Protocol] (LSP). +The LSP allows various code editors, like VS Code, Emacs or Vim, to implement semantic features like completion or goto definition by talking to an external language server process. + +To improve this document, send a pull request against +https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/manual.adoc[this file]. + +If you have questions about using rust-analyzer, please ask them in the https://users.rust-lang.org/c/ide/14["`IDEs and Editors`"] topic of Rust users forum. + +== Installation + +In theory, one should be able to just install the <> and have it automatically work with any editor. +We are not there yet, so some editor specific setup is required. + +Additionally, rust-analyzer needs the sources of the standard library. +If the source code is not present, rust-analyzer will attempt to install it automatically. + +To add the sources manually, run the following command: + +```bash +$ rustup component add rust-src +``` + +=== VS Code + +This is the best supported editor at the moment. +The 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 prompt you to download the matching version of the server as well: + +image::https://user-images.githubusercontent.com/9021944/75067008-17502500-54ba-11ea-835a-f92aac50e866.png[] + +[NOTE] +==== +To disable this notification put the following to `settings.json` + +[source,json] +---- +{ "rust-analyzer.updates.askBeforeDownload": false } +---- +==== + +The server binary is stored in: + +* Linux: `~/.config/Code/User/globalStorage/matklad.rust-analyzer` +* macOS: `~/Library/Application Support/Code/User/globalStorage/matklad.rust-analyzer` +* Windows: `%APPDATA%\Code\User\globalStorage\matklad.rust-analyzer` + +Note that we only support two most recent versions of VS Code. + +==== Special `when` clause context for keybindings. +You may use `inRustProject` context to configure keybindings for rust projects only. For example: +[source,json] +---- +{ "key": "ctrl+shift+f5", "command": "workbench.action.debug.restart", "when": "inDebugMode && !inRustProject"}, +{ "key": "ctrl+shift+f5", "command": "rust-analyzer.debug", "when": "inRustProject"}, +{ "key": "ctrl+i", "command": "rust-analyzer.toggleInlayHints", "when": "inRustProject" } +---- +More about `when` clause contexts https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[here]. + +==== Updates + +The extension will be updated automatically as new versions become available. It will ask your permission to download the matching language server version binary if needed. + +===== Nightly + +We ship nightly releases for VS Code. To help us out with testing the newest code and follow the bleeding edge of our `master`, please use the following config: + +[source,json] +---- +{ "rust-analyzer.updates.channel": "nightly" } +---- + +You will be prompted to install the `nightly` extension version. Just click `Download now` and from that moment you will get automatic updates every 24 hours. + +If you don't want to be asked for `Download now` every day when the new nightly version is released add the following to your `settings.json`: +[source,json] +---- +{ "rust-analyzer.updates.askBeforeDownload": false } +---- + +NOTE: Nightly extension should **only** be installed via the `Download now` action from VS Code. + +==== 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 && cd rust-analyzer +$ cargo xtask install +---- + +You'll need Cargo, nodejs and npm for this. + +Note that installing via `xtask install` does not work for VS Code Remote, instead you'll need to install the `.vsix` manually. + +==== Troubleshooting + +Here are some useful self-diagnostic commands: + +* **Rust Analyzer: Show RA Version** shows the version of `rust-analyzer` binary +* **Rust Analyzer: Status** prints some statistics about the server, like the few latest LSP requests +* To enable server-side logging, run with `env RA_LOG=info` and see `Output > Rust Analyzer Language Server` in VS Code's panel. +* To log all LSP requests, add `"rust-analyzer.trace.server": "verbose"` to the settings and look for `Server Trace` in the panel. +* To enable client-side logging, add `"rust-analyzer.trace.extension": true` to the settings and open the `Console` tab of VS Code developer tools. + +=== rust-analyzer Language Server Binary + +Other editors generally require the `rust-analyzer` binary to be in `$PATH`. +You can download the pre-built binary from the https://github.com/rust-analyzer/rust-analyzer/releases[releases] page. Typically, you then need to rename the binary for your platform, e.g. `rust-analyzer-mac` if you're on Mac OS, to `rust-analyzer` and make it executable in addition to moving it into a directory in your `$PATH`. + +On Linux to install the `rust-analyzer` binary into `~/.local/bin`, this commands could be used + +[source,bash] +---- +$ curl -L https://github.com/rust-analyzer/rust-analyzer/releases/latest/download/rust-analyzer-linux -o ~/.local/bin/rust-analyzer +$ chmod +x ~/.local/bin/rust-analyzer +---- + +Ensure `~/.local/bin` is listed in the `$PATH` variable. + +Alternatively, you can install it from source using the following command: + +[source,bash] +---- +$ git clone https://github.com/rust-analyzer/rust-analyzer.git && cd rust-analyzer +$ cargo xtask install --server +---- + +If your editor can't find the binary even though the binary is on your `$PATH`, the likely explanation is that it doesn't see the same `$PATH` as the shell, see https://github.com/rust-analyzer/rust-analyzer/issues/1811[this issue]. On Unix, running the editor from a shell or changing the `.desktop` file to set the environment should help. + +==== Arch Linux + +The `rust-analyzer` binary can be installed from the repos or AUR (Arch User Repository): + +- https://www.archlinux.org/packages/community/x86_64/rust-analyzer/[`rust-analyzer`] (built from latest tagged source) +- https://aur.archlinux.org/packages/rust-analyzer-git[`rust-analyzer-git`] (latest Git version) + +Install it with pacman, for example: + +[source,bash] +---- +$ pacman -S rust-analyzer +---- + +=== Emacs + +Prerequisites: You have installed the <>. + +Emacs support is maintained as part of the https://github.com/emacs-lsp/lsp-mode[Emacs-LSP] package in https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-rust.el[lsp-rust.el]. + +1. Install the most recent version of `emacs-lsp` package by following the https://github.com/emacs-lsp/lsp-mode[Emacs-LSP instructions]. +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/NeoVim + +Prerequisites: You have installed the <>. Not needed if the extension can install/update it on its own, coc-rust-analyzer is one example. + +The are several LSP client implementations for vim or neovim: + +==== coc-rust-analyzer + +1. Install coc.nvim by following the instructions at + https://github.com/neoclide/coc.nvim[coc.nvim] + (Node.js 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: + * automatically install and upgrade stable/nightly releases + * same configurations as VSCode extension, `rust-analyzer.serverPath`, `rust-analyzer.cargo.features` etc. + * same commands too, `rust-analyzer.analyzerStatus`, `rust-analyzer.ssr` etc. + * inlay hints for method chaining support, _Neovim Only_ + * semantic highlighting is 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': ['rust-analyzer'], +\ } +---- + +==== YouCompleteMe + +1. Install YouCompleteMe by following the instructions + https://github.com/ycm-core/lsp-examples#rust-rust-analyzer[here] + +2. Configure by adding this to your vim/neovim config file (replacing the existing Rust-specific line if it exists): ++ +[source,vim] +---- +let g:ycm_language_server = +\ [ +\ { +\ 'name': 'rust', +\ 'cmdline': ['rust-analyzer'], +\ 'filetypes': ['rust'], +\ 'project_root_files': ['Cargo.toml'] +\ } +\ ] +---- + +==== ALE + +To use the LSP server in https://github.com/dense-analysis/ale[ale]: + +[source,vim] +---- +let g:ale_linters = {'rust': ['analyzer']} +---- + +==== 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: You have installed the <>. + +You also need the `LSP` package. To install it: + +1. If you've never installed a Sublime Text package, install Package Control: + * Open the command palette (Win/Linux: `ctrl+shift+p`, Mac: `cmd+shift+p`) + * Type `Install Package Control`, press enter +2. In the command palette, run `Package control: Install package`, and in the list that pops up, type `LSP` and press enter. + +Finally, with your Rust project open, in the command palette, run `LSP: Enable Language Server In Project` or `LSP: Enable Language Server Globally`, then select `rust-analyzer` in the list that pops up to enable the rust-analyzer LSP. The latter means that rust-analyzer is enabled by default in Rust projects. + +If it worked, you should see "rust-analyzer, Line X, Column Y" on the left side of the bottom bar, and after waiting a bit, functionality like tooltips on hovering over variables should become available. + +If you get an error saying `No such file or directory: 'rust-analyzer'`, see the <> section on installing the language server binary. + +=== GNOME Builder + +Prerequisites: You have installed the <>. + +Gnome Builder currently has support for RLS, and there's no way to configure the language server executable. A future version might support `rust-analyzer` out of the box. + +1. Rename, symlink or copy the `rust-analyzer` binary to `rls` and place it somewhere Builder can find (in `PATH`, or under `~/.cargo/bin`). +2. Enable the Rust Builder plugin. + +== Features + +include::./generated_features.adoc[] + +== Assists (Code Actions) + +Assists, or code actions, are small local refactorings, available in a particular context. +They are usually triggered by a shortcut or by clicking a light bulb icon in the editor. + +See [assists.md](./assists.md) for the list of available assists. diff --git a/docs/user/readme.adoc b/docs/user/readme.adoc deleted file mode 100644 index 12def7327..000000000 --- a/docs/user/readme.adoc +++ /dev/null @@ -1,282 +0,0 @@ -= User Manual -:toc: preamble -:sectanchors: -:page-layout: post -// https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda74#admonitions -:tip-caption: :bulb: -:note-caption: :information_source: -:important-caption: :heavy_exclamation_mark: -:caution-caption: :fire: -:warning-caption: :warning: -:source-highlighter: rouge -:experimental: - -// Master copy of this document lives in the https://github.com/rust-analyzer/rust-analyzer repository - -At its core, rust-analyzer is a *library* for semantic analysis of Rust code as it changes over time. -This manual focuses on a specific usage of the library -- running it as part of a server that implements the -https://microsoft.github.io/language-server-protocol/[Language Server Protocol] (LSP). -The LSP allows various code editors, like VS Code, Emacs or Vim, to implement semantic features like completion or goto definition by talking to an external language server process. - -To improve this document, send a pull request against -https://github.com/rust-analyzer/rust-analyzer/blob/master/docs/user/readme.adoc[this file]. - -If you have questions about using rust-analyzer, please ask them in the https://users.rust-lang.org/c/ide/14["`IDEs and Editors`"] topic of Rust users forum. - -== Installation - -In theory, one should be able to just install the <> and have it automatically work with any editor. -We are not there yet, so some editor specific setup is required. - -Additionally, rust-analyzer needs the sources of the standard library. -If the source code is not present, rust-analyzer will attempt to install it automatically. - -To add the sources manually, run the following command: - -```bash -$ rustup component add rust-src -``` - -=== VS Code - -This is the best supported editor at the moment. -The 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 prompt you to download the matching version of the server as well: - -image::https://user-images.githubusercontent.com/9021944/75067008-17502500-54ba-11ea-835a-f92aac50e866.png[] - -[NOTE] -==== -To disable this notification put the following to `settings.json` - -[source,json] ----- -{ "rust-analyzer.updates.askBeforeDownload": false } ----- -==== - -The server binary is stored in: - -* Linux: `~/.config/Code/User/globalStorage/matklad.rust-analyzer` -* macOS: `~/Library/Application Support/Code/User/globalStorage/matklad.rust-analyzer` -* Windows: `%APPDATA%\Code\User\globalStorage\matklad.rust-analyzer` - -Note that we only support two most recent versions of VS Code. - -==== Special `when` clause context for keybindings. -You may use `inRustProject` context to configure keybindings for rust projects only. For example: -[source,json] ----- -{ "key": "ctrl+shift+f5", "command": "workbench.action.debug.restart", "when": "inDebugMode && !inRustProject"}, -{ "key": "ctrl+shift+f5", "command": "rust-analyzer.debug", "when": "inRustProject"}, -{ "key": "ctrl+i", "command": "rust-analyzer.toggleInlayHints", "when": "inRustProject" } ----- -More about `when` clause contexts https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[here]. - -==== Updates - -The extension will be updated automatically as new versions become available. It will ask your permission to download the matching language server version binary if needed. - -===== Nightly - -We ship nightly releases for VS Code. To help us out with testing the newest code and follow the bleeding edge of our `master`, please use the following config: - -[source,json] ----- -{ "rust-analyzer.updates.channel": "nightly" } ----- - -You will be prompted to install the `nightly` extension version. Just click `Download now` and from that moment you will get automatic updates every 24 hours. - -If you don't want to be asked for `Download now` every day when the new nightly version is released add the following to your `settings.json`: -[source,json] ----- -{ "rust-analyzer.updates.askBeforeDownload": false } ----- - -NOTE: Nightly extension should **only** be installed via the `Download now` action from VS Code. - -==== 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 && cd rust-analyzer -$ cargo xtask install ----- - -You'll need Cargo, nodejs and npm for this. - -Note that installing via `xtask install` does not work for VS Code Remote, instead you'll need to install the `.vsix` manually. - -==== Troubleshooting - -Here are some useful self-diagnostic commands: - -* **Rust Analyzer: Show RA Version** shows the version of `rust-analyzer` binary -* **Rust Analyzer: Status** prints some statistics about the server, like the few latest LSP requests -* To enable server-side logging, run with `env RA_LOG=info` and see `Output > Rust Analyzer Language Server` in VS Code's panel. -* To log all LSP requests, add `"rust-analyzer.trace.server": "verbose"` to the settings and look for `Server Trace` in the panel. -* To enable client-side logging, add `"rust-analyzer.trace.extension": true` to the settings and open the `Console` tab of VS Code developer tools. - -=== rust-analyzer Language Server Binary - -Other editors generally require the `rust-analyzer` binary to be in `$PATH`. -You can download the pre-built binary from the https://github.com/rust-analyzer/rust-analyzer/releases[releases] page. Typically, you then need to rename the binary for your platform, e.g. `rust-analyzer-mac` if you're on Mac OS, to `rust-analyzer` and make it executable in addition to moving it into a directory in your `$PATH`. - -On Linux to install the `rust-analyzer` binary into `~/.local/bin`, this commands could be used - -[source,bash] ----- -$ curl -L https://github.com/rust-analyzer/rust-analyzer/releases/latest/download/rust-analyzer-linux -o ~/.local/bin/rust-analyzer -$ chmod +x ~/.local/bin/rust-analyzer ----- - -Ensure `~/.local/bin` is listed in the `$PATH` variable. - -Alternatively, you can install it from source using the following command: - -[source,bash] ----- -$ git clone https://github.com/rust-analyzer/rust-analyzer.git && cd rust-analyzer -$ cargo xtask install --server ----- - -If your editor can't find the binary even though the binary is on your `$PATH`, the likely explanation is that it doesn't see the same `$PATH` as the shell, see https://github.com/rust-analyzer/rust-analyzer/issues/1811[this issue]. On Unix, running the editor from a shell or changing the `.desktop` file to set the environment should help. - -==== Arch Linux - -The `rust-analyzer` binary can be installed from the repos or AUR (Arch User Repository): - -- https://www.archlinux.org/packages/community/x86_64/rust-analyzer/[`rust-analyzer`] (built from latest tagged source) -- https://aur.archlinux.org/packages/rust-analyzer-git[`rust-analyzer-git`] (latest Git version) - -Install it with pacman, for example: - -[source,bash] ----- -$ pacman -S rust-analyzer ----- - -=== Emacs - -Prerequisites: You have installed the <>. - -Emacs support is maintained as part of the https://github.com/emacs-lsp/lsp-mode[Emacs-LSP] package in https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-rust.el[lsp-rust.el]. - -1. Install the most recent version of `emacs-lsp` package by following the https://github.com/emacs-lsp/lsp-mode[Emacs-LSP instructions]. -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/NeoVim - -Prerequisites: You have installed the <>. Not needed if the extension can install/update it on its own, coc-rust-analyzer is one example. - -The are several LSP client implementations for vim or neovim: - -==== coc-rust-analyzer - -1. Install coc.nvim by following the instructions at - https://github.com/neoclide/coc.nvim[coc.nvim] - (Node.js 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: - * automatically install and upgrade stable/nightly releases - * same configurations as VSCode extension, `rust-analyzer.serverPath`, `rust-analyzer.cargo.features` etc. - * same commands too, `rust-analyzer.analyzerStatus`, `rust-analyzer.ssr` etc. - * inlay hints for method chaining support, _Neovim Only_ - * semantic highlighting is 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': ['rust-analyzer'], -\ } ----- - -==== YouCompleteMe - -1. Install YouCompleteMe by following the instructions - https://github.com/ycm-core/lsp-examples#rust-rust-analyzer[here] - -2. Configure by adding this to your vim/neovim config file (replacing the existing Rust-specific line if it exists): -+ -[source,vim] ----- -let g:ycm_language_server = -\ [ -\ { -\ 'name': 'rust', -\ 'cmdline': ['rust-analyzer'], -\ 'filetypes': ['rust'], -\ 'project_root_files': ['Cargo.toml'] -\ } -\ ] ----- - -==== ALE - -To use the LSP server in https://github.com/dense-analysis/ale[ale]: - -[source,vim] ----- -let g:ale_linters = {'rust': ['analyzer']} ----- - -==== 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: You have installed the <>. - -You also need the `LSP` package. To install it: - -1. If you've never installed a Sublime Text package, install Package Control: - * Open the command palette (Win/Linux: `ctrl+shift+p`, Mac: `cmd+shift+p`) - * Type `Install Package Control`, press enter -2. In the command palette, run `Package control: Install package`, and in the list that pops up, type `LSP` and press enter. - -Finally, with your Rust project open, in the command palette, run `LSP: Enable Language Server In Project` or `LSP: Enable Language Server Globally`, then select `rust-analyzer` in the list that pops up to enable the rust-analyzer LSP. The latter means that rust-analyzer is enabled by default in Rust projects. - -If it worked, you should see "rust-analyzer, Line X, Column Y" on the left side of the bottom bar, and after waiting a bit, functionality like tooltips on hovering over variables should become available. - -If you get an error saying `No such file or directory: 'rust-analyzer'`, see the <> section on installing the language server binary. - -=== GNOME Builder - -Prerequisites: You have installed the <>. - -Gnome Builder currently has support for RLS, and there's no way to configure the language server executable. A future version might support `rust-analyzer` out of the box. - -1. Rename, symlink or copy the `rust-analyzer` binary to `rls` and place it somewhere Builder can find (in `PATH`, or under `~/.cargo/bin`). -2. Enable the Rust Builder plugin. - -== Features - -include::./generated_features.adoc[] - -== Assists (Code Actions) - -Assists, or code actions, are small local refactorings, available in a particular context. -They are usually triggered by a shortcut or by clicking a light bulb icon in the editor. - -See [assists.md](./assists.md) for the list of available assists. diff --git a/xtask/src/lib.rs b/xtask/src/lib.rs index 2b7a461e5..06043d19f 100644 --- a/xtask/src/lib.rs +++ b/xtask/src/lib.rs @@ -191,7 +191,11 @@ Release: release:{}[] let path = changelog_dir.join(format!("{}-changelog-{}.adoc", today, changelog_n)); fs2::write(&path, &contents)?; - fs2::copy(project_root().join("./docs/user/readme.adoc"), website_root.join("manual.adoc"))?; + for &adoc in ["manual.adoc", "generated_features.adoc"].iter() { + let src = project_root().join("./docs/user/").join(adoc); + let dst = website_root.join(adoc); + fs2::copy(src, dst)?; + } let tags = run!("git tag --list"; echo = false)?; let prev_tag = tags.lines().filter(|line| is_release_tag(line)).last().unwrap(); -- cgit v1.2.3