Skip to content

Commit 525bd66

Browse files
JDevlieghereJDevlieghere
authored
[lldb-dap] Separate user and developer documentation (#92428)
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
1 parent 0dc80e4 commit 525bd66

File tree

3 files changed

+119
-135
lines changed

3 files changed

+119
-135
lines changed

‎lldb/docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,7 @@ interesting areas to contribute to lldb.
161161
resources/lldbplatformpackets
162162
resources/caveats
163163
resources/projects
164+
resources/lldbdap
164165
Public C++ API <https://lldb.llvm.org/cpp_reference/namespacelldb.html>
165166
Private C++ API <https://lldb.llvm.org/cpp_reference/index.html>
166167

‎lldb/docs/resources/lldbdap.md

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# LLDB-DAP
2+
3+
The `lldb-dap` tool (formerly `lldb-vscode`) is a command line tool that
4+
implements the [Debug Adapter
5+
Protocol](https://microsoft.github.io/debug-adapter-protocol/). It can be
6+
installed as an extension for Visual Studio Code and other IDEs supporting DAP.
7+
The protocol is easy to run remotely and also can allow other tools and IDEs to
8+
get a full featured debugger with a well defined protocol.
9+
10+
## Local Installation for Visual Studio Code
11+
12+
Installing the plug-in is very straightforward and involves just a few steps.
13+
14+
### Pre-requisites
15+
16+
- Install a modern version of node (e.g. `v20.0.0`).
17+
- On VS Code, execute the command `Install 'code' command in PATH`. You need to
18+
do it only once. This enables the command `code` in the PATH.
19+
20+
### Packaging and installation
21+
22+
```bash
23+
cd /path/to/lldb/tools/lldb-dap
24+
npm install
25+
npm run package # This also compiles the extension.
26+
npm run vscode-install
27+
```
28+
29+
On VS Code, set the setting `lldb-dap.executable-path` to the path of your local
30+
build of `lldb-dap`.
31+
32+
And then you are ready!
33+
34+
### Updating the extension
35+
36+
*Note: It's not necessary to update the extension if there has been changes
37+
to `lldb-dap`. The extension needs to be updated only if the TypesScript code
38+
has changed.*
39+
40+
Updating the extension is pretty much the same process as installing it from
41+
scratch. However, VS Code expects the version number of the upgraded extension
42+
to be greater than the previous one, otherwise the installation step might have
43+
no effect.
44+
45+
```bash
46+
# Bump version in package.json
47+
cd /path/to/lldb/tools/lldb-dap
48+
npm install
49+
npm run package
50+
npm run vscode-install
51+
```
52+
53+
Another way upgrade without bumping the extension version is to first uninstall
54+
the extension, then reload VS Code, and then install it again. This is
55+
an unfortunate limitation of the editor.
56+
57+
```bash
58+
cd /path/to/lldb/tools/lldb-dap
59+
npm run vscode-uninstall
60+
# Then reload VS Code: reopen the IDE or execute the `Developer: Reload Window`
61+
# command.
62+
npm run package
63+
npm run vscode-install
64+
```
65+
66+
### Deploying for Visual Studio Code
67+
68+
The easiest way to deploy the extension for execution on other machines requires
69+
copying `lldb-dap` and its dependencies into a`./bin` subfolder and then create a
70+
standalone VSIX package.
71+
72+
```bash
73+
cd /path/to/lldb/tools/lldb-dap
74+
mkdir -p ./bin
75+
cp /path/to/a/built/lldb-dap ./bin/
76+
cp /path/to/a/built/liblldb.so ./bin/
77+
npm run package
78+
```
79+
80+
This will produce the file `./out/lldb-dap.vsix` that can be distributed. In
81+
this type of installation, users don't need to manually set the path to
82+
`lldb-dap`. The extension will automatically look for it in the `./bin`
83+
subfolder.
84+
85+
*Note: It's not possible to use symlinks to `lldb-dap`, as the packaging tool
86+
forcefully performs a deep copy of all symlinks.*
87+
88+
*Note: It's possible to use this kind flow for local installations, but it's
89+
not recommended because updating `lldb-dap` requires rebuilding the extension.*
90+
91+
## Formatting the Typescript code
92+
93+
This is also very simple, just run:
94+
95+
```bash
96+
npm run format
97+
```

‎lldb/tools/lldb-dap/README.md

Lines changed: 21 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,133 +1,19 @@
1+
# LLDB DAP
12

2-
# Table of Contents
3-
4-
- [Table of Contents](#table-of-contents)
5-
- [Introduction](#introduction)
6-
- [Local Installation for Visual Studio Code](#local-installation-for-visual-studio-code)
7-
- [Pre-requisites](#pre-requisites)
8-
- [Packaging and installation](#packaging-and-installation)
9-
- [Updating the extension](#updating-the-extension)
10-
- [Deploying for Visual Studio Code](#deploying-for-visual-studio-code)
11-
- [Formatting the Typescript code](#formatting-the-typescript-code)
12-
- [Configurations](#configurations)
13-
- [Launch Configuration Settings](#launch-configuration-settings)
14-
- [Attaching Settings](#attaching-settings)
15-
- [Example configurations](#example-configurations)
16-
- [Launching](#launching)
17-
- [Attach using PID](#attach-using-pid)
18-
- [Attach by Name](#attach-by-name)
19-
- [Loading a Core File](#loading-a-core-file)
20-
- [Connect to a Debug Server on the Current Machine](#connect-to-a-debug-server-on-the-current-machine)
21-
- [Connect to a Debug Server on Another Machine](#connect-to-a-debug-server-on-another-machine)
22-
- [Custom debugger commands](#custom-debugger-commands)
23-
- [startDebugging](#startdebugging)
24-
- [repl-mode](#repl-mode)
25-
26-
# Introduction
27-
28-
The `lldb-dap` tool (formerly `lldb-vscode`) creates a command line tool that
29-
implements the [Debug Adapter
30-
Protocol](https://microsoft.github.io/debug-adapter-protocol/). It can be
31-
installed as an extension for Visual Studio Code and other IDEs supporting DAP.
3+
## `lldb-dap` Configurations
4+
5+
The extension requires the `lldb-dap` (formerly `lldb-vscode`) binary. It is a
6+
command line tool that implements the [Debug Adapter
7+
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.
328
The protocol is easy to run remotely and also can allow other tools and IDEs to
339
get a full featured debugger with a well defined protocol.
3410

35-
# Local Installation for Visual Studio Code
36-
37-
Installing the plug-in is very straightforward and involves just a few steps.
38-
39-
## Pre-requisites
40-
41-
- Install a modern version of node (e.g. `v20.0.0`).
42-
- On VS Code, execute the command `Install 'code' command in PATH`. You need to
43-
do it only once. This enables the command `code` in the PATH.
44-
45-
## Packaging and installation
46-
47-
```bash
48-
cd /path/to/lldb/tools/lldb-dap
49-
npm install
50-
npm run package # This also compiles the extension.
51-
npm run vscode-install
52-
```
53-
54-
On VS Code, set the setting `lldb-dap.executable-path` to the path of your local
55-
build of `lldb-dap`.
56-
57-
And then you are ready!
58-
59-
## Updating the extension
60-
61-
*Note: It's not necessary to update the extension if there has been changes
62-
to `lldb-dap`. The extension needs to be updated only if the TypesScript code
63-
has changed.*
64-
65-
Updating the extension is pretty much the same process as installing it from
66-
scratch. However, VS Code expects the version number of the upgraded extension
67-
to be greater than the previous one, otherwise the installation step might have
68-
no effect.
69-
70-
```bash
71-
# Bump version in package.json
72-
cd /path/to/lldb/tools/lldb-dap
73-
npm install
74-
npm run package
75-
npm run vscode-install
76-
```
77-
78-
Another way upgrade without bumping the extension version is to first uninstall
79-
the extension, then reload VS Code, and then install it again. This is
80-
an unfortunate limitation of the editor.
81-
82-
```bash
83-
cd /path/to/lldb/tools/lldb-dap
84-
npm run vscode-uninstall
85-
# Then reload VS Code: reopen the IDE or execute the `Developer: Reload Window`
86-
# command.
87-
npm run package
88-
npm run vscode-install
89-
```
90-
91-
## Deploying for Visual Studio Code
92-
93-
The easiest way to deploy the extension for execution on other machines requires
94-
copying `lldb-dap` and its dependencies into a`./bin` subfolder and then create a
95-
standalone VSIX package.
96-
97-
```bash
98-
cd /path/to/lldb/tools/lldb-dap
99-
mkdir -p ./bin
100-
cp /path/to/a/built/lldb-dap ./bin/
101-
cp /path/to/a/built/liblldb.so ./bin/
102-
npm run package
103-
```
104-
105-
This will produce the file `./out/lldb-dap.vsix` that can be distributed. In
106-
this type of installation, users don't need to manually set the path to
107-
`lldb-dap`. The extension will automatically look for it in the `./bin`
108-
subfolder.
109-
110-
*Note: It's not possible to use symlinks to `lldb-dap`, as the packaging tool
111-
forcefully performs a deep copy of all symlinks.*
112-
113-
*Note: It's possible to use this kind flow for local installations, but it's
114-
not recommended because updating `lldb-dap` requires rebuilding the extension.*
115-
116-
# Formatting the Typescript code
117-
118-
This is also very simple, just run:
119-
120-
```bash
121-
npm run format
122-
```
123-
124-
# Configurations
11+
## Launching & Attaching Configuration
12512

126-
Launching to attaching require you to create a [launch configuration](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations). This file
127-
defines arguments that get passed to `lldb-dap` and the configuration settings
128-
control how the launch or attach happens.
13+
Launching to attaching require you to create a [launch configuration](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations).
14+
This file defines arguments that get passed to `lldb-dap` and the configuration settings control how the launch or attach happens.
12915

130-
## Launch Configuration Settings
16+
### Launch Configuration Settings
13117

13218
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)
13319
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
15137
|**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.
15238
|**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.
15339

154-
## Attaching Settings
40+
### Attaching Settings
15541

15642
When attaching to a process using LLDB you can attach in a few ways
15743

@@ -177,9 +63,9 @@ The JSON configuration file can contain the following `lldb-dap` specific launch
17763
|**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.
17864
|**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.
17965

180-
## Example configurations
66+
### Example configurations
18167

182-
### Launching
68+
#### Launching
18369

18470
This will launch `/tmp/a.out` with arguments `one`, `two`, and `three` and
18571
adds `FOO=1` and `bar` to the environment:
@@ -195,7 +81,7 @@ adds `FOO=1` and `bar` to the environment:
19581
}
19682
```
19783

198-
### Attach using PID
84+
#### Attach using PID
19985

20086
This will attach to a process `a.out` whose process ID is 123:
20187

@@ -209,7 +95,7 @@ This will attach to a process `a.out` whose process ID is 123:
20995
}
21096
```
21197

212-
### Attach by Name
98+
#### Attach by Name
21399

214100
This will attach to an existing process whose base
215101
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:
240126
This will work as long as the architecture, vendor and OS supports waiting
241127
for processes. Currently MacOS is the only platform that supports this.
242128

243-
### Loading a Core File
129+
#### Loading a Core File
244130

245131
This loads the coredump file `/cores/123.core` associated with the program
246132
`/tmp/a.out`:
@@ -255,7 +141,7 @@ This loads the coredump file `/cores/123.core` associated with the program
255141
}
256142
```
257143

258-
### Connect to a Debug Server on the Current Machine
144+
#### Connect to a Debug Server on the Current Machine
259145

260146
This connects to a debug server (e.g. `lldb-server`, `gdbserver`) on
261147
the current machine, that is debugging the program `/tmp/a.out` and listening
@@ -271,7 +157,7 @@ locally on port `2345`.
271157
}
272158
```
273159

274-
### Connect to a Debug Server on Another Machine
160+
#### Connect to a Debug Server on Another Machine
275161

276162
This connects to a debug server running on another machine with hostname
277163
`hostnmame`. Which is debugging the program `/tmp/a.out` and listening on
@@ -287,12 +173,12 @@ port `5678` of that other machine.
287173
}
288174
```
289175

290-
# Custom debugger commands
176+
## Custom debugger commands
291177

292178
The `lldb-dap` tool includes additional custom commands to support the Debug
293179
Adapter Protocol features.
294180

295-
## startDebugging
181+
### startDebugging
296182

297183
Using the command `lldb-dap startDebugging` it is possible to trigger a
298184
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.
317203
}
318204
```
319205

320-
## repl-mode
206+
### repl-mode
321207

322208
Inspect or adjust the behavior of lldb-dap repl evaluation requests. The
323209
supported modes are `variable`, `command` and `auto`.

0 commit comments

Comments
 (0)