Skip to content

Commit f861781

Browse files
author
Alex J Lennon
committed
docs(vscode): shared launch/tasks for remote debug via rsgdb
Add cppdbg configurations (gdb-multiarch, extended-remote) to localhost:3333, compound tasks to build rsgdb/board_test_app and start remote_ssh proxy, extensions recommendation. Document in board_test_app README, main README, CONTRIBUTING; allow tracking .vscode via gitignore exceptions. Made-with: Cursor
1 parent 43b0d7e commit f861781

7 files changed

Lines changed: 140 additions & 2 deletions

File tree

‎.gitignore‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,11 @@ examples/board_test_app/board_test_app
66
**/*.rs.bk
77
*.pdb
88

9-
# IDE
10-
.vscode/
9+
# IDE — keep shared debug configs; ignore local settings
10+
.vscode/*
11+
!.vscode/launch.json
12+
!.vscode/tasks.json
13+
!.vscode/extensions.json
1114
.idea/
1215
*.swp
1316
*.swo

‎.vscode/extensions.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"recommendations": ["ms-vscode.cpptools"]
3+
}

‎.vscode/launch.json‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"name": "rsgdb: board_test_app (build, start proxy, debug)",
6+
"type": "cppdbg",
7+
"request": "launch",
8+
"program": "${workspaceFolder}/examples/board_test_app/board_test_app",
9+
"args": [],
10+
"cwd": "${workspaceFolder}",
11+
"stopAtEntry": false,
12+
"MIMode": "gdb",
13+
"miDebuggerPath": "gdb-multiarch",
14+
"miDebuggerServerAddress": "127.0.0.1:3333",
15+
"useExtendedRemote": true,
16+
"preLaunchTask": "rsgdb: board_test_app (build + proxy)",
17+
"setupCommands": [
18+
{
19+
"text": "set debuginfod enabled off",
20+
"description": "Avoid batch hangs / noise when debuginfod is unavailable",
21+
"ignoreFailures": true
22+
}
23+
]
24+
},
25+
{
26+
"name": "rsgdb: board_test_app (proxy already running)",
27+
"type": "cppdbg",
28+
"request": "launch",
29+
"program": "${workspaceFolder}/examples/board_test_app/board_test_app",
30+
"args": [],
31+
"cwd": "${workspaceFolder}",
32+
"stopAtEntry": false,
33+
"MIMode": "gdb",
34+
"miDebuggerPath": "gdb-multiarch",
35+
"miDebuggerServerAddress": "127.0.0.1:3333",
36+
"useExtendedRemote": true,
37+
"setupCommands": [
38+
{
39+
"text": "set debuginfod enabled off",
40+
"description": "Avoid batch hangs / noise when debuginfod is unavailable",
41+
"ignoreFailures": true
42+
}
43+
]
44+
}
45+
]
46+
}

‎.vscode/tasks.json‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
{
2+
"version": "2.0.0",
3+
"tasks": [
4+
{
5+
"label": "rsgdb: ensure release binary",
6+
"type": "shell",
7+
"command": "test -x \"${workspaceFolder}/target/release/rsgdb\" || cargo build --release",
8+
"options": {
9+
"cwd": "${workspaceFolder}",
10+
"env": {}
11+
},
12+
"problemMatcher": [],
13+
"group": "build"
14+
},
15+
{
16+
"label": "board_test_app: make",
17+
"type": "shell",
18+
"command": "make",
19+
"options": {
20+
"cwd": "${workspaceFolder}/examples/board_test_app"
21+
},
22+
"problemMatcher": [],
23+
"group": "build"
24+
},
25+
{
26+
"label": "rsgdb: remote_ssh proxy",
27+
"type": "shell",
28+
"command": "\"${workspaceFolder}/target/release/rsgdb\"",
29+
"args": [
30+
"--config",
31+
"${workspaceFolder}/examples/board_test_app/rsgdb.remote.toml"
32+
],
33+
"options": {
34+
"cwd": "${workspaceFolder}"
35+
},
36+
"isBackground": true,
37+
"problemMatcher": {
38+
"owner": "rsgdb",
39+
"pattern": {
40+
"regexp": "^(.*)$",
41+
"file": 1,
42+
"location": 1,
43+
"message": 1
44+
},
45+
"background": {
46+
"activeOnStart": true,
47+
"beginsPattern": ".",
48+
"endsPattern": "Proxy server listening"
49+
}
50+
},
51+
"presentation": {
52+
"reveal": "silent",
53+
"panel": "dedicated"
54+
}
55+
},
56+
{
57+
"label": "rsgdb: board_test_app (build + proxy)",
58+
"dependsOn": [
59+
"rsgdb: ensure release binary",
60+
"board_test_app: make",
61+
"rsgdb: remote_ssh proxy"
62+
],
63+
"dependsOrder": "sequence"
64+
}
65+
]
66+
}

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ Use this when iterating on `src/protocol/codec.rs` or `tests/proxy_integration.r
7070

7171
### Phase B — GDB snippet + thread reply logging
7272

73+
- **VS Code / Cursor:** repo-root [`.vscode/launch.json`](.vscode/launch.json) and [`.vscode/tasks.json`](.vscode/tasks.json) attach **`gdb-multiarch`** to **`127.0.0.1:<rsgdb listen port>`** after starting **`rsgdb`** (see [`examples/board_test_app/README.md`](examples/board_test_app/README.md) § *Visual debug*). Requires the **C/C++** extension (`ms-vscode.cpptools`).
7374
- Copy or source [`scripts/gdbinit.rsgdb.example`](scripts/gdbinit.rsgdb.example) when connecting GDB through rsgdb (adjust `target extended-remote` to your listen port).
7475
- Backend **thread-related** RSP replies (`m…` / `l` / `QC…` / hex thread names) get short summaries at **`rsgdb::rtos`** (debug); packets are unchanged on the wire.
7576

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,8 @@ Enable thread-oriented logs with e.g. `RUST_LOG=rsgdb::rtos=debug,rsgdb=info` (o
228228

229229
This README, [CONTRIBUTING.md](CONTRIBUTING.md), [CHANGELOG.md](CHANGELOG.md), and [RELEASING.md](RELEASING.md) (maintainer release checklist). Design notes: [docs/ADR-001-breakpoints-semihosting.md](docs/ADR-001-breakpoints-semihosting.md) (breakpoint policy + semihosting spike).
230230

231+
**Visual debugging (VS Code / Cursor):** open the **repo root** as the workspace. Shared [`.vscode/launch.json`](.vscode/launch.json) and [`.vscode/tasks.json`](.vscode/tasks.json) drive **`rsgdb`** then attach **GDB** (`gdb-multiarch`) to **`127.0.0.1:<listen_port>`** — same RSP path as the CLI. See [`examples/board_test_app/README.md`](examples/board_test_app/README.md) § *Visual debug*.
232+
231233
## Releases
232234

233235
- **Development**: tagged pre-releases (e.g. **`v0.2.0-dev.1`**) are documented in [`CHANGELOG.md`](CHANGELOG.md); see [`RELEASING.md`](RELEASING.md) to cut the next tag.
@@ -306,6 +308,7 @@ RUST_LOG=debug cargo run
306308
rsgdb/
307309
├── src/ # Library + CLI
308310
├── tests/ # Integration tests
311+
├── .vscode/ # shared VS Code / Cursor: launch + tasks (board_test_app remote debug)
309312
├── examples/board_test_app/ # remote Linux target smoke (Makefile, rsgdb.remote.toml, helper scripts)
310313
├── CHANGELOG.md
311314
├── RELEASING.md

‎examples/board_test_app/README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,22 @@ gdb-multiarch -ex "set debuginfod enabled off" \
6262
-ex "target extended-remote 127.0.0.1:3333"
6363
```
6464

65+
### Visual debug (VS Code / Cursor)
66+
67+
Use the **repository root** as the workspace folder so `${workspaceFolder}` resolves correctly.
68+
69+
1. Install the **C/C++** extension (`ms-vscode.cpptools`) — Cursor/VS Code may prompt from [`.vscode/extensions.json`](../../.vscode/extensions.json).
70+
2. Install **`gdb-multiarch`** on the host (e.g. `sudo apt install gdb-multiarch`).
71+
3. **SSH**: same as above — keys or `RSGDB_SSH_PASSWORD` for non-interactive `scp`/`ssh`. For password auth, start VS Code from a shell where `RSGDB_SSH_PASSWORD` is exported, or rely on SSH keys.
72+
4. **Run and Debug**: pick **`rsgdb: board_test_app (build, start proxy, debug)`** — it runs tasks that:
73+
- build **`target/release/rsgdb`** if missing,
74+
- **`make`** the example ELF,
75+
- start **`rsgdb`** with [`rsgdb.remote.toml`](rsgdb.remote.toml) (waits until the proxy is listening on **127.0.0.1:3333**),
76+
- then attaches **GDB** to that port with **`useExtendedRemote`** (same path as manual GDB).
77+
5. If **`rsgdb` is already running** (e.g. you started it in a terminal), use **`rsgdb: board_test_app (proxy already running)`** so the preLaunch task is not started twice.
78+
79+
**Troubleshooting:** If something else holds **3333/tcp**, stop it or change **`listen_port`** in `rsgdb.remote.toml` and **`miDebuggerServerAddress`** / **`preLaunchTask`** references in [`.vscode/launch.json`](../../.vscode/launch.json). Only **one** GDB client should use the proxy at a time.
80+
6581
### Manual gdbserver on target
6682

6783
On the **target**:

0 commit comments

Comments
 (0)