RT-Thread-vscode插件 - RT-Thread Studio项目助手 | 跨平台开发RT-Thread问答社区

vscode插件 - RT-Thread Studio项目助手 | 跨平台开发

发布于 2025-01-02 21:46:17 浏览：96 订阅该版

[tocm]

大家好，我是一枚RT-Thread、Typescript爱好者。

用了RT-Thread三四年了，更多的时候由于目标芯片的FLASH限制用的是Nano版，手动写makefile、vscode配置。

用了esp-idf的vscode扩展，不禁赞叹它的强大：下载框架、构建、下载、终端、串口监视、调试、代码覆盖率测试...

也在RT-Thread Studio使用RT-Thread标准版，可是在这个大模型时代，怎么能不用AI辅助编码呢？用过env+vscode，奈何scons虐我千百遍，于是利用业余时间搓了一个小助手。

# RT-Thread Studio项目助手

> 本扩展适用于使用RT-Thread Studio新建或导入的项目（或使用`scons --dist-ide --target=eclipse`生成然后使用RT-Thread Studio导入的），可生成vscode的代码浏览、编辑、编译、下载、调试的配置文件。

## 快速开始

1. 使用RT-Thread Studio新建或导入的项目，在RT-Thread Studio构建一次

2. 在vscode中安装并启用本扩展（`jswyll.jswyll-vscode-rtthread`），依赖的扩展会被自动安装。

3. 打开项目根目录（`.cproject`文件的所在文件夹），点击状态栏的“导入”按钮

![1735660800001.png](https://oss-club.rt-thread.org/uploads/20250102/043b6c2058f1852249ce874f7470f7cf.png.webp)

4. 根据配置面板提示填写相关信息

点击“RT-Thread Studio路径”右方的打开文件按钮，选择RT-Thread Studio安装路径（`studio.exe`的所在文件夹）

根据情况选择调试器类型及其接口

点击“生成”按钮

![1735660800002.gif](https://oss-club.rt-thread.org/uploads/20250102/11cfa28b30b20f36f3bf44cbc188e8d4.gif)

5. 点击状态栏的“构建并下载”按钮（或按快捷键`Ctrl+Shift+B`）

![1735660800003.gif](https://oss-club.rt-thread.org/uploads/20250102/e7bb409cbcff8b00654a6eff19bd70c3.gif)

## 软件特性

- 解析项目信息，生成vscode的配置文件：

- 可视化：通过配置向导面板进行输入或选择参数。从环境变量`PATH`中寻找可用的GCC编译器；Windows环境下选择RT-Thread Studio路径后，自动寻找GCC编译器路径、Make工具路径、调试器服务器等以供选择

- 代码浏览：生成C/C++浏览配置（`.vscode/c_cpp_properties.json`）的宏定义、头文件（搜索）路径；根据排除路径生成vscode资源管理器排除规则（`files.exclude`）。

- 程序编译：

- 多进程编译加快速度；如果make的主版本号大于4，添加`--output-sync=target`避免不同文件的编译报错混淆。

- 屏蔽编译和链接的一长串参数输出，并添加形如Keil IDE的编译与链接提示：

```sh
      compiling ../rt-thread/src/clock.c...
      compiling ../rt-thread/src/components.c...
      compiling ../rt-thread/src/device.c...
      compiling ../applications/main.c...
      linking ...
      arm-none-eabi-objcopy -O binary "rtthread.elf"  "rtthread.bin"
      arm-none-eabi-size --format=berkeley "rtthread.elf"
      text    data     bss     dec     hex filename
      55400    1468    3368   60236    eb4c rtthread.elf
      ```

- 提供更准确的问题匹配器，避免在问题面板打开出错文件跳转失败

- 下载程序：调试服务器类型支持Segger JLink、PyOCD、OpenOCD（前两个Windows环境下RT-Thread Studio已经内置），调试器类型支持常用的JLink、ST-Link、CMSIS-DAP。

- 调试程序：调试所支持的调试器类型和下载程序的一样；生成[Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug)扩展的调试启动配置。

![1735660800004.png](https://oss-club.rt-thread.org/uploads/20250102/b8b86d3979478f07c56e7c8b8d0c1542.png.webp)

- [跨平台开发](#其它平台)：已在Windows、MacOS（10.13和15.2）、Linux（Ubuntu 24.04）上测试通过。

- [检查中断函数](https://github.com/jswyll/jswyll-vscode-rtthread/blob/HEAD/中断检查)：检查形如`void xxx_IRQHandler(void)`的函数是否调用了`rt_interrupt_enter()`和`rt_interrupt_leave()`。

- 国际化：支持简体中文和英文。

## 操作说明

vscode支持[多根工作区](https://code.visualstudio.com/docs/editor/multi-root-workspaces)，可以在一个工作区中同时打开多个工程。

本扩展兼容多根工作区。如果打开的是多根工作区且有多个根文件夹，将弹出工作区文件夹的选择器：

![1735660800005.png](https://oss-club.rt-thread.org/uploads/20250102/9905e3b37f6046c046c700d166e54406.png.webp)

后续的操作都将基于该文件夹，相关的配置文件会保存在该工作区文件夹。可以通过点击状态栏的子模块图标来再次切换。

> **说明**
>
> 以下所提到的“工作区文件夹”都是指已选择的根文件夹。如果打开的是单个文件夹或多根工作区下只有一个根文件夹，“工作区文件夹”就是指这个文件夹。

### 扩展激活

启用扩展后，当工作区文件夹中（第一级）有`.cproject`文件时，扩展会自动激活。

### 导入项目

点击状态里的“导入”（生成）来生成vscode的配置文件。

> **说明**
>
> - 重复导入应该是没有副作用的，需要修改或更新选项的时候可以再导入。
>
> - 项目可以是已经移动的（不在RT-Thread Studio workspace文件夹中的）。

#### 面板选项

- **构建配置**：在RT-Thread Studio项目中创建的构建配置。如果只有一个则无需选择。必要项。

- **RT-Thread Studio路径**：你的RT-Thread Studio安装路径（`studio.exe`的所在文件夹）。目前仅用于推导可能的工具位置以供选择。非Windows平台没有这个选项。非必要项。

- **GCC编译器路径**：用于C/C++扩展分析代码、编译程序。必要项。

可以直接选择RT-Thread Studio内置的5.4.1和10.3.1的arm-none-eabi两个版本：

![1735660800006.png](https://oss-club.rt-thread.org/uploads/20250102/2161f211bd45748b0aad79ebe7be6a65.png.webp)

对于ARM架构的芯片，可以前往<https://developer.arm.com/downloads/-/gnu-rm>下载特定的版本。

- **Make工具路径**：用于构建项目。非必要项（如果你只想浏览代码）。

可以选择RT-Thread Studio内置的`platform/env_released/env/tools/BuildTools/2.12-20190422-1053/bin`。Windows平台可以前往<https://github.com/skeeto/w64devkit/releases>下载命令更丰富的开发包。

- **调试服务器**：支持OpenOCD、JLink或PyOCD。非必要项（如果你不需要在vscode下载、调试程序）。

![1735660800007.png](https://oss-club.rt-thread.org/uploads/20250102/0fd5d67a97daf60c20094a4161371cc3.png.webp)

- Segger JLink：可以选择RT-Thread Studio内置的v7.50a，RT-Thread Studio v2.2.8以上还可以选v7.92（推荐）。或者，前往<https://www.segger.com/downloads/jlink>下载特定的版本。特点是：快！

![1735660800008.png](https://oss-club.rt-thread.org/uploads/20250102/bf96186c71bf3c592d0a30ea9b85d7c1.png.webp)

![1735660800009.png](https://oss-club.rt-thread.org/uploads/20250102/db81f82266e87f354e0d7ba8ae672266.png.webp)

- PyOCD：可以选择RT-Thread Studio内置的v0.1.3。但经测试它不支持我的JLink，可以参考<https://pyocd.io/docs/installing>安装最新的新版本（Windows平台pip安装的pyocd可能需要拷贝libusb.dll到python根目录才可用），新版本对ST-Link、JLink和CMSIS-DAP调试器都支持。

除非是[PyOCD内置目标](https://pyocd.io/docs/builtin-targets.html)，否则需要填写Cmsis包。可以输入关键词然后选择RT-Thread Studio内置的。

![1735660800010.png](https://oss-club.rt-thread.org/uploads/20250102/6c6987670d9ab203b247bda45cb137c7.png.webp)

- OpenOCD：可以前往<https://github.com/xpack-dev-tools/openocd-xpack/releases>下载，对于Windows还可以前往<https://gnutoolchains.com/arm-eabi/openocd/>下载包含的额外驱动软件的。支持ST-Link、JLink和CMSIS-DAP。特点是：很多芯片厂商都支持。

![1735660800011.png](https://oss-club.rt-thread.org/uploads/20250102/b9c0d767c12ba5f6394969f29e8dd9ae.png.webp)

> **说明**
    >
    > Windows平台选择OpenOCD调试服务器且使用JLink调试器时，需要使用<https://gnutoolchains.com/arm-eabi/openocd/>里的`UsbDriverTool.exe`或[zadig](https://zadig.akeo.ie/)把JLink驱动更换为libusb：
    >
    > ![1735660800012.gif](https://oss-club.rt-thread.org/uploads/20250102/622cbfb446d0fa9488b72114ca0c514c.gif)
    >
    > 修改驱动后在MDK IDE就不能使用JLink下载了，可以使用<https://gnutoolchains.com/arm-eabi/openocd/>里的`UsbDriverTool.exe`把驱动恢复为JLlink驱动：
    >
    > ![1735660800013.gif](https://oss-club.rt-thread.org/uploads/20250102/3e15618316a18265e77f936cb5f4fd67.gif)

- **芯片名称**：用于下载程序时让调试器识别出对应的FLASH大小。一般来说保持不变即可。对于STM32，应至少精确到11位字符，例如`STM32L431CC`。

> **说明**
>
> 以上的**xxx路径**选项，你可以通过右方的打开文件图标按钮来选择，可以选择提示的选项，还可以手动输入，见[路径规则](#路径规则)。

#### 开始生成

填写参数的过程中会校验输入是否有效。对于错误，根据提示检查并更正。

![1735660800014.png](https://oss-club.rt-thread.org/uploads/20250102/68cc570b751f43448d574480581b2e7a.png.webp)

对于警告，点击“生成”时会弹窗提示，如果确定可以点击“忽略”按钮。

![1735660800015.png](https://oss-club.rt-thread.org/uploads/20250102/d19c8ffc78d445297b6fa523a69c3038.png.webp)

![1735660800016.png](https://oss-club.rt-thread.org/uploads/20250102/823a1619ebdb467df86fc6d6c38bce21.png.webp)

点击“生成”按钮，开始校验并生成配置文件。如果生成成功，配置面板将自动关闭。

对于JLink，会添加hex输出（这是因为：旧版本RT-Thread Studio内置的`J-Link/v7.50a`不支持解析elf文件）。

> **注意**
>
> 切换编译器版本后（在本扩展的配置面板选择的GCC版本和RT-Thread Studio的不一样，或前后两次在本扩展的配置面板选择GCC版本不一样，先后编译），应重新编译，以消除编译器版本差异引发不可预料的结果。

### 构建项目

可以点击状态栏的图标`清除`、`构建`、`下载`或`构建并下载`来执行构建任务。

也可以在菜单栏->终端->运行任务...来选择`重新构建`任务。

![1735660800017.png](https://oss-club.rt-thread.org/uploads/20250102/8dc6da39a0883820f3576e2f2bebdc54.png.webp)

[导入项目](#导入项目)时如果指定了默认构建任务，可以按快捷键`Ctrl+Shift+B`来执行。

![1735660800018.png](https://oss-club.rt-thread.org/uploads/20250102/92498adca12c870850586d30b62f51f9.png.webp)

任务结束时会提示结果及耗时。

![1735660800019.png](https://oss-club.rt-thread.org/uploads/20250102/1c8b072ce498490a6b57c256f32c7689.png.webp)

> **说明**
>
> 构建失败时你可以在终端或问题面板跳转到对应的文件位置：
>
> ![1735660800020.png](https://oss-club.rt-thread.org/uploads/20250102/fe25f9d52b8bf6430a37bc6ca65735a5.png.webp)
>
> ![1735660800021.png](https://oss-club.rt-thread.org/uploads/20250102/3f365e7540813be02a1bff61f30f4c23.png.webp)
>
> 修改代码后不会立刻移除错误标记，需要再次执行构建任务。

### 下载运行

可以安装微软的“串行监视器”扩展来查看串口输出或当作终端来操作：

```plaintext
名称: Serial Monitor
ID: ms-vscode.vscode-serial-monitor
说明: Send and receive text from serial ports.
发布者: Microsoft
VS Marketplace 链接: https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-serial-monitor
```

![1735660800022.gif](https://oss-club.rt-thread.org/uploads/20250102/da50652edd00271ad827529a20e032aa.gif)

### 调试代码

按F5键或“菜单栏->运行->启动调试”来开始调试。

除了常规的GDB调试功能以外，Cortex-Debug扩展还支持查看内存、片上外设寄存器等功能，详情请查看[Cortex-Debug文档](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug)。

可以在vscode扩展搜索`Cortex Debug Device Support Pack`安装对应芯片系列的片上外设支持包。

> **说明**
>
> 调试任务启动前会调用默认构建任务，调试任务启动时会下载程序，所以启动或重启调试任务无需先点击构建或下载。

### 目录检测

对于已加入编译的文件夹，当文件夹内（第一级）有新增或移除的文件时，会自动更新对应的makefile规则。

![1735660800023.png](https://oss-club.rt-thread.org/uploads/20250102/cbd2d4cfa8f8df5892be7ec5239a25f0.png.webp)

可以在扩展设置中关闭。

> **说明**
>
> 本扩展开发时参考了[eclipse-cdt - gnu2/GnuMakefileGenerator.java](https://github.com/eclipse-cdt/cdt/blob/main/build/org.eclipse.cdt.managedbuilder.core/src/org/eclipse/cdt/managedbuilder/makegen/gnu2/GnuMakefileGenerator.java)自动生成makefile的源码，目前只实现了更新它已经生成的makefile。如果自动更新有问题，可以在扩展设置中关闭此功能，然后在RT-Thread Studio构建项目一次，相关的文件会还原为GnuMakefileGenerator自动生成的值。

## 更佳实践

本扩展只实现了一小部分功能，可能不满足实际的需求，可以在生成的基础上进行修改；或者，使用其它扩展进行嵌入式开发。不管怎样，以下的操作和建议应该是通用的。

### 其它平台

- Linux发行版（以Ubuntu为例）

1. 切换apt源（非必要项）。参考[阿里云 - Ubuntu 镜像](https://developer.aliyun.com/mirror/ubuntu?spm=a2c6h.13651102.0.0.68a51b11PeE4rU)修改系统配置，加快下载速度。

2. GCC工具链。

在<https://developer.arm.com/downloads/-/gnu-rm>下载预构建的linux的，例如x86/64架构可以下载[gcc-arm-none-eabi-10.3-2021.10-x86_64-linux.tar.bz2](https://developer.arm.com/-/media/Files/downloads/gnu-rm/10.3-2021.10/gcc-arm-none-eabi-10.3-2021.10-x86_64-linux.tar.bz2?rev=78196d3461ba4c9089a67b5f33edf82a&hash=5631ACEF1F8F237389F14B41566964EC)并解压。

> **说明**
    >
    > 旧版本的`gcc-arm-none-eabi-gdb`依赖于`libncurses.so.5`库，而Ubuntu18以后已经移除，可以链接到`libncurses.so.6库：
    >
    > ```sh
    > # 例如10.3.1，假设解压到了 ~/Desktop/software/gcc-arm-none-eabi-10.3-2021.10
    > 
    > ~/Desktop/software/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gdb -v
    > # 报错arm-none-eabi-gdb: error while loading shared libraries: libncurses.so.5: cannot open shared object> file: No such file or directory
    > 
    > # 查看依赖
    > ldd ~/Desktop/software/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gdb
    > #         linux-vdso.so.1 (0x00007fffe41eb000)
    > #         libncurses.so.5 => not found
    > #         libtinfo.so.5 => not found
    > #         libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x000074afbe2ec000)
    > #         libstdc++.so.6 => /lib/x86_64-linux-gnu/libstdc++.so.6 (0x000074afbe000000)
    > #         libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x000074afbdf17000)
    > #         libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x000074afbe2bc000)
    > #         libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x000074afbe2b7000)
    > #         libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x000074afbdc00000)
    > #         /lib64/ld-linux-x86-64.so.2 (0x000074afbe303000)
    > 
    > # 说明缺少libncurses.so.5和libtinfo.so.5，查找其它可用的libncurses
    > sudo find / -name 'libncurses.so.*'
    > # /usr/lib/x86_64-linux-gnu/libncurses.so.6
    > sudo find / -name 'libtinfo.so.*'
    > # /usr/lib/x86_64-linux-gnu/libtinfo.so.6
    > # 创建软链接
    > sudo ln -s /usr/lib/x86_64-linux-gnu/libncurses.so.6 /lib/x86_64-linux-gnu/libncurses.so.5
    > sudo ln -s /usr/lib/x86_64-linux-gnu/libtinfo.so.6 /lib/x86_64-linux-gnu/libtinfo.so.5
    > 
    > # 验证
    > ~/Desktop/software/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-gdb -v
    > # GNU gdb (GNU Arm Embedded Toolchain 10.3-2021.10) 10.2.90.20210621-git
    > # Copyright (C) 2021 Free Software Foundation, Inc.
    > # License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
    > # This is free software: you are free to change and redistribute it.
    > # There is NO WARRANTY, to the extent permitted by law.
    > ```

3. make。一般是内置的，可以用`make -v`查看版本，如果小于4.0，建议用`sudo apt update && sudo apt install --reinstall make`升级到最新版本。

4. 调试服务器。

- OpenOCD：

```sh
        # 安装OpenOCD，安装后openocd会被添加到环境变量PATH。
        sudo apt install openocd
        ```

- Jlink：

```sh
        # 安装JLink，安装后JLinkExe会被添加到环境变量PATH。
        sudo apt install jlink
        ```

> **注意**
        >
        > Linux下JLink的可行性文件名为`JLinkExe`。

- PyOCD：

```sh
        # 安装python3
        sudo apt install pyton3

# 安装python3的venv模块
        sudo apt install python3-venv

# 创建一个虚拟环境
        python3 -m venv ~/embed-venv
        # 激活虚拟环境
        source ~/embed-venv/bin/activate

# 在虚拟环境中安装pyocd
        pip3 install pyocd

# 查看pyocd的所在位置（在~/虚拟环境位置/bin下，例如`~/embed-venv/bin/pyocd`）
        which pyocd
        ```

- MacOS

1. 安装包管理器

```sh
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    ```

或者，参考brew安装文档`https://docs.brew.sh/Installation`。

2. GCC工具链。

在<https://developer.arm.com/downloads/-/gnu-rm>下载预构建的MacOS的，例如下载[gcc-arm-none-eabi-10.3-2021.10-mac.pkg](https://developer.arm.com/-/media/Files/downloads/gnu-rm/10.3-2021.10/gcc-arm-none-eabi-10.3-2021.10-mac.pkg?rev=b382d51ec8d34c3fa421cf57ce97f146&hash=86689FEB39DA7A381FF78A2E70F7ABCE)然后安装。安装后位于`/Applications/ARM/bin/arm-none-eabi-gcc`。

3. make。一般是内置的，可以用`make -v`查看版本，如果小于4.0，建议用`brew install make`升级到最新版本。

> **说明**
    >
    > 新版本的GNU“make”已安装为“gmake”，在`/usr/local/opt/make/libexec/gnubin/make`。

4. 调试服务器

- OpenOCD：

```sh
        # 安装openocd，安装后openocd会被添加到环境变量PATH。
        brew install open-ocd
        ```

- JLink：

在<https://www.segger.com/downloads/jlink>下载并安装macOS的`JLink_MacOSX_Vxxx_universal.pkg`文件。

安装后位于`/Applications/SEGGER/JLink_Vxxx/JLinkExe`

- PyOCD：

```sh
        # 安装python3
        brew install python3

# 安装pyocd，安装后pyocd会被添加到环境变量PATH。
        python3 -m pip install pyocd
        ```

### 路径规则

支持的路径表达方式：

- 绝对路径。例如：

```sh
    D:/RT-ThreadStudio/repo/Extract/ToolChain_Support_Packages/ARM/GNU_Tools_for_ARM_Embedded_Processors/5.4.1/bin/arm-none-eabi-gcc.exe
    ```

- 相对于工作区文件夹的路径。例如`tools/make.exe`。

- 已添加到[环境变量](#环境变量)`PATH`中的路径。例如openocd工具在`D:/openocd-v0.12.0-i686-w64-mingw32/bin/openocd.exe`，把`D:/openocd-v0.12.0-i686-w64-mingw32/bin`添加到环境变量`PATH`中后，可以填写`openocd.exe`。

- 可以[引用环境变量](https://code.visualstudio.com/docs/editor/variables-reference#_environment-variables)。

> **说明**
>
> 优化建议：
>
> - 虽然Windows的路径分隔符是反斜杠`\`、Linux和MacOS的路径分隔符是斜杠`/`，但在Windows中绝大多数程序都能识别`/`；反而，在Windows中有些程序和命令行会将`\`视为拼接转义（例如`E:\workspace/foo\bar`被解析为`E:workspace/foobar`）从而导致编译失败。因此，可以统一使用`/`。
>
> - 在Windows选择文件路径时，可以省略`.exe`后缀。
>
> - 如果指定的绝对路径与工作区文件夹在同一盘符内，尝试将绝对路径转为相对路径。
>
> 生成配置文件时本扩展会按照这些建议优化路径。

### 环境变量

在跨平台或团队协作中，不同的环境下的工具、库等路径可能不同。如果工具位于项目根目录下，可以引用相对路径；如果在其它路径，引用绝对路径要求每个环境的路径都一样，这显然不太可能。使用环境变量可以解决这种问题。

> **说明**
>
> Windows平台powershell中可以用`Get-ChildItem Env:`来查看环境变量；Linux或MacOS中可以用`printenv`来查看环境变量。

最常见的环境变量是`PATH`，它列举多个文件夹的路径，可以让程序通过环境变量找到需要的工具。例如ARM GCC10.3.1工具的`arm-none-eabi-gcc.exe`位于`D:\gcc-arm-none-eabi-10.3-2021.10\bin`文件夹，则可以：

1. 把`D:\gcc-arm-none-eabi-10.3-2021.10`追加到环境变量`PATH`中；

2. 使用arm-none-eabi-gcc命令时可以简写成`arm-none-eabi-gcc`。

如果有不同版本的`arm-none-eabi-gcc.exe`，可以为不同版本的各创建一个环境变量。例如ARM GCC10.3.1工具位于`D:\gcc-arm-none-eabi-10.3-2021.10\bin`文件夹，则可以：

1. 在系统中新建一个`ARM_NONE_EABI_GCC_V10_HOME`的环境变量取值为`D:\gcc-arm-none-eabi-10.3-2021.10`；

2. 使用arm-none-eabi-gcc命令时可以写成`${env:ARM_NONE_EABI_GCC_V10_HOME}\bin\arm-none-eabi-gcc.exe`。

> **说明**
>
> 步骤1的设置存在系统中，步骤2的存在于项目中，这就消除了在项目中的差异。

综上所述，建议：

- 如果不同项目所使用的工具的版本一样或版本差异对项目没有影响：将工具的所在文件夹添加到环境变量`PATH`中，使用时直接引用文件的基本名。例如`make`、`openocd`、`pyocd`、`Jlink`。

- 如果不同项目使用的工具的版本不一样：为每个版本的工具的所在文件夹创建一个环境变量。例如：

1. 三个版本的ARM GCC工具链分别位于

```sh
        D:\foo\gcc-arm-none-eabi-4_9-2015q3-20150921-win32
        D:\RT-ThreadStudio\repo\Extract\ToolChain_Support_Packages\ARM\GNU_Tools_for_ARM_Embedded_Processors\5.4.1
        D:\foo\bar\gcc-arm-none-eabi-10.3-2021.10
        ```

2. 在系统创建环境变量

```sh
        # 名称为ARM_NONE_EABI_GCC_V4_9_3_HOME，值为D:\foo\gcc-arm-none-eabi-4_9-2015q3-20150921-win32
        # 名称为ARM_NONE_EABI_GCC_V5_4_1_HOME，值为D:\RT-ThreadStudio\repo\Extract\ToolChain_Support_Packages\ARM\GNU_Tools_for_ARM_Embedded_Processors\5.4.1
        # 名称为ARM_NONE_EABI_GCC_V10_3_1_HOME，值为D:\foo\bar\gcc-arm-none-eabi-10.3-2021.10
        ```

3. 项目中使用的是v10.3.1版本的arm-none-eabi-gcc

```sh
        ${env:ARM_NONE_EABI_GCC_V10_3_1_HOME}/bin/arm-none-eabi-gcc
        ```

> **说明**
        >
        > Linux或MacOS的对应工具没有`.exe`后缀，省略掉可以提高兼容性。

### 扩展设置

扩展设置的作用域分为用户、工作区、工作区文件夹3类。

在导入项目的面板生成配置时，自动保存的相关设置的作用域是工作区文件夹。

vscode设置的优先级是`工作区文件夹 > 工作区 > 用户 > 默认值`。可以在“用户”域修改默认值，为新的工作区文件夹提供自定义的默认值，就不需要在每次打开新的项目时重复配置。而且，在“用户”域修改的值不会保存到工作区文件夹中，可以提高团队协作时的项目兼容性。例如：

![1735660800024.png](https://oss-club.rt-thread.org/uploads/20250102/a441c3a6189e30c44caaeec443b62b46.png.webp)

### 中断检查

检查工作区文件夹下的源文件是否在每个`xxx_IRQHandler`函数中调用了`rt_interrupt_enter()`和`rt_interrupt_leave()`，不符合要求时，发出警告：

![1735660800025.png](https://oss-club.rt-thread.org/uploads/20250102/40b6cf9f1a461dbb021767b9134c326e.png.webp)

可以在`问题`面板中的警告上右键（或编辑器出现警告波浪线的地方点击`快速修复`），选择`添加所有缺少的调用`即可补齐该文件中的所有缺失的调用：

![1735660800026.gif](https://oss-club.rt-thread.org/uploads/20250102/faa08fc7f1f2e6b1ab112c8177014827.gif)

> **说明**
>
> 快速修复时，如果有`/* USER CODE BEGIN xxx */`、`/* USER CODE END xxx */`则添加到模板之间，否则添加到函数体的开头和结尾。

#### 触发条件

- 自动诊断：指定的路径（默认为`stm32*_it.c`）文件（例如`Core/Src/stm32f4xx_it.c`）中存在以下任意一行之一：

```c
    #include <rtthread.h>
    #include "rtthread.h"
    rt_interrupt_enter();
    rt_interrupt_leave();
    ```

> **说明**
    >
    > 可以在扩展设置中修改是否启用自动诊断及其路径匹配模式。例：
    >
    > - 全部源文件：`**/*.c`
    >
    > - `Core/Src`的全部源文件：`Core/Src/*.c`

- 手动诊断：资源管理器中的`.c`文件上右键，选择`诊断中断函数`。

![1735660800027.png](https://oss-club.rt-thread.org/uploads/20250102/c92703903de63244a44a7fdf93c73d9c.png.webp)

### 定制任务

如果本扩展生成的配置不满足需求，可以在`.vscode/tasks.json`、`.vscode/c_cpp_properties.json`、`.vscode/launch.json`添加任务，重新导入时不会被覆盖。

- 任务

```json
    {
        "tasks": [
            // ...
            {
                "label": "push",
                "detail": "推送",
                "command": "git",
                "args": [
                    "push",
                ],
                "problemMatcher": []
            }
        ]
    }
    ```

![1735660800028.png](https://oss-club.rt-thread.org/uploads/20250102/a1ee97cc677c0f1d7cf781de10dd37c2.png)

- 状态栏按钮

本扩展状态栏按钮的“清除”、“构建”、“下载”、“构建并下载”所执行的任务分别对应`.vscode/tasks.json`中任务如下`label`：

```sh
    jswyll-vscode-rtthread: clean
    jswyll-vscode-rtthread: build
    jswyll-vscode-rtthread: download
    jswyll-vscode-rtthread: build and download
    ```

重新导入时这些任务会被覆盖，如果要修改状态栏按钮的任务，可以定义不包含`jswyll-vscode-rtthread:`前缀的。例如定制“编译并下载”任务

```json
    {
        "tasks": [
            // ...
            {
                "label": "build and download",
                "detail": "构建、下载并暂存",
                "dependsOn": [
                    "jswyll-vscode-rtthread: build and download",
                ],
                "dependsOrder": "sequence",
                "command": "git",
                "args": [
                    "add",
                    ".",
                ],
                "problemMatcher": []
            }
        ]
    }
    ```

这表示先执行本扩展定义的“构建并下载”，然后执行自定义的命令。也可以自由定义依赖和命令，只要label符合要求。

- 调试

可以自行添加Cortex-Deubg扩展支持的其它调试器，或其它架构的调试配置。

```json
    {
        "version": "0.2.0",
        "configurations": [
            {
                "name": "Debug",
                // ...
            },
            {
                "name": "MyDebug",
                "cwd": "${workspaceFolder}",
                "toolchainPrefix": "arm-none-eabi",
                "executable": "Debug/rtthread.elf",
                "request": "launch",
                "type": "cortex-debug",
                "device": "STM32L431CCTx",
                "runToEntryPoint": "main",
                "servertype": "qemu",
                // ...
            }
        ]
    }
    ```

![1735660800029.png](https://oss-club.rt-thread.org/uploads/20250102/81b1753ccd142a2972cba316c69c58c9.png)

- C/C++配置

例：切换为使用`scons --target=vsc`生成的

![1735660800030.png](https://oss-club.rt-thread.org/uploads/20250102/f3d35ce4d0a6a8d387984416ce17559b.png.webp)

## 常见问题

```sh
rror: open failed
in procedure 'program'
** OpenOCD init failed **
shutdown command invoked
```

调试器已正确连接芯片和电脑？选择的调试器类型正确？已安装调试服务器（驱动）？

---

```sh
** Programming Started **
Error: couldn't open Debug/rtthread.elf
** Programming Failed **
shutdown command invoked
```

还没构建就点了下载。

---

```sh
process_begin: CreateProcess(NULL, echo " ", ...) failed.
make (e=2): 系统找不到指定的文件。
```

环境变量`PATH`中没有echo命令。Linux和MacOS是系统自带的，Windows选择了RT-Thread的make工具路径也是有的。

可以把RT-Thread的make工具路径添加到环境变量`PATH`中。或者，下载并解压<https://github.com/skeeto/w64devkit/releases>然后添加到环境变量`PATH`中。

---

## 使用局限

- 目前仅支持用RT-Thread Studio的新建、导入项目，或使用`scons --dist-ide --target=eclipse`生成然后使用RT-Thread Studio导入的。理论上Eclipse C/C++的项目可以使用，但未测试过。只支持GCC Make类型的编译方式。

- 调试依赖于Cortex-Debug扩展，只支持ARM-Cortex架构（如果GCC编译器的前缀不是`arm-none-eabi-`将不生成调试配置`.vscode/launch.json`）。

- 暂不支持在资源管理器中右键添加新增编译的源文件文件夹、新的头文件包含路径；暂不支持像ESP-IDF一样通过界面配置项目（代替menuconfig）。未来可能支持，目前需要使用RT-Thread Studio构建一次后才会管理新增的源文件文件夹。

## 问题反馈

前往[github/issues](https://github.com/jswyll/jswyll-vscode-rtthread/issues?utm_source=vsmp&utm_medium=ms%20web&utm_campaign=mpdetails)或联系<jswyll@qq.com>。

如有必要，打开输出面板，把日志等级调到“调试”，复现问题，提供你脱敏处理后的日志。

![1735660800031.png](https://oss-club.rt-thread.org/uploads/20250102/d3e0eb1faa93cbe7cb98e64a91cd80b7.png.webp)

## 实现细节

受影响文件的范围：

- 在`.vsocde`下生成相关配置。

- 优化所选构建配置（例如工作区文件夹的`Debug`文件夹）下的makefile。

查看源码：

- 仓库地址：<https://github.com/jswyll/jswyll-vscode-rtthread/>。

- 开发说明：<https://github.com/jswyll/jswyll-vscode-rtthread/tree/main/docs/README.md>。

## 特别鸣谢

- [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug)：一款适用于ARM Cortex-M架构的GDB调试扩展。

```sh
    名称: Cortex-Debug
    ID: marus25.cortex-debug
    说明: ARM Cortex-M GDB Debugger support for VSCode
    发布者: marus25
    VS Marketplace 链接: https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug
    ```

- [espressif - esp-idf-extension](https://marketplace.visualstudio.com/items?itemName=espressif.esp-idf-extension)：参考了该扩展的部分功能和界面设计。

- [eclipse-cdt - gnu2/GnuMakefileGenerator.java](https://github.com/eclipse-cdt/cdt/blob/main/build/org.eclipse.cdt.managedbuilder.core/src/org/eclipse/cdt/managedbuilder/makegen/gnu2/GnuMakefileGenerator.java)：了解了其makefile生成逻辑。