lldb/tools/lldb-dap/README.md

   1 # LLDB DAP
   2
   3 ## `lldb-dap` Configurations
   4
   5 The extension requires the `lldb-dap` (formerly `lldb-vscode`) binary. It is a
   6 command line tool that implements the [Debug Adapter
   7 Protocol](https://microsoft.github.io/debug-adapter-protocol/). It is used to power the Visual Studio Code extension but can also be used with other IDEs and editors that support DAP.
   8 The protocol is easy to run remotely and also can allow other tools and IDEs to
   9 get a full featured debugger with a well defined protocol.
  10
  11 ## Launching & Attaching Configuration
  12
  13 Launching to attaching require you to create a [launch configuration](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations).
  14 This file defines arguments that get passed to `lldb-dap` and the configuration settings control how the launch or attach happens.
  15
  16 ### Launch Configuration Settings
  17
  18 When you launch a program with Visual Studio Code you will need to create a [launch.json](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations)
  19 file that defines how your program will be run. The JSON configuration file can contain the following `lldb-dap` specific launch key/value pairs:
  20
  21 |parameter          |type|req |         |
  22 |-------------------|----|:--:|---------|
  23 |**name**           |string|Y| A configuration name that will be displayed in the IDE.
  24 |**type**           |string|Y| Must be "lldb-dap".
  25 |**request**        |string|Y| Must be "launch".
  26 |**program**        |string|Y| Path to the executable to launch.
  27 |**args**           |[string]|| An array of command line argument strings to be passed to the program being launched.
  28 |**cwd**            |string| | The program working directory.
  29 |**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.
  30 |**stopOnEntry**    |boolean| | Whether to stop program immediately after launching.
  31 |**initCommands**   |[string]| | LLDB commands executed upon debugger startup prior to creating the LLDB target. Commands and command output will be sent to the debugger console when they are executed.
  32 |**preRunCommands** |[string]| | LLDB commands executed just before launching after the LLDB target has been created. Commands and command output will be sent to the debugger console when they are executed.
  33 |**stopCommands**   |[string]| | LLDB commands executed just after each stop. Commands and command output will be sent to the debugger console when they are executed.
  34 |**launchCommands** |[string]| | LLDB commands executed to launch the program. Commands and command output will be sent to the debugger console when they are executed.
  35 |**exitCommands**   |[string]| | LLDB commands executed when the program exits. Commands and command output will be sent to the debugger console when they are executed.
  36 |**terminateCommands** |[string]| | LLDB commands executed when the debugging session ends. Commands and command output will be sent to the debugger console when they are executed.
  37 |**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.
  38 |**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.
  39
  40 ### Attaching Settings
  41
  42 When attaching to a process using LLDB you can attach in a few ways
  43
  44 1. Attach to an existing process using the process ID
  45 2. Attach to an existing process by name
  46 3. Attach by name by waiting for the next instance of a process to launch
  47
  48 The JSON configuration file can contain the following `lldb-dap` specific launch key/value pairs:
  49
  50 |parameter          |type    |req |         |
  51 |-------------------|--------|:--:|---------|
  52 |**name**           |string  |Y| A configuration name that will be displayed in the IDE.
  53 |**type**           |string  |Y| Must be "lldb-dap".
  54 |**request**        |string  |Y| Must be "attach".
  55 |**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.
  56 |**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.
  57 |**stopOnEntry**    |boolean| | Whether to stop program immediately after launching.
  58 |**waitFor**        |boolean | | Wait for the process to launch.
  59 |**initCommands**   |[string]| | LLDB commands executed upon debugger startup prior to creating the LLDB target. Commands and command output will be sent to the debugger console when they are executed.
  60 |**preRunCommands** |[string]| | LLDB commands executed just before launching after the LLDB target has been created. Commands and command output will be sent to the debugger console when they are executed.
  61 |**stopCommands**   |[string]| | LLDB commands executed just after each stop. Commands and command output will be sent to the debugger console when they are executed.
  62 |**exitCommands**   |[string]| | LLDB commands executed when the program exits. Commands and command output will be sent to the debugger console when they are executed.
  63 |**terminateCommands** |[string]| | LLDB commands executed when the debugging session ends. Commands and command output will be sent to the debugger console when they are executed.
  64 |**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.
  65
  66 ### Example configurations
  67
  68 #### Launching
  69
  70 This will launch `/tmp/a.out` with arguments `one`, `two`, and `three` and
  71 adds `FOO=1` and `bar` to the environment:
  72
  73 ```javascript
  74 {
  75   "type": "lldb-dap",
  76   "request": "launch",
  77   "name": "Debug",
  78   "program": "/tmp/a.out",
  79   "args": [ "one", "two", "three" ],
  80   "env": [ "FOO=1", "BAR" ],
  81 }
  82 ```
  83
  84 #### Attach using PID
  85
  86 This will attach to a process `a.out` whose process ID is 123:
  87
  88 ```javascript
  89 {
  90   "type": "lldb-dap",
  91   "request": "attach",
  92   "name": "Attach to PID",
  93   "program": "/tmp/a.out",
  94   "pid": 123
  95 }
  96 ```
  97
  98 #### Attach by Name
  99
 100 This will attach to an existing process whose base
 101 name matches `a.out`. All we have to do is leave the `pid` value out of the
 102 above configuration:
 103
 104 ```javascript
 105 {
 106   "name": "Attach to Name",
 107   "type": "lldb-dap",
 108   "request": "attach",
 109   "program": "/tmp/a.out",
 110 }
 111 ```
 112
 113 If you want to ignore any existing a.out processes and wait for the next instance
 114 to be launched you can add the "waitFor" key value pair:
 115
 116 ```javascript
 117 {
 118   "name": "Attach to Name (wait)",
 119   "type": "lldb-dap",
 120   "request": "attach",
 121   "program": "/tmp/a.out",
 122   "waitFor": true
 123 }
 124 ```
 125
 126 This will work as long as the architecture, vendor and OS supports waiting
 127 for processes. Currently MacOS is the only platform that supports this.
 128
 129 #### Loading a Core File
 130
 131 This loads the coredump file `/cores/123.core` associated with the program
 132 `/tmp/a.out`:
 133
 134 ```javascript
 135 {
 136   "name": "Load coredump",
 137   "type": "lldb-dap",
 138   "request": "attach",
 139   "coreFile": "/cores/123.core",
 140   "program": "/tmp/a.out"
 141 }
 142 ```
 143
 144 #### Connect to a Debug Server on the Current Machine
 145
 146 This connects to a debug server (e.g. `lldb-server`, `gdbserver`) on
 147 the current machine, that is debugging the program `/tmp/a.out` and listening
 148 locally on port `2345`.
 149
 150 ```javascript
 151 {
 152   "name": "Local Debug Server",
 153   "type": "lldb-dap",
 154   "request": "attach",
 155   "program": "/tmp/a.out",
 156   "attachCommands": ["gdb-remote 2345"],
 157 }
 158 ```
 159
 160 #### Connect to a Debug Server on Another Machine
 161
 162 This connects to a debug server running on another machine with hostname
 163 `hostnmame`. Which is debugging the program `/tmp/a.out` and listening on
 164 port `5678` of that other machine.
 165
 166 ```javascript
 167 {
 168   "name": "Remote Debug Server",
 169   "type": "lldb-dap",
 170   "request": "attach",
 171   "program": "/tmp/a.out",
 172   "attachCommands": ["gdb-remote hostname:5678"],
 173 }
 174 ```
 175
 176 ## Custom debugger commands
 177
 178 The `lldb-dap` tool includes additional custom commands to support the Debug
 179 Adapter Protocol features.
 180
 181 ### startDebugging
 182
 183 Using the command `lldb-dap startDebugging` it is possible to trigger a
 184 reverse request to the client requesting a child debug session with the
 185 specified configuration. For example, this can be used to attached to forked or
 186 spawned processes. For more information see
 187 [Reverse Requests StartDebugging](https://microsoft.github.io/debug-adapter-protocol/specification#Reverse_Requests_StartDebugging).
 188
 189 The custom command has the following format:
 190
 191 ```
 192 lldb-dap startDebugging <launch|attach> <configuration>
 193 ```
 194
 195 This will launch a server and then request a child debug session for a client.
 196
 197 ```javascript
 198 {
 199   "program": "server",
 200   "postRunCommand": [
 201     "lldb-dap startDebugging launch '{\"program\":\"client\"}'"
 202   ]
 203 }
 204 ```
 205
 206 ### repl-mode
 207
 208 Inspect or adjust the behavior of lldb-dap repl evaluation requests. The
 209 supported modes are `variable`, `command` and `auto`.
 210
 211 - `variable` - Variable mode expressions are evaluated in the context of the
 212    current frame. Use a `\`` prefix on the command to run an lldb command.
 213 - `command` - Command mode expressions are evaluated as lldb commands, as a
 214    result, values printed by lldb are always stringified representations of the
 215    expression output.
 216 - `auto` - Auto mode will attempt to infer if the expression represents an lldb
 217    command or a variable expression. A heuristic is used to infer if the input
 218    represents a variable or a command. Use a `\`` prefix to ensure an expression
 219    is evaluated as a command.
 220
 221 The initial repl-mode can be configured with the cli flag `--repl-mode=<mode>`
 222 and may also be adjusted at runtime using the lldb command
 223 `lldb-dap repl-mode <mode>`.