Skip to content

[lldb-dap][docs] Fix README #110982

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 3, 2024
Merged

[lldb-dap][docs] Fix README #110982

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 13 additions & 11 deletions lldb/tools/lldb-dap/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ The extension requires the `lldb-dap` (formerly `lldb-vscode`) binary.
This binary is not packaged with the VS Code extension.

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 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.
* use the binary provided by your toolchain (for example `xcrun -f lldb-dap` on macOS) or contact your toolchain vendor to include it.
* 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.
* build it from source (see [LLDB's build instructions](https://lldb.llvm.org/resources/build.html))

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.
Expand Down Expand Up @@ -185,7 +185,7 @@ specific key/value pairs:
|**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.
|**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.
|**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.
|**displayExtendedBacktrace**|bool| | Enable language specific extended backtraces.
Expand Down Expand Up @@ -227,11 +227,11 @@ the following `lldb-dap` specific key/value pairs:

## Debug Console

The debug console allows printing variables / expressions and executing lldb commands.
By default, lldb-dap tries to auto-detect whether a provided commands is a variable
name / expressions whose values will be printed to the Debug Console or a LLDB command.
To side-step this auto-dection and execute a LLDB command, prefix it with the `\``
character.
The Debug Console allows printing variables / expressions and executing lldb commands.
By default, lldb-dap tries to auto-detect whether a provided command is a variable
name / expression whose values will be printed to the Debug Console or a LLDB command.
To side-step this auto-detection and execute a LLDB command, prefix it with the
`commandEscapePrefix`.

The auto-detection can be disabled using the `lldb-dap repl-mode` command.
The escape character can be adjusted via the `commandEscapePrefix` configuration option.
Expand Down Expand Up @@ -272,14 +272,16 @@ Inspect or adjust the behavior of lldb-dap repl evaluation requests. The
supported modes are `variable`, `command` and `auto`.

- `variable` - Variable mode expressions are evaluated in the context of the
current frame. Use a `\`` prefix on the command to run an lldb command.
current frame.
- `command` - Command mode expressions are evaluated as lldb commands, as a
result, values printed by lldb are always stringified representations of the
expression output.
- `auto` - Auto mode will attempt to infer if the expression represents an lldb
command or a variable expression. A heuristic is used to infer if the input
represents a variable or a command. Use a `\`` prefix to ensure an expression
is evaluated as a command.
represents a variable or a command.

In all three modes, you can use the `commandEscapePrefix` to ensure an expression
is evaluated as a command.

The initial repl-mode can be configured with the cli flag `--repl-mode=<mode>`
and may also be adjusted at runtime using the lldb command
Expand Down
Loading