add vscode debug example

.gitignore

@@ -56,6 +56,7 @@ build
 .config
 .config.old
 .config.mk
+!assets/vscode_*_debug/.vscode
 
 # python
 *.pyc

README.md

@@ -261,6 +261,31 @@ node demo1.js
 By default we can use `python project.py run` to call [tools/run.py](./tools/run.py) file, and execute the binary file.
 If you want to add commands for your SDK, just create new `py` file in tools directory, write a script and content refer to [tools/run.py](./tools/run.py).
 
+## Online Debugging
+
+### VSCode + GDB Online Debugging
+
+Here take PC with Linux system as an example:
+
+* Add `c_cpp_project_framework` (recommended for the first trial) or project directory to VSCode workspace
+* Copy the [./assets/vscode_local_debug/.vscode](./assets/vscode_local_debug/.vscode) directory to the working directory of the previous step
+* Edit the `cwd` field in `.vscode/launch.json` according to whether `.vscode` is under `c_cpp_project_framework` or under the project directory
+* Press F5 on the keyboard to start debugging
+> Windows is similar, just modify the relevant commands and paths in `.vscode`
+
+### VSCode + gdbserver Debugging on Embedded Device (/Remote Device with Linux System)
+
+Here take PC with Linux system as an example:
+
+* Firstly, Ensure that the remote device has the `gdbserver` program, and the PC has the `gdb-multiarch` program
+* Copy the [./assets/vscode_remote_debug/.vscode](./assets/vscode_remote_debug/.vscode) directory to the project directory
+* Edit the `launch.json` and `build_run_gdbserver.sh` files, modify the paths and commands inside, as well as the username, etc.
+> It is recommended to add the PC's ssh key to the `~/.ssh/authorized_keys` file of the remote device first, so you don't need to enter a password.
+* The `build_run_gdbserver.sh` script needs to be executed every time you debug, and then press F5 in VSCode to start debugging
+> The script will compile the project, then copy the executable file to the remote device, and start `gdbserver`.
+> Press F5 to start debugging, VSCode uses GDB to connect to `gdbserver` on the remote device for debugging.
+
+
 ## License
 
 **MIT**， see [LICENSE](./LICENSE)

README_ZH.md

@@ -36,6 +36,7 @@ C CPP Project Framework (Template)
 * 交叉编译友好, 很好地作为嵌入式设备 `SDK`
 * 生成各种 `IDE` 可以直接使用的工程文件, 可以方便地导入到各种 `IDE` 中使用
 * 支持编译成 `WASM`（Web Assembly）
+* 支持 VSCode + GDB 在线调试（PC 或者嵌入式设备均支持）
 
 
 ## 快速上手
@@ -171,7 +172,7 @@ python3 project.py menuconfig
 python3 project.py build
 ```
 
-## 调试版本和发布版本
+## 调试 (Debug) 版本和发布 (Release) 版本
 
 默认都是以 debug 版本编译，如果要发布版本，可以使用以下命令：
 ```shell
@@ -258,6 +259,30 @@ node demo1.js
 比如默认使用 `python project.py run` 命令会调用`tools/run.py`脚本来执行构建出来的可执行文件。
 如果你需要给你的 SDK 增加命令，只需要创建一个新的文件，参考[tools/run.py](./tools/run.py)文件的写法即可
 
+## 在线调试
+
+### VSCode + GDB 在线调试
+
+这里以 PC 为 Linux 系统为例：
+
+* 添加 c_cpp_project_framework（第一次试用推荐这样） 或者 工程目录到 VSCode 工作区
+* 拷贝 [./assets/vscode_local_debug/.vscode](./assets/vscode_local_debug/.vscode) 目录到上一步的工作目录下
+* 根据`.vscode`是在 c_cpp_project_framework 还是在工程目录下，修改`.vscode/launch.json`中的`cwd`字段
+* 按键盘 `F5` 即可开始调试
+> windows 也类似，修改`.vscode`里面的相关命令和路径即可
+
+### VSCode + gdbserver 在嵌入式设备（/远程设备，带 Linux 系统）调试
+
+这里以 PC 为 Linux 系统为例：
+
+* 先保证远程设备有`gdbserver`这个程序，以及 PC 有`gdb-multiarch`这个程序
+* 将 [./assets/vscode_remote_debug/.vscode](./assets/vscode_remote_debug/.vscode) 目录拷贝到工程目录下
+* 编辑 `launch.json` 和 `build_run_gdbserver.sh` 文件，修改里面的路径和命令，以及用户名等。
+> 建议先将 PC 的 ssh key 加入到远程设备的 `~/.ssh/authorized_keys` 文件中，这样就不需要输入密码了。
+* 每次调试需要执行 `build_run_gdbserver.sh` 脚本，然后在 VSCode 中按 `F5` 即可开始调试
+> 脚本会编译工程，然后拷贝可执行文件到远程设备，并且启动 `gdbserver`。
+> 按 F5 启动调试时， VSCode 使用 GDB 连接到远程设备的`gdbserver`以调试。
+
 
 ## 开源许可
 

assets/vscode_local_debug/.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+    // 使用 IntelliSense 了解相关属性。 
+    // 悬停以查看现有属性的描述。
+    // 欲了解更多信息，请访问: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug",
+            "type": "gdb",
+            "request": "launch",
+            "preLaunchTask": "rebuild",
+            "target": "build/demo1",
+            "cwd": "${workspaceRoot}/examples/demo1",
+            "valuesFormatting": "parseText"
+        }
+    ]
+}

assets/vscode_local_debug/.vscode/tasks.json

@@ -0,0 +1,24 @@
+{
+    "tasks": [
+        {
+            "type": "shell",
+            "label": "rebuild",
+            "command": "python",
+            "args": [
+                "project.py",
+                "rebuild"
+            ],
+            "options": {
+                "cwd": "${workspaceRoot}/examples/demo1"
+            },
+            "problemMatcher": [
+                "$gcc"
+            ],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        }
+    ],
+    "version": "2.0.0"
+}

assets/vscode_remote_debug/.vscode/build_run_gdbserver.sh

@@ -0,0 +1,30 @@
+#/bin/bash
+
+set -e
+
+##################### config #####################
+project_path=$(pwd)/../examples/demo1
+program_path=${project_path}/build/demo1
+target_ip=rock-5b.local
+target_port=9000
+target_user=root
+##################################################
+
+## build first
+cd ${project_path}
+# python project.py --toolchain "" --toolchain-prefix aarch64-linux-gnu- config
+python project.py rebuild
+
+# kill gdbserver first if it is running
+ssh ${target_user}@${target_ip} "killall gdbserver > /dev/null 2>&1 || true"
+
+## copy to target
+scp ${program_path} ${target_user}@${target_ip}:~/dbg_program.bin
+
+## run gdbserver
+ssh ${target_user}@${target_ip} "gdbserver :${target_port} ~/dbg_program.bin"
+
+
+## now you can run debug in vscode
+
+

assets/vscode_remote_debug/.vscode/launch.json

@@ -0,0 +1,20 @@
+{
+    // 使用 IntelliSense 了解相关属性。 
+    // 悬停以查看现有属性的描述。
+    // 欲了解更多信息，请访问: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug Program On Remote",
+            "type": "gdb",
+            "request": "attach",
+            "gdbpath":"gdb-multiarch",
+            "executable": "${workspaceRoot}/examples/demo1/build/demo1",
+            "target": "rock-5b.local:9000",
+            "remote": true,
+            "printCalls": true,
+            "cwd": "${workspaceRoot}/examples/demo1",
+            "valuesFormatting": "parseText",
+        }
+    ]
+}