llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-lldb
Author: Adrian Vogelsgesang (vogelsgesang)
<details>
<summary>Changes</summary>
* 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.
---
Full diff: https://github.com/llvm/llvm-project/pull/109266.diff
1 Files Affected:
- (modified) lldb/tools/lldb-dap/README.md (+80-61)
``````````diff
diff --git a/lldb/tools/lldb-dap/README.md b/lldb/tools/lldb-dap/README.md
index 11a14d29ab51e2..eddeab469d9345 100644
--- a/lldb/tools/lldb-dap/README.md
+++ b/lldb/tools/lldb-dap/README.md
@@ -1,71 +1,30 @@
# LLDB DAP
-## `lldb-dap` Configurations
+## Procuring the `lldb-dap` binary
-The extension requires the `lldb-dap` (formerly `lldb-vscode`) binary. It is a
-command line tool that implements the [Debug Adapter
-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.
-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.
+The extension requires the `lldb-dap` (formerly `lldb-vscode`) binary.
+This binary is not currently packaged with the VS-Code extension.
-## Launching & Attaching Configuration
+There are multiple ways to obtain this binary:
+* build it from source (see [LLDB's build
instructions](https://lldb.llvm.org/resources/build.html))
+* 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.
+* contact your toolchain vendor
-Launching to attaching require you to create a [launch
configuration](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations).
-This file defines arguments that get passed to `lldb-dap` and the
configuration settings control how the launch or attach happens.
+By default, the VS-Code extension will expect to find `lldb-dap` in your
`PATH`.
+Alternatively, you can explictly specify the location of the `lldb-dap` binary
using the `lldb-dap.executable-path` setting.
-### Launch Configuration Settings
+### Usage with other editors
-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)
-file that defines how your program will be run. The JSON configuration file
can contain the following `lldb-dap` specific launch key/value pairs:
+The `lldb-dap` binary is a command line tool that implements the [Debug
Adapter 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.
+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.
-|parameter |type|req | |
-|-------------------|----|:--:|---------|
-|**name** |string|Y| A configuration name that will be displayed in
the IDE.
-|**type** |string|Y| Must be "lldb-dap".
-|**request** |string|Y| Must be "launch".
-|**program** |string|Y| Path to the executable to launch.
-|**args** |[string]|| An array of command line argument strings to
be passed to the program being launched.
-|**cwd** |string| | The program working directory.
-|**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.
-|**stopOnEntry** |boolean| | Whether to stop program immediately after
launching.
-|**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.
-|**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.
-|**stopCommands** |[string]| | LLDB commands executed just after each stop.
Commands and command output will be sent to the debugger console when they are
executed.
-|**launchCommands** |[string]| | LLDB commands executed to launch the program.
Commands and command output will be sent to the debugger console when they are
executed.
-|**exitCommands** |[string]| | LLDB commands executed when the program
exits. Commands and command output will be sent to the debugger console when
they are executed.
-|**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.
-|**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.
-|**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.
-
-### Attaching Settings
-
-When attaching to a process using LLDB you can attach in a few ways
+## Launching & Attaching to a debugee
-1. Attach to an existing process using the process ID
-2. Attach to an existing process by name
-3. Attach by name by waiting for the next instance of a process to launch
-
-The JSON configuration file can contain the following `lldb-dap` specific
launch key/value pairs:
-
-|parameter |type |req | |
-|-------------------|--------|:--:|---------|
-|**name** |string |Y| A configuration name that will be displayed
in the IDE.
-|**type** |string |Y| Must be "lldb-dap".
-|**request** |string |Y| Must be "attach".
-|**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.
-|**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.
-|**stopOnEntry** |boolean| | Whether to stop program immediately after
launching.
-|**waitFor** |boolean | | Wait for the process to launch.
-|**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.
-|**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.
-|**stopCommands** |[string]| | LLDB commands executed just after each stop.
Commands and command output will be sent to the debugger console when they are
executed.
-|**exitCommands** |[string]| | LLDB commands executed when the program
exits. Commands and command output will be sent to the debugger console when
they are executed.
-|**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.
-|**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.
-
-### Example configurations
+Launching or attaching a debugee require you to create a [launch
configuration](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations).
+This file defines arguments that get passed to `lldb-dap` and the
configuration settings control how the launch or attach happens.
-#### Launching
+### Launching a debugee
This will launch `/tmp/a.out` with arguments `one`, `two`, and `three` and
adds `FOO=1` and `bar` to the environment:
@@ -81,6 +40,14 @@ adds `FOO=1` and `bar` to the environment:
}
```
+### Attaching to a process
+
+When attaching to a process using LLDB you can attach in a few ways
+
+1. Attach to an existing process using the process ID
+2. Attach to an existing process by name
+3. Attach by name by waiting for the next instance of a process to launch
+
#### Attach using PID
This will attach to a process `a.out` whose process ID is 123:
@@ -126,7 +93,7 @@ to be launched you can add the "waitFor" key value pair:
This will work as long as the architecture, vendor and OS supports waiting
for processes. Currently MacOS is the only platform that supports this.
-#### Loading a Core File
+### Loading a Core File
This loads the coredump file `/cores/123.core` associated with the program
`/tmp/a.out`:
@@ -141,7 +108,7 @@ This loads the coredump file `/cores/123.core` associated
with the program
}
```
-#### Connect to a Debug Server on the Current Machine
+### Connect to a Debug Server on the Current Machine
This connects to a debug server (e.g. `lldb-server`, `gdbserver`) on
the current machine, that is debugging the program `/tmp/a.out` and listening
@@ -171,7 +138,7 @@ instead of using the custom command `attachCommands`.
}
```
-#### Connect to a Debug Server on Another Machine
+### Connect to a Debug Server on Another Machine
This connects to a debug server running on another machine with hostname
`hostnmame`. Which is debugging the program `/tmp/a.out` and listening on
@@ -204,6 +171,58 @@ The default hostname being used `localhost`.
}
```
+### Configuration Settings Reference
+
+For both launch and attach configurations, lldb-dap accepts the following
`lldb-dap`
+specific key/value pairs:
+
+|parameter |type|req | |
+|-------------------|----|:--:|---------|
+|**name** |string|Y| A configuration name that will be displayed in
the IDE.
+|**type** |string|Y| Must be "lldb-dap".
+|**request** |string|Y| Must be "launch" or "attach".
+|**program** |string|Y| Path to the executable to launch.
+|**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.
+|**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.
+|**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.
+|**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.
+|**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.
+|**customThreadFormat** | string | | Same as `customFrameFormat`, but for
threads instead of stack frames.
+|**initCommands** |[string]| | LLDB commands executed upon debugger startup
prior to creating the LLDB target.
+|**preRunCommands** |[string]| | LLDB commands executed just before
launching/attaching, after the LLDB target has been created.
+|**stopCommands** |[string]| | LLDB commands executed just after each stop.
+|**exitCommands** |[string]| | LLDB commands executed when the program exits.
+|**terminateCommands** |[string]| | LLDB commands executed when the debugging
session ends.
+
+All commands and command outputs will be sent to the debugger console when
they are executed.
+
+For JSON configurations of `"type": "launch"`, the JSON configuration can
additionally
+contain the following key/value pairs:
+
+|parameter |type|req | |
+|-------------------|----|:--:|---------|
+|**program** |string|Y| Path to the executable to launch.
+|**args** |[string]|| An array of command line argument strings to
be passed to the program being launched.
+|**cwd** |string| | The program working directory.
+|**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.
+|**stopOnEntry** |boolean| | Whether to stop program immediately after
launching.
+|**runInTerminal** |boolean| | Launch the program inside an integrated
terminal in the IDE. Useful for debugging interactive command line programs.
+|**launchCommands** |[string]| | LLDB commands executed to launch the program.
+
+For JSON configurations of `"type": "attach"`, the JSON configuration can
contain
+the following `lldb-dap` specific key/value pairs:
+
+|parameter |type |req | |
+|-------------------|--------|:--:|---------|
+|**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.
+|**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.
+|**waitFor** |boolean | | Wait for the process to launch.
+|**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.
+
+## Debug Console
+
+
+
## Custom debugger commands
The `lldb-dap` tool includes additional custom commands to support the Debug
``````````
</details>
https://github.com/llvm/llvm-project/pull/109266
_______________________________________________
lldb-commits mailing list
[email protected]
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
