Add doc: Debugging with vscode (#142)

ckb-debugger/docs/debugging_contract_with_vscode.md

@@ -0,0 +1,139 @@
+# Debugging Contracts with VSCode
+
+The `ckb-debugger` provides a gdb-server mode for contract debugging. In VSCode, this requires the [Native Debug](https://marketplace.visualstudio.com/items?itemName=webfreak.debug) extension to connect to `ckb-debugger`'s gdb-server for debugging.
+* **Note:** While CodeLLDB supports remote debugging, it does not work well in this case due to its use of `LLDB` version 17.
+
+## Compile
+
+The compiled contract must include the appropriate symbol files for debugging. For C, add `-g`; for Rust, set `strip = false` and `debug = true` in the `profile` section. After compiling, since binaries with symbol files tend to be large, you need to process them with `llvm-objcopy`:
+
+```shell
+cp build/ckb-debug/<Contract-Name> build/ckb-debug/<Contract-Name>.debug
+llvm-objcopy --strip-debug --strip-all build/ckb-debug/<Contract-Name>
+```
+
+To configure `tasks.json` in VSCode (using the `c1` contract as an example):
+
+```json
+{
+    "label": "Build Debug",
+    "type": "shell",
+    "command": "make build && cp build/ckb-debug/c1 build/ckb-debug/c1.debug && llvm-objcopy --strip-debug --strip-all build/ckb-debug/c1"
+}
+```
+
+### Running `ckb-debugger`
+
+(Skip this section if the contract you're debugging doesn't require transaction information.)
+
+Typically, contracts require transaction data, which can be extracted from unit tests using the [dump_tx](https://github.com/nervosnetwork/ckb-testtool/blob/41c76ed2aef128fdf6e7e73b61d1bfa45e02b005/src/context.rs#L573) function. Add the following code before `context.verify_tx(&tx, MAX_CYCLES)` in your unit tests:
+
+```rust
+let tx_data = context.dump_tx(&tx).expect("dump tx info");
+std::fs::write(
+    "tx.json",
+    serde_json::to_string_pretty(&tx_data).expect("json"),
+).expect("write tx");
+```
+
+Then start `ckb-debugger` with:
+
+```shell
+ckb-debugger \
+    --bin=build/ckb-debug/c1 \
+    --mode=gdb_gdbstub \
+    --gdb-listen=0.0.0.0:8000 \
+    --tx-file=tests/tx.json \
+    -s=lock \
+    -i=0
+```
+
+* This example uses port 8000, but feel free to change it if needed.
+* Adjust `-s` and `-i` according to your contract’s requirements.
+
+You can configure `tasks.json` in VSCode to automatically start `ckb-debugger`:
+
+```json
+{
+    "label": "Debug c1",
+    "isBackground": true,
+    "type": "process",
+    "command": "ckb-debugger",
+    "args": [
+        "--bin=build/ckb-debug/c1",
+        "--mode=gdb_gdbstub",
+        "--gdb-listen=0.0.0.0:8000",
+        "--tx-file=tests/tx.json",
+        "-s=lock",
+        "-i=0"
+    ],
+    "options": {
+        "cwd": "${workspaceRoot}"
+    }
+}
+```
+* The `isBackground` setting ensures the task runs in the background and stays active during debugging.
+
+Since `ckb-debugger` doesn’t automatically exit after debugging, you'll need a task to stop it:
+
+```json
+{
+    "label": "stop-ckb-debugger",
+    "type": "shell",
+    "command": "killall ckb-debugger || true"
+}
+```
+
+### GDB Debugging
+
+```shell
+gdb build/ckb-debug/c1.debug
+```
+
+Then connect to `ckb-debugger`'s GDB server:
+
+```shell
+target remote 127.0.0.1:8000
+```
+
+Once connected, you can debug using standard GDB commands.
+
+### LLDB Debugging
+
+* Ensure you are using LLDB version 18 or later.
+
+```shell
+lldb build/ckb-debugger/c1.debug
+```
+
+Then connect to `ckb-debugger`'s GDB server (you can omit the local address and just use the port):
+
+```shell
+gdb-remote 8000
+```
+
+After connecting, use standard LLDB commands for debugging.
+
+### VSCode Debugging
+
+* GDB must be installed.
+* The Native Debug extension is required for debugging in VSCode.
+
+First, configure `tasks.json` as described above. Then set up your `launch.json` for debugging:
+
+```json
+{
+    "name": "GDB",
+    "type": "gdb",
+    "request": "attach",
+    "executable": "build/ckb-debug/c1.debug",
+    "debugger_args": [],
+    "cwd": "${workspaceRoot}",
+    "remote": true,
+    "target": "127.0.0.1:8000",
+    "preLaunchTask": "Debug c1",
+    "postDebugTask": "stop-ckb-debugger"
+}
+```
+
+After launching the debugger, you can set breakpoints and inspect variables as usual.