docs/dev/debugging.md

   1 # Debugging VSCode plugin and the language server
   2
   3 ## Prerequisites
   4
   5 - Install [LLDB](https://lldb.llvm.org/) and the [LLDB Extension](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb).
   6 - Open the root folder in VSCode. Here you can access the preconfigured debug setups.
   7
   8   <img height=150px src="https://user-images.githubusercontent.com/36276403/74611090-92ec5380-5101-11ea-8a41-598f51f3f3e3.png" alt="Debug options view">
   9
  10 - Install all TypeScript dependencies
  11   ```bash
  12   cd editors/code
  13   npm ci
  14   ```
  15
  16 ## Common knowledge
  17
  18 * All debug configurations open a new `[Extension Development Host]` VSCode instance
  19 where **only** the `rust-analyzer` extension being debugged is enabled.
  20 * To activate the extension you need to open any Rust project folder in `[Extension Development Host]`.
  21
  22
  23 ## Debug TypeScript VSCode extension
  24
  25 - `Run Installed Extension` - runs the extension with the globally installed `rust-analyzer` binary.
  26 - `Run Extension (Debug Build)` - runs extension with the locally built LSP server (`target/debug/rust-analyzer`).
  27
  28 TypeScript debugging is configured to watch your source edits and recompile.
  29 To apply changes to an already running debug process, press <kbd>Ctrl+Shift+P</kbd> and run the following command in your `[Extension Development Host]`
  30
  31 ```
  32 > Developer: Reload Window
  33 ```
  34
  35 ## Debug Rust LSP server
  36
  37 - When attaching a debugger to an already running `rust-analyzer` server on Linux you might need to enable `ptrace` for unrelated processes by running:
  38
  39   ```
  40   echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
  41   ```
  42
  43
  44 - By default, the LSP server is built without debug information. To enable it, you'll need to change `Cargo.toml`:
  45   ```toml
  46     [profile.dev]
  47     debug = 2
  48   ```
  49
  50 - Select `Run Extension (Debug Build)` to run your locally built `target/debug/rust-analyzer`.
  51
  52 - In the original VSCode window once again select the `Attach To Server` debug configuration.
  53
  54 - A list of running processes should appear. Select the `rust-analyzer` from this repo.
  55
  56 - Navigate to `crates/rust-analyzer/src/main_loop.rs` and add a breakpoint to the `on_request` function.
  57
  58 - Go back to the `[Extension Development Host]` instance and hover over a Rust variable and your breakpoint should hit.
  59
  60 If you need to debug the server from the very beginning, including its initialization code, you can use the `--wait-dbg` command line argument or `RA_WAIT_DBG` environment variable. The server will spin at the beginning of the `try_main` function (see `crates\rust-analyzer\src\bin\main.rs`)
  61 ```rust
  62     let mut d = 4;
  63     while d == 4 { // set a breakpoint here and change the value
  64         d = 4;
  65     }
  66 ```
  67
  68 However for this to work, you will need to enable debug_assertions in your build
  69 ```rust
  70 RUSTFLAGS='--cfg debug_assertions' cargo build --release
  71 ```
  72
  73 ## Demo
  74
  75 - [Debugging TypeScript VScode extension](https://www.youtube.com/watch?v=T-hvpK6s4wM).
  76 - [Debugging Rust LSP server](https://www.youtube.com/watch?v=EaNb5rg4E0M).
  77
  78 ## Troubleshooting
  79
  80 ### Can't find the `rust-analyzer` process
  81
  82 It could be a case of just jumping the gun.
  83
  84 The `rust-analyzer` is only started once the `onLanguage:rust` activation.
  85
  86 Make sure you open a rust file in the `[Extension Development Host]` and try again.
  87
  88 ### Can't connect to `rust-analyzer`
  89
  90 Make sure you have run `echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope`.
  91
  92 By default this should reset back to 1 every time you log in.
  93
  94 ### Breakpoints are never being hit
  95
  96 Check your version of `lldb`. If it's version 6 and lower, use the `classic` adapter type.
  97 It's `lldb.adapterType` in settings file.
  98
  99 If you're running `lldb` version 7, change the lldb adapter type to `bundled` or `native`.