From e15ac1d8383a220e2bd931f659ce91cc309b8f57 Mon Sep 17 00:00:00 2001 From: Zalathar Date: Tue, 29 Oct 2024 20:54:18 +1100 Subject: [PATCH] Describe why and how to use a separate build directory for rust-analyzer --- src/building/suggested.md | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/src/building/suggested.md b/src/building/suggested.md index 58f36eadd..2368a1308 100644 --- a/src/building/suggested.md +++ b/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