From 4b03abeed1819cef61cfa26fa802678ff2057707 Mon Sep 17 00:00:00 2001
From: Jonah Graham <jonah@kichwacoders.com>
Date: Wed, 18 Dec 2024 15:32:05 -0500
Subject: [PATCH] Document the way to debug cdt-gdb-adapter (#129)

Fixes https://github.com/eclipse-cdt-cloud/cdt-gdb-vscode/issues/121#issuecomment-2548283454
---
 README.md | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index c6bff63..69ccf75 100644
--- a/README.md
+++ b/README.md
@@ -47,4 +47,15 @@ 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.
+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.