You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- First release to the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=eclipse-cdt.cdt-gdb-vscode) in addition to existing releases to the [Open VSX Registry](https://open-vsx.org/extension/eclipse-cdt/cdt-gdb-vscode).
See build instructions in the [developer documentation](./DEVELOPMENT.md). Further information on building, including CI information, download locations, etc can be found in the [Wiki](https://github.com/eclipse-cdt/cdt-infra/wiki).
This document provides instructions and hints for how to build and develop this extension. More information on contributions to this project can be found in the [contribution guidelines](/CONTRIBUTING.md).
4
+
5
+
## Building
6
+
7
+
### Building the extension
8
+
9
+
We use yarn to as our package manager. To build, simply do
10
+
11
+
```
12
+
yarn
13
+
yarn build
14
+
```
15
+
16
+
You can also run the build in watch mode using
17
+
18
+
```
19
+
yarn watch
20
+
```
21
+
22
+
### Co-developing cdt-gdb-adapter
23
+
24
+
If you are working on the cdt-gdb-adapter you can check it out to a different location and then link it in.
25
+
26
+
From the cdt-gdb-adapter project run
27
+
28
+
```
29
+
yarn link
30
+
```
31
+
32
+
Then from this project run
33
+
34
+
```
35
+
yarn link cdt-gdb-adapter
36
+
```
37
+
38
+
You can set up a VS Code workspace that has both folders. Also make sure you have builds running in each folder to pick up updates (e.g. `yarn watch`).
39
+
40
+
The way to debug cdt-gdb-adapter works with the same principle as the example Mock Debug Adapter provided by VSCode.
41
+
For detailed instructions please refer to [Development Setup for Mock Debug](https://code.visualstudio.com/api/extension-guides/debugger-extension#development-setup-for-mock-debug).
42
+
43
+
The short step-by-step version is:
44
+
45
+
1. Launch this extension with the `Extension` launch configuration ([cdt-gdb-vscode's launch.json](https://github.com/eclipse-cdt-cloud/cdt-gdb-vscode/blob/004a59f329136c2d5eb23e11e54b1f3f51b4d197/.vscode/launch.json#L8))
46
+
2. Launch cdt-gdb-adapter in server mode with either `Server` or `Server (Target adapter)` depending on whether you want to use local debugging or target debugging, corresponding to `"type": "gdb"` and `"type": "gdbtarget"` respectively. ([cdt-gdb-adapter's launch.json](https://github.com/eclipse-cdt-cloud/cdt-gdb-adapter/blob/92bb15046fea82256742a69f0b240129a1949a76/.vscode/launch.json#L4-L21))
47
+
3. Add a breakpoint somewhere useful, such as [`launchRequest`](https://github.com/eclipse-cdt-cloud/cdt-gdb-adapter/blob/6ba0de8e466f4953501181f53ecdfb14c7988973/src/desktop/GDBTargetDebugSession.ts#L94)
48
+
4. Add `"debugServer": 4711` to the launch configuration in the extension development host. The `4711` is the port number that cdt-gdb-adapter is listening on.
49
+
5. Debug the C/C++ program in the extension development host.
@@ -6,56 +6,117 @@ This is a Visual Studio Code extension that supports debugging using gdb and any
6
6
7
7
This extension provides a number of features that integrate into the Visual Studio Code debug environment. This includes launch types, support for the standard debug views as well as a custom viewer for memory browsing.
8
8
9
-
## Launch Settings
10
-
11
-
TODO
9
+
## Prerequisites
10
+
11
+
External tools are expected to be present on your system depending on the intended use case.
12
+
***Local GDB Debug**: A GDB installation is required on your system.
13
+
***Remote GDB Debug**: A GDB installation is required on your system. In addition to that you must have either access to a running GDB server instance (`attach` use case), or a suitable GDB server variant must be installed to `launch` and connect to your debug target.
14
+
15
+
## Launch Configurations
16
+
17
+
The Visual Studio Debug Extension for GDB contributes two debugger types:
18
+
*`gdb`: Support for **Local GDB Debug**. Launch or attach to an already running application locally on your host machine using GDB.
19
+
*`gdbtarget`: Support for **Remote GDB Debug**. Launch or attach to an already running remote GDB server using GDB.
20
+
21
+
Both come as `launch` and `attach` request types, each with a sophisticated set of configuration settings.
22
+
23
+
### `gdb` Type
24
+
25
+
Launch and attach configuration settings that can be used with the `gdb` debugger type for local GDB debug.
26
+
27
+
| Setting |`launch`|`attach`| Type | Description |
28
+
|:---|:---:|:---:|:---:|:---|
29
+
|`gdb`| x | x |`string`| Path to GDB. This can be an absolute path or the name of an executable on your PATH environment variable.<br>Default: `gdb`|
30
+
|`cwd`| x | x |`string`| Current working directory for launching GDB.<br>Default: Directory of the debugged `program`. |
31
+
|`environment`| x | x |`object`| Environment variables to use when launching GDB, defined as a key-value pairs. Use `null` value to remove variable.<br>Example:<pre>\"environment\": {<br> \"VARNAME\": \"value\",<br> \"PATH\": \"/new/item:${env:PATH}\",<br> \"REMOVEME\": null<br>}</pre> |
32
+
|`program`| x | x |`string`| Path to the program to be debugged. For `launch` requests, this program is also launched.<br>Default: `${workspaceFolder}/${command:askProgramPath}`, which allows to interactively enter the full program path. |
33
+
|`arguments`| x ||`string`| Arguments for the program. |
34
+
|`processId`|| x |`string`| Process ID to attach to. |
35
+
|`gdbAsync`| x | x |`boolean`| Use `mi-async` mode for communication with GDB. Always `true` if `gdbNonStop` is `true`.<br>Default: `true`|
36
+
|`gdbNonStop`| x | x |`boolean`| Use `non-stop` mode for controlling multiple threads.<br> Default: `false`|
37
+
|`verbose`| x | x |`boolean`| Produce verbose log output. |
38
+
|`logFile`| x | x |`string`| Absolute path to the file to log interaction with GDB.|
39
+
|`openGdbConsole`| x | x |`boolean`|*(UNIX-only)* Open a GDB console in your IDE while debugging. |
40
+
|`initCommands`| x | x |`string[]`| List of GDB commands sent before attaching to inferior. |
41
+
42
+
43
+
### `gdbtarget` Type
44
+
45
+
Launch and attach configuration settings that can be used with the `gdbtarget` debugger type for remote GDB debug connections.
46
+
47
+
| Setting |`launch`|`attach`| Type | Description |
48
+
|:---|:---:|:---:|:---:|:---|
49
+
|`gdb`| x | x |`string`| Path to GDB. This can be an absolute path or the name of an executable on your PATH environment variable.<br>Default: `gdb`|
50
+
|`cwd`| x | x |`string`| Current working directory for launching GDB.<br>Default: Directory of the debugged `program`. |
51
+
|`environment`| x | x |`object`| Environment variables to use when launching GDB, defined as a key-value pairs. Use `null` value to remove variable.<br>Example:<pre>\"environment\": {<br> \"VARNAME\": \"value\",<br> \"PATH\": \"/new/item:${env:PATH}\",<br> \"REMOVEME\": null<br>}</pre> |
52
+
|`program`| x | x |`string`| Path to the program to be debugged. For `launch` requests, this program is also launched.<br>Default: `${workspaceFolder}/${command:askProgramPath}`, which allows to interactively enter the full program path.<br>**Note**: While `program` is marked as required, the debug adapter launches anyway for remote GDB connections. For example to inspect an embedded target system's memory and other hardware resources without debugging a program. |
53
+
|`gdbAsync`| x | x |`boolean`| Use `mi-async` mode for communication with GDB. Always `true` if `gdbNonStop` is `true`.<br>Default: `true`|
54
+
|`gdbNonStop`| x | x |`boolean`| Use `non-stop` mode for controlling multiple threads.<br> Default: `false`|
55
+
|`verbose`| x | x |`boolean`| Produce verbose log output. |
56
+
|`logFile`| x | x |`string`| Absolute path to the file to log interaction with GDB.|
57
+
|`openGdbConsole`| x | x |`boolean`|*(UNIX-only)* Open a GDB console in your IDE while debugging. |
58
+
|`initCommands`| x | x |`string[]`| List of GDB commands sent before attaching to inferior. |
59
+
|`preRunCommands`| x | x |`string[]`| List of GDB commands sent after loading image on target before resuming target. |
60
+
| `imageAndSymbols` | x | x | `object` | Additional settings for loading images to the target and symbols into the debugger. See section "`imageAndSymbols` object" for details.
61
+
|`target`| x | x |`object`| Additional settings to configure the remote GDB target. See section "`target` object" for details. |
62
+
63
+
#### `imageAndSymbols` object
64
+
65
+
Additional settings for loading images to the target and symbols into the debugger. This object can be used in `launch` and `attach` configurations for the `gdbtarget` debugger type for remote GDB connections.
66
+
67
+
| Setting |`launch`|`attach`| Type | Description |
68
+
|:---|:---:|:---:|:---:|:---|
69
+
|`symbolFileName`| x | x |`string`| If specified, a symbol file to load at the given (optional) offset. Also see `symbolOffset`. |
70
+
|`symbolOffset`| x | x |`string`| If `symbolFileName` is specified, the offset added to symbol addresses when loaded. |
71
+
|`imageFileName`| x | x |`string`| If specified, an image file to load at the given (optional) offset. Also see `imageOffset`. |
72
+
|`imageOffset`| x | x |`string`| If `imageFileName` is specified, the offset used to load the image. |
73
+
74
+
#### `target` object
75
+
76
+
Additional settings for loading images to the target and symbols into the debugger. This object can be used in `launch` and `attach` configurations for the `gdbtarget` debugger type for remote GDB connections.
77
+
78
+
| Setting |`launch`|`attach`| Type | Description |
79
+
|:---|:---:|:---:|:---:|:---|
80
+
|`type`| x | x |`string`| The kind of target debugging to do. This is passed to `-target-select`.<br>Default: `remote`|
81
+
|`parameters`| x | x |`string[]`| Target parameters for the type of target. Normally something like `localhost:12345`.<br>Default: `${host}:${port}`. |
82
+
|`host`| x | x |`string`| Target host to connect to. Ignored if `parameters` is set.<br>Default: `localhost`|
83
+
|`port`| x | x |`string`| Target port to connect to. Ignored if `parameters` is set.<br>Default: Value captured by `serverPortRegExp`, otherwise defaults to `2331`|
84
+
|`cwd`| x ||`string`| Specifies the working directory of the server.<br>Default: Working directory of GDB |
85
+
|`environment`| x ||`object`| Environment variables to use when launching server, defined as key-value pairs. Defaults to the environment used to launch GDB. Use `null` value to remove variable.<br>Example:<pre>\"environment\": {<br> \"VARNAME\": \"value\",<br> \"PATH\": \"/new/item:${env:PATH}\",<br> \"REMOVEME\": null<br>}</pre> |
86
+
|`server`| x ||`string`| The executable for the target server to launch (e.g. `gdbserver` or `JLinkGDBServerCLExe`). This can be an absolute path or the name of an executable on your PATH environment variable.<br>Default: `gdbserver`|
87
+
|`serverParameters`| x ||`string[]`| Command line arguments passed to server.<br>Default: `--once :0 ${args.program}`|
88
+
|`serverPortRegExp`| x ||`string`| Regular expression to extract `port` from by examining stdout/stderr of the GDB server. Once the server is launched, `port` will be set to this if unspecified. Defaults to matching a string like `Listening on port 41551` which is what `gdbserver` provides. Ignored if `port` or `parameters` is set. |
89
+
|`serverStartupDelay`| x ||`number`| Delay, in milliseconds, after startup but before continuing launch. If `serverPortRegExp` is provided, it is the delay after that regexp is seen. |
90
+
|`automaticallyKillServer`| x ||`boolean`| Automatically terminate the launched server when client issues a disconnect.<br>Default: `true`|
91
+
|`uart`| x | x |`object`| Settings related to displaying UART output in the debug console. |
92
+
93
+
##### `uart` object
94
+
95
+
Settings related to displaying UART output in the debug console. This object can be used in the `target` object of `launch` and `attach` configurations for the `gdbtarget` debugger type for remote GDB connections.
96
+
97
+
| Setting |`launch`|`attach`| Type | Description |
98
+
|:---|:---:|:---:|:---:|:---|
99
+
|`serialPort`| x | x |`string`| Path to the serial port connected to the UART on the board. |
100
+
|`socketPort`| x | x |`string`| Target TCP port on the host machine to attach socket to print UART output.<br>Default: `3456`|
101
+
|`baudRate`| x | x |`number`| Baud Rate (in bits/s) of the serial port to be opened.<br>Default: `115200`.|
102
+
|`characterSize`| x | x |`number`| The number of bits in each character of data sent across the serial line.<br>Supported values: `5`, `6`, `7`, `8`<br>Default: `8`|
103
+
|`parity`| x | x |`string`| The type of parity check enabled with the transmitted data.<br>Supported values: `none`, `odd`, `even`, `mark`, `space`<br>Default: `none` - no parity bit sent |
104
+
|`stopBits`| x | x |`number`| The number of stop bits sent to allow the receiver to detect the end of characters and resynchronize with the character stream.<br>Supported values: `1`, `1.5`, `2`<br>Default: `1`|
105
+
|`handshakingMethod`| x | x |`string`| The handshaking method used for flow control across the serial line.<br>Supported values: `none`, `XON/XOFF`, `RTS/CTS`<br>Default: `none` - no handshaking |
106
+
|`eolCharacter`| x | x |`string`| The EOL character used to parse the UART output line-by-line.<br>Supported values: `LF`, `CRLF`<br>Default: `LF`|
12
107
13
108
## Memory Browser
14
109
15
-
TODO
16
-
17
-
## Building
18
-
19
-
### Building the extension
20
-
21
-
We use yarn to as our package manager. To build, simply do
22
-
23
-
```
24
-
yarn
25
-
yarn build
26
-
```
27
-
28
-
You can also run the build in watch mode using
29
-
30
-
```
31
-
yarn watch
32
-
```
33
-
34
-
### Co-developing cdt-gdb-adapter
35
-
36
-
If you are working on the cdt-gdb-adapter you can check it out to a different location and then link it in.
37
-
38
-
From the cdt-gdb-adapter project run
39
-
40
-
```
41
-
yarn link
42
-
```
110
+
The extension comes with a Memory Browser window. However, we have plans to deprecate and remove the window in favour of the Eclipse CDT Cloud [Memory Inspector](https://github.com/eclipse-cdt-cloud/vscode-memory-inspector) extension for Visual Studio Code which is available from the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=eclipse-cdt.memory-inspector) and the [Open VSX Registry](https://open-vsx.org/extension/eclipse-cdt/memory-inspector).
43
111
44
-
Then from this project run
112
+
Any feedback on these plans is welcomed in the discussion in GitHub issue [#110](https://github.com/eclipse-cdt-cloud/cdt-gdb-vscode/issues/110).
45
113
46
-
```
47
-
yarn link cdt-gdb-adapter
48
-
```
114
+
## Contributions
49
115
50
-
You can set up a VS Code workspace that has both folders. Also make sure you have builds running in each folder to pick up updates (e.g. `yarn watch`).
116
+
We welcome any feedback and contributions on [GitHub](https://github.com/eclipse-cdt-cloud/cdt-gdb-vscode).
51
117
52
-
The way to debug cdt-gdb-adapter works with the same principle as the example Mock Debug Adapter provided by VSCode.
53
-
For detailed instructions please refer to [Development Setup for Mock Debug](https://code.visualstudio.com/api/extension-guides/debugger-extension#development-setup-for-mock-debug).
118
+
Please raise [GitHub issues](https://github.com/eclipse-cdt-cloud/cdt-gdb-vscode/issues/new?template=Blank+issue) to submit feedback, defect reports, and enhancement requests.
54
119
55
-
The short step-by-step version is:
120
+
Check our [contribution guidelines](./CONTRIBUTING.md) for more information on how to contribute changes. And our [developer documentation](./DEVELOPMENT.md) for how to build and develop the extension.
56
121
57
-
1. Launch this extension with the `Extension` launch configuration ([cdt-gdb-vscode's launch.json](https://github.com/eclipse-cdt-cloud/cdt-gdb-vscode/blob/004a59f329136c2d5eb23e11e54b1f3f51b4d197/.vscode/launch.json#L8))
58
-
2. Launch cdt-gdb-adapter in server mode with either `Server` or `Server (Target adapter)` depending on whether you want to use local debugging or target debugging, corresponding to `"type": "gdb"` and `"type": "gdbtarget"` respectively. ([cdt-gdb-adapter's launch.json](https://github.com/eclipse-cdt-cloud/cdt-gdb-adapter/blob/92bb15046fea82256742a69f0b240129a1949a76/.vscode/launch.json#L4-L21))
59
-
3. Add a breakpoint somewhere useful, such as [`launchRequest`](https://github.com/eclipse-cdt-cloud/cdt-gdb-adapter/blob/6ba0de8e466f4953501181f53ecdfb14c7988973/src/desktop/GDBTargetDebugSession.ts#L94)
60
-
4. Add `"debugServer": 4711` to the launch configuration in the extension development host. The `4711` is the port number that cdt-gdb-adapter is listening on.
61
-
5. Debug the C/C++ program in the extension development host.
122
+
This open-source project is part of [Eclipse CDT Cloud](https://eclipse.dev/cdt-cloud/).
Copy file name to clipboardExpand all lines: package.json
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -384,7 +384,7 @@
384
384
},
385
385
"serverPortRegExp": {
386
386
"type": "string",
387
-
"description": "Regular expression to extract port from by examinging stdout/err of server. Once server is launched, port will be set to this if port is not set. Defaults to matching a string like 'Listening on port 41551' which is what gdbserver provides. Ignored if port or parameters is set",
387
+
"description": "Regular expression to extract port from by examining stdout/err of server. Once server is launched, port will be set to this if port is not set. Defaults to matching a string like 'Listening on port 41551' which is what gdbserver provides. Ignored if port or parameters is set",
0 commit comments