[Lldb-commits] [lldb] [lldb-dap] Separate user and developer documentation (PR #92428)
via lldb-commits
lldb-commits at lists.llvm.org
Thu May 16 09:47:44 PDT 2024
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-lldb
Author: Jonas Devlieghere (JDevlieghere)
<details>
<summary>Changes</summary>
The README.md is what users see when they look for the extension in the Marketplace [1]. Right now, it's a mix of developer documentation (for us) and user documentation. This commit moves the developer docs into `docs` and the lldb website and refocuses the README on using the extension.
[1] https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap
---
Full diff: https://github.com/llvm/llvm-project/pull/92428.diff
3 Files Affected:
- (modified) lldb/docs/index.rst (+1)
- (added) lldb/docs/resources/lldbdap.md (+97)
- (modified) lldb/tools/lldb-dap/README.md (+21-135)
``````````diff
diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst
index 7a27f6914fa89..1e7d69002dd3e 100644
--- a/lldb/docs/index.rst
+++ b/lldb/docs/index.rst
@@ -161,6 +161,7 @@ interesting areas to contribute to lldb.
resources/lldbplatformpackets
resources/caveats
resources/projects
+ resources/lldbdap
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.md b/lldb/docs/resources/lldbdap.md
new file mode 100644
index 0000000000000..6c2252d77e55c
--- /dev/null
+++ b/lldb/docs/resources/lldbdap.md
@@ -0,0 +1,97 @@
+# LLDB-DAP
+
+The `lldb-dap` tool (formerly `lldb-vscode`) creates 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
+
+Installing the plug-in is very straightforward and involves just a few steps.
+
+### 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
+
+*Note: It's not necessary to update the extension if there has been changes
+to `lldb-dap`. The extension needs to be updated only if the TypesScript code
+has changed.*
+
+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
+```
diff --git a/lldb/tools/lldb-dap/README.md b/lldb/tools/lldb-dap/README.md
index 16ce4672be71c..8ecbaf7ce9816 100644
--- a/lldb/tools/lldb-dap/README.md
+++ b/lldb/tools/lldb-dap/README.md
@@ -1,133 +1,19 @@
+# LLDB DAP
-# Table of Contents
-
-- [Table of Contents](#table-of-contents)
-- [Introduction](#introduction)
-- [Local Installation for Visual Studio Code](#local-installation-for-visual-studio-code)
- - [Pre-requisites](#pre-requisites)
- - [Packaging and installation](#packaging-and-installation)
- - [Updating the extension](#updating-the-extension)
- - [Deploying for Visual Studio Code](#deploying-for-visual-studio-code)
-- [Formatting the Typescript code](#formatting-the-typescript-code)
-- [Configurations](#configurations)
- - [Launch Configuration Settings](#launch-configuration-settings)
- - [Attaching Settings](#attaching-settings)
- - [Example configurations](#example-configurations)
- - [Launching](#launching)
- - [Attach using PID](#attach-using-pid)
- - [Attach by Name](#attach-by-name)
- - [Loading a Core File](#loading-a-core-file)
- - [Connect to a Debug Server on the Current Machine](#connect-to-a-debug-server-on-the-current-machine)
- - [Connect to a Debug Server on Another Machine](#connect-to-a-debug-server-on-another-machine)
-- [Custom debugger commands](#custom-debugger-commands)
- - [startDebugging](#startdebugging)
- - [repl-mode](#repl-mode)
-
-# Introduction
-
-The `lldb-dap` tool (formerly `lldb-vscode`) creates 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.
+## `lldb-dap` Configurations
+
+The extension requires the `lldb-dap` (formerly `lldb-vscode`) binary. It is a
+command line tool that implements the [Debug Adapter
+Protocol](https://microsoft.github.io/debug-adapter-protocol/). It is used to power the Visual Studio Code extension but can also be used with other IDEs and editors that support 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
-
-Installing the plug-in is very straightforward and involves just a few steps.
-
-## 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
-
-*Note: It's not necessary to update the extension if there has been changes
-to `lldb-dap`. The extension needs to be updated only if the TypesScript code
-has changed.*
-
-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
-```
-
-# Configurations
+## Launching & Attaching Configuration
-Launching to attaching require you to create a [launch configuration](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations). This file
-defines arguments that get passed to `lldb-dap` and the configuration settings
-control how the launch or attach happens.
+Launching to attaching require you to create a [launch configuration](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations).
+This file defines arguments that get passed to `lldb-dap` and the configuration settings control how the launch or attach happens.
-## Launch Configuration Settings
+### Launch Configuration Settings
When you launch a program with Visual Studio Code you will need to create a [launch.json](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations)
file that defines how your program will be run. The JSON configuration file can contain the following `lldb-dap` specific launch key/value pairs:
@@ -151,7 +37,7 @@ file that defines how your program will be run. The JSON configuration file can
|**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.
|**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.
-## Attaching Settings
+### Attaching Settings
When attaching to a process using LLDB you can attach in a few ways
@@ -177,9 +63,9 @@ The JSON configuration file can contain the following `lldb-dap` specific launch
|**terminateCommands** |[string]| | LLDB commands executed when the debugging session ends. Commands and command output will be sent to the debugger console when they are executed.
|**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.
-## Example configurations
+### Example configurations
-### Launching
+#### Launching
This will launch `/tmp/a.out` with arguments `one`, `two`, and `three` and
adds `FOO=1` and `bar` to the environment:
@@ -195,7 +81,7 @@ adds `FOO=1` and `bar` to the environment:
}
```
-### Attach using PID
+#### Attach using PID
This will attach to a process `a.out` whose process ID is 123:
@@ -209,7 +95,7 @@ This will attach to a process `a.out` whose process ID is 123:
}
```
-### Attach by Name
+#### Attach by Name
This will attach to an existing process whose base
name matches `a.out`. All we have to do is leave the `pid` value out of the
@@ -240,7 +126,7 @@ to be launched you can add the "waitFor" key value pair:
This will work as long as the architecture, vendor and OS supports waiting
for processes. Currently MacOS is the only platform that supports this.
-### Loading a Core File
+#### Loading a Core File
This loads the coredump file `/cores/123.core` associated with the program
`/tmp/a.out`:
@@ -255,7 +141,7 @@ This loads the coredump file `/cores/123.core` associated with the program
}
```
-### Connect to a Debug Server on the Current Machine
+#### Connect to a Debug Server on the Current Machine
This connects to a debug server (e.g. `lldb-server`, `gdbserver`) on
the current machine, that is debugging the program `/tmp/a.out` and listening
@@ -271,7 +157,7 @@ locally on port `2345`.
}
```
-### Connect to a Debug Server on Another Machine
+#### Connect to a Debug Server on Another Machine
This connects to a debug server running on another machine with hostname
`hostnmame`. Which is debugging the program `/tmp/a.out` and listening on
@@ -287,12 +173,12 @@ port `5678` of that other machine.
}
```
-# Custom debugger commands
+## Custom debugger commands
The `lldb-dap` tool includes additional custom commands to support the Debug
Adapter Protocol features.
-## startDebugging
+### startDebugging
Using the command `lldb-dap startDebugging` it is possible to trigger a
reverse request to the client requesting a child debug session with the
@@ -317,7 +203,7 @@ This will launch a server and then request a child debug session for a client.
}
```
-## repl-mode
+### repl-mode
Inspect or adjust the behavior of lldb-dap repl evaluation requests. The
supported modes are `variable`, `command` and `auto`.
``````````
</details>
https://github.com/llvm/llvm-project/pull/92428
More information about the lldb-commits
mailing list