[Lldb-commits] [lldb] [lldb-dap][docs] Fix README (PR #110982)

Thu Oct 3 03:58:39 PDT 2024

llvmbot wrote:




@llvm/pr-subscribers-lldb

Author: Adrian Vogelsgesang (vogelsgesang)

<details>
<summary>Changes</summary>

Apparently, the markdown parser used by the VSCode Marketplace does not support escaped backticks the same way that Github does. This lead to the table of launch / attach options to be rendered as an unformatted blob instead of as a table.

See https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap

This commit fixes the issue by completely avoiding escaped backticks in the README.

While at it, I also fixed a couple of typos / small wording issues. Also, I reordered the ways to procure the `lldb-dap` binary in priority order: Most users should prefer the toolchain-provided binary over building it from source.

---
Full diff: https://github.com/llvm/llvm-project/pull/110982.diff


1 Files Affected:

- (modified) lldb/tools/lldb-dap/README.md (+13-11) 


``````````diff

diff --git a/lldb/tools/lldb-dap/README.md b/lldb/tools/lldb-dap/README.md
index 0c1a5a5ef344ac..343383ea7196d6 100644
--- a/lldb/tools/lldb-dap/README.md
+++ b/lldb/tools/lldb-dap/README.md
@@ -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.
@@ -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.
@@ -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.
@@ -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

``````````

</details>


https://github.com/llvm/llvm-project/pull/110982
