[lldb] Update LLDB DAP documentation.#172580
Merged
Conversation
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.
Member
|
@llvm/pr-subscribers-lldb Author: John Harrison (ashgti) ChangesThis 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. Patch is 38.98 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/172580.diff 4 Files Affected:
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 atta...
[truncated]
|
Member
JDevlieghere
left a comment
JDevlieghere
left a comment
There was a problem hiding this comment.
I think this is a great start. I left some comments with the things that stood out, but they don't necessarily need to be addressed in this PR. I'm happy to merge something to get started and iterate with help from myself and anyone else that wants to help out.
lldb/docs/resources/lldbdap.md
Outdated
| ``` | ||
|
|
||
| ### Deploying for Visual Studio Code | ||
| Welcome to the `llb-dap` documentation! |
Member
There was a problem hiding this comment.
I know this is well intended, but I don' think this adds much and we don't welcome readers elsewhere either.
Contributor
Author
There was a problem hiding this comment.
I was mimicking the lldb homepage
llvm-project/lldb/docs/index.rst
Line 6 in 68e4a75
Member
There was a problem hiding this comment.
Right... If it were up to me I would remove that one too.
lldb/docs/resources/lldbdap.md
Outdated
| cp /path/to/a/built/liblldb.so ./bin/ | ||
| npm run package | ||
| ``` | ||
| ## Prerequisites |
Member
There was a problem hiding this comment.
Maybe this would be better framed as explaining that the lldb-dap binary is the implementation of the debug adapter, then go into how to procure it. If things are setup correctly, e.g. on macOS if they have Xcode or CLT, they may not even be aware of this binary.
DrSergei
reviewed
Dec 17, 2025
Contributor
DrSergei
left a comment
DrSergei
left a comment
There was a problem hiding this comment.
Thank you very much! Maybe we can add section how to debug lldb-dap and extension. I think it is not necessary, but might be useful for beginners.
Contributor
|
It seems there is no way to get to |
Contributor
Author
|
As an overview with this change:
|
Contributor
Author
|
@JDevlieghere Do I need to make any changes to the documentation generator for the adjustments to the generated html files? This does update index and list of linked files, but I haven't made any changes that include a new file. |
da-viper
approved these changes
Jan 6, 2026
Member
You should be all set. Including the page in the index is all it takes. |
JDevlieghere
approved these changes
Jan 6, 2026
Member
JDevlieghere
left a comment
JDevlieghere
left a comment
There was a problem hiding this comment.
LGTM. I still don't like the welcome thingy, but if everyone else does I won't stand in the way.
Contributor
Author
|
Removed the "welcome" first line. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This adds a new page to lldb.llvm.org that includes a user guide for lldb-dap.
The overall structure for documentation:
This is a first pass at the documentation, I expect to expand on it further as needed.