From a191b24fec0e4a0b447072f7e44fa1ea4650c6e1 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sat, 8 May 2021 13:18:25 +0300 Subject: feat: friendlier trouble shooting guide --- docs/user/manual.adoc | 40 ++++++++++++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 8 deletions(-) (limited to 'docs') 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 ==== Troubleshooting -Here are some useful self-diagnostic commands: - -* **Rust Analyzer: Show RA Version** shows the version of `rust-analyzer` binary. -* **Rust Analyzer: Status** prints some statistics about the server, and dependency information for the current file. -* To enable server-side logging, run with `env RA_LOG=info` and see `Output > Rust Analyzer Language Server` in VS Code's panel. -* To log project loading (sysroot & `cargo metadata`), set `RA_LOG=project_model=debug`. -* 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. -* To enable client-side logging, add `"rust-analyzer.trace.extension": true` to the settings and open `Output > Rust Analyzer Client` in the panel. +Start with looking at the rust-analyzer version. +Try **Rust Analyzer: Show RA Version** and `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 then in the `Output > Rust Analyzer Language Server` tab of the panel. +To see more logs, set `RA_LOG=info` environmental variable. + +To fully capture LSP messages between the editor and the server, set `"rust-analyzer.trace.server": "verbose"` config 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: + +```bash +$ 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. === rust-analyzer Language Server Binary -- cgit v1.2.3