1# LLDB DAP 2 3## Procuring the `lldb-dap` binary 4 5The extension requires the `lldb-dap` (formerly `lldb-vscode`) binary. 6This binary is not packaged with the VS Code extension. 7 8There are multiple ways to obtain this binary: 9* Use the binary provided by your toolchain (for example `xcrun -f lldb-dap` on macOS) or contact your toolchain vendor to include it. 10* Download one of the relase packages from the [LLVM release page](https://github.com/llvm/llvm-project/releases/). The `LLVM-19.1.0-{operating_system}.tar.xz` packages contain a prebuilt `lldb-dap` binary. 11* Build it from source (see [LLDB's build instructions](https://lldb.llvm.org/resources/build.html)). 12 13By default, the VS Code extension will expect to find `lldb-dap` in your `PATH`. 14Alternatively, you can explictly specify the location of the `lldb-dap` binary using the `lldb-dap.executable-path` setting. 15 16### Usage with other IDEs 17 18The `lldb-dap` binary is a command line tool that implements the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/). 19It is used to power the VS Code extension but can also be used with other IDEs and editors that support DAP. 20The protocol is easy to run remotely and also can allow other tools and IDEs to get a full featured debugger with a well defined protocol. 21 22## Launching & Attaching to a debugee 23 24Launching or attaching a debugee require you to create a [launch configuration](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations). 25This file defines arguments that get passed to `lldb-dap` and the configuration settings control how the launch or attach happens. 26 27### Launching a debugee 28 29This will launch `/tmp/a.out` with arguments `one`, `two`, and `three` and 30adds `FOO=1` and `bar` to the environment: 31 32```javascript 33{ 34 "type": "lldb-dap", 35 "request": "launch", 36 "name": "Debug", 37 "program": "/tmp/a.out", 38 "args": [ "one", "two", "three" ], 39 "env": { 40 "FOO": "1" 41 "BAR": "" 42 } 43} 44``` 45 46### Attaching to a process 47 48When attaching to a process using LLDB, you can attach in multiple ways: 49 501. Attach to an existing process using the process ID 512. Attach to an existing process by name 523. Attach by name by waiting for the next instance of a process to launch 53 54#### Attach using PID 55 56This will attach to a process `a.out` whose process ID is 123: 57 58```javascript 59{ 60 "type": "lldb-dap", 61 "request": "attach", 62 "name": "Attach to PID", 63 "program": "/tmp/a.out", 64 "pid": 123 65} 66``` 67 68#### Attach by Name 69 70This will attach to an existing process whose base 71name matches `a.out`. All we have to do is leave the `pid` value out of the 72above configuration: 73 74```javascript 75{ 76 "name": "Attach to Name", 77 "type": "lldb-dap", 78 "request": "attach", 79 "program": "/tmp/a.out", 80} 81``` 82 83If you want to ignore any existing a.out processes and wait for the next instance 84to be launched you can add the "waitFor" key value pair: 85 86```javascript 87{ 88 "name": "Attach to Name (wait)", 89 "type": "lldb-dap", 90 "request": "attach", 91 "program": "/tmp/a.out", 92 "waitFor": true 93} 94``` 95 96This will work as long as the architecture, vendor and OS supports waiting 97for processes. Currently MacOS is the only platform that supports this. 98 99### Loading a Core File 100 101This loads the coredump file `/cores/123.core` associated with the program 102`/tmp/a.out`: 103 104```javascript 105{ 106 "name": "Load coredump", 107 "type": "lldb-dap", 108 "request": "attach", 109 "coreFile": "/cores/123.core", 110 "program": "/tmp/a.out" 111} 112``` 113 114### Connect to a Debug Server on the Current Machine 115 116This connects to a debug server (e.g. `lldb-server`, `gdbserver`) on 117the current machine, that is debugging the program `/tmp/a.out` and listening 118locally on port `2345`. 119 120```javascript 121{ 122 "name": "Local Debug Server", 123 "type": "lldb-dap", 124 "request": "attach", 125 "program": "/tmp/a.out", 126 "attachCommands": ["gdb-remote 2345"], 127} 128``` 129 130You can also use the `gdb-remote-port` parameter to send an attach request 131to a debug server running on the current machine, 132instead of using the custom command `attachCommands`. 133 134```javascript 135{ 136 "name": "Local Debug Server", 137 "type": "lldb-dap", 138 "request": "attach", 139 "program": "/tmp/a.out", 140 "gdb-remote-port": 2345, 141} 142``` 143 144### Connect to a Debug Server on Another Machine 145 146This connects to a debug server running on another machine with hostname 147`hostnmame`. Which is debugging the program `/tmp/a.out` and listening on 148port `5678` of that other machine. 149 150```javascript 151{ 152 "name": "Remote Debug Server", 153 "type": "lldb-dap", 154 "request": "attach", 155 "program": "/tmp/a.out", 156 "attachCommands": ["gdb-remote hostname:5678"], 157} 158``` 159 160You can also use the `gdb-remote-hostname` and `gdb-remote-port` parameters 161to send an attach request to a debug server running on a different machine, 162instead of custom command `attachCommands`. 163The default hostname being used `localhost`. 164 165 166```javascript 167{ 168 "name": "Local Debug Server", 169 "type": "lldb-dap", 170 "request": "attach", 171 "program": "/tmp/a.out", 172 "gdb-remote-port": 5678, 173 "gdb-remote-hostname": "hostname", 174} 175``` 176 177### Configuration Settings Reference 178 179For both launch and attach configurations, lldb-dap accepts the following `lldb-dap` 180specific key/value pairs: 181 182| Parameter | Type | Req | | 183|-----------------------------------|-------------|:---:|---------| 184| **name** | string | Y | A configuration name that will be displayed in the IDE. 185| **type** | string | Y | Must be "lldb-dap". 186| **request** | string | Y | Must be "launch" or "attach". 187| **program** | string | Y | Path to the executable to launch. 188| **sourcePath** | string | | Specify a source path to remap \"./\" to allow full paths to be used when setting breakpoints in binaries that have relative source paths. 189| **sourceMap** | [string[2]] | | Specify an array of path re-mappings. Each element in the array must be a two element array containing a source and destination pathname. Overrides sourcePath. 190| **debuggerRoot** | string | | Specify a working directory to use when launching lldb-dap. If the debug information in your executable contains relative paths, this option can be used so that `lldb-dap` can find source files and object files that have relative paths. 191| **commandEscapePrefix** | string | | The escape prefix to use for executing regular LLDB commands in the Debug Console, instead of printing variables. Defaults to a backtick. If it's an empty string, then all expression in the Debug Console are treated as regular LLDB commands. 192| **customFrameFormat** | string | | If non-empty, stack frames will have descriptions generated based on the provided format. See https://lldb.llvm.org/use/formatting.html for an explanation on format strings for frames. If the format string contains errors, an error message will be displayed on the Debug Console and the default frame names will be used. This might come with a performance cost because debug information might need to be processed to generate the description. 193| **customThreadFormat** | string | | Same as `customFrameFormat`, but for threads instead of stack frames. 194| **displayExtendedBacktrace** | bool | | Enable language specific extended backtraces. 195| **enableAutoVariableSummaries** | bool | | Enable auto generated summaries for variables when no summaries exist for a given type. This feature can cause performance delays in large projects when viewing variables. 196| **enableSyntheticChildDebugging** | bool | | If a variable is displayed using a synthetic children, also display the actual contents of the variable at the end under a [raw] entry. This is useful when creating sythetic child plug-ins as it lets you see the actual contents of the variable. 197| **initCommands** | [string] | | LLDB commands executed upon debugger startup prior to creating the LLDB target. 198| **preRunCommands** | [string] | | LLDB commands executed just before launching/attaching, after the LLDB target has been created. 199| **stopCommands** | [string] | | LLDB commands executed just after each stop. 200| **exitCommands** | [string] | | LLDB commands executed when the program exits. 201| **terminateCommands** | [string] | | LLDB commands executed when the debugging session ends. 202 203All commands and command outputs will be sent to the debugger console when they are executed. 204Commands can be prefixed with `?` or `!` to modify their behavior: 205* Commands prefixed with `?` are quiet on success, i.e. nothing is written to stdout if the command succeeds. 206* Prefixing a command with `!` enables error checking: If a command prefixed with `!` fails, subsequent commands will not be run. This is usefule if one of the commands depends on another, as it will stop the chain of commands. 207 208For JSON configurations of `"type": "launch"`, the JSON configuration can additionally 209contain the following key/value pairs: 210 211| Parameter | Type | Req | | 212|-----------------------------------|-------------|:---:|---------| 213| **program** | string | Y | Path to the executable to launch. 214| **args** | [string] | | An array of command line argument strings to be passed to the program being launched. 215| **cwd** | string | | The program working directory. 216| **env** | dictionary | | Environment variables to set when launching the program. The format of each environment variable string is "VAR=VALUE" for environment variables with values or just "VAR" for environment variables with no values. 217| **stopOnEntry** | boolean | | Whether to stop program immediately after launching. 218| **runInTerminal** | boolean | | Launch the program inside an integrated terminal in the IDE. Useful for debugging interactive command line programs. 219| **launchCommands** | [string] | | LLDB commands executed to launch the program. 220 221For JSON configurations of `"type": "attach"`, the JSON configuration can contain 222the following `lldb-dap` specific key/value pairs: 223 224| Parameter | Type | Req | | 225|-----------------------------------|-------------|:---:|---------| 226| **program** | string | | Path to the executable to attach to. This value is optional but can help to resolve breakpoints prior the attaching to the program. 227| **pid** | number | | The process id of the process you wish to attach to. If **pid** is omitted, the debugger will attempt to attach to the program by finding a process whose file name matches the file name from **porgram**. Setting this value to `${command:pickMyProcess}` will allow interactive process selection in the IDE. 228| **waitFor** | boolean | | Wait for the process to launch. 229| **attachCommands** | [string] | | LLDB commands that will be executed after **preRunCommands** which take place of the code that normally does the attach. The commands can create a new target and attach or launch it however desired. This allows custom launch and attach configurations. Core files can use `target create --core /path/to/core` to attach to core files. 230 231## Debug Console 232 233The Debug Console allows printing variables / expressions and executing lldb commands. 234By default, lldb-dap tries to auto-detect whether a provided command is a variable 235name / expression whose values will be printed to the Debug Console or a LLDB command. 236To side-step this auto-detection and execute a LLDB command, prefix it with the 237`commandEscapePrefix`. 238 239The auto-detection can be disabled using the `lldb-dap repl-mode` command. 240The escape character can be adjusted via the `commandEscapePrefix` configuration option. 241 242### lldb-dap specific commands 243 244The `lldb-dap` tool includes additional custom commands to support the Debug 245Adapter Protocol features. 246 247#### `lldb-dap start-debugging` 248 249Using the command `lldb-dap start-debugging` it is possible to trigger a 250reverse request to the client requesting a child debug session with the 251specified configuration. For example, this can be used to attached to forked or 252spawned processes. For more information see 253[Reverse Requests StartDebugging](https://microsoft.github.io/debug-adapter-protocol/specification#Reverse_Requests_StartDebugging). 254 255The custom command has the following format: 256 257``` 258lldb-dap start-debugging <launch|attach> <configuration> 259``` 260 261This will launch a server and then request a child debug session for a client. 262 263```javascript 264{ 265 "program": "server", 266 "postRunCommand": [ 267 "lldb-dap start-debugging launch '{\"program\":\"client\"}'" 268 ] 269} 270``` 271 272#### `lldb-dap repl-mode` 273 274Inspect or adjust the behavior of lldb-dap repl evaluation requests. The 275supported modes are `variable`, `command` and `auto`. 276 277- `variable` - Variable mode expressions are evaluated in the context of the 278 current frame. 279- `command` - Command mode expressions are evaluated as lldb commands, as a 280 result, values printed by lldb are always stringified representations of the 281 expression output. 282- `auto` - Auto mode will attempt to infer if the expression represents an lldb 283 command or a variable expression. A heuristic is used to infer if the input 284 represents a variable or a command. 285 286In all three modes, you can use the `commandEscapePrefix` to ensure an expression 287is evaluated as a command. 288 289The initial repl-mode can be configured with the cli flag `--repl-mode=<mode>` 290and may also be adjusted at runtime using the lldb command 291`lldb-dap repl-mode <mode>`. 292 293#### `lldb-dap send-event` 294 295lldb-dap includes a command to trigger a Debug Adapter Protocol event 296from a script. 297 298The event maybe a custom DAP event or a standard event, if the event is not 299handled internally by `lldb-dap`. 300 301This command has the format: 302 303``` 304lldb-dap send-event <name> <body>? 305``` 306 307For example you can use a launch configuration hook to trigger custom events like: 308 309```json 310{ 311 "program": "exe", 312 "stopCommands": [ 313 "lldb-dap send-event MyStopEvent", 314 "lldb-dap send-event MyStopEvent '{\"key\": 321}", 315 ] 316} 317``` 318 319[See the specification](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_Event) 320for more details on Debug Adapter Protocol events and the VS Code 321[debug.onDidReceiveDebugSessionCustomEvent](https://code.visualstudio.com/api/references/vscode-api#debug.onDidReceiveDebugSessionCustomEvent) 322API for handling a custom event from an extension. 323 324## Contributing 325 326`lldb-dap` and `lldb` are developed under the umbrella of the [LLVM project](https://llvm.org/). 327The source code is part of the [LLVM repository](https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-dap) on Github. 328We use Github's [issue tracker](https://github.com/llvm/llvm-project/issues?q=label%3Alldb-dap) and patches can be submitted via [pull requests](https://github.com/llvm/llvm-project/pulls?q=label%3Alldb-dap). 329Furthermore, there is a [LLDB category](https://discourse.llvm.org/c/subprojects/lldb/8) on the LLVM discourse forum. 330 331For instructions on how to get started with development on lldb-dap, see the "[Contributing to lldb-dap](https://lldb.llvm.org/resources/lldbdap.html)" 332