Merge pull request #19015 from Wilfred/mdbook

manual: Convert to mdbook

docs/book/README.md

@@ -0,0 +1,29 @@
+# rust-analyzer documentation
+
+The rust analyzer manual uses [mdbook](https://rust-lang.github.io/mdBook/).
+
+## Quick start
+
+To run the documentation site locally:
+
+```shell
+cargo install mdbook
+cd docs/book
+mdbook serve
+# make changes to documentation files in doc/book/src
+# ...
+```
+
+mdbook will rebuild the documentation as changes are made.
+
+## Making updates
+
+While not required, installing the mdbook binary can be helfpul in order to see the changes.
+Start with the mdbook [User Guide](https://rust-lang.github.io/mdBook/guide/installation.html) to familiarize yourself with the tool.
+
+## Generated documentation
+
+Four sections are generated dynamically: assists, configuration, diagnostics and features. Their content is found in the `generated.md` files
+of the respective book section, for example `src/configuration_generated.md`, and are included in the book via mdbook's
+[include](https://rust-lang.github.io/mdBook/format/mdbook.html#including-files) functionality. Generated files can be rebuilt by running the various
+test cases that generate them, or by simply running all of the `rust-analyzer` tests with `cargo test`.

docs/book/book.toml

@@ -0,0 +1,41 @@
+[book]
+authors = ["The rust-analyzer authors"]
+language = "en"
+multilingual = false
+src = "src"
+title = "rust-analyzer"
+
+[rust]
+edition = "2021"
+
+[output.html]
+edit-url-template = "https://github.com/rust-lang/rust-analyzer/edit/master/manual/{path}"
+git-repository-url = "https://github.com/rust-lang/rust-analyzer/tree/master/manual"
+mathjax-support = true
+site-url = "/manual/"
+
+[output.html.playground]
+editable = true
+runnable = false
+line-numbers = true
+
+[output.html.search]
+boost-hierarchy = 2
+boost-paragraph = 1
+boost-title = 2
+expand = true
+heading-split-level = 2
+limit-results = 20
+use-boolean-and = true
+
+[output.html.redirect]
+"/manual.html" = "/index.html"
+
+[output.html.fold]
+enable = true
+level = 3
+
+[preprocessor.toc]
+command = "mdbook-toc"
+renderer = ["html"]
+max-level = 3

docs/book/src/README.md

@@ -0,0 +1,21 @@
+# rust-analyzer
+
+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 [Language Server
+Protocol](https://microsoft.github.io/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:
+[https://github.com/rust-lang/rust-analyzer](https://github.com/rust-lang/rust-analyzer/blob/docs/book/README.md)
+
+The manual is written in markdown and includes
+some extra files which are generated from the source code. Run
+`cargo test` and `cargo xtask codegen` to create these.
+
+If you have questions about using rust-analyzer, please ask them in the
+["IDEs and Editors"](https://users.rust-lang.org/c/ide/14) topic of Rust
+users forum.

docs/book/src/SUMMARY.md

@@ -0,0 +1,13 @@
+# Summary
+
+- [Introduction](README.md)
+- [Installation](installation.md)
+- [Troubleshooting](troubleshooting.md)
+- [Configuration](configuration.md)
+- [Non-Cargo Based Projects](non_cargo_based_projects.md)
+- [Security](security.md)
+- [Privacy](privacy.md)
+- [Features](features.md)
+- [Assists (Code Actions)](assists.md)
+- [Diagnostics](diagnostics.md)
+- [Editor Features](editor_features.md)

docs/book/src/assists.md

@@ -0,0 +1,8 @@
+# Assists
+
+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. Cursor position or selection
+is signified by `┃` character.
+
+{{#include assists_generated.md:2:}}

docs/book/src/configuration.md

@@ -0,0 +1,51 @@
+# Configuration
+
+**Source:**
+[config.rs](https://github.com/rust-lang/rust-analyzer/blob/master/crates/rust-analyzer/src/config.rs)
+
+The [Installation](#_installation) section contains details on
+configuration for some of the editors. In 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.
+
+Some clients, such as [VS Code](#vs-code) or [COC plugin in
+Vim](#coc-rust-analyzer) provide `rust-analyzer` specific configuration
+UIs. Others may require you to know a bit more about the interaction
+with `rust-analyzer`.
+
+For the later category, it might help to know that the initial
+configuration is specified as a value of the `initializationOptions`
+field of the [`InitializeParams` message, in the LSP
+protocol](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#initialize).
+The 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. Name of the setting, ignoring the `rust-analyzer.` prefix,
+is used as a path, and value of the setting becomes the JSON property
+value.
+
+For example, a very common configuration is to enable proc-macro
+support, can be achieved by sending this JSON:
+
+    {
+      "cargo": {
+        "buildScripts": {
+          "enable": true,
+        },
+      },
+      "procMacro": {
+        "enable": true,
+      }
+    }
+
+Please consult your editor’s documentation to learn more about how to
+configure [LSP
+servers](https://microsoft.github.io/language-server-protocol/).
+
+To verify which configuration is actually used by `rust-analyzer`, set
+`RA_LOG` environment variable to `rust_analyzer=info` and look for
+config-related messages. Logs should show both the JSON that
+`rust-analyzer` sees as well as the updated config.
+
+This is the list of config options `rust-analyzer` supports:
+
+{{#include configuration_generated.md}}

docs/book/src/diagnostics.md

@@ -0,0 +1,16 @@
+# Diagnostics
+
+While 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. Some 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.
+
+## Clippy
+
+To run `cargo clippy` instead of `cargo check`, you can set
+`"rust-analyzer.check.command": "clippy"`.
+
+{{#include diagnostics_generated.md:2:}}

docs/book/src/editor_features.md

@@ -0,0 +1,204 @@
+# Editor Features
+
+
+## VS Code
+
+### Color configurations
+
+It is possible to change the foreground/background color and font
+family/size of inlay hints. Just add this to your `settings.json`:
+
+```json
+{
+  "editor.inlayHints.fontFamily": "Courier New",
+  "editor.inlayHints.fontSize": 11,
+
+  "workbench.colorCustomizations": {
+    // Name of the theme you are currently using
+    "[Default Dark+]": {
+      "editorInlayHint.foreground": "#868686f0",
+      "editorInlayHint.background": "#3d3d3d48",
+
+      // Overrides for specific kinds of inlay hints
+      "editorInlayHint.typeForeground": "#fdb6fdf0",
+      "editorInlayHint.parameterForeground": "#fdb6fdf0",
+    }
+  }
+}
+```
+
+### Semantic style customizations
+
+You can customize the look of different semantic elements in the source
+code. For example, mutable bindings are underlined by default and you
+can override this behavior by adding the following section to your
+`settings.json`:
+
+```json
+{
+  "editor.semanticTokenColorCustomizations": {
+    "rules": {
+      "*.mutable": {
+        "fontStyle": "", // underline is the default
+      },
+    }
+  },
+}
+```
+
+Most 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`:
+
+```json
+{
+   "editor.semanticTokenColorCustomizations": {
+         "rules": {
+             "operator.unsafe": "#ff6600",
+             "function.unsafe": "#ff6600",
+             "method.unsafe": "#ff6600"
+         }
+    },
+}
+```
+
+In 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:
+
+```json
+{
+   "editor.semanticTokenColorCustomizations": {
+         "rules": {
+             "operator.unsafe": "#ff6600"
+         },
+         "[Ayu Light]": {
+            "rules": {
+               "operator.unsafe": "#572300"
+            }
+         }
+    },
+}
+```
+
+Make sure you include the brackets around the theme name. For example,
+use `"[Ayu Light]"` to customize the theme Ayu Light.
+
+### Special `when` clause context for keybindings.
+
+You may use `inRustProject` context to configure keybindings for rust
+projects only. For example:
+
+```json
+{
+    "key": "ctrl+alt+d",
+    "command": "rust-analyzer.openDocs",
+    "when": "inRustProject"
+}
+```
+
+More about `when` clause contexts
+[here](https://code.visualstudio.com/docs/getstarted/keybindings#_when-clause-contexts).
+
+### Setting runnable environment variables
+
+You can use "rust-analyzer.runnables.extraEnv" setting to define
+runnable environment-specific substitution variables. The simplest way
+for all runnables in a bunch:
+
+```json
+"rust-analyzer.runnables.extraEnv": {
+    "RUN_SLOW_TESTS": "1"
+}
+```
+
+Or it is possible to specify vars more granularly:
+
+```json
+"rust-analyzer.runnables.extraEnv": [
+    {
+        // "mask": null, // null mask means that this rule will be applied for all runnables
+        env: {
+                "APP_ID": "1",
+                "APP_DATA": "asdf"
+        }
+    },
+    {
+        "mask": "test_name",
+        "env": {
+                "APP_ID": "2", // overwrites only APP_ID
+        }
+    }
+]
+```
+
+You can use any valid regular expression as a mask. Also 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.
+
+If needed, you can set different values for different platforms:
+
+```json
+"rust-analyzer.runnables.extraEnv": [
+    {
+        "platform": "win32", // windows only
+        env: {
+                "APP_DATA": "windows specific data"
+        }
+    },
+    {
+        "platform": ["linux"],
+        "env": {
+                "APP_DATA": "linux data",
+        }
+    },
+    { // for all platforms
+        "env": {
+                "APP_COMMON_DATA": "xxx",
+        }
+    }
+]
+```
+
+### Compiler feedback from external commands
+
+Instead 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.
+
+To do this you need to create a new [VS Code
+Task](https://code.visualstudio.com/docs/editor/tasks) and set
+`"rust-analyzer.checkOnSave": false` in preferences.
+
+For example, if you want to run
+[`cargo watch`](https://crates.io/crates/cargo-watch) instead, you might
+add the following to `.vscode/tasks.json`:
+
+```json
+{
+    "label": "Watch",
+    "group": "build",
+    "type": "shell",
+    "command": "cargo watch",
+    "problemMatcher": "$rustc-watch",
+    "isBackground": true
+}
+```
+
+### Live Share
+
+VS Code Live Share has partial support for rust-analyzer.
+
+Live Share *requires* the official Microsoft build of VS Code, OSS
+builds will not work correctly.
+
+The host’s rust-analyzer instance will be shared with all guests joining
+the session. The guests do not have to have the rust-analyzer extension
+installed for this to work.
+
+If you are joining a Live Share session and *do* have rust-analyzer
+installed locally, commands from the command palette will not work
+correctly since they will attempt to communicate with the local server.

docs/book/src/features.md

@@ -0,0 +1,3 @@
+# Features
+
+{{#include features_generated.md:2:}}

docs/book/src/installation.md

@@ -0,0 +1,644 @@
+# Installation
+
+In theory, one should be able to just install the [`rust-analyzer`
+binary](#rust-analyzer-language-server-binary) 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:
+
+    $ rustup component add rust-src
+
+## Toolchain
+
+Only the latest stable standard library source is officially supported
+for use with rust-analyzer. If you are using an older toolchain or have
+an override set, rust-analyzer may fail to understand the Rust source.
+You will either need to update your toolchain or use an older version of
+rust-analyzer that is compatible with your toolchain.
+
+If 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`. For example, with VS Code or coc-rust-analyzer:
+
+    { "rust-analyzer.server.extraEnv": { "RUSTUP_TOOLCHAIN": "stable" } }
+
+## VS Code
+
+This is the best supported editor at the moment. The rust-analyzer
+plugin for VS Code is maintained [in
+tree](https://github.com/rust-lang/rust-analyzer/tree/master/editors/code).
+
+You can install the latest release of the plugin from [the
+marketplace](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer).
+
+Note that the plugin may cause conflicts with the [previous official
+Rust
+plugin](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust).
+The latter is no longer maintained and should be uninstalled.
+
+The server binary is stored in the extension install directory, which
+starts with `rust-lang.rust-analyzer-` and is located under:
+
+-   Linux: `~/.vscode/extensions`
+
+-   Linux (Remote, such as WSL): `~/.vscode-server/extensions`
+
+-   macOS: `~/.vscode/extensions`
+
+-   Windows: `%USERPROFILE%\.vscode\extensions`
+
+As an exception, on NixOS, the extension makes a copy of the server and
+stores it under
+`~/.config/Code/User/globalStorage/rust-lang.rust-analyzer`.
+
+Note that we only support the two most recent versions of VS Code.
+
+### 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 by testing the
+newest code, you can enable pre-release versions in the Code extension
+page.
+
+### Manual installation
+
+Alternatively, download a VSIX corresponding to your platform from the
+[releases](https://github.com/rust-lang/rust-analyzer/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
+
+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:
+
+    { "rust-analyzer.server.path": "~/.local/bin/rust-analyzer-linux" }
+
+### Building From Source
+
+Both the server and the Code plugin can be installed from source:
+
+    $ git clone https://github.com/rust-lang/rust-analyzer.git && cd rust-analyzer
+    $ cargo xtask install
+
+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.
+
+If you’re not using Code, you can compile and install only the LSP
+server:
+
+    $ cargo xtask install --server
+
+Make sure that `.cargo/bin` is in `$PATH` and precedes paths where
+`rust-analyzer` may also be installed. Specifically, `rustup` includes a
+proxy called `rust-analyzer`, which can cause problems if you’re
+planning to use a source build or even a downloaded binary.
+
+## rust-analyzer Language Server Binary
+
+Other editors generally require the `rust-analyzer` binary to be in
+`$PATH`. You can download pre-built binaries from the
+[releases](https://github.com/rust-lang/rust-analyzer/releases) page.
+You 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`.
+
+On Linux to install the `rust-analyzer` binary into `~/.local/bin`,
+these commands should work:
+
+    $ mkdir -p ~/.local/bin
+    $ 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
+    $ 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.
+
+    $ git clone https://github.com/rust-lang/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 [this
+issue](https://github.com/rust-lang/rust-analyzer/issues/1811). On Unix,
+running the editor from a shell or changing the `.desktop` file to set
+the environment should help.
+
+### rustup
+
+`rust-analyzer` is available in `rustup`:
+
+    $ rustup component add rust-analyzer
+
+### Arch Linux
+
+The `rust-analyzer` binary can be installed from the repos or AUR (Arch
+User Repository):
+
+-   [`rust-analyzer`](https://www.archlinux.org/packages/extra/x86_64/rust-analyzer/)
+    (built from latest tagged source)
+
+-   [`rust-analyzer-git`](https://aur.archlinux.org/packages/rust-analyzer-git)
+    (latest Git version)
+
+Install it with pacman, for example:
+
+    $ pacman -S rust-analyzer
+
+### Gentoo Linux
+
+`rust-analyzer` is installed when the `rust-analyzer` use flag is set for dev-lang/rust or dev-lang/rust-bin. You also need to set the `rust-src` use flag.
+
+### macOS
+
+The `rust-analyzer` binary can be installed via
+[Homebrew](https://brew.sh/).
+
+    $ brew install rust-analyzer
+
+### Windows
+
+It is recommended to install the latest Microsoft Visual C++ Redistributable prior to installation.
+Download links can be found
+[here](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist).
+
+## VS Code or VSCodium in Flatpak
+
+Setting up `rust-analyzer` with a Flatpak version of Code is not trivial
+because of the Flatpak sandbox. While the sandbox can be disabled for
+some directories, `/usr/bin` will always be mounted under
+`/run/host/usr/bin`. This prevents access to the system’s C compiler, a
+system-wide installation of Rust, or any other libraries you might want
+to link to. Some compilers and libraries can be acquired as Flatpak
+SDKs, such as `org.freedesktop.Sdk.Extension.rust-stable` or
+`org.freedesktop.Sdk.Extension.llvm15`.
+
+If you use a Flatpak SDK for Rust, it must be in your `PATH`:
+
+ * install the SDK extensions with `flatpak install org.freedesktop.Sdk.Extension.{llvm15,rust-stable}//23.08`
+ * enable SDK extensions in the editor with the environment variable `FLATPAK_ENABLE_SDK_EXT=llvm15,rust-stable` (this can be done using flatseal or `flatpak override`)
+
+If you want to use Flatpak in combination with `rustup`, the following
+steps might help:
+
+-   both Rust and `rustup` have to be installed using
+    <https://rustup.rs>. Distro packages *will not* work.
+
+-   you need to launch Code, open a terminal and run `echo $PATH`
+
+-   using
+    [Flatseal](https://flathub.org/apps/details/com.github.tchx84.Flatseal),
+    you must add an environment variable called `PATH`. Set its value to
+    the output from above, appending `:~/.cargo/bin`, where `~` is the
+    path to your home directory. You must replace `~`, as it won’t be
+    expanded otherwise.
+
+-   while Flatseal is open, you must enable access to "All user files"
+
+A C compiler should already be available via `org.freedesktop.Sdk`. Any
+other tools or libraries you will need to acquire from Flatpak.
+
+## Emacs
+
+Prerequisites: You have installed the [`rust-analyzer`
+binary](#rust-analyzer-language-server-binary).
+
+To use `rust-analyzer`, you need to install and enable one of the two
+popular LSP client implementations for Emacs,
+[Eglot](https://github.com/joaotavora/eglot) or [LSP
+Mode](https://github.com/emacs-lsp/lsp-mode). Both enable
+`rust-analyzer` by default in rust buffers if it is available.
+
+### Eglot
+
+Eglot is the more minimalistic and lightweight LSP client for Emacs,
+integrates well with existing Emacs functionality and is built into
+Emacs starting from release 29.
+
+After installing Eglot, e.g. via `M-x package-install` (not needed from
+Emacs 29), you can enable it via the `M-x eglot` command or load it
+automatically in `rust-mode` via
+
+    (add-hook 'rust-mode-hook 'eglot-ensure)
+
+To enable clippy, you will need to configure the initialization options
+to pass the `check.command` setting.
+
+    (add-to-list 'eglot-server-programs
+                 '((rust-ts-mode rust-mode) .
+                   ("rust-analyzer" :initializationOptions (:check (:command "clippy")))))
+
+For more detailed instructions and options see the [Eglot
+manual](https://joaotavora.github.io/eglot) (also available from Emacs
+via `M-x info`) and the [Eglot
+readme](https://github.com/joaotavora/eglot/blob/master/README.md).
+
+Eglot does not support the rust-analyzer extensions to the
+language-server protocol and does not aim to do so in the future. The
+[eglot-x](https://github.com/nemethf/eglot-x#rust-analyzer-extensions)
+package adds experimental support for those LSP extensions.
+
+### LSP Mode
+
+LSP-mode is the original LSP-client for emacs. Compared to Eglot it has
+a larger codebase and supports more features, like LSP protocol
+extensions. With extension packages like [LSP
+UI](https://github.com/emacs-lsp/lsp-mode) it offers a lot of visual
+eyecandy. Further it integrates well with [DAP
+mode](https://github.com/emacs-lsp/dap-mode) for support of the Debug
+Adapter Protocol.
+
+You can install LSP-mode via `M-x package-install` and then run it via
+the `M-x lsp` command or load it automatically in rust buffers with
+
+    (add-hook 'rust-mode-hook 'lsp-deferred)
+
+For more information on how to set up LSP mode and its extension package
+see the instructions in the [LSP mode
+manual](https://emacs-lsp.github.io/lsp-mode/page/installation). Also
+see the [rust-analyzer
+section](https://emacs-lsp.github.io/lsp-mode/page/lsp-rust-analyzer/)
+for `rust-analyzer` specific options and commands, which you can
+optionally bind to keys.
+
+Note the excellent
+[guide](https://robert.kra.hn/posts/2021-02-07_rust-with-emacs/) from
+[@rksm](https://github.com/rksm) on how to set-up Emacs for Rust
+development with LSP mode and several other packages.
+
+## Vim/Neovim
+
+Prerequisites: You have installed the [`rust-analyzer`
+binary](#rust-analyzer-language-server-binary). Not needed if the
+extension can install/update it on its own, coc-rust-analyzer is one
+example.
+
+There are several LSP client implementations for Vim or Neovim:
+
+### coc-rust-analyzer
+
+1.  Install coc.nvim by following the instructions at
+    [coc.nvim](https://github.com/neoclide/coc.nvim) (Node.js required)
+
+2.  Run `:CocInstall coc-rust-analyzer` to install
+    [coc-rust-analyzer](https://github.com/fannheyward/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.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*
+
+Note: for code actions, use `coc-codeaction-cursor` and
+`coc-codeaction-selected`; `coc-codeaction` and `coc-codeaction-line`
+are unlikely to be useful.
+
+### LanguageClient-neovim
+
+1.  Install LanguageClient-neovim by following the instructions
+    [here](https://github.com/autozimu/LanguageClient-neovim)
+
+    -   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):
+
+        let g:LanguageClient_serverCommands = {
+        \ 'rust': ['rust-analyzer'],
+        \ }
+
+### YouCompleteMe
+
+Install YouCompleteMe by following the instructions
+[here](https://github.com/ycm-core/YouCompleteMe#installation).
+
+rust-analyzer is the default in ycm, it should work out of the box.
+
+### ALE
+
+To use the LSP server in [ale](https://github.com/dense-analysis/ale):
+
+    let g:ale_linters = {'rust': ['analyzer']}
+
+### nvim-lsp
+
+Neovim 0.5 has built-in language server support. For a quick start
+configuration of rust-analyzer, use
+[neovim/nvim-lspconfig](https://github.com/neovim/nvim-lspconfig#rust_analyzer).
+Once `neovim/nvim-lspconfig` is installed, use
+`lua require'lspconfig'.rust_analyzer.setup({})` in your `init.vim`.
+
+You can also pass LSP settings to the server:
+
+    lua << EOF
+    local lspconfig = require'lspconfig'
+
+    local on_attach = function(client)
+        require'completion'.on_attach(client)
+    end
+
+    lspconfig.rust_analyzer.setup({
+        on_attach = on_attach,
+        settings = {
+            ["rust-analyzer"] = {
+                imports = {
+                    granularity = {
+                        group = "module",
+                    },
+                    prefix = "self",
+                },
+                cargo = {
+                    buildScripts = {
+                        enable = true,
+                    },
+                },
+                procMacro = {
+                    enable = true
+                },
+            }
+        }
+    })
+    EOF
+
+If you're running Neovim 0.10 or later, you can enable inlay hints via `on_attach`:
+
+```vim
+lspconfig.rust_analyzer.setup({
+    on_attach = function(client, bufnr)
+        vim.lsp.inlay_hint.enable(true, { bufnr = bufnr })
+    end
+})
+```
+
+Note that the hints are only visible after `rust-analyzer` has finished loading **and** you have to
+edit the file to trigger a re-render.
+
+See <https://sharksforarms.dev/posts/neovim-rust/> for more tips on
+getting started.
+
+Check out <https://github.com/mrcjkb/rustaceanvim> for a batteries
+included rust-analyzer setup for Neovim.
+
+### vim-lsp
+
+vim-lsp is installed by following [the plugin
+instructions](https://github.com/prabirshrestha/vim-lsp). It can be as
+simple as adding this line to your `.vimrc`:
+
+    Plug 'prabirshrestha/vim-lsp'
+
+Next you need to register the `rust-analyzer` binary. If it is avim.lspvailable
+in `$PATH`, you may want to add this to your `.vimrc`:
+
+    if executable('rust-analyzer')
+      au User lsp_setup call lsp#register_server({
+            \   'name': 'Rust Language Server',
+            \   'cmd': {server_info->['rust-analyzer']},
+            \   'whitelist': ['rust'],
+            \ })
+    endif
+
+There 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. Here is an
+example of how to enable the proc-macro support:
+
+    if executable('rust-analyzer')
+      au User lsp_setup call lsp#register_server({
+            \   'name': 'Rust Language Server',
+            \   'cmd': {server_info->['rust-analyzer']},
+            \   'whitelist': ['rust'],
+            \   'initialization_options': {
+            \     'cargo': {
+            \       'buildScripts': {
+            \         'enable': v:true,
+            \       },
+            \     },
+            \     'procMacro': {
+            \       'enable': v:true,
+            \     },
+            \   },
+            \ })
+    endif
+
+## Sublime Text
+
+### Sublime Text 4:
+
+-   Follow the instructions in
+    [LSP-rust-analyzer](https://github.com/sublimelsp/LSP-rust-analyzer).
+
+Install
+[LSP-file-watcher-chokidar](https://packagecontrol.io/packages/LSP-file-watcher-chokidar)
+to enable file watching (`workspace/didChangeWatchedFiles`).
+
+### Sublime Text 3:
+
+-   Install the [`rust-analyzer`
+    binary](#rust-analyzer-language-server-binary).
+
+-   Install the [LSP package](https://packagecontrol.io/packages/LSP).
+
+-   From the command palette, run `LSP: Enable Language Server Globally`
+    and select `rust-analyzer`.
+
+If 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.
+
+If you get an error saying `No such file or directory: 'rust-analyzer'`,
+see the [`rust-analyzer` binary](#rust-analyzer-language-server-binary)
+section on installing the language server binary.
+
+## GNOME Builder
+
+GNOME Builder 3.37.1 and newer has native `rust-analyzer` support. If
+the LSP binary is not available, GNOME Builder can install it when
+opening a Rust file.
+
+## Eclipse IDE
+
+Support for Rust development in the Eclipse IDE is provided by [Eclipse
+Corrosion](https://github.com/eclipse/corrosion). If available in PATH
+or in some standard location, `rust-analyzer` is detected and powers
+editing of Rust files without further configuration. If `rust-analyzer`
+is not detected, Corrosion will prompt you for configuration of your
+Rust toolchain and language server with a link to the *Window &gt;
+Preferences &gt; Rust* preference page; from here a button allows to
+download and configure `rust-analyzer`, but you can also reference
+another installation. You’ll need to close and reopen all .rs and Cargo
+files, or to restart the IDE, for this change to take effect.
+
+## 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
+rust-analyzer for Rust sources since Kate 21.12.
+
+To change rust-analyzer config options, start from the following example
+and put it into Kate’s "User Server Settings" tab (located under the LSP
+Client settings):
+
+    {
+        "servers": {
+            "rust": {
+                "initializationOptions": {
+                    "cachePriming": {
+                        "enable": false
+                    },
+                    "check": {
+                        "allTargets": false
+                    },
+                    "checkOnSave": false
+                }
+            }
+        }
+    }
+
+Then click on apply, and restart the LSP server for your rust project.
+
+## juCi++
+
+[juCi++](https://gitlab.com/cppit/jucipp) 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.
+
+## Kakoune
+
+[Kakoune](https://kakoune.org/) supports LSP with the help of
+[`kak-lsp`](https://github.com/kak-lsp/kak-lsp). Follow the
+[instructions](https://github.com/kak-lsp/kak-lsp#installation) to
+install `kak-lsp`. To configure `kak-lsp`, refer to the [configuration
+section](https://github.com/kak-lsp/kak-lsp#configuring-kak-lsp) which
+is basically about copying the [configuration
+file](https://github.com/kak-lsp/kak-lsp/blob/master/kak-lsp.toml) in
+the right place (latest versions should use `rust-analyzer` by default).
+
+Finally, you need to configure Kakoune to talk to `kak-lsp` (see [Usage
+section](https://github.com/kak-lsp/kak-lsp#usage)). A basic
+configuration will only get you LSP but you can also activate inlay
+diagnostics and auto-formatting on save. The following might help you
+get all of this.
+
+    eval %sh{kak-lsp --kakoune -s $kak_session}  # Not needed if you load it with plug.kak.
+    hook global WinSetOption filetype=rust %{
+        # Enable LSP
+        lsp-enable-window
+
+        # Auto-formatting on save
+        hook window BufWritePre .* lsp-formatting-sync
+
+        # Configure inlay hints (only on save)
+        hook window -group rust-inlay-hints BufWritePost .* rust-analyzer-inlay-hints
+        hook -once -always window WinSetOption filetype=.* %{
+            remove-hooks window rust-inlay-hints
+        }
+    }
+
+## Helix
+
+[Helix](https://docs.helix-editor.com/) supports LSP by default.
+However, it won’t install `rust-analyzer` automatically. You can follow
+instructions for installing [`rust-analyzer`
+binary](#rust-analyzer-language-server-binary).
+
+## Visual Studio 2022
+
+There are multiple rust-analyzer extensions for Visual Studio 2022 on
+Windows:
+
+### rust-analyzer.vs
+
+(License: Creative Commons Attribution-NonCommercial-ShareAlike 4.0
+International)
+
+[Visual Studio
+Marketplace](https://marketplace.visualstudio.com/items?itemName=kitamstudios.RustAnalyzer)
+
+[GitHub](https://github.com/kitamstudios/rust-analyzer/)
+
+Support for Rust development in the Visual Studio IDE is enabled by the
+[rust-analyzer](https://marketplace.visualstudio.com/items?itemName=kitamstudios.RustAnalyzer)
+package. Either click on the download link or install from IDE’s
+extension manager. For now [Visual Studio
+2022](https://visualstudio.microsoft.com/downloads/) is required. All
+editions are supported viz. Community, Professional & Enterprise. The
+package aims to provide 0-friction installation and therefore comes
+loaded with most things required including rust-analyzer binary. If
+anything it needs is missing, appropriate errors / warnings will guide
+the user. E.g. cargo.exe needs to be in path and the package will tell
+you as much. This package is under rapid active development. So if you
+encounter any issues please file it at
+[rust-analyzer.vs](https://github.com/kitamstudios/rust-analyzer/).
+
+### VS\_RustAnalyzer
+
+(License: GPL)
+
+[Visual Studio
+Marketplace](https://marketplace.visualstudio.com/items?itemName=cchharris.vsrustanalyzer)
+
+[GitHub](https://github.com/cchharris/VS-RustAnalyzer)
+
+### SourceGear Rust
+
+(License: closed source)
+
+[Visual Studio
+Marketplace](https://marketplace.visualstudio.com/items?itemName=SourceGear.SourceGearRust)
+
+[GitHub (docs, issues,
+discussions)](https://github.com/sourcegear/rust-vs-extension)
+
+-   Free (no-cost)
+
+-   Supports all editions of Visual Studio 2022 on Windows: Community,
+    Professional, or Enterprise
+
+## Lapce
+
+[Lapce](https://lapce.dev/) has a Rust plugin which you can install
+directly. Unfortunately, it downloads an old version of `rust-analyzer`,
+but you can set the server path under Settings.
+
+## Crates
+
+There is a package named `ra_ap_rust_analyzer` available on
+[crates.io](https://crates.io/crates/ra_ap_rust-analyzer), for someone
+who wants to use it programmatically.
+
+For more details, see [the publish
+workflow](https://github.com/rust-lang/rust-analyzer/blob/master/.github/workflows/autopublish.yaml).
+
+## Zed
+
+[Zed](https://zed.dev) has native `rust-analyzer` support. If the LSP
+binary is not available, Zed can install it when opening a Rust file.

docs/book/src/non_cargo_based_projects.md

@@ -0,0 +1,246 @@
+# Non-Cargo Based Projects
+
+rust-analyzer does not require Cargo. However, 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:
+
+```typescript
+interface JsonProject {
+    /// Path to the sysroot directory.
+    ///
+    /// The sysroot is where rustc looks for the
+    /// crates that are built-in to rust, such as
+    /// std.
+    ///
+    /// https://doc.rust-lang.org/rustc/command-line-arguments.html#--sysroot-override-the-system-root
+    ///
+    /// To see the current value of sysroot, you
+    /// can query rustc:
+    ///
+    /// ```
+    /// $ rustc --print sysroot
+    /// /Users/yourname/.rustup/toolchains/stable-x86_64-apple-darwin
+    /// ```
+    sysroot?: string;
+    /// Path to the directory with *source code* of
+    /// sysroot crates.
+    ///
+    /// By default, this is `lib/rustlib/src/rust/library`
+    /// relative to the sysroot.
+    ///
+    /// It should point to the directory where std,
+    /// core, and friends can be found:
+    ///
+    /// https://github.com/rust-lang/rust/tree/master/library.
+    ///
+    /// If provided, rust-analyzer automatically adds
+    /// dependencies on sysroot crates. Conversely,
+    /// if you omit this path, you can specify sysroot
+    /// dependencies yourself and, for example, have
+    /// several different "sysroots" in one graph of
+    /// crates.
+    sysroot_src?: string;
+    /// List of groups of common cfg values, to allow
+    /// sharing them between crates.
+    ///
+    /// Maps from group name to its cfgs. Cfg follow
+    /// the same format as `Crate.cfg`.
+    cfg_groups?: { [key: string]: string[]; };
+    /// The set of crates comprising the current
+    /// project. Must include all transitive
+    /// dependencies as well as sysroot crate (libstd,
+    /// libcore and such).
+    crates: Crate[];
+    /// Configuration for CLI commands.
+    ///
+    /// These are used for running and debugging binaries
+    /// and tests without encoding build system-specific
+    /// knowledge into rust-analyzer.
+    ///
+    /// # Example
+    ///
+    /// Below is an example of a test runnable. `{label}` and `{test_id}`
+    /// are explained in `Runnable::args`'s documentation below.
+    ///
+    /// ```json
+    /// {
+    ///     "program": "buck",
+    ///     "args": [
+    ///         "test",
+    ///          "{label}",
+    ///          "--",
+    ///          "{test_id}",
+    ///          "--print-passing-details"
+    ///     ],
+    ///     "cwd": "/home/user/repo-root/",
+    ///     "kind": "testOne"
+    /// }
+    /// ```
+    runnables?: Runnable[];
+}
+
+interface Crate {
+    /// Optional crate name used for display purposes,
+    /// without affecting semantics. See the `deps`
+    /// key for semantically-significant crate names.
+    display_name?: string;
+    /// Path to the root module of the crate.
+    root_module: string;
+    /// Edition of the crate.
+    edition: '2015' | '2018' | '2021' | '2024';
+    /// The version of the crate. Used for calculating
+    /// the correct docs.rs URL.
+    version?: string;
+    /// Dependencies
+    deps: Dep[];
+    /// Should this crate be treated as a member of
+    /// current "workspace".
+    ///
+    /// By default, inferred from the `root_module`
+    /// (members are the crates which reside inside
+    /// the directory opened in the editor).
+    ///
+    /// Set this to `false` for things like standard
+    /// library and 3rd party crates to enable
+    /// performance optimizations (rust-analyzer
+    /// assumes that non-member crates don't change).
+    is_workspace_member?: boolean;
+    /// Optionally specify the (super)set of `.rs`
+    /// files comprising this crate.
+    ///
+    /// By default, rust-analyzer assumes that only
+    /// files under `root_module.parent` can belong
+    /// to a crate. `include_dirs` are included
+    /// recursively, unless a subdirectory is in
+    /// `exclude_dirs`.
+    ///
+    /// Different crates can share the same `source`.
+    ///
+    /// If two crates share an `.rs` file in common,
+    /// they *must* have the same `source`.
+    /// rust-analyzer assumes that files from one
+    /// source can't refer to files in another source.
+    source?: {
+        include_dirs: string[];
+        exclude_dirs: string[];
+    };
+    /// List of cfg groups this crate inherits.
+    ///
+    /// All cfg in these groups will be concatenated to
+    /// `cfg`. It is impossible to replace a value from
+    /// the groups.
+    cfg_groups?: string[];
+    /// The set of cfgs activated for a given crate, like
+    /// `["unix", "feature=\"foo\"", "feature=\"bar\""]`.
+    cfg: string[];
+    /// Target tuple for this Crate.
+    ///
+    /// Used when running `rustc --print cfg`
+    /// to get target-specific cfgs.
+    target?: string;
+    /// Environment variables, used for
+    /// the `env!` macro
+    env: { [key: string]: string; };
+
+    /// Whether the crate is a proc-macro crate.
+    is_proc_macro: boolean;
+    /// For proc-macro crates, path to compiled
+    /// proc-macro (.so file).
+    proc_macro_dylib_path?: string;
+
+    /// Repository, matching the URL that would be used
+    /// in Cargo.toml.
+    repository?: string;
+
+    /// Build-specific data about this crate.
+    build?: BuildInfo;
+}
+
+interface Dep {
+    /// Index of a crate in the `crates` array.
+    crate: number;
+    /// Name as should appear in the (implicit)
+    /// `extern crate name` declaration.
+    name: string;
+}
+
+interface BuildInfo {
+    /// The name associated with this crate.
+    ///
+    /// This is determined by the build system that produced
+    /// the `rust-project.json` in question. For instance, if buck were used,
+    /// the label might be something like `//ide/rust/rust-analyzer:rust-analyzer`.
+    ///
+    /// Do not attempt to parse the contents of this string; it is a build system-specific
+    /// identifier similar to `Crate::display_name`.
+    label: string;
+    /// Path corresponding to the build system-specific file defining the crate.
+    build_file: string;
+    /// The kind of target.
+    ///
+    /// This information is used to determine what sort
+    /// of runnable codelens to provide, if any.
+    target_kind: 'bin' | 'lib' | 'test';
+}
+
+interface Runnable {
+    /// The program invoked by the runnable.
+    ///
+    /// For example, this might be `cargo`, `buck`, or `bazel`.
+    program: string;
+    /// The arguments passed to `program`.
+    args: string[];
+    /// The current working directory of the runnable.
+    cwd: string;
+    /// Used to decide what code lens to offer.
+    ///
+    /// `testOne`: This runnable will be used when the user clicks the 'Run Test'
+    /// CodeLens above a test.
+    ///
+    /// The args for testOne can contain two template strings:
+    /// `{label}` and `{test_id}`. `{label}` will be replaced
+    /// with the `Build::label` and `{test_id}` will be replaced
+    /// with the test name.
+    kind: 'testOne' | string;
+}
+```
+
+This format is provisional and subject to change. Specifically, the
+`roots` setup will be different eventually.
+
+There are three ways to feed `rust-project.json` to rust-analyzer:
+
+-   Place `rust-project.json` file at the root of the project, and
+    rust-analyzer will discover it.
+
+-   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).
+
+-   Specify
+    `"rust-analyzer.linkedProjects": [ { "roots": […​], "crates": […​] }]`
+    inline.
+
+Relative paths are interpreted relative to `rust-project.json` file
+location or (for inline JSON) relative to `rootUri`.
+
+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
+`rust-analyzer.check.overrideCommand` configuration. As an example, the
+following configuration explicitly sets `cargo check` as the `check`
+command.
+
+    { "rust-analyzer.check.overrideCommand": ["cargo", "check", "--message-format=json"] }
+
+`check.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](#_configuration)
+section for more information.

docs/book/src/privacy.md

@@ -0,0 +1,15 @@
+# Privacy
+
+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 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.

docs/book/src/security.md

@@ -0,0 +1,19 @@
+# Security
+
+At the moment, rust-analyzer assumes that all code is trusted. Here is a
+**non-exhaustive** list of ways to make rust-analyzer execute arbitrary
+code:
+
+-   proc macros and build scripts are executed by default
+
+-   `.cargo/config` can override `rustc` with an arbitrary executable
+
+-   `rust-toolchain.toml` can override `rustc` with an arbitrary
+    executable
+
+-   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.
+
+-   rust-analyzer’s syntax trees library uses a lot of `unsafe` and
+    hasn’t been properly audited for memory safety.

docs/book/src/troubleshooting.md

@@ -0,0 +1,50 @@
+# Troubleshooting
+
+Start with looking at the rust-analyzer version. Try **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. If the date is more than a week ago, it’s better to update
+rust-analyzer version.
+
+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 them in the
+`Output > Rust Analyzer Language Server` tab of the panel. 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, run
+the `rust-analyzer: Toggle LSP Logs` command and check `Output > Rust
+Analyzer Language Server Trace`.
+
+The root cause for many "nothing works" problems is that rust-analyzer
+fails to understand the project structure. To debug that, first note the
+`rust-analyzer` section in the status bar. If it has an error icon and
+red, that’s the problem (hover will have somewhat helpful error
+message). **rust-analyzer: Status** prints dependency information for
+the current file. Finally, `RA_LOG=project_model=debug` enables verbose
+logs during project loading.
+
+If rust-analyzer outright crashes, try running
+`rust-analyzer analysis-stats /path/to/project/directory/` on the
+command line. This command type checks the whole project in batch mode
+bypassing LSP machinery.
+
+When filing issues, it is useful (but not necessary) to try to minimize
+examples. An ideal bug reproduction looks like this:
+
+```shell
+$ git clone https://github.com/username/repo.git && cd repo && git switch --detach commit-hash
+$ rust-analyzer --version
+rust-analyzer dd12184e4 2021-05-08 dev
+$ rust-analyzer analysis-stats .
+💀 💀 💀
+```
+
+It is especially useful when the `repo` doesn’t use external crates or
+the standard library.
+
+If you want to go as far as to modify the source code to debug the
+problem, be sure to take a look at the [dev
+docs](https://github.com/rust-lang/rust-analyzer/tree/master/docs/dev)!

docs/dev/style.md

@@ -873,7 +873,7 @@ Use `anyhow::format_err!` rather than `anyhow::anyhow`.
 **Rationale:** consistent, boring, avoids stuttering.
 
 There's no specific guidance on the formatting of error messages, see [anyhow/#209](https://github.com/dtolnay/anyhow/issues/209).
-Do not end error and context messages with `.` though. 
+Do not end error and context messages with `.` though.
 
 ## Early Returns
 
@@ -1172,7 +1172,7 @@ MergeBehavior::Last => {
 **Rationale:** writing a sentence (or maybe even a paragraph) rather just "a comment" creates a more appropriate frame of mind.
 It tricks you into writing down more of the context you keep in your head while coding.
 
-For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
+For `.md` files prefer a sentence-per-line format, don't wrap lines.
 If the line is too long, you want to split the sentence in two :-)
 
 **Rationale:** much easier to edit the text and read the diff, see [this link](https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line).

docs/user/.gitignore

@@ -1 +0,0 @@
-manual.html