fork/rust-analyzer

git clone https://git.julia.blue/fork/rust-analyzer

borsAuto merge of #12742 - TonalidadeHidrica:fix-obsolete-config-keys, r=Veykril84a6bc99ad

nightly
33.7 KiB863 linesraw
1= User Manual
2:toc: preamble
3:sectanchors:
4:page-layout: post
5:icons: font
6:source-highlighter: rouge
7:experimental:
8
9////
10IMPORTANT: the master copy of this document lives in the https://github.com/rust-lang/rust-analyzer repository
11////
12
13At its core, rust-analyzer is a *library* for semantic analysis of Rust code as it changes over time.
14This manual focuses on a specific usage of the library -- running it as part of a server that implements the
15https://microsoft.github.io/language-server-protocol/[Language Server Protocol] (LSP).
16The 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.
17
18[TIP]
19====
20[.lead]
21To improve this document, send a pull request: +
22https://github.com/rust-lang/rust-analyzer/blob/master/docs/user/manual.adoc[https://github.com/rust-analyzer/.../manual.adoc]
23
24The manual is written in https://asciidoc.org[AsciiDoc] and includes some extra files which are generated from the source code. Run `cargo test` and `cargo test -p xtask` to create these and then `asciidoctor manual.adoc` to create an HTML copy.
25====
26
27If 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.
28
29== Installation
30
31In theory, one should be able to just install the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>> and have it automatically work with any editor.
32We are not there yet, so some editor specific setup is required.
33
34Additionally, rust-analyzer needs the sources of the standard library.
35If the source code is not present, rust-analyzer will attempt to install it automatically.
36
37To add the sources manually, run the following command:
38
39```bash
40$ rustup component add rust-src
41```
42
43=== Toolchain
44
45Only the latest stable standard library source is officially supported for use with rust-analyzer.
46If you are using an older toolchain or have an override set, rust-analyzer may fail to understand the Rust source.
47You will either need to update your toolchain or use an older version of rust-analyzer that is compatible with your toolchain.
48
49If you are using an override in your project, you can still force rust-analyzer to use the stable toolchain via the environment variable `RUSTUP_TOOLCHAIN`.
50For example, with VS Code or coc-rust-analyzer:
51
52[source,json]
53----
54{ "rust-analyzer.server.extraEnv": { "RUSTUP_TOOLCHAIN": "stable" } }
55----
56
57=== VS Code
58
59This is the best supported editor at the moment.
60The rust-analyzer plugin for VS Code is maintained
61https://github.com/rust-lang/rust-analyzer/tree/master/editors/code[in tree].
62
63You can install the latest release of the plugin from
64https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer[the marketplace].
65
66Note that the plugin may cause conflicts with the
67https://marketplace.visualstudio.com/items?itemName=rust-lang.rust[official Rust plugin].
68It is recommended to disable the Rust plugin when using the rust-analyzer extension.
69
70By default, the plugin will prompt you to download the matching version of the server as well:
71
72image::https://user-images.githubusercontent.com/9021944/75067008-17502500-54ba-11ea-835a-f92aac50e866.png[]
73
74[NOTE]
75====
76To disable this notification put the following to `settings.json`
77
78[source,json]
79----
80{ "rust-analyzer.updates.askBeforeDownload": false }
81----
82====
83
84The server binary is stored in the extension install directory, which starts with `rust-lang.rust-analyzer-` and is located under:
85
86* Linux: `~/.vscode/extensions`
87* Linux (Remote, such as WSL): `~/.vscode-server/extensions`
88* macOS: `~/.vscode/extensions`
89* Windows: `%USERPROFILE%\.vscode\extensions`
90
91As an exception, on NixOS, the extension makes a copy of the server and stores it under `~/.config/Code/User/globalStorage/rust-lang.rust-analyzer`.
92
93Note that we only support the two most recent versions of VS Code.
94
95==== Updates
96
97The extension will be updated automatically as new versions become available.
98It will ask your permission to download the matching language server version binary if needed.
99
100===== Nightly
101
102We ship nightly releases for VS Code.
103To help us out by testing the newest code, you can enable pre-release versions in the Code extension page.
104
105==== Manual installation
106
107Alternatively, download a VSIX corresponding to your platform from the
108https://github.com/rust-lang/rust-analyzer/releases[releases] page.
109
110Install the extension with the `Extensions: Install from VSIX` command within VS Code, or from the command line via:
111[source]
112----
113$ code --install-extension /path/to/rust-analyzer.vsix
114----
115
116If you are running an unsupported platform, you can install `rust-analyzer-no-server.vsix` and compile or obtain a server binary.
117Copy the server anywhere, then add the path to your settings.json, for example:
118[source,json]
119----
120{ "rust-analyzer.server.path": "~/.local/bin/rust-analyzer-linux" }
121----
122
123==== Building From Source
124
125Both the server and the Code plugin can be installed from source:
126
127[source]
128----
129$ git clone https://github.com/rust-lang/rust-analyzer.git && cd rust-analyzer
130$ cargo xtask install
131----
132
133You'll need Cargo, nodejs (matching a supported version of VS Code) and npm for this.
134
135Note that installing via `xtask install` does not work for VS Code Remote, instead you'll need to install the `.vsix` manually.
136
137If you're not using Code, you can compile and install only the LSP server:
138
139[source]
140----
141$ cargo xtask install --server
142----
143
144=== rust-analyzer Language Server Binary
145
146Other editors generally require the `rust-analyzer` binary to be in `$PATH`.
147You can download pre-built binaries from the https://github.com/rust-lang/rust-analyzer/releases[releases] page.
148You will need to uncompress and rename the binary for your platform, e.g. from `rust-analyzer-aarch64-apple-darwin.gz` on Mac OS to `rust-analyzer`, make it executable, then move it into a directory in your `$PATH`.
149
150On Linux to install the `rust-analyzer` binary into `~/.local/bin`, these commands should work:
151
152[source,bash]
153----
154$ mkdir -p ~/.local/bin
155$ curl -L https://github.com/rust-lang/rust-analyzer/releases/latest/download/rust-analyzer-x86_64-unknown-linux-gnu.gz | gunzip -c - > ~/.local/bin/rust-analyzer
156$ chmod +x ~/.local/bin/rust-analyzer
157----
158
159Make sure that `~/.local/bin` is listed in the `$PATH` variable and use the appropriate URL if you're not on a `x86-64` system.
160
161You don't have to use `~/.local/bin`, any other path like `~/.cargo/bin` or `/usr/local/bin` will work just as well.
162
163Alternatively, you can install it from source using the command below.
164You'll need the latest stable version of the Rust toolchain.
165
166[source,bash]
167----
168$ git clone https://github.com/rust-lang/rust-analyzer.git && cd rust-analyzer
169$ cargo xtask install --server
170----
171
172If 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-lang/rust-analyzer/issues/1811[this issue].
173On Unix, running the editor from a shell or changing the `.desktop` file to set the environment should help.
174
175==== `rustup`
176
177`rust-analyzer` is available in `rustup`, but only in the nightly toolchain:
178
179[source,bash]
180----
181$ rustup +nightly component add rust-analyzer-preview
182----
183
184However, 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].
185
186==== Arch Linux
187
188The `rust-analyzer` binary can be installed from the repos or AUR (Arch User Repository):
189
190- https://www.archlinux.org/packages/community/x86_64/rust-analyzer/[`rust-analyzer`] (built from latest tagged source)
191- https://aur.archlinux.org/packages/rust-analyzer-git[`rust-analyzer-git`] (latest Git version)
192
193Install it with pacman, for example:
194
195[source,bash]
196----
197$ pacman -S rust-analyzer
198----
199
200==== Gentoo Linux
201
202`rust-analyzer` is available in the GURU repository:
203
204- https://gitweb.gentoo.org/repo/proj/guru.git/tree/dev-util/rust-analyzer?id=9895cea62602cfe599bd48e0fb02127411ca6e81[`dev-util/rust-analyzer`] builds from source
205- 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
206
207If not already, GURU must be enabled (e.g. using `app-eselect/eselect-repository`) and sync'd before running `emerge`:
208
209[source,bash]
210----
211$ eselect repository enable guru && emaint sync -r guru
212$ emerge rust-analyzer-bin
213----
214
215==== macOS
216
217The `rust-analyzer` binary can be installed via https://brew.sh/[Homebrew].
218
219[source,bash]
220----
221$ brew install rust-analyzer
222----
223
224=== Emacs
225
226Note this excellent https://robert.kra.hn/posts/2021-02-07_rust-with-emacs/[guide] from https://github.com/rksm[@rksm].
227
228Prerequisites: You have installed the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>>.
229
230Emacs 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].
231
2321. Install the most recent version of `emacs-lsp` package by following the https://github.com/emacs-lsp/lsp-mode[Emacs-LSP instructions].
2332. Set `lsp-rust-server` to `'rust-analyzer`.
2343. Run `lsp` in a Rust buffer.
2354. (Optionally) bind commands like `lsp-rust-analyzer-join-lines`, `lsp-extend-selection` and `lsp-rust-analyzer-expand-macro` to keys.
236
237=== Vim/NeoVim
238
239Prerequisites: You have installed the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>>.
240Not needed if the extension can install/update it on its own, coc-rust-analyzer is one example.
241
242There are several LSP client implementations for vim or neovim:
243
244==== coc-rust-analyzer
245
2461. Install coc.nvim by following the instructions at
247   https://github.com/neoclide/coc.nvim[coc.nvim]
248   (Node.js required)
2492. Run `:CocInstall coc-rust-analyzer` to install
250   https://github.com/fannheyward/coc-rust-analyzer[coc-rust-analyzer],
251   this extension implements _most_ of the features supported in the VSCode extension:
252   * automatically install and upgrade stable/nightly releases
253   * same configurations as VSCode extension, `rust-analyzer.server.path`, `rust-analyzer.cargo.features` etc.
254   * same commands too, `rust-analyzer.analyzerStatus`, `rust-analyzer.ssr` etc.
255   * inlay hints for variables and method chaining, _Neovim Only_
256
257Note: for code actions, use `coc-codeaction-cursor` and `coc-codeaction-selected`; `coc-codeaction` and `coc-codeaction-line` are unlikely to be useful.
258
259==== LanguageClient-neovim
260
2611. Install LanguageClient-neovim by following the instructions
262   https://github.com/autozimu/LanguageClient-neovim[here]
263   * The GitHub project wiki has extra tips on configuration
264
2652. Configure by adding this to your vim/neovim config file (replacing the existing Rust-specific line if it exists):
266+
267[source,vim]
268----
269let g:LanguageClient_serverCommands = {
270\ 'rust': ['rust-analyzer'],
271\ }
272----
273
274==== YouCompleteMe
275
276Install YouCompleteMe by following the instructions
277  https://github.com/ycm-core/YouCompleteMe#installation[here].
278
279rust-analyzer is the default in ycm, it should work out of the box.
280
281==== ALE
282
283To use the LSP server in https://github.com/dense-analysis/ale[ale]:
284
285[source,vim]
286----
287let g:ale_linters = {'rust': ['analyzer']}
288----
289
290==== nvim-lsp
291
292NeoVim 0.5 has built-in language server support.
293For a quick start configuration of rust-analyzer, use https://github.com/neovim/nvim-lspconfig#rust_analyzer[neovim/nvim-lspconfig].
294Once `neovim/nvim-lspconfig` is installed, use `+lua require'lspconfig'.rust_analyzer.setup({})+` in your `init.vim`.
295
296You can also pass LSP settings to the server:
297
298[source,vim]
299----
300lua << EOF
301local nvim_lsp = require'lspconfig'
302
303local on_attach = function(client)
304    require'completion'.on_attach(client)
305end
306
307nvim_lsp.rust_analyzer.setup({
308    on_attach=on_attach,
309    settings = {
310        ["rust-analyzer"] = {
311            imports = {
312                granularity = {
313                    group = "module",
314                },
315                prefix = "self",
316            },
317            cargo = {
318                buildScripts = {
319                    enable = true,
320                },
321            },
322            procMacro = {
323                enable = true
324            },
325        }
326    }
327})
328EOF
329----
330
331See https://sharksforarms.dev/posts/neovim-rust/ for more tips on getting started.
332
333Check out https://github.com/simrat39/rust-tools.nvim for a batteries included rust-analyzer setup for neovim.
334
335==== vim-lsp
336
337vim-lsp is installed by following https://github.com/prabirshrestha/vim-lsp[the plugin instructions].
338It can be as simple as adding this line to your `.vimrc`:
339
340[source,vim]
341----
342Plug 'prabirshrestha/vim-lsp'
343----
344
345Next you need to register the `rust-analyzer` binary.
346If it is available in `$PATH`, you may want to add this to your `.vimrc`:
347
348[source,vim]
349----
350if executable('rust-analyzer')
351  au User lsp_setup call lsp#register_server({
352        \   'name': 'Rust Language Server',
353        \   'cmd': {server_info->['rust-analyzer']},
354        \   'whitelist': ['rust'],
355        \ })
356endif
357----
358
359There is no dedicated UI for the server configuration, so you would need to send any options as a value of the `initialization_options` field, as described in the <<_configuration,Configuration>> section.
360Here is an example of how to enable the proc-macro support:
361
362[source,vim]
363----
364if executable('rust-analyzer')
365  au User lsp_setup call lsp#register_server({
366        \   'name': 'Rust Language Server',
367        \   'cmd': {server_info->['rust-analyzer']},
368        \   'whitelist': ['rust'],
369        \   'initialization_options': {
370        \     'cargo': {
371        \       'buildScripts': {
372        \         'enable': v:true,
373        \       },
374        \     },
375        \     'procMacro': {
376        \       'enable': v:true,
377        \     },
378        \   },
379        \ })
380endif
381----
382
383=== Sublime Text
384
385==== Sublime Text 4:
386* Follow the instructions in link:https://github.com/sublimelsp/LSP-rust-analyzer[LSP-rust-analyzer].
387
388NOTE: Install link:https://packagecontrol.io/packages/LSP-file-watcher-chokidar[LSP-file-watcher-chokidar] to enable file watching (`workspace/didChangeWatchedFiles`).
389
390==== Sublime Text 3:
391* Install the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>>.
392* Install the link:https://packagecontrol.io/packages/LSP[LSP package].
393* From the command palette, run `LSP: Enable Language Server Globally` and select `rust-analyzer`.
394
395If it worked, you should see "rust-analyzer, Line X, Column Y" on the left side of the status bar, and after waiting a bit, functionalities like tooltips on hovering over variables should become available.
396
397If you get an error saying `No such file or directory: 'rust-analyzer'`, see the <<rust-analyzer-language-server-binary,`rust-analyzer` binary>> section on installing the language server binary.
398
399=== GNOME Builder
400
401GNOME Builder 3.37.1 and newer has native `rust-analyzer` support.
402If the LSP binary is not available, GNOME Builder can install it when opening a Rust file.
403
404
405=== Eclipse IDE
406
407Support for Rust development in the Eclipse IDE is provided by link:https://github.com/eclipse/corrosion[Eclipse Corrosion].
408If available in PATH or in some standard location, `rust-analyzer` is detected and powers editing of Rust files without further configuration.
409If `rust-analyzer` is not detected, Corrosion will prompt you for configuration of your Rust toolchain and language server with a link to the __Window > Preferences > Rust__ preference page; from here a button allows to download and configure `rust-analyzer`, but you can also reference another installation.
410You'll need to close and reopen all .rs and Cargo files, or to restart the IDE, for this change to take effect.
411
412=== Kate Text Editor
413
414Support for the language server protocol is built into Kate through the LSP plugin, which is included by default.
415It is preconfigured to use rust-analyzer for Rust sources since Kate 21.12.
416
417Earlier versions allow you to use rust-analyzer through a simple settings change.
418In the LSP Client settings of Kate, copy the content of the third tab "default parameters" to the second tab "server configuration".
419Then in the configuration replace:
420[source,json]
421----
422        "rust": {
423            "command": ["rls"],
424            "rootIndicationFileNames": ["Cargo.lock", "Cargo.toml"],
425            "url": "https://github.com/rust-lang/rls",
426            "highlightingModeRegex": "^Rust$"
427        },
428----
429With
430[source,json]
431----
432        "rust": {
433            "command": ["rust-analyzer"],
434            "rootIndicationFileNames": ["Cargo.lock", "Cargo.toml"],
435            "url": "https://github.com/rust-lang/rust-analyzer",
436            "highlightingModeRegex": "^Rust$"
437        },
438----
439Then click on apply, and restart the LSP server for your rust project.
440
441=== juCi++
442
443https://gitlab.com/cppit/jucipp[juCi++] has built-in support for the language server protocol, and since version 1.7.0 offers installation of both Rust and rust-analyzer when opening a Rust file.
444
445=== Kakoune
446
447https://kakoune.org/[Kakoune] supports LSP with the help of https://github.com/kak-lsp/kak-lsp[`kak-lsp`].
448Follow the https://github.com/kak-lsp/kak-lsp#installation[instructions] to install `kak-lsp`.
449To configure `kak-lsp`, refer to the https://github.com/kak-lsp/kak-lsp#configuring-kak-lsp[configuration section] which is basically about copying the https://github.com/kak-lsp/kak-lsp/blob/master/kak-lsp.toml[configuration file] in the right place (latest versions should use `rust-analyzer` by default).
450
451Finally, you need to configure Kakoune to talk to `kak-lsp` (see https://github.com/kak-lsp/kak-lsp#usage[Usage section]).
452A basic configuration will only get you LSP but you can also activate inlay diagnostics and auto-formatting on save.
453The following might help you get all of this.
454
455[source,txt]
456----
457eval %sh{kak-lsp --kakoune -s $kak_session}  # Not needed if you load it with plug.kak.
458hook global WinSetOption filetype=rust %{
459    # Enable LSP
460    lsp-enable-window
461
462    # Auto-formatting on save
463    hook window BufWritePre .* lsp-formatting-sync
464
465    # Configure inlay hints (only on save)
466    hook window -group rust-inlay-hints BufWritePost .* rust-analyzer-inlay-hints
467    hook -once -always window WinSetOption filetype=.* %{
468        remove-hooks window rust-inlay-hints
469    }
470}
471----
472
473=== Helix
474
475https://docs.helix-editor.com/[Helix] supports LSP by default.
476However, it won't install `rust-analyzer` automatically.
477You can follow instructions for installing <<rust-analyzer-language-server-binary,`rust-analyzer` binary>>.
478
479== Troubleshooting
480
481Start with looking at the rust-analyzer version.
482Try **Rust Analyzer: Show RA Version** in VS Code (using **Command Palette** feature typically activated by Ctrl+Shift+P) or `rust-analyzer --version` in the command line.
483If the date is more than a week ago, it's better to update rust-analyzer version.
484
485The next thing to check would be panic messages in rust-analyzer's log.
486Log messages are printed to stderr, in VS Code you can see then in the `Output > Rust Analyzer Language Server` tab of the panel.
487To 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.
488
489To fully capture LSP messages between the editor and the server, set `"rust-analyzer.trace.server": "verbose"` config and check
490`Output > Rust Analyzer Language Server Trace`.
491
492The root cause for many "`nothing works`" problems is that rust-analyzer fails to understand the project structure.
493To debug that, first note the `rust-analyzer` section in the status bar.
494If it has an error icon and red, that's the problem (hover will have somewhat helpful error message).
495**Rust Analyzer: Status** prints dependency information for the current file.
496Finally, `RA_LOG=project_model=debug` enables verbose logs during project loading.
497
498If rust-analyzer outright crashes, try running `rust-analyzer analysis-stats /path/to/project/directory/` on the command line.
499This command type checks the whole project in batch mode bypassing LSP machinery.
500
501When filing issues, it is useful (but not necessary) to try to minimize examples.
502An ideal bug reproduction looks like this:
503
504```bash
505$ git clone https://github.com/username/repo.git && cd repo && git switch --detach commit-hash
506$ rust-analyzer --version
507rust-analyzer dd12184e4 2021-05-08 dev
508$ rust-analyzer analysis-stats .
509💀 💀 💀
510```
511
512It is especially useful when the `repo` doesn't use external crates or the standard library.
513
514If you want to go as far as to modify the source code to debug the problem, be sure to take a look at the
515https://github.com/rust-lang/rust-analyzer/tree/master/docs/dev[dev docs]!
516
517== Configuration
518
519**Source:** https://github.com/rust-lang/rust-analyzer/blob/master/crates/rust-analyzer/src/config.rs[config.rs]
520
521The <<_installation,Installation>> section contains details on configuration for some of the editors.
522In general `rust-analyzer` is configured via LSP messages, which means that it's up to the editor to decide on the exact format and location of configuration files.
523
524Some clients, such as <<vs-code,VS Code>> or <<coc-rust-analyzer,COC plugin in Vim>> provide `rust-analyzer` specific configuration UIs. Others may require you to know a bit more about the interaction with `rust-analyzer`.
525
526For the later category, it might help to know that the initial configuration is specified as a value of the `initializationOptions` field of the https://microsoft.github.io/language-server-protocol/specifications/specification-current/#initialize[`InitializeParams` message, in the LSP protocol].
527The spec says that the field type is `any?`, but `rust-analyzer` is looking for a JSON object that is constructed using settings from the list below.
528Name of the setting, ignoring the `rust-analyzer.` prefix, is used as a path, and value of the setting becomes the JSON property value.
529
530For example, a very common configuration is to enable proc-macro support, can be achieved by sending this JSON:
531
532[source,json]
533----
534{
535  "cargo": {
536    "buildScripts": {
537      "enable": true,
538    },
539  },
540  "procMacro": {
541    "enable": true,
542  }
543}
544----
545
546Please consult your editor's documentation to learn more about how to configure https://microsoft.github.io/language-server-protocol/[LSP servers].
547
548To verify which configuration is actually used by `rust-analyzer`, set `RA_LOG` environment variable to `rust_analyzer=info` and look for config-related messages.
549Logs should show both the JSON that `rust-analyzer` sees as well as the updated config.
550
551This is the list of config options `rust-analyzer` supports:
552
553include::./generated_config.adoc[]
554
555== Non-Cargo Based Projects
556
557rust-analyzer does not require Cargo.
558However, if you use some other build system, you'll have to describe the structure of your project for rust-analyzer in the `rust-project.json` format:
559
560[source,TypeScript]
561----
562interface JsonProject {
563    /// Path to the directory with *source code* of
564    /// sysroot crates.
565    ///
566    /// It should point to the directory where std,
567    /// core, and friends can be found:
568    ///
569    /// https://github.com/rust-lang/rust/tree/master/library.
570    ///
571    /// If provided, rust-analyzer automatically adds
572    /// dependencies on sysroot crates. Conversely,
573    /// if you omit this path, you can specify sysroot
574    /// dependencies yourself and, for example, have
575    /// several different "sysroots" in one graph of
576    /// crates.
577    sysroot_src?: string;
578    /// The set of crates comprising the current
579    /// project. Must include all transitive
580    /// dependencies as well as sysroot crate (libstd,
581    /// libcore and such).
582    crates: Crate[];
583}
584
585interface Crate {
586    /// Optional crate name used for display purposes,
587    /// without affecting semantics. See the `deps`
588    /// key for semantically-significant crate names.
589    display_name?: string;
590    /// Path to the root module of the crate.
591    root_module: string;
592    /// Edition of the crate.
593    edition: "2015" | "2018" | "2021";
594    /// Dependencies
595    deps: Dep[];
596    /// Should this crate be treated as a member of
597    /// current "workspace".
598    ///
599    /// By default, inferred from the `root_module`
600    /// (members are the crates which reside inside
601    /// the directory opened in the editor).
602    ///
603    /// Set this to `false` for things like standard
604    /// library and 3rd party crates to enable
605    /// performance optimizations (rust-analyzer
606    /// assumes that non-member crates don't change).
607    is_workspace_member?: boolean;
608    /// Optionally specify the (super)set of `.rs`
609    /// files comprising this crate.
610    ///
611    /// By default, rust-analyzer assumes that only
612    /// files under `root_module.parent` can belong
613    /// to a crate. `include_dirs` are included
614    /// recursively, unless a subdirectory is in
615    /// `exclude_dirs`.
616    ///
617    /// Different crates can share the same `source`.
618    ///
619    /// If two crates share an `.rs` file in common,
620    /// they *must* have the same `source`.
621    /// rust-analyzer assumes that files from one
622    /// source can't refer to files in another source.
623    source?: {
624        include_dirs: string[],
625        exclude_dirs: string[],
626    },
627    /// The set of cfgs activated for a given crate, like
628    /// `["unix", "feature=\"foo\"", "feature=\"bar\""]`.
629    cfg: string[];
630    /// Target triple for this Crate.
631    ///
632    /// Used when running `rustc --print cfg`
633    /// to get target-specific cfgs.
634    target?: string;
635    /// Environment variables, used for
636    /// the `env!` macro
637    env: { [key: string]: string; },
638
639    /// Whether the crate is a proc-macro crate.
640    is_proc_macro: boolean;
641    /// For proc-macro crates, path to compiled
642    /// proc-macro (.so file).
643    proc_macro_dylib_path?: string;
644}
645
646interface Dep {
647    /// Index of a crate in the `crates` array.
648    crate: number,
649    /// Name as should appear in the (implicit)
650    /// `extern crate name` declaration.
651    name: string,
652}
653----
654
655This format is provisional and subject to change.
656Specifically, the `roots` setup will be different eventually.
657
658There are three ways to feed `rust-project.json` to rust-analyzer:
659
660* Place `rust-project.json` file at the root of the project, and rust-analyzer will discover it.
661* Specify `"rust-analyzer.linkedProjects": [ "path/to/rust-project.json" ]` in the settings (and make sure that your LSP client sends settings as a part of initialize request).
662* Specify `"rust-analyzer.linkedProjects": [ { "roots": [...], "crates": [...] }]` inline.
663
664Relative paths are interpreted relative to `rust-project.json` file location or (for inline JSON) relative to `rootUri`.
665
666See https://github.com/rust-analyzer/rust-project.json-example for a small example.
667
668You can set the `RA_LOG` environment variable to `rust_analyzer=info` to inspect how rust-analyzer handles config and project loading.
669
670Note 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.
671
672[source,json]
673----
674{ "rust-analyzer.checkOnSave.overrideCommand": ["cargo", "check", "--message-format=json"] }
675----
676
677The `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.
678
679== Security
680
681At the moment, rust-analyzer assumes that all code is trusted.
682Here is a **non-exhaustive** list of ways to make rust-analyzer execute arbitrary code:
683
684* proc macros and build scripts are executed by default
685* `.cargo/config` can override `rustc` with an arbitrary executable
686* `rust-toolchain.toml` can override `rustc` with an arbitrary executable
687* VS Code plugin reads configuration from project directory, and that can be used to override paths to various executables, like `rustfmt` or `rust-analyzer` itself.
688* rust-analyzer's syntax trees library uses a lot of `unsafe` and hasn't been properly audited for memory safety.
689
690== Privacy
691
692The 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.
693If enabled (the default), build scripts and procedural macros can do anything.
694
695The Code extension does not access the network.
696
697Any other editor plugins are not under the control of the `rust-analyzer` developers. For any privacy concerns, you should check with their respective developers.
698
699For `rust-analyzer` developers, `cargo xtask release` uses the GitHub API to put together the release notes.
700
701== Features
702
703include::./generated_features.adoc[]
704
705== Assists (Code Actions)
706
707Assists, or code actions, are small local refactorings, available in a particular context.
708They are usually triggered by a shortcut or by clicking a light bulb icon in the editor.
709Cursor position or selection is signified by `┃` character.
710
711include::./generated_assists.adoc[]
712
713== Diagnostics
714
715While most errors and warnings provided by rust-analyzer come from the `cargo check` integration, there's a growing number of diagnostics implemented using rust-analyzer's own analysis.
716Some of these diagnostics don't respect `\#[allow]` or `\#[deny]` attributes yet, but can be turned off using the `rust-analyzer.diagnostics.enable`, `rust-analyzer.diagnostics.experimental.enable` or `rust-analyzer.diagnostics.disabled` settings.
717
718include::./generated_diagnostic.adoc[]
719
720== Editor Features
721=== VS Code
722
723==== Color configurations
724
725It is possible to change the foreground/background color and font family/size of inlay hints.
726Just add this to your `settings.json`:
727
728[source,jsonc]
729----
730{
731  "editor.inlayHints.fontFamily": "Courier New",
732  "editor.inlayHints.fontSize": 11,
733
734  "workbench.colorCustomizations": {
735    // Name of the theme you are currently using
736    "[Default Dark+]": {
737      "editorInlayHint.foreground": "#868686f0",
738      "editorInlayHint.background": "#3d3d3d48",
739
740      // Overrides for specific kinds of inlay hints
741      "editorInlayHint.typeForeground": "#fdb6fdf0",
742      "editorInlayHint.parameterForeground": "#fdb6fdf0",
743    }
744  }
745}
746----
747
748==== Semantic style customizations
749
750You can customize the look of different semantic elements in the source code.
751For example, mutable bindings are underlined by default and you can override this behavior by adding the following section to your `settings.json`:
752
753[source,jsonc]
754----
755{
756  "editor.semanticTokenColorCustomizations": {
757    "rules": {
758      "*.mutable": {
759        "fontStyle": "", // underline is the default
760      },
761    }
762  },
763}
764----
765
766Most themes doesn't support styling unsafe operations differently yet. You can fix this by adding overrides for the rules `operator.unsafe`, `function.unsafe`, and `method.unsafe`:
767
768[source,jsonc]
769----
770{
771   "editor.semanticTokenColorCustomizations": {
772         "rules": {
773             "operator.unsafe": "#ff6600",
774             "function.unsafe": "#ff6600",
775             "method.unsafe": "#ff6600"
776         }
777    },
778}
779----
780
781In addition to the top-level rules you can specify overrides for specific themes. For example, if you wanted to use a darker text color on a specific light theme, you might write:
782
783[source,jsonc]
784----
785{
786   "editor.semanticTokenColorCustomizations": {
787         "rules": {
788             "operator.unsafe": "#ff6600"
789         },
790         "[Ayu Light]": {
791            "rules": {
792               "operator.unsafe": "#572300"
793            }
794         }
795    },
796}
797----
798
799Make sure you include the brackets around the theme name. For example, use `"[Ayu Light]"` to customize the theme Ayu Light.
800
801==== Special `when` clause context for keybindings.
802You may use `inRustProject` context to configure keybindings for rust projects only.
803For example:
804
805[source,json]
806----
807{
808  "key": "ctrl+alt+d",
809  "command": "rust-analyzer.openDocs",
810  "when": "inRustProject"
811}
812----
813More about `when` clause contexts https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts[here].
814
815==== Setting runnable environment variables
816You can use "rust-analyzer.runnableEnv" setting to define runnable environment-specific substitution variables.
817The simplest way for all runnables in a bunch:
818```jsonc
819"rust-analyzer.runnableEnv": {
820    "RUN_SLOW_TESTS": "1"
821}
822```
823
824Or it is possible to specify vars more granularly:
825```jsonc
826"rust-analyzer.runnableEnv": [
827    {
828        // "mask": null, // null mask means that this rule will be applied for all runnables
829        env: {
830             "APP_ID": "1",
831             "APP_DATA": "asdf"
832        }
833    },
834    {
835        "mask": "test_name",
836        "env": {
837             "APP_ID": "2", // overwrites only APP_ID
838        }
839    }
840]
841```
842
843You can use any valid regular expression as a mask.
844Also note that a full runnable name is something like *run bin_or_example_name*, *test some::mod::test_name* or *test-mod some::mod*, so it is possible to distinguish binaries, single tests, and test modules with this masks: `"^run"`, `"^test "` (the trailing space matters!), and `"^test-mod"` respectively.
845
846==== Compiler feedback from external commands
847
848Instead of relying on the built-in `cargo check`, you can configure Code to run a command in the background and use the `$rustc-watch` problem matcher to generate inline error markers from its output.
849
850To do this you need to create a new https://code.visualstudio.com/docs/editor/tasks[VS Code Task] and set `rust-analyzer.checkOnSave.enable: false` in preferences.
851
852For example, if you want to run https://crates.io/crates/cargo-watch[`cargo watch`] instead, you might add the following to `.vscode/tasks.json`:
853
854```json
855{
856    "label": "Watch",
857    "group": "build",
858    "type": "shell",
859    "command": "cargo watch",
860    "problemMatcher": "$rustc-watch",
861    "isBackground": true
862}
863```