https://github.com/ashgti updated https://github.com/llvm/llvm-project/pull/172580
>From 1deb17e7a1f402481f43009dde126f0fc754efdd Mon Sep 17 00:00:00 2001 From: John Harrison <[email protected]> Date: Tue, 16 Dec 2025 16:33:43 -0800 Subject: [PATCH 1/4] [lldb] Update LLDB DAP documentation. This adds a new page to lldb.llvm.org that includes a user guide for lldb-dap. I moved the existing lldbdap.md page to lldbdap-contributing.md and updated it to focus on contributing to the project. This is a first pass at the documentation, I expect to expand on it further as needed. --- lldb/docs/index.rst | 1 + lldb/docs/resources/lldbdap-contributing.md | 195 +++++++++++++ lldb/docs/resources/lldbdap.md | 302 ++++++++------------ lldb/tools/lldb-dap/README.md | 2 +- 4 files changed, 318 insertions(+), 182 deletions(-) create mode 100644 lldb/docs/resources/lldbdap-contributing.md diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst index df8fa4e250456..5c948ae920173 100644 --- a/lldb/docs/index.rst +++ b/lldb/docs/index.rst @@ -172,6 +172,7 @@ interesting areas to contribute to lldb. resources/caveats resources/projects resources/lldbdap + resources/lldbdap-contributing resources/addinglanguagesupport Public C++ API <https://lldb.llvm.org/cpp_reference/namespacelldb.html> Private C++ API <https://lldb.llvm.org/cpp_reference/index.html> diff --git a/lldb/docs/resources/lldbdap-contributing.md b/lldb/docs/resources/lldbdap-contributing.md new file mode 100644 index 0000000000000..522fe6c707a41 --- /dev/null +++ b/lldb/docs/resources/lldbdap-contributing.md @@ -0,0 +1,195 @@ +# Contributing to LLDB-DAP + +This guide describes how to extend and contribute to lldb-dap. +For documentation on how to use lldb-dap, see [lldb-dap's README](https://github.com/llvm/llvm-project/blob/main/lldb/tools/lldb-dap/README.md). + +lldb-dap and LLDB are developed under the umbrella of the +[LLVM project](https://llvm.org/). As such, the +"[Getting Started with the LLVM System](https://llvm.org/docs/GettingStarted.html)", +"[Contributing to LLVM](https://llvm.org/docs/Contributing.html)" and +"[LLVM coding standard](https://llvm.org/docs/CodingStandards.html)" +guides might also be relevant, if you are a first-time contributor to the LLVM +project. + +lldb-dap's source code is [part of the LLVM +repository](https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-dap) +on Github. We use Github's [issue +tracker](https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-dap) +and patches can be submitted via [pull +requests](https://github.com/llvm/llvm-project/pulls). + +## Building `lldb-dap` from source + +To build lldb-dap from source, first need to [setup a LLDB build](https://lldb.llvm.org/resources/build.html). +After doing so, run `ninja lldb-dap`. To use your freshly built `lldb-dap` +binary, install the VS Code extension and point it to lldb-dap by setting the +`lldb-dap.executable-path` setting. + +## Responsibilities of LLDB, lldb-dap and the Visual Studio Code Extension + +Under the hood, the UI-based debugging experience is fueled by three separate +components: + +* LLDB provides general, IDE-independent debugging features, such as: + loading binaries / core dumps, interpreting debug info, setting breakpoints, + pretty-printing variables, etc. The `lldb` binary exposes this functionality + via a command line interface. +* `lldb-dap` exposes LLDB's functionality via the + "[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)", + i.e. a protocol through which various IDEs (VS Code, Emacs, vim, neovim, ...) + can interact with a wide range of debuggers (`lldb-dap` and many others). +* The VS Code extension exposes the lldb-dap binary within VS Code. It acts + as a thin wrapper around the lldb-dap binary, and adds VS-Code-specific UI + integration on top of lldb-dap, such as autocompletion for `launch.json` + configuration files. + +Since lldb-dap builds on top of LLDB, all of LLDB's extensibility mechanisms +such as [Variable Pretty-Printing](https://lldb.llvm.org/use/variable.html), +[Frame recognizers](https://lldb.llvm.org/use/python-reference.html#writing-lldb-frame-recognizers-in-python) +and [Python Scripting](https://lldb.llvm.org/use/python.html) are available +also in lldb-dap. + +When adding new functionality, you generally want to add it on the lowest +applicable level. I.e., quite frequently you actually want to add functionality +to LLDB's core in order to improve your debugging experience in VS Code. + +### The Debug Adapter Protocol + +The most relevant resources for the Debug Adapter Protocol are: +* [The overview](https://microsoft.github.io/debug-adapter-protocol/overview) + which provides a high-level introduction, +* the [human-readable specification](https://microsoft.github.io/debug-adapter-protocol/specification), and +* the [JSON-schema specification](https://github.com/microsoft/debug-adapter-protocol/blob/main/debugAdapterProtocol.json). + +lldb-dap adds some additional non-standard extensions to the protocol. To take +advantage of those extensions, IDE-specific support code is needed, usually +inside the VS Code extension. When adding a new extension, please first look +through the [issue tracker of the Debug Adapter +Protocol](https://github.com/microsoft/debug-adapter-protocol/issues) to check +if there already is a proposal serving your use case. If so, try to take +inspiration from it. If not, consider opening an upstream issue. + +To avoid naming collisions with potential future extensions of the Debug +Adapter protocol, all non-standard extensions should use the prefix +`$__lldb_extension` in their JSON property names. + +### Debugging the Debug Adapter Protocol + +To debug the Debug Adapter Protocol, point the `LLDBDAP_LOG` environment +variable to a file on your disk. lldb-dap will log all communication received +from / sent to the IDE to the provided path. In the VS Code extension, you +can also set the log path through the `lldb-dap.log-path` VS Code setting. + +## Building the VS Code extension from source + +Installing the plug-in is very straightforward and involves just a few steps. + +In most cases, installing the VS Code extension from the [VS Code +Marketplace](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap) +and pointing it to a locally built lldb-dap binary is sufficient. Building +the VS Code extension from source is only necessary if the TypeScript code is +changed. + +### Pre-requisites + +- Install a modern version of node (e.g. `v20.0.0`). +- On VS Code, execute the command `Install 'code' command in PATH`. You need to + do it only once. This enables the command `code` in the PATH. + +### Packaging and installation + +```bash +cd /path/to/lldb/tools/lldb-dap +npm install +npm run package # This also compiles the extension. +npm run vscode-install +``` + +On VS Code, set the setting `lldb-dap.executable-path` to the path of your local +build of `lldb-dap`. + +And then you are ready! + +### Updating the extension + +Updating the extension is pretty much the same process as installing it from +scratch. However, VS Code expects the version number of the upgraded extension +to be greater than the previous one, otherwise the installation step might have +no effect. + +```bash +# Bump version in package.json +cd /path/to/lldb/tools/lldb-dap +npm install +npm run package +npm run vscode-install +``` + +Another way upgrade without bumping the extension version is to first uninstall +the extension, then reload VS Code, and then install it again. This is +an unfortunate limitation of the editor. + +```bash +cd /path/to/lldb/tools/lldb-dap +npm run vscode-uninstall +# Then reload VS Code: reopen the IDE or execute the `Developer: Reload Window` +# command. +npm run package +npm run vscode-install +``` + +### Deploying for Visual Studio Code + +The easiest way to deploy the extension for execution on other machines requires +copying `lldb-dap` and its dependencies into a`./bin` subfolder and then create a +standalone VSIX package. + +```bash +cd /path/to/lldb/tools/lldb-dap +mkdir -p ./bin +cp /path/to/a/built/lldb-dap ./bin/ +cp /path/to/a/built/liblldb.so ./bin/ +npm run package +``` + +This will produce the file `./out/lldb-dap.vsix` that can be distributed. In +this type of installation, users don't need to manually set the path to +`lldb-dap`. The extension will automatically look for it in the `./bin` +subfolder. + +*Note: It's not possible to use symlinks to `lldb-dap`, as the packaging tool +forcefully performs a deep copy of all symlinks.* + +*Note: It's possible to use this kind flow for local installations, but it's +not recommended because updating `lldb-dap` requires rebuilding the extension.* + +## Formatting the Typescript code + +This is also very simple, just run: + +```bash +npm run format +``` + +## Working with the VS Code extension from another extension + +The VS Code extension exposes the following [VS Code +commands](https://code.visualstudio.com/api/extension-guides/command), +which can be invoked by other debugger extensions to leverage this extension's +settings and logic. The commands help resolve configuration, create adapter +descriptor, and get the lldb-dap process for state tracking, additional +interaction, and telemetry. + +``` +// Resolve debug configuration +const resolvedConfiguration = await vscode.commands.executeCommand("lldb-dap.resolveDebugConfiguration", folder, configuration, token); + +// Resolve debug configuration with substituted variables +const resolvedConfigurationWithSubstitutedVariables = await vscode.commands.executeCommand("lldb-dap.resolveDebugConfigurationWithSubstitutedVariables", folder, configuration, token); + +// Create debug adapter descriptor +const adapterDescriptor = await vscode.commands.executeCommand("lldb-dap.createDebugAdapterDescriptor", session, executable); + +// Get DAP server process +const process = await vscode.commands.executeCommand("lldb-dap.getServerProcess"); +``` diff --git a/lldb/docs/resources/lldbdap.md b/lldb/docs/resources/lldbdap.md index 3838c82ab5dfb..6f840443b5c91 100644 --- a/lldb/docs/resources/lldbdap.md +++ b/lldb/docs/resources/lldbdap.md @@ -1,195 +1,135 @@ -# Contributing to LLDB-DAP - -This guide describes how to extend and contribute to lldb-dap. -For documentation on how to use lldb-dap, see [lldb-dap's README](https://github.com/llvm/llvm-project/blob/main/lldb/tools/lldb-dap/README.md). - -lldb-dap and LLDB are developed under the umbrella of the -[LLVM project](https://llvm.org/). As such, the -"[Getting Started with the LLVM System](https://llvm.org/docs/GettingStarted.html)", -"[Contributing to LLVM](https://llvm.org/docs/Contributing.html)" and -"[LLVM coding standard](https://llvm.org/docs/CodingStandards.html)" -guides might also be relevant, if you are a first-time contributor to the LLVM -project. - -lldb-dap's source code is [part of the LLVM -repository](https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-dap) -on Github. We use Github's [issue -tracker](https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-dap) -and patches can be submitted via [pull -requests](https://github.com/llvm/llvm-project/pulls). - -## Building `lldb-dap` from soruce - -To build lldb-dap from source, first need to [setup a LLDB build](https://lldb.llvm.org/resources/build.html). -After doing so, run `ninja lldb-dap`. To use your freshly built `lldb-dap` -binary, install the VS Code extension and point it to lldb-dap by setting the -`lldb-dap.executable-path` setting. - -## Responsibilities of LLDB, lldb-dap and the Visual Studio Code Extension - -Under the hood, the UI-based debugging experience is fueled by three separate -components: - -* LLDB provides general, IDE-indepedent debugging features, such as: - loading binaries / core dumps, interpreting debug info, setting breakpoints, - pretty-printing variables, etc. The `lldb` binary exposes this functionality - via a command line interface. -* `lldb-dap` exposes LLDB's functionality via the - "[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)", - i.e. a protocol through which various IDEs (VS Code, Emacs, vim, neovim, ...) - can interact with a wide range of debuggers (`lldb-dap` and many others). -* The VS Code extension exposes the lldb-dap binary within VS Code. It acts - as a thin wrapper around the lldb-dap binary, and adds VS-Code-specific UI - integration on top of lldb-dap, such as autocompletion for `launch.json` - configuration files. - -Since lldb-dap builds on top of LLDB, all of LLDB's extensibility mechanisms -such as [Variable Pretty-Printing](https://lldb.llvm.org/use/variable.html), -[Frame recognizers](https://lldb.llvm.org/use/python-reference.html#writing-lldb-frame-recognizers-in-python) -and [Python Scripting](https://lldb.llvm.org/use/python.html) are available -also in lldb-dap. - -When adding new functionality, you generally want to add it on the lowest -applicable level. I.e., quite frequently you actually want to add functionality -to LLDB's core in order to improve your debugging experience in VS Code. - -### The Debug Adapter Protocol - -The most relevant resources for the Debug Adapter Protocol are: -* [The overview](https://microsoft.github.io/debug-adapter-protocol/overview) - which provides a high-level introduction, -* the [human-readable specification](https://microsoft.github.io/debug-adapter-protocol/specification), and -* the [JSON-schema specification](https://github.com/microsoft/debug-adapter-protocol/blob/main/debugAdapterProtocol.json). - -lldb-dap adds some additional non-standard extensions to the protocol. To take -advantage of those extensions, IDE-specific support code is needed, usually -inside the VS Code extension. When adding a new extension, please first look -through the [issue tracker of the Debug Adapter -Protocol](https://github.com/microsoft/debug-adapter-protocol/issues) to check -if there already is a proposal serving your use case. If so, try to take -inspiration from it. If not, consider opening an upstream issue. - -To avoid naming collisions with potential future extensions of the Debug -Adapter protocol, all non-standard extensions should use the prefix -`$__lldb_extension` in their JSON property names. - -### Debugging the Debug Adapter Protocol - -To debug the Debug Adapter Protocol, point the `LLDBDAP_LOG` environment -variable to a file on your disk. lldb-dap will log all communication received -from / sent to the IDE to the provided path. In the VS Code extension, you -can also set the log path through the `lldb-dap.log-path` VS Code setting. - -## Building the VS Code extension from source - -Installing the plug-in is very straightforward and involves just a few steps. - -In most cases, installing the VS Code extension from the [VS Code -Marketplace](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap) -and pointing it to a locally built lldb-dap binary is sufficient. Building -the VS Code extension from source is only necessary if the TypeScript code is -changed. - -### Pre-requisites - -- Install a modern version of node (e.g. `v20.0.0`). -- On VS Code, execute the command `Install 'code' command in PATH`. You need to - do it only once. This enables the command `code` in the PATH. - -### Packaging and installation - -```bash -cd /path/to/lldb/tools/lldb-dap -npm install -npm run package # This also compiles the extension. -npm run vscode-install -``` - -On VS Code, set the setting `lldb-dap.executable-path` to the path of your local -build of `lldb-dap`. - -And then you are ready! - -### Updating the extension - -Updating the extension is pretty much the same process as installing it from -scratch. However, VS Code expects the version number of the upgraded extension -to be greater than the previous one, otherwise the installation step might have -no effect. - -```bash -# Bump version in package.json -cd /path/to/lldb/tools/lldb-dap -npm install -npm run package -npm run vscode-install -``` +# Getting started with `lldb-dap` -Another way upgrade without bumping the extension version is to first uninstall -the extension, then reload VS Code, and then install it again. This is -an unfortunate limitation of the editor. - -```bash -cd /path/to/lldb/tools/lldb-dap -npm run vscode-uninstall -# Then reload VS Code: reopen the IDE or execute the `Developer: Reload Window` -# command. -npm run package -npm run vscode-install -``` - -### Deploying for Visual Studio Code +Welcome to the `llb-dap` documentation! -The easiest way to deploy the extension for execution on other machines requires -copying `lldb-dap` and its dependencies into a`./bin` subfolder and then create a -standalone VSIX package. +`lldb-dap` brings the power of `lldb` into any editor or IDE that supports the [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/). -```bash -cd /path/to/lldb/tools/lldb-dap -mkdir -p ./bin -cp /path/to/a/built/lldb-dap ./bin/ -cp /path/to/a/built/liblldb.so ./bin/ -npm run package -``` +## Prerequisites -This will produce the file `./out/lldb-dap.vsix` that can be distributed. In -this type of installation, users don't need to manually set the path to -`lldb-dap`. The extension will automatically look for it in the `./bin` -subfolder. +In order to begin debugging with `lldb-dap`, you may first need to acquire the +`lldb-dap` binary from an LLVM distribution. For general LLVM releases visit +https://releases.llvm.org/ or check your systems preferred package manager for +the `lldb` package. -*Note: It's not possible to use symlinks to `lldb-dap`, as the packaging tool -forcefully performs a deep copy of all symlinks.* +In some cases, a language specific build of `lldb` / `lldb-dap` may also be +available as part of the languages toolchain. For example the +[swift language](https://www.swift.org/) toolchain includes additional language integrations in `lldb` and the toolchain builds provider both the `lldb` driver binary and `lldb-dap` binary. -*Note: It's possible to use this kind flow for local installations, but it's -not recommended because updating `lldb-dap` requires rebuilding the extension.* +## IDE Integration -## Formatting the Typescript code +In addition to the `lldb-dap` binary, some IDEs have additional extensions to +support debugging. -This is also very simple, just run: +- Visual Studio Code - +[LLDB DAP Extension](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap) +<!-- Add other IDE integrations. --> -```bash -npm run format -``` +## Launching a program -## Working with the VS Code extension from another extension +To launch an executable for debugging, first define a launch configuration tells `lldb-dap` how to launch the binary. -The VS Code extension exposes the following [VS Code -commands](https://code.visualstudio.com/api/extension-guides/command), -which can be invoked by other debugger extensions to leverage this extension's -settings and logic. The commands help resolve configuration, create adapter -descriptor, and get the lldb-dap process for state tracking, additional -interaction, and telemetry. +A simple launch configuration may look like +```json +{ + "type": "lldb-dap", + "request": "launch", + "name": "Debug a.out", + "program": "a.out" +} ``` -// Resolve debug configuration -const resolvedConfiguration = await vscode.commands.executeCommand("lldb-dap.resolveDebugConfiguration", folder, configuration, token); -// Resolve debug configuration with substituted variables -const resolvedConfigurationWithSubstitutedVariables = await vscode.commands.executeCommand("lldb-dap.resolveDebugConfigurationWithSubstitutedVariables", folder, configuration, token); - -// Create debug adapter descriptor -const adapterDescriptor = await vscode.commands.executeCommand("lldb-dap.createDebugAdapterDescriptor", session, executable); - -// Get DAP server process -const process = await vscode.commands.executeCommand("lldb-dap.getServerProcess"); -``` +See the [Configuration Settings Reference](#configuration-settings-reference) for more information. + +# Supported Features + +`lldb-dap` supports many features of the DAP spec. + +* Breakpoints + * Source breakpoints + * Function breakpoint + * Exception breakpoints +* Call Stacks +* Variables +* Watch points +* Expression Evaluation +* And more... + +For more information, visit +[Visual Studio Code's Debugging User Documentation](https://code.visualstudio.com/docs/debugtest/debugging) + +## Debug Console + +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 mode can ba adjusted using the `lldb-dap repl-mode` command in the Debug Console or by adjusting the `--repl-mode [mode]` argument to `lldb-dap`. The supported modes are `variable`, `command` and `auto`. + +# Configuration Settings Reference + +## Common configurations + +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 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. | +| **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. | +| **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 synthetic child plug-ins as it lets you see the actual contents of the variable. | +| **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. Commands can be prefixed with `?` or `!` to modify their behavior: + +- Commands prefixed with `?` are quiet on success, i.e. nothing is written to + stdout if the command succeeds. +- Prefixing a command with `!` enables error checking: If a command prefixed + with `!` fails, subsequent commands will not be run. This is useful if one of + the commands depends on another, as it will stop the chain of commands. + +## Launch configurations + +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** (deprecated) | boolean | | Launch the program inside an integrated terminal in the IDE. Useful for debugging interactive command line programs. | +| **console** | string | | Specify where to launch the program: internal console (`internalConsole`), integrated terminal (`integratedTerminal`) or external terminal (`externalTerminal`). Supported from lldb-dap 21.0 version. | +| **stdio** | [string] | | The stdio property specifies the redirection targets for the debuggee's stdio streams. A null value redirects a stream to the default debug terminal. String can be a path to file, named pipe or TTY device. If less than three values are provided, the list will be padded with the last value. Specifying more than three values will create additional file descriptors (4, 5, etc.). Supported from lldb-dap 22.0 version. | +| **launchCommands** | [string] | | LLDB commands executed to launch the program. | + +## Attach configurations + +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 **program**. 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. | diff --git a/lldb/tools/lldb-dap/README.md b/lldb/tools/lldb-dap/README.md index e83384f89bc1f..052812acdc60f 100644 --- a/lldb/tools/lldb-dap/README.md +++ b/lldb/tools/lldb-dap/README.md @@ -421,4 +421,4 @@ The source code is part of the [LLVM repository](https://github.com/llvm/llvm-pr We use Github's [issue tracker](https://github.com/llvm/llvm-project/issues?q=label%3Alldb-dap) and patches can be submitted via [pull requests](https://github.com/llvm/llvm-project/pulls?q=label%3Alldb-dap). Furthermore, there is a [LLDB category](https://discourse.llvm.org/c/subprojects/lldb/8) on the LLVM discourse forum. -For instructions on how to get started with development on lldb-dap, see the "[Contributing to lldb-dap](https://lldb.llvm.org/resources/lldbdap.html)" guide. +For instructions on how to get started with development on lldb-dap, see the "[Contributing to lldb-dap](https://lldb.llvm.org/resources/lldbdap-contributing.html)" guide. >From 8fae1abbdcfce4e78e5042130af7c85e0bfbdc2f Mon Sep 17 00:00:00 2001 From: John Harrison <[email protected]> Date: Tue, 16 Dec 2025 16:41:38 -0800 Subject: [PATCH 2/4] Updating the required keys. --- lldb/docs/resources/lldbdap.md | 64 ++++++++++++++++++++-------------- 1 file changed, 38 insertions(+), 26 deletions(-) diff --git a/lldb/docs/resources/lldbdap.md b/lldb/docs/resources/lldbdap.md index 6f840443b5c91..b7d9df33a9ed3 100644 --- a/lldb/docs/resources/lldbdap.md +++ b/lldb/docs/resources/lldbdap.md @@ -2,7 +2,8 @@ Welcome to the `llb-dap` documentation! -`lldb-dap` brings the power of `lldb` into any editor or IDE that supports the [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/). +`lldb-dap` brings the power of `lldb` into any editor or IDE that supports the +[Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/). ## Prerequisites @@ -13,7 +14,9 @@ the `lldb` package. In some cases, a language specific build of `lldb` / `lldb-dap` may also be available as part of the languages toolchain. For example the -[swift language](https://www.swift.org/) toolchain includes additional language integrations in `lldb` and the toolchain builds provider both the `lldb` driver binary and `lldb-dap` binary. +[swift language](https://www.swift.org/) toolchain includes additional language +integrations in `lldb` and the toolchain builds provider both the `lldb` driver +binary and `lldb-dap` binary. ## IDE Integration @@ -26,7 +29,8 @@ support debugging. ## Launching a program -To launch an executable for debugging, first define a launch configuration tells `lldb-dap` how to launch the binary. +To launch an executable for debugging, first define a launch configuration tells +`lldb-dap` how to launch the binary. A simple launch configuration may look like @@ -39,21 +43,22 @@ A simple launch configuration may look like } ``` -See the [Configuration Settings Reference](#configuration-settings-reference) for more information. +See the [Configuration Settings Reference](#configuration-settings-reference) +for more information. # Supported Features `lldb-dap` supports many features of the DAP spec. -* Breakpoints - * Source breakpoints - * Function breakpoint - * Exception breakpoints -* Call Stacks -* Variables -* Watch points -* Expression Evaluation -* And more... +- Breakpoints + - Source breakpoints + - Function breakpoint + - Exception breakpoints +- Call Stacks +- Variables +- Watch points +- Expression Evaluation +- And more... For more information, visit [Visual Studio Code's Debugging User Documentation](https://code.visualstudio.com/docs/debugtest/debugging) @@ -66,7 +71,9 @@ 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 mode can ba adjusted using the `lldb-dap repl-mode` command in the Debug Console or by adjusting the `--repl-mode [mode]` argument to `lldb-dap`. The supported modes are `variable`, `command` and `auto`. +The auto-detection mode can ba adjusted using the `lldb-dap repl-mode` command +in the Debug Console or by adjusting the `--repl-mode [mode]` argument to +`lldb-dap`. The supported modes are `variable`, `command` and `auto`. # Configuration Settings Reference @@ -80,7 +87,7 @@ For both launch and attach configurations, lldb-dap accepts the following | **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. | +| **program** | string | | 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. | @@ -107,23 +114,28 @@ are executed. Commands can be prefixed with `?` or `!` to modify their behavior: ## Launch configurations +_NOTE:_ Either `program` or `launchCommands` must be specified. + 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** (deprecated) | boolean | | Launch the program inside an integrated terminal in the IDE. Useful for debugging interactive command line programs. | -| **console** | string | | Specify where to launch the program: internal console (`internalConsole`), integrated terminal (`integratedTerminal`) or external terminal (`externalTerminal`). Supported from lldb-dap 21.0 version. | -| **stdio** | [string] | | The stdio property specifies the redirection targets for the debuggee's stdio streams. A null value redirects a stream to the default debug terminal. String can be a path to file, named pipe or TTY device. If less than three values are provided, the list will be padded with the last value. Specifying more than three values will create additional file descriptors (4, 5, etc.). Supported from lldb-dap 22.0 version. | -| **launchCommands** | [string] | | LLDB commands executed to launch the program. | +| Parameter | Type | Req | | +| ------------------------------ | ---------------------- | :-: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **program** | string | | 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 or [string] | | Environment variables to set when launching the program. The string 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** (deprecated) | boolean | | Launch the program inside an integrated terminal in the IDE. Useful for debugging interactive command line programs. | +| **console** | string | | Specify where to launch the program: internal console (`internalConsole`), integrated terminal (`integratedTerminal`) or external terminal (`externalTerminal`). Supported from lldb-dap 21.0 version. | +| **stdio** | [string] | | The stdio property specifies the redirection targets for the debuggee's stdio streams. A null value redirects a stream to the default debug terminal. String can be a path to file, named pipe or TTY device. If less than three values are provided, the list will be padded with the last value. Specifying more than three values will create additional file descriptors (4, 5, etc.). Supported from lldb-dap 22.0 version. | +| **launchCommands** | [string] | | LLDB commands executed to launch the program. | ## Attach configurations +_NOTE:_ Either `pid`, `program`, `coreFile`, `attachCommands` +or`gdb-remote-port` must be specified. + For JSON configurations of `"type": "attach"`, the JSON configuration can contain the following `lldb-dap` specific key/value pairs: >From 60ff87c165f4314b6f6271334670df965f83861b Mon Sep 17 00:00:00 2001 From: John Harrison <[email protected]> Date: Thu, 18 Dec 2025 18:12:56 -0800 Subject: [PATCH 3/4] Adding a section on supported features and updating some wording. --- lldb/docs/resources/lldbdap-contributing.md | 2 +- lldb/docs/resources/lldbdap.md | 118 +++++++++++++++----- 2 files changed, 91 insertions(+), 29 deletions(-) diff --git a/lldb/docs/resources/lldbdap-contributing.md b/lldb/docs/resources/lldbdap-contributing.md index 522fe6c707a41..7586254a4de95 100644 --- a/lldb/docs/resources/lldbdap-contributing.md +++ b/lldb/docs/resources/lldbdap-contributing.md @@ -14,7 +14,7 @@ project. lldb-dap's source code is [part of the LLVM repository](https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-dap) on Github. We use Github's [issue -tracker](https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-dap) +tracker](https://github.com/llvm/llvm-project/issues) and patches can be submitted via [pull requests](https://github.com/llvm/llvm-project/pulls). diff --git a/lldb/docs/resources/lldbdap.md b/lldb/docs/resources/lldbdap.md index b7d9df33a9ed3..a2056bb0f708b 100644 --- a/lldb/docs/resources/lldbdap.md +++ b/lldb/docs/resources/lldbdap.md @@ -1,32 +1,53 @@ # Getting started with `lldb-dap` -Welcome to the `llb-dap` documentation! +Welcome to the `lldb-dap` documentation! `lldb-dap` brings the power of `lldb` into any editor or IDE that supports the [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/). -## Prerequisites +## Responsibilities of LLDB, `lldb-dap` and IDE Integrations -In order to begin debugging with `lldb-dap`, you may first need to acquire the -`lldb-dap` binary from an LLVM distribution. For general LLVM releases visit -https://releases.llvm.org/ or check your systems preferred package manager for -the `lldb` package. +Under the hood, the UI-based debugging experience is fueled by three separate +components: -In some cases, a language specific build of `lldb` / `lldb-dap` may also be -available as part of the languages toolchain. For example the -[swift language](https://www.swift.org/) toolchain includes additional language -integrations in `lldb` and the toolchain builds provider both the `lldb` driver -binary and `lldb-dap` binary. +- LLDB provides general, IDE-independent debugging features, such as: + loading binaries / core dumps, interpreting debug info, setting breakpoints, + pretty-printing variables, etc. The `lldb` binary exposes this functionality + via a command line interface. +- `lldb-dap` exposes LLDB's functionality via the + "[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)", + i.e. a protocol through which various IDEs (Visual Studio Code, Emacs, vim, + neovim, ...) can interact with a wide range of debuggers (`lldb-dap` and many + others). +- An IDE specific extension is used to hook lldb-dap and the IDEs DAP + implementations together for launching a binary. -## IDE Integration +Since `lldb-dap` builds on top of LLDB, all of LLDB's extensibility mechanisms +such as [Variable Pretty-Printing](https://lldb.llvm.org/use/variable.html), +[Frame recognizers](https://lldb.llvm.org/use/python-reference.html#writing-lldb-frame-recognizers-in-python) +and [Python Scripting](https://lldb.llvm.org/use/python.html) are available +also in `lldb-dap`. -In addition to the `lldb-dap` binary, some IDEs have additional extensions to -support debugging. +#### Links to IDE Extensions - Visual Studio Code - [LLDB DAP Extension](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap) <!-- Add other IDE integrations. --> +## Procuring the `lldb-dap` binary + +There are multiple ways to obtain this 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 release packages from the [LLVM release page](https://github.com/llvm/llvm-project/releases/). The `LLVM-{version}-{operating_system}.tar.xz` packages contain a prebuilt `lldb-dap` binary or check your systems prefered package manager. +- Build it from source (see [LLDB's build instructions](https://lldb.llvm.org/resources/build.html)). + +In some cases, a language specific build of `lldb` / `lldb-dap` may also be +available as part of the languages toolchain. For example the +[swift language](https://www.swift.org/) toolchain includes additional language +integrations in `lldb` and the toolchain builds provider both the `lldb` driver +binary and `lldb-dap` binary. + ## Launching a program To launch an executable for debugging, first define a launch configuration tells @@ -48,20 +69,55 @@ for more information. # Supported Features -`lldb-dap` supports many features of the DAP spec. - -- Breakpoints - - Source breakpoints - - Function breakpoint - - Exception breakpoints -- Call Stacks -- Variables -- Watch points -- Expression Evaluation -- And more... - -For more information, visit -[Visual Studio Code's Debugging User Documentation](https://code.visualstudio.com/docs/debugtest/debugging) +`lldb-dap` supports the following capabilities: + +| Capability | Supported | Description | +| ------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| supportsConfigurationDoneRequest | Y | The debug adapter supports the `configurationDone` request. | +| supportsFunctionBreakpoints | Y | The debug adapter supports function breakpoints. | +| supportsConditionalBreakpoints | Y | The debug adapter supports conditional breakpoints. | +| supportsHitConditionalBreakpoints | Y | The debug adapter supports breakpoints that break execution after a specified number of hits. | +| supportsEvaluateForHovers | Y | The debug adapter supports a (side effect free) `evaluate` request for data hovers. | +| exceptionBreakpointFilters | Y | Available exception filter options for the `setExceptionBreakpoints` request. | +| supportsStepBack | N | The debug adapter supports stepping back via the `stepBack` and `reverseContinue` requests. | +| supportsSetVariable | Y | The debug adapter supports setting a variable to a value. | +| supportsRestartFrame | Y | The debug adapter supports restarting a frame. | +| supportsGotoTargetsRequest | Y | The debug adapter supports the `gotoTargets` request. | +| supportsStepInTargetsRequest | Y | The debug adapter supports the `stepInTargets` request. | +| supportsCompletionsRequest | Y | The debug adapter supports the `completions` request. | +| completionTriggerCharacters | `['.', '\s', '\t']` | The set of characters that should trigger completion in a REPL. If not specified, the UI should assume the `.` character. | +| supportsModulesRequest | Y | The debug adapter supports the `modules` request. | +| additionalModuleColumns | N | The set of additional module information exposed by the debug adapter. | +| supportedChecksumAlgorithms | N | Checksum algorithms supported by the debug adapter. | +| supportsRestartRequest | Y (for launch requests) | The debug adapter supports the `restart` request. In this case a client should not implement `restart` by terminating and relaunching the adapter but by calling the `restart` request. | +| supportsExceptionOptions | N | The debug adapter supports `exceptionOptions` on the `setExceptionBreakpoints` request. | +| supportsValueFormattingOptions | Y | The debug adapter supports a `format` attribute on the `stackTrace`, `variables`, and `evaluate` requests. | +| supportsExceptionInfoRequest | Y | The debug adapter supports the `exceptionInfo` request. | +| supportTerminateDebuggee | Y | The debug adapter supports the `terminateDebuggee` attribute on the `disconnect` request. | +| supportSuspendDebuggee | N | The debug adapter supports the `suspendDebuggee` attribute on the `disconnect` request. | +| supportsDelayedStackTraceLoading | Y | The debug adapter supports the delayed loading of parts of the stack, which requires that both the `startFrame` and `levels` arguments and the `totalFrames` result of the `stackTrace` request are supported. | +| supportsLoadedSourcesRequest | N | The debug adapter supports the `loadedSources` request. | +| supportsLogPoints | Y | The debug adapter supports log points by interpreting the `logMessage` attribute of the `SourceBreakpoint`. | +| supportsTerminateThreadsRequest | N | The debug adapter supports the `terminateThreads` request. | +| supportsSetExpression | Y | The debug adapter supports the `setExpression` request. | +| supportsTerminateRequest | Y | The debug adapter supports the `terminate` request. | +| supportsDataBreakpoints | Y | The debug adapter supports data breakpoints. | +| supportsReadMemoryRequest | Y | The debug adapter supports the `readMemory` request. | +| supportsWriteMemoryRequest | Y | The debug adapter supports the `writeMemory` request. | +| supportsDisassembleRequest | Y | The debug adapter supports the `disassemble` request. | +| supportsCancelRequest | Y | The debug adapter supports the `cancel` request. | +| supportsBreakpointLocationsRequest | Y | The debug adapter supports the `breakpointLocations` request. | +| supportsClipboardContext | N | The debug adapter supports the `clipboard` context value in the `evaluate` request. | +| supportsSteppingGranularity | Y | The debug adapter supports stepping granularities (argument `granularity`) for the stepping requests. | +| supportsInstructionBreakpoints | Y | The debug adapter supports adding breakpoints based on instruction references. | +| supportsExceptionFilterOptions | N | The debug adapter supports `filterOptions` as an argument on the `setExceptionBreakpoints` request. | +| supportsSingleThreadExecutionRequests | N | The debug adapter supports the `singleThread` property on the execution requests (`continue`, `next`, `stepIn`, `stepOut`, `reverseContinue`, `stepBack`). | +| supportsDataBreakpointBytes | Y | The debug adapter supports the `asAddress` and `bytes` fields in the `dataBreakpointInfo` request. | +| breakpointModes | `[]` | Modes of breakpoints supported by the debug adapter, such as 'hardware' or 'software'. If present, the client may allow the user to select a mode and include it in its `setBreakpoints` request. Clients may present the first applicable mode in this array as the 'default' mode in gestures that set breakpoints. | +| supportsANSIStyling | Y | The debug adapter supports ANSI escape sequences in styling of `OutputEvent.output` and `Variable.value` fields. | + +For more information, see +[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/). ## Debug Console @@ -77,6 +133,12 @@ in the Debug Console or by adjusting the `--repl-mode [mode]` argument to # Configuration Settings Reference +In order for `lldb-dap` to know how to start a debug session a launch or attach +configuration may be specified. Different IDEs may have different mechanisms in +place for configuring the launch configuration. + +For Visual Studio Code, see [Visual Studio Code's Debugging User Documentation](https://code.visualstudio.com/docs/debugtest/debugging). + ## Common configurations For both launch and attach configurations, lldb-dap accepts the following >From 112cb4c1da6669c67db84307101888c2db27126c Mon Sep 17 00:00:00 2001 From: John Harrison <[email protected]> Date: Thu, 18 Dec 2025 18:18:01 -0800 Subject: [PATCH 4/4] Fixing a spelling mistake. --- lldb/docs/resources/lldbdap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lldb/docs/resources/lldbdap.md b/lldb/docs/resources/lldbdap.md index a2056bb0f708b..b15a03ce524e9 100644 --- a/lldb/docs/resources/lldbdap.md +++ b/lldb/docs/resources/lldbdap.md @@ -127,7 +127,7 @@ 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 mode can ba adjusted using the `lldb-dap repl-mode` command +The auto-detection mode can be adjusted using the `lldb-dap repl-mode` command in the Debug Console or by adjusting the `--repl-mode [mode]` argument to `lldb-dap`. The supported modes are `variable`, `command` and `auto`. _______________________________________________ lldb-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
