diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..904b698 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,7 @@ +# Change Log + +## Unreleased +- 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). +- Updated extension logo. +- Updated user and repository documentation. +- Updated extension dependencies. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 46b8c24..aa15a12 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,9 +13,7 @@ the gdb support in the Eclipse C/C++ IDE (CDT). ## Build Instructions -See build instructions in the [Readme](README.md#building). Further information on building, -including CI information, download locations, etc can be found in the -[Wiki](https://github.com/eclipse-cdt/cdt-infra/wiki) +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). ## Eclipse Contributor Agreement diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..e722e02 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,49 @@ +# Developing the VS Code Debug Extension for GDB + +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). + +## Building + +### Building the extension + +We use yarn to as our package manager. To build, simply do + +``` +yarn +yarn build +``` + +You can also run the build in watch mode using + +``` +yarn watch +``` + +### Co-developing cdt-gdb-adapter + +If you are working on the cdt-gdb-adapter you can check it out to a different location and then link it in. + +From the cdt-gdb-adapter project run + +``` +yarn link +``` + +Then from this project run + +``` +yarn link cdt-gdb-adapter +``` + +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`). + +The way to debug cdt-gdb-adapter works with the same principle as the example Mock Debug Adapter provided by VSCode. +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). + +The short step-by-step version is: + +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)) +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)) +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) +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. +5. Debug the C/C++ program in the extension development host. diff --git a/README.md b/README.md index 69ccf75..65b619f 100644 --- a/README.md +++ b/README.md @@ -6,56 +6,117 @@ This is a Visual Studio Code extension that supports debugging using gdb and any 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. -## Launch Settings - -TODO +## Prerequisites + +External tools are expected to be present on your system depending on the intended use case. +* **Local GDB Debug**: A GDB installation is required on your system. +* **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. + +## Launch Configurations + +The Visual Studio Debug Extension for GDB contributes two debugger types: +* `gdb`: Support for **Local GDB Debug**. Launch or attach to an already running application locally on your host machine using GDB. +* `gdbtarget`: Support for **Remote GDB Debug**. Launch or attach to an already running remote GDB server using GDB. + +Both come as `launch` and `attach` request types, each with a sophisticated set of configuration settings. + +### `gdb` Type + +Launch and attach configuration settings that can be used with the `gdb` debugger type for local GDB debug. + +| Setting | `launch` | `attach` | Type | Description | +|:---|:---:|:---:|:---:|:---| +| `gdb` | x | x | `string` | Path to GDB. This can be an absolute path or the name of an executable on your PATH environment variable.
Default: `gdb` | +| `cwd` | x | x | `string` | Current working directory for launching GDB.
Default: Directory of the debugged `program`. | +| `environment` | x | x | `object` | Environment variables to use when launching GDB, defined as a key-value pairs. Use `null` value to remove variable.
Example:
\"environment\": {
  \"VARNAME\": \"value\",
  \"PATH\": \"/new/item:${env:PATH}\",
  \"REMOVEME\": null
}
| +| `program` | x | x | `string` | Path to the program to be debugged. For `launch` requests, this program is also launched.
Default: `${workspaceFolder}/${command:askProgramPath}`, which allows to interactively enter the full program path. | +| `arguments` | x | | `string` | Arguments for the program. | +| `processId` | | x | `string` | Process ID to attach to. | +| `gdbAsync` | x | x | `boolean` | Use `mi-async` mode for communication with GDB. Always `true` if `gdbNonStop` is `true`.
Default: `true` | +| `gdbNonStop` | x | x | `boolean` | Use `non-stop` mode for controlling multiple threads.
Default: `false` | +| `verbose` | x | x | `boolean` | Produce verbose log output. | +| `logFile` | x | x | `string` | Absolute path to the file to log interaction with GDB.| +| `openGdbConsole` | x | x | `boolean` | *(UNIX-only)* Open a GDB console in your IDE while debugging. | +| `initCommands` | x | x | `string[]` | List of GDB commands sent before attaching to inferior. | + + +### `gdbtarget` Type + +Launch and attach configuration settings that can be used with the `gdbtarget` debugger type for remote GDB debug connections. + +| Setting | `launch` | `attach` | Type | Description | +|:---|:---:|:---:|:---:|:---| +| `gdb` | x | x | `string` | Path to GDB. This can be an absolute path or the name of an executable on your PATH environment variable.
Default: `gdb` | +| `cwd` | x | x | `string` | Current working directory for launching GDB.
Default: Directory of the debugged `program`. | +| `environment` | x | x | `object` | Environment variables to use when launching GDB, defined as a key-value pairs. Use `null` value to remove variable.
Example:
\"environment\": {
  \"VARNAME\": \"value\",
  \"PATH\": \"/new/item:${env:PATH}\",
  \"REMOVEME\": null
}
| +| `program` | x | x | `string` | Path to the program to be debugged. For `launch` requests, this program is also launched.
Default: `${workspaceFolder}/${command:askProgramPath}`, which allows to interactively enter the full program path.
**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. | +| `gdbAsync` | x | x | `boolean` | Use `mi-async` mode for communication with GDB. Always `true` if `gdbNonStop` is `true`.
Default: `true` | +| `gdbNonStop` | x | x | `boolean` | Use `non-stop` mode for controlling multiple threads.
Default: `false` | +| `verbose` | x | x | `boolean` | Produce verbose log output. | +| `logFile` | x | x | `string` | Absolute path to the file to log interaction with GDB.| +| `openGdbConsole` | x | x | `boolean` | *(UNIX-only)* Open a GDB console in your IDE while debugging. | +| `initCommands` | x | x | `string[]` | List of GDB commands sent before attaching to inferior. | +| `preRunCommands` | x | x | `string[]` | List of GDB commands sent after loading image on target before resuming target. | +| `imageAndSymbols` | x | x | `object` | Additional settings for loading images to the target and symbols into the debugger. See section "`imageAndSymbols` object" for details. +| `target` | x | x | `object` | Additional settings to configure the remote GDB target. See section "`target` object" for details. | + +#### `imageAndSymbols` object + +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. + +| Setting | `launch` | `attach` | Type | Description | +|:---|:---:|:---:|:---:|:---| +| `symbolFileName` | x | x | `string` | If specified, a symbol file to load at the given (optional) offset. Also see `symbolOffset`. | +| `symbolOffset` | x | x | `string` | If `symbolFileName` is specified, the offset added to symbol addresses when loaded. | +| `imageFileName` | x | x | `string` | If specified, an image file to load at the given (optional) offset. Also see `imageOffset`. | +| `imageOffset` | x | x | `string` | If `imageFileName` is specified, the offset used to load the image. | + +#### `target` object + +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. + +| Setting | `launch` | `attach` | Type | Description | +|:---|:---:|:---:|:---:|:---| +| `type` | x | x | `string` | The kind of target debugging to do. This is passed to `-target-select`.
Default: `remote` | +| `parameters` | x | x | `string[]`| Target parameters for the type of target. Normally something like `localhost:12345`.
Default: `${host}:${port}`. | +| `host` | x | x | `string` | Target host to connect to. Ignored if `parameters` is set.
Default: `localhost` | +| `port` | x | x | `string` | Target port to connect to. Ignored if `parameters` is set.
Default: Value captured by `serverPortRegExp`, otherwise defaults to `2331` | +| `cwd` | x | | `string` | Specifies the working directory of the server.
Default: Working directory of GDB | +| `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.
Example:
\"environment\": {
  \"VARNAME\": \"value\",
  \"PATH\": \"/new/item:${env:PATH}\",
  \"REMOVEME\": null
}
| +| `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.
Default: `gdbserver` | +| `serverParameters` | x | | `string[]` | Command line arguments passed to server.
Default: `--once :0 ${args.program}` | +| `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. | +| `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. | +| `automaticallyKillServer` | x | | `boolean` | Automatically terminate the launched server when client issues a disconnect.
Default: `true` | +| `uart` | x | x | `object` | Settings related to displaying UART output in the debug console. | + +##### `uart` object + +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. + +| Setting | `launch` | `attach` | Type | Description | +|:---|:---:|:---:|:---:|:---| +| `serialPort` | x | x | `string` | Path to the serial port connected to the UART on the board. | +| `socketPort` | x | x | `string` | Target TCP port on the host machine to attach socket to print UART output.
Default: `3456` | +| `baudRate` | x | x | `number` | Baud Rate (in bits/s) of the serial port to be opened.
Default: `115200`.| +| `characterSize` | x | x | `number` | The number of bits in each character of data sent across the serial line.
Supported values: `5`, `6`, `7`, `8`
Default: `8` | +| `parity` | x | x | `string` | The type of parity check enabled with the transmitted data.
Supported values: `none`, `odd`, `even`, `mark`, `space`
Default: `none` - no parity bit sent | +| `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.
Supported values: `1`, `1.5`, `2`
Default: `1` | +| `handshakingMethod` | x | x | `string` | The handshaking method used for flow control across the serial line.
Supported values: `none`, `XON/XOFF`, `RTS/CTS`
Default: `none` - no handshaking | +| `eolCharacter` | x | x | `string` | The EOL character used to parse the UART output line-by-line.
Supported values: `LF`, `CRLF`
Default: `LF` | ## Memory Browser -TODO - -## Building - -### Building the extension - -We use yarn to as our package manager. To build, simply do - -``` -yarn -yarn build -``` - -You can also run the build in watch mode using - -``` -yarn watch -``` - -### Co-developing cdt-gdb-adapter - -If you are working on the cdt-gdb-adapter you can check it out to a different location and then link it in. - -From the cdt-gdb-adapter project run - -``` -yarn link -``` +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). -Then from this project run +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). -``` -yarn link cdt-gdb-adapter -``` +## Contributions -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`). +We welcome any feedback and contributions on [GitHub](https://github.com/eclipse-cdt-cloud/cdt-gdb-vscode). -The way to debug cdt-gdb-adapter works with the same principle as the example Mock Debug Adapter provided by VSCode. -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). +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. -The short step-by-step version is: +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. -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)) -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)) -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) -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. -5. Debug the C/C++ program in the extension development host. +This open-source project is part of [Eclipse CDT Cloud](https://eclipse.dev/cdt-cloud/). diff --git a/package.json b/package.json index 7f73d51..3b5a7da 100644 --- a/package.json +++ b/package.json @@ -384,7 +384,7 @@ }, "serverPortRegExp": { "type": "string", - "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", + "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", "default": "" }, "serverStartupDelay": {