Describe why and how to use a separate build directory for rust-analyzer (#2106)

1 files changed, 25 insertions, 4 deletions

diff --git a/src/doc/rustc-dev-guide/src/building/suggested.md b/src/doc/rustc-dev-guide/src/building/suggested.md
index 58f36eadd5c..2368a1308ec 100644
--- a/src/doc/rustc-dev-guide/src/building/suggested.md
+++ b/src/doc/rustc-dev-guide/src/building/suggested.md
@@ -37,14 +37,35 @@ checking time. For example, if you are working on the compiler, you can override
 the command to `x check compiler --json-output` to only check the compiler part.
 You can run `x check --help --verbose` to see the available parts.
 
-If you have enough free disk space and you would like to be able to run `x`
-commands while rust-analyzer runs in the background, you can also add
-`--build-dir build-rust-analyzer` to the `overrideCommand` to avoid x locking.
-
 Running `./x setup editor` will prompt you to create a project-local LSP config
 file for one of the supported editors. You can also create the config file as a
 step of running `./x setup`.
 
+### Using a separate build directory for rust-analyzer
+
+By default, when rust-analyzer runs a check or format command, it will share
+the same build directory as manual command-line builds. This can be inconvenient
+for two reasons:
+- Each build will lock the build directory and force the other to wait, so it
+  becomes impossible to run command-line builds while rust-analyzer is running
+  commands in the background.
+- There is an increased risk of one of the builds deleting previously-built
+  artifacts due to conflicting compiler flags or other settings, forcing
+  additional rebuilds in some cases.
+
+To avoid these problems:
+- Add `--build-dir=build-rust-analyzer` to all of the custom `x` commands in
+  your editor's rust-analyzer configuration.
+  (Feel free to choose a different directory name if desired.)
+- Modify the `rust-analyzer.procMacro.server` setting so that it points to the
+  copy of `rust-analyzer-proc-macro-srv` in that other build directory.
+
+Using separate build directories for command-line builds and rust-analyzer
+requires extra disk space, and also means that running `./x clean` on the
+command-line will not clean out the separate build directory. To clean the
+separate build directory, run `./x clean --build-dir=build-rust-analyzer`
+instead.
+
 ### Visual Studio Code
 
 Selecting `vscode` in `./x setup editor` will prompt you to create a