Skip to content

Commit 65c5706

Browse files
vogelsgesangvogelsgesang
authored
[lldb-dap][docs] Improve README (#109266)
* Document how to procure and configure the `lldb-dap` binary * Improve documentation for `launch.json`: * Show the examples before the reference. Most new users just want to get going, and will only need the reference later on * Deduplicate the list of "launch" and "attach" config settings * Remove the `stopOnEntry` setting from "attach", since this is a launch-only setting * Document the previously undocumented settings `sourcePath`, `commandEscapePrefix`, `custom{Frame,Thread}Format`, `runInTerminal` * Add the settings `debuggerRoot` and `sourceMap` to the common section. So far they were documented as launch-only settings. * Document that the Debug Console prints variables / expressions by default and that LLDB commands need to be escaped.
1 parent d8d252f commit 65c5706

File tree

1 file changed

+92
-70
lines changed

1 file changed

+92
-70
lines changed

‎lldb/tools/lldb-dap/README.md

Lines changed: 92 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,30 @@
11
# LLDB DAP
22

3-
## `lldb-dap` Configurations
3+
## Procuring the `lldb-dap` binary
44

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.
5+
The extension requires the `lldb-dap` (formerly `lldb-vscode`) binary.
6+
This binary is not packaged with the VS Code extension.
107

11-
## Launching & Attaching Configuration
8+
There are multiple ways to obtain this binary:
9+
* build it from source (see [LLDB's build instructions](https://lldb.llvm.org/resources/build.html))
10+
* download it 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+
* use the binary provided by your toolchain (for example `xcrun -f lldb-dap` on macOS) or contact your toolchain vendor to include it.
1212

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-
|**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.
40-
|**enableDisplayExtendedBacktrace**|bool| | Enable language specific extended backtraces.
41-
|**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.
42-
43-
### Attaching Settings
13+
By default, the VS Code extension will expect to find `lldb-dap` in your `PATH`.
14+
Alternatively, you can explictly specify the location of the `lldb-dap` binary using the `lldb-dap.executable-path` setting.
4415

45-
When attaching to a process using LLDB you can attach in a few ways
16+
### Usage with other IDEs
4617

47-
1. Attach to an existing process using the process ID
48-
2. Attach to an existing process by name
49-
3. Attach by name by waiting for the next instance of a process to launch
18+
The `lldb-dap` binary is a command line tool that implements the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/).
19+
It is used to power the VS Code extension but can also be used with other IDEs and editors that support DAP.
20+
The 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.
5021

51-
The JSON configuration file can contain the following `lldb-dap` specific launch key/value pairs:
52-
53-
|parameter |type |req | |
54-
|-------------------|--------|:--:|---------|
55-
|**name** |string |Y| A configuration name that will be displayed in the IDE.
56-
|**type** |string |Y| Must be "lldb-dap".
57-
|**request** |string |Y| Must be "attach".
58-
|**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.
59-
|**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.
60-
|**stopOnEntry** |boolean| | Whether to stop program immediately after launching.
61-
|**waitFor** |boolean | | Wait for the process to launch.
62-
|**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.
63-
|**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.
64-
|**stopCommands** |[string]| | LLDB commands executed just after each stop. Commands and command output will be sent to the debugger console when they are executed.
65-
|**exitCommands** |[string]| | LLDB commands executed when the program exits. Commands and command output will be sent to the debugger console when they are executed.
66-
|**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.
67-
|**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.
68-
|**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.
69-
|**enableDisplayExtendedBacktrace**|bool| | Enable language specific extended backtraces.
70-
|**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.
22+
## Launching & Attaching to a debugee
7123

72-
### Example configurations
24+
Launching or attaching a debugee require you to create a [launch configuration](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations).
25+
This file defines arguments that get passed to `lldb-dap` and the configuration settings control how the launch or attach happens.
7326

74-
#### Launching
27+
### Launching a debugee
7528

7629
This will launch `/tmp/a.out` with arguments `one`, `two`, and `three` and
7730
adds `FOO=1` and `bar` to the environment:
@@ -87,6 +40,14 @@ adds `FOO=1` and `bar` to the environment:
8740
}
8841
```
8942

43+
### Attaching to a process
44+
45+
When attaching to a process using LLDB, you can attach in multiple ways:
46+
47+
1. Attach to an existing process using the process ID
48+
2. Attach to an existing process by name
49+
3. Attach by name by waiting for the next instance of a process to launch
50+
9051
#### Attach using PID
9152

9253
This will attach to a process `a.out` whose process ID is 123:
@@ -132,7 +93,7 @@ to be launched you can add the "waitFor" key value pair:
13293
This will work as long as the architecture, vendor and OS supports waiting
13394
for processes. Currently MacOS is the only platform that supports this.
13495

135-
#### Loading a Core File
96+
### Loading a Core File
13697

13798
This loads the coredump file `/cores/123.core` associated with the program
13899
`/tmp/a.out`:
@@ -147,7 +108,7 @@ This loads the coredump file `/cores/123.core` associated with the program
147108
}
148109
```
149110

150-
#### Connect to a Debug Server on the Current Machine
111+
### Connect to a Debug Server on the Current Machine
151112

152113
This connects to a debug server (e.g. `lldb-server`, `gdbserver`) on
153114
the current machine, that is debugging the program `/tmp/a.out` and listening
@@ -177,7 +138,7 @@ instead of using the custom command `attachCommands`.
177138
}
178139
```
179140

180-
#### Connect to a Debug Server on Another Machine
141+
### Connect to a Debug Server on Another Machine
181142

182143
This connects to a debug server running on another machine with hostname
183144
`hostnmame`. Which is debugging the program `/tmp/a.out` and listening on
@@ -210,12 +171,73 @@ The default hostname being used `localhost`.
210171
}
211172
```
212173

213-
## Custom debugger commands
174+
### Configuration Settings Reference
175+
176+
For both launch and attach configurations, lldb-dap accepts the following `lldb-dap`
177+
specific key/value pairs:
178+
179+
|parameter |type|req | |
180+
|-------------------|----|:--:|---------|
181+
|**name** |string|Y| A configuration name that will be displayed in the IDE.
182+
|**type** |string|Y| Must be "lldb-dap".
183+
|**request** |string|Y| Must be "launch" or "attach".
184+
|**program** |string|Y| Path to the executable to launch.
185+
|**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.
186+
|**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.
187+
|**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.
188+
|**commandEscapePrefix** | string | | The escape prefix to use for executing regular LLDB commands in the Debug Console, instead of printing variables. Defaults to a back-tick (`\``). If it's an empty string, then all expression in the Debug Console are treated as regular LLDB commands.
189+
|**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.
190+
|**customThreadFormat** | string | | Same as `customFrameFormat`, but for threads instead of stack frames.
191+
|**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.
192+
|**enableDisplayExtendedBacktrace**|bool| | Enable language specific extended backtraces.
193+
|**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.
194+
|**initCommands** |[string]| | LLDB commands executed upon debugger startup prior to creating the LLDB target.
195+
|**preRunCommands** |[string]| | LLDB commands executed just before launching/attaching, after the LLDB target has been created.
196+
|**stopCommands** |[string]| | LLDB commands executed just after each stop.
197+
|**exitCommands** |[string]| | LLDB commands executed when the program exits.
198+
|**terminateCommands** |[string]| | LLDB commands executed when the debugging session ends.
199+
200+
All commands and command outputs will be sent to the debugger console when they are executed.
201+
Commands can be prefixed with `?` or `!` to modify their behavior:
202+
* Commands prefixed with `?` are quiet on success, i.e. nothing is written to stdout if the command succeeds.
203+
* 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.
204+
205+
For JSON configurations of `"type": "launch"`, the JSON configuration can additionally
206+
contain the following key/value pairs:
207+
208+
|parameter |type|req | |
209+
|-------------------|----|:--:|---------|
210+
|**program** |string|Y| Path to the executable to launch.
211+
|**args** |[string]|| An array of command line argument strings to be passed to the program being launched.
212+
|**cwd** |string| | The program working directory.
213+
|**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.
214+
|**stopOnEntry** |boolean| | Whether to stop program immediately after launching.
215+
|**runInTerminal** |boolean| | Launch the program inside an integrated terminal in the IDE. Useful for debugging interactive command line programs.
216+
|**launchCommands** |[string]| | LLDB commands executed to launch the program.
217+
218+
For JSON configurations of `"type": "attach"`, the JSON configuration can contain
219+
the following `lldb-dap` specific key/value pairs:
220+
221+
|parameter |type |req | |
222+
|-------------------|--------|:--:|---------|
223+
|**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.
224+
|**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.
225+
|**waitFor** |boolean | | Wait for the process to launch.
226+
|**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.
227+
228+
## Debug Console
229+
230+
The debug console allows printing variables / expressions and executing lldb commands.
231+
By default, all provided commands are interpreteted as variable names / expressions whose values will be printed to the Debug Console.
232+
To execute regular LLDB commands, prefix them with the `\`` character.
233+
The escape character can be changed via the `commandEscapePrefix` configuration option.
234+
235+
### lldb-dap specific commands
214236

215237
The `lldb-dap` tool includes additional custom commands to support the Debug
216238
Adapter Protocol features.
217239

218-
### startDebugging
240+
#### `lldb-dap startDebugging`
219241

220242
Using the command `lldb-dap startDebugging` it is possible to trigger a
221243
reverse request to the client requesting a child debug session with the
@@ -240,7 +262,7 @@ This will launch a server and then request a child debug session for a client.
240262
}
241263
```
242264

243-
### repl-mode
265+
#### `lldb-dap repl-mode`
244266

245267
Inspect or adjust the behavior of lldb-dap repl evaluation requests. The
246268
supported modes are `variable`, `command` and `auto`.

0 commit comments

Comments
 (0)