aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAleksey Kladov <[email protected]>2021-05-08 11:18:25 +0100
committerAleksey Kladov <[email protected]>2021-05-08 11:18:25 +0100
commita191b24fec0e4a0b447072f7e44fa1ea4650c6e1 (patch)
tree2ee2c545042989c1e19030a28208aa9c3a21b655
parente443d5a89b0ac245ea3d30792888bb3783bc38e8 (diff)
feat: friendlier trouble shooting guide
-rw-r--r--docs/user/manual.adoc40
1 files changed, 32 insertions, 8 deletions
diff --git a/docs/user/manual.adoc b/docs/user/manual.adoc
index ddd876580..8bd861b8a 100644
--- a/docs/user/manual.adoc
+++ b/docs/user/manual.adoc
@@ -139,14 +139,38 @@ $ cargo xtask install --server
139 139
140==== Troubleshooting 140==== Troubleshooting
141 141
142Here are some useful self-diagnostic commands: 142Start with looking at the rust-analyzer version.
143 143Try **Rust Analyzer: Show RA Version** and `rust-analyzer --version` in the command line.
144* **Rust Analyzer: Show RA Version** shows the version of `rust-analyzer` binary. 144If the date is more than a week ago, it's better to update rust-analyzer version.
145* **Rust Analyzer: Status** prints some statistics about the server, and dependency information for the current file. 145
146* To enable server-side logging, run with `env RA_LOG=info` and see `Output > Rust Analyzer Language Server` in VS Code's panel. 146The next thing to check would be panic messages in rust-analyzer's log.
147* To log project loading (sysroot & `cargo metadata`), set `RA_LOG=project_model=debug`. 147Log messages are printed to stderr, in VS Code you can see then in the `Output > Rust Analyzer Language Server` tab of the panel.
148* To log all LSP requests, add `"rust-analyzer.trace.server": "verbose"` to the settings and look for `Rust Analyzer Language Server Trace` in the panel. 148To see more logs, set `RA_LOG=info` environmental variable.
149* To enable client-side logging, add `"rust-analyzer.trace.extension": true` to the settings and open `Output > Rust Analyzer Client` in the panel. 149
150To fully capture LSP messages between the editor and the server, set `"rust-analyzer.trace.server": "verbose"` config and check
151`Output > Rust Analyzer Language Server Trace`.
152
153The root cause for many "`nothing works`" problems is that rust-analyzer fails to understand the project structure.
154To debug that, first note the `rust-analyzer` section in the status bar.
155If it has an error icon and red, that's the problem (hover will have somewhat helpful error message).
156**Rust Analyzer: Status** prints dependency information for the current file.
157Finally, `RA_LOG=project_model=debug` enables verbose logs during project loading.
158
159If rust-analyzer outright crashes, try running `rust-analyzer analysis-stats /path/to/project/directory/` on the command line.
160This command type checks the whole project in batch mode bypassing LSP machinery.
161
162When filing issues, it is useful (but not necessary) to try to minimize examples.
163An ideal bug reproduction looks like this:
164
165```bash
166$ git clone https://github.com/username/repo.git && cd repo && git switch --detach commit-hash
167$ rust-analyzer --version
168rust-analyzer dd12184e4 2021-05-08 dev
169$ rust-analyzer analysis-stats .
170💀 💀 💀
171```
172
173It is especially useful when the `repo` doesn't use external crates or the standard library.
150 174
151=== rust-analyzer Language Server Binary 175=== rust-analyzer Language Server Binary
152 176