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.

lldb-dap and LLDB are developed under the umbrella of the LLVM project. As such, the “Getting Started with the LLVM System”, “Contributing to LLVM” and “LLVM coding standard” 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 on Github. We use Github’s issue tracker and patches can be submitted via pull requests.

Building `lldb-dap` from soruce#

To build lldb-dap from source, first need to setup a LLDB build. 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”, 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, Frame recognizers and Python Scripting 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 which provides a high-level introduction,
the human-readable specification, and
the JSON-schema specification.

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 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 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#

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.

# 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.

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.

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:

npm run format