:source-highlighter: rouge
:experimental:
+////
+IMPORTANT: the 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 server binary is stored in:
+The server binary is stored in the extension install directory, which starts with `matklad.rust-analyzer-` and is located under:
+
+* Linux: `~/.vscode/extensions`
+* Linux (Remote, such as WSL): `~/.vscode-server/extensions`
+* macOS: `~/.vscode/extensions`
+* Windows: `%USERPROFILE%\.vscode\extensions`
-* Linux: `~/.config/Code/User/globalStorage/matklad.rust-analyzer`
-* Linux (Remote, such as WSL): `~/.vscode-server/data/User/globalStorage/matklad.rust-analyzer`
-* macOS: `~/Library/Application\ Support/Code/User/globalStorage/matklad.rust-analyzer`
-* Windows: `%APPDATA%\Code\User\globalStorage\matklad.rust-analyzer`
+As an exception, on NixOS, the extension makes a copy of the server and stores it under `~/.config/Code/User/globalStorage/matklad.rust-analyzer`.
-Note that we only support two most recent versions of VS Code.
+Note that we only support the two most recent versions of VS Code.
==== Updates
===== Nightly
We ship nightly releases for VS Code.
+You can opt in to these by switching to the pre-release version in the Code extension page or settings.
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.
-
==== Manual installation
-Alternatively, procure both `rust-analyzer.vsix` and your platform's matching `rust-analyzer-{platform}`, for example from the
+Alternatively, download a VSIX corresponding to your platform from the
https://github.com/rust-analyzer/rust-analyzer/releases[releases] page.
Install the extension with the `Extensions: Install from VSIX` command within VS Code, or from the command line via:
$ code --install-extension /path/to/rust-analyzer.vsix
----
-Copy the `rust-analyzer-{platform}` binary anywhere, then add the path to your settings.json, for example:
+If you are running an unsupported platform, you can install `rust-analyzer-no-server.vsix` and compile or obtain a server binary.
+Copy the server anywhere, then add the path to your settings.json, for example:
[source,json]
----
{ "rust-analyzer.server.path": "~/.local/bin/rust-analyzer-linux" }
==== Building From Source
-Alternatively, both the server and the Code plugin can be installed from source:
+Both the server and the Code plugin can be installed from source:
[source]
----
$ cargo xtask install
----
-You'll need Cargo, nodejs and npm for this.
+You'll need Cargo, nodejs (matching a supported version of VS Code) 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.
[source,bash]
----
+$ mkdir -p ~/.local/bin
$ curl -L https://github.com/rust-analyzer/rust-analyzer/releases/latest/download/rust-analyzer-x86_64-unknown-linux-gnu.gz | gunzip -c - > ~/.local/bin/rust-analyzer
$ chmod +x ~/.local/bin/rust-analyzer
----
Make sure that `~/.local/bin` is listed in the `$PATH` variable and use the appropriate URL if you're not on a `x86-64` system.
+You don't have to use `~/.local/bin`, any other path like `~/.cargo/bin` or `/usr/local/bin` will work just as well.
+
Alternatively, you can install it from source using the command below.
You'll need the latest stable version of the Rust toolchain.
`rust-analyzer` is available in `rustup`, but only in the nightly toolchain:
[source,bash]
----
+----
$ rustup +nightly component add rust-analyzer-preview
----
+----
+
+However, in contrast to `component add clippy` or `component add rustfmt`, this does not actually place a `rust-analyzer` binary in `~/.cargo/bin`, see https://github.com/rust-lang/rustup/issues/2411[this issue].
==== Arch Linux
`rust-analyzer` is available in the GURU repository:
-- https://gitweb.gentoo.org/repo/proj/guru.git/tree/dev-util/rust-analyzer-bin/rust-analyzer-bin-9999.ebuild[`dev-util/rust-analyzer-bin-9999`] (the https://github.com/rust-analyzer/rust-analyzer/releases/latest[latest release] as a live binary ebuild)
+- https://gitweb.gentoo.org/repo/proj/guru.git/tree/dev-util/rust-analyzer?id=9895cea62602cfe599bd48e0fb02127411ca6e81[`dev-util/rust-analyzer`] builds from source
+- https://gitweb.gentoo.org/repo/proj/guru.git/tree/dev-util/rust-analyzer-bin?id=9895cea62602cfe599bd48e0fb02127411ca6e81[`dev-util/rust-analyzer-bin`] installs an official binary release
If not already, GURU must be enabled (e.g. using `app-eselect/eselect-repository`) and sync'd before running `emerge`:
* same configurations as VSCode extension, `rust-analyzer.server.path`, `rust-analyzer.cargo.features` etc.
* same commands too, `rust-analyzer.analyzerStatus`, `rust-analyzer.ssr` etc.
* inlay hints for variables and method chaining, _Neovim Only_
- * semantic highlighting is not implemented yet
Note: for code actions, use `coc-codeaction-cursor` and `coc-codeaction-selected`; `coc-codeaction` and `coc-codeaction-line` are unlikely to be useful.
=== Kate Text Editor
Support for the language server protocol is built into Kate through the LSP plugin, which is included by default.
-It is preconfigured to use Rls for rust sources, but allows you to use rust-analyzer through a simple settings change.
+It is preconfigured to use rust-analyzer for Rust sources since Kate 21.12.
+
+Earlier versions allow you to use rust-analyzer through a simple settings change.
In the LSP Client settings of Kate, copy the content of the third tab "default parameters" to the second tab "server configuration".
Then in the configuration replace:
[source,json]
The next thing to check would be panic messages in rust-analyzer's log.
Log messages are printed to stderr, in VS Code you can see then in the `Output > Rust Analyzer Language Server` tab of the panel.
-To see more logs, set `RA_LOG=info` environmental variable.
+To see more logs, set the `RA_LOG=info` environment variable, this can be done either by setting the environment variable manually or by using `rust-analyzer.server.extraEnv`, note that both of these approaches require the server to be restarted.
To fully capture LSP messages between the editor and the server, set `"rust-analyzer.trace.server": "verbose"` config and check
`Output > Rust Analyzer Language Server Trace`.
target?: string;
/// Environment variables, used for
/// the `env!` macro
- env: : { [key: string]: string; },
+ env: { [key: string]: string; },
/// Whether the crate is a proc-macro crate.
- is_proc_macro: bool;
+ is_proc_macro: boolean;
/// For proc-macro crates, path to compiled
/// proc-macro (.so file).
proc_macro_dylib_path?: string;
See https://github.com/rust-analyzer/rust-project.json-example for a small example.
-You can set `RA_LOG` environmental variable to `rust_analyzer=info` to inspect how rust-analyzer handles config and project loading.
+You can set the `RA_LOG` environment variable to `rust_analyzer=info` to inspect how rust-analyzer handles config and project loading.
Note that calls to `cargo check` are disabled when using `rust-project.json` by default, so compilation errors and warnings will no longer be sent to your LSP client. To enable these compilation errors you will need to specify explicitly what command rust-analyzer should run to perform the checks using the `checkOnSave.overrideCommand` configuration. As an example, the following configuration explicitly sets `cargo check` as the `checkOnSave` command.
{ "rust-analyzer.checkOnSave.overrideCommand": ["cargo", "check", "--message-format=json"] }
----
-The `checkOnSave.overrideCommand` requires the command specified to output json error messages for rust-analyzer to consume. The `--message-format=json` flag does this for `cargo check` so whichever command you use must also output errors in this format. See the <<Configuration>> section for more information.
+The `checkOnSave.overrideCommand` requires the command specified to output json error messages for rust-analyzer to consume. The `--message-format=json` flag does this for `cargo check` so whichever command you use must also output errors in this format. See the <<Configuration>> section for more information.
== Security
The LSP server performs no network access in itself, but runs `cargo metadata` which will update or download the crate registry and the source code of the project dependencies.
If enabled (the default), build scripts and procedural macros can do anything.
-The Code extension automatically connects to GitHub to download updated LSP binaries and, if the nightly channel is selected, to perform update checks using the GitHub API. For `rust-analyzer` developers, using `cargo xtask release` uses the same API to put together the release notes.
+The Code extension does not access the network.
Any other editor plugins are not under the control of the `rust-analyzer` developers. For any privacy concerns, you should check with their respective developers.
+For `rust-analyzer` developers, `cargo xtask release` uses the GitHub API to put together the release notes.
+
== Features
include::./generated_features.adoc[]
projects / rust.git / blobdiff