lldb/docs/resources/lldbdap.md

   1 # Contributing to LLDB-DAP
   2
   3 This guide describes how to extend and contribute to lldb-dap.
   4 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).
   5
   6 lldb-dap and LLDB are developed under the umbrella of the
   7 [LLVM project](https://llvm.org/). As such, the
   8 "[Getting Started with the LLVM System](https://llvm.org/docs/GettingStarted.html)",
   9 "[Contributing to LLVM](https://llvm.org/docs/Contributing.html)" and
  10 "[LLVM coding standard](https://llvm.org/docs/CodingStandards.html)"
  11 guides might also be relevant, if you are a first-time contributor to the LLVM
  12 project.
  13
  14 lldb-dap's source code is [part of the LLVM
  15 repository](https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-dap)
  16 on Github. We use Github's [issue
  17 tracker](https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-dap)
  18 and patches can be submitted via [pull
  19 requests](https://github.com/llvm/llvm-project/pulls).
  20
  21 ## Building `lldb-dap` from soruce
  22
  23 To build lldb-dap from source, first need to [setup a LLDB build](https://lldb.llvm.org/resources/build.html).
  24 After doing so, run `ninja lldb-dap`. To use your freshly built `lldb-dap`
  25 binary, install the VS Code extension and point it to lldb-dap by setting the
  26 `lldb-dap.executable-path` setting.
  27
  28 ## Responsibilities of LLDB, lldb-dap and the Visual Studio Code Extension
  29
  30 Under the hood, the UI-based debugging experience is fueled by three separate
  31 components:
  32
  33 * LLDB provides general, IDE-indepedent debugging features, such as:
  34   loading binaries / core dumps, interpreting debug info, setting breakpoints,
  35   pretty-printing variables, etc. The `lldb` binary exposes this functionality
  36   via a command line interface.
  37 * `lldb-dap` exposes LLDB's functionality via the
  38   "[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)",
  39   i.e. a protocol through which various IDEs (VS Code, Emacs, vim, neovim, ...)
  40   can interact with a wide range of debuggers (`lldb-dap` and many others).
  41 * The VS Code extension exposes the lldb-dap binary within VS Code. It acts
  42   as a thin wrapper around the lldb-dap binary, and adds VS-Code-specific UI
  43   integration on top of lldb-dap, such as autocompletion for `launch.json`
  44   configuration files.
  45
  46 Since lldb-dap builds on top of LLDB, all of LLDB's extensibility mechanisms
  47 such as [Variable Pretty-Printing](https://lldb.llvm.org/use/variable.html),
  48 [Frame recognizers](https://lldb.llvm.org/use/python-reference.html#writing-lldb-frame-recognizers-in-python)
  49 and [Python Scripting](https://lldb.llvm.org/use/python.html) are available
  50 also in lldb-dap.
  51
  52 When adding new functionality, you generally want to add it on the lowest
  53 applicable level. I.e., quite frequently you actually want to add functionality
  54 to LLDB's core in order to improve your debugging experience in VS Code.
  55
  56 ### The Debug Adapter Protocol
  57
  58 The most relevant resources for the Debug Adapter Protocol are:
  59 * [The overview](https://microsoft.github.io/debug-adapter-protocol/overview)
  60   which provides a high-level introduction,
  61 * the [human-readable specification](https://microsoft.github.io/debug-adapter-protocol/specification), and
  62 * the [JSON-schema specification](https://github.com/microsoft/debug-adapter-protocol/blob/main/debugAdapterProtocol.json).
  63
  64 lldb-dap adds some additional non-standard extensions to the protocol. To take
  65 advantage of those extensions, IDE-specific support code is needed, usually
  66 inside the VS Code extension. When adding a new extension, please first look
  67 through the [issue tracker of the Debug Adapter
  68 Protocol](https://github.com/microsoft/debug-adapter-protocol/issues) to check
  69 if there already is a proposal serving your use case. If so, try to take
  70 inspiration from it. If not, consider opening an upstream issue.
  71
  72 To avoid naming collisions with potential future extensions of the Debug
  73 Adapter protocol, all non-standard extensions should use the prefix
  74 `$__lldb_extension` in their JSON property names.
  75
  76 ### Debugging the Debug Adapter Protocol
  77
  78 To debug the Debug Adapter Protocol, point the `LLDBDAP_LOG` environment
  79 variable to a file on your disk. lldb-dap will log all communication received
  80 from / sent to the IDE to the provided path. In the VS Code extension, you
  81 can also set the log path through the `lldb-dap.log-path` VS Code setting.
  82
  83 ## Building the VS Code extension from source
  84
  85 Installing the plug-in is very straightforward and involves just a few steps.
  86
  87 In most cases, installing the VS Code extension from the [VS Code
  88 Marketplace](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap)
  89 and pointing it to a locally built lldb-dap binary is sufficient. Building
  90 the VS Code extension from source is only necessary if the TypeScript code is
  91 changed.
  92
  93 ### Pre-requisites
  94
  95 - Install a modern version of node (e.g. `v20.0.0`).
  96 - On VS Code, execute the command `Install 'code' command in PATH`. You need to
  97   do it only once. This enables the command `code` in the PATH.
  98
  99 ### Packaging and installation
 100
 101 ```bash
 102 cd /path/to/lldb/tools/lldb-dap
 103 npm install
 104 npm run package # This also compiles the extension.
 105 npm run vscode-install
 106 ```
 107
 108 On VS Code, set the setting `lldb-dap.executable-path` to the path of your local
 109 build of `lldb-dap`.
 110
 111 And then you are ready!
 112
 113 ### Updating the extension
 114
 115 Updating the extension is pretty much the same process as installing it from
 116 scratch. However, VS Code expects the version number of the upgraded extension
 117 to be greater than the previous one, otherwise the installation step might have
 118 no effect.
 119
 120 ```bash
 121 # Bump version in package.json
 122 cd /path/to/lldb/tools/lldb-dap
 123 npm install
 124 npm run package
 125 npm run vscode-install
 126 ```
 127
 128 Another way upgrade without bumping the extension version is to first uninstall
 129 the extension, then reload VS Code, and then install it again. This is
 130 an unfortunate limitation of the editor.
 131
 132 ```bash
 133 cd /path/to/lldb/tools/lldb-dap
 134 npm run vscode-uninstall
 135 # Then reload VS Code: reopen the IDE or execute the `Developer: Reload Window`
 136 # command.
 137 npm run package
 138 npm run vscode-install
 139 ```
 140
 141 ### Deploying for Visual Studio Code
 142
 143 The easiest way to deploy the extension for execution on other machines requires
 144 copying `lldb-dap` and its dependencies into a`./bin` subfolder and then create a
 145 standalone VSIX package.
 146
 147 ```bash
 148 cd /path/to/lldb/tools/lldb-dap
 149 mkdir -p ./bin
 150 cp /path/to/a/built/lldb-dap ./bin/
 151 cp /path/to/a/built/liblldb.so ./bin/
 152 npm run package
 153 ```
 154
 155 This will produce the file `./out/lldb-dap.vsix` that can be distributed. In
 156 this type of installation, users don't need to manually set the path to
 157 `lldb-dap`. The extension will automatically look for it in the `./bin`
 158 subfolder.
 159
 160 *Note: It's not possible to use symlinks to `lldb-dap`, as the packaging tool
 161 forcefully performs a deep copy of all symlinks.*
 162
 163 *Note: It's possible to use this kind flow for local installations, but it's
 164 not recommended because updating `lldb-dap` requires rebuilding the extension.*
 165
 166 ## Formatting the Typescript code
 167
 168 This is also very simple, just run:
 169
 170 ```bash
 171 npm run format
 172 ```