================ @@ -1,16 +1,95 @@ -# LLDB-DAP - -The `lldb-dap` tool (formerly `lldb-vscode`) is a command line tool that -implements the [Debug Adapter -Protocol](https://microsoft.github.io/debug-adapter-protocol/). It can be -installed as an extension for Visual Studio Code and other IDEs supporting DAP. -The protocol is easy to run remotely and also can allow other tools and IDEs to -get a full featured debugger with a well defined protocol. - -## Local Installation for Visual Studio Code +# 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/release/19.x/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). + +Sometimes, lldb-dap also adds proprietary extensions to the protocol. To take +advantage of those proprietary protocol 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 proprietary extensions should use the prefix ---------------- ashgti wrote:
ditto https://github.com/llvm/llvm-project/pull/110987 _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
