RT-Thread项目助手
本扩展适用于使用RT-Thread Studio新建或导入的项目（或使用scons --dist-ide --target=eclipse生成然后使用RT-Thread Studio导入的），也适用于支持scons构建的RT-Thread项目，可生成vscode的代码浏览、编辑、编译、下载、调试的配置文件。
快速开始
在vscode中安装并启用本扩展（jswyll.jswyll-vscode-rtthread），依赖的扩展会被自动安装。
打开项目根目录（.cproject或rt_config.py文件的所在文件夹），点击状态栏的“导入”按钮
根据配置面板提示填写相关信息
点击“RT-Thread Studio路径”右方的打开文件按钮，选择RT-Thread Studio安装路径（studio.exe的所在文件夹）
根据情况选择调试器类型及其接口
点击“生成”按钮
点击状态栏的“构建并下载”按钮（或按快捷键Ctrl+Shift+B）
扩展特性
操作说明
vscode支持多根工作区，可以在一个工作区中同时打开多个工程。
本扩展兼容多根工作区。如果打开的是多根工作区且有多个根文件夹，将弹出工作区文件夹的选择器：
后续的操作都将基于该文件夹，相关的配置文件会保存在该工作区文件夹。可以通过点击状态栏的子模块图标来再次切换。
说明
以下所提到的“工作区文件夹”都是指已选择的根文件夹。如果打开的是单个文件夹或多根工作区下只有一个根文件夹，“工作区文件夹”就是指这个文件夹。
名称约定
以下的名词表中每行的各列在本文档中表示同一个意思：
| 名称 |
英文 |
其它常用名称 |
| 扩展 |
extension |
插件 |
| 项目 |
project |
工程 |
| 构建 |
build |
编译（compile） |
| 下载 |
download |
烧写、烧录、闪存（flash） |
| 根目录 |
root dir |
主目录（项目或工具的顶层文件夹） |
扩展激活
启用扩展后，当工作区文件夹中（第一级）有.cproject文件或rt_config.py文件时，扩展会自动激活。
提示
如果选择的构建方式RT-Thread Studio Makefile，需要在RT-Thread Studio构建一次。
在vscode打开的主目录应该是BSP主目录或RT-Thread Studio项目的主目录。如果不是（例如想同时看RT-Thread主仓库源码和BSP），可参考子文件夹将项目转为多根工作区。
BSP的Kconfig中的路径可能是导入后的，如果在RT-Thread主仓库中的BSP开发，可以尝试使用RT-Thread Studio导入项目或使用scons --dist相关命令生成标准的目录结构。
生成配置
点击状态里的“导入”来生成vscode的配置文件。
说明
选项说明
项目类型：项目的构建方式，RT-Thread Studio Makefile（eclipse cdt）或RT-Thread Env（scons）。
构建配置：在RT-Thread Studio项目中创建的构建配置，例如Debug或Release。如果只有一个则无需选择。必要项。
RT-Thread Studio路径：你的RT-Thread Studio安装路径（studio.exe的所在文件夹）。目前仅用于推导可能的工具位置以供选择。非Windows平台没有这个选项。非必要项。
GCC编译器路径：用于C/C++扩展分析代码、编译程序。必要项。
可以直接选择RT-Thread Studio内置的arm-none-eabi-gcc：
对于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下载命令更丰富的开发包。
芯片名称：用于下载程序时让调试器识别出对应的FLASH大小。对于STM32，应至少精确到11位字符，例如STM32L431CC。
调试服务器：支持OpenOCD、JLink、ST-LINK_gdbserver、PyOCD。非必要项（如果你不需要在vscode下载、调试程序）。
Segger JLink：要求版本大于等于V7.90，RT-Thread Studio v2.2.8以上可以选内置的v7.92。或者，前往https://www.segger.com/downloads/jlink下载特定的版本。特点是：快！
OpenOCD：可以前往https://github.com/xpack-dev-tools/openocd-xpack/releases下载，对于Windows还可以前往https://gnutoolchains.com/arm-eabi/openocd/下载包含的额外驱动软件的。支持ST-Link、JLink和CMSIS-DAP。特点是：很多芯片厂商都支持。
说明
Windows平台选择OpenOCD调试服务器且使用JLink调试器时，需要使用https://gnutoolchains.com/arm-eabi/openocd/里的UsbDriverTool.exe或zadig把JLink驱动更换为libusb：
修改驱动后在MDK IDE就不能使用JLink下载了，可以使用https://gnutoolchains.com/arm-eabi/openocd/里的UsbDriverTool.exe把驱动恢复为JLlink驱动：
ST-LINK_gdbserver：支持在RT-Thread Studio的SDK Manager安装的或通过官网 STM32CubeCLT页面下载安装的。经测试，通过RT-Thread Studio安装的 1.4.0 和 1.2.0 版本只能下载，启动调试失败。 默认内置的1.6.0版本及更高的版本可用。
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内置目标，否则需要填写Cmsis包的路径。Windows平台可以输入关键词然后选择RT-Thread Studio内置的。
提示
可以通过pyocd命令添加内置的支持包：pyocd pack find 芯片名称查找，pyocd pack install 包名称安装。例：
D:\RT-ThreadStudio\workspace\stm32f407-atk-explorer-v5.2.0>pyocd pack find STM32F407ZG
0000455 I No pack index present, downloading now... [pack_cmd]
Part Vendor Pack Version Installed
---------------------------------------------------------------------------------
STM32F407ZGTx STMicroelectronics Keil.STM32F4xx_DFP 3.0.0 False
D:\RT-ThreadStudio\workspace\stm32f407-atk-explorer-v5.2.0>pyocd pack install STM32F407ZGTx
Downloading packs (press Control-C to cancel):
Keil.STM32F4xx_DFP.3.0.0
Downloading descriptors (001/001)
D:\RT-ThreadStudio\workspace\stm32f407-atk-explorer-v5.2.0>
添加后不需要填写Cmsis包的路径。
说明
以上的xxx路径选项，你可以通过右方的打开文件图标按钮来选择，可以选择提示的选项，还可以手动输入，见路径规则。
开始生成
填写参数的过程中会校验输入是否有效。对于错误，根据提示检查并更正。
对于警告，点击“生成”时会弹窗提示，如果确定可以点击“忽略”按钮。
点击“生成”按钮，开始校验并生成配置文件。如果生成成功，配置面板将自动关闭。
注意
切换编译器版本后，应重新编译，以消除编译器版本差异引发不可预料的结果。比如，RT-Thread Studio默认使用的是GCC 5.4.1，在vscode选择RT-Thread Studio内置的env_released/env/tools/gnu_gcc/arm_gcc/mingw/bin/arm-none-eabi-gcc.exe是GCC 10.3.1，在RT-Thread Studio构建或再次构建过然后又转到vscode构建。再比如，在vscode前后两次生成配置时选择的GCC的版本不一样。
生成配置成功后状态栏将显示清除、构建、下载、构建并下载按钮，可以点击这些来快速执行相应的操作。
提示
vscode支持在状态栏按钮上右键，切换是否显示该按钮，你可以用这个方法隐藏不常用的按钮。另外，其它扩展可能也会显示一堆按钮，你可以在vscode侧边栏->扩展中指定的扩展上右键，选择“禁用（工作区）”来关闭不必要的扩展（例如CMake）。
你可以在菜单栏->终端->运行任务...来选择运行指定的任务，例如重新构建：
构建项目
生成配置时如果指定了默认构建任务，可以按快捷键Ctrl+Shift+B来执行。
如果是通过状态栏按钮启动任务的，任务结束时会提示结果及耗时。
提示
构建失败时你可以在终端或问题面板跳转到对应的文件位置：
修改代码后vscode不会立刻移除错误标记，需要再次执行构建任务。
下载运行
可以安装微软的“串行监视器”扩展来查看串口输出或当作终端来操作：
名称: 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
调试代码
按F5键或“菜单栏->运行->启动调试”来开始调试。
除了常规的GDB调试功能以外，Cortex-Debug扩展还支持查看内存、片上外设寄存器等功能，详情请查看Cortex-Debug文档。
可以在vscode扩展搜索Cortex Debug Device Support Pack安装对应芯片系列的片上外设支持包。
提示
调试任务启动前会调用默认构建任务，调试任务启动时会下载程序，所以启动或重启调试任务无需先点击构建或下载。
目录检测
选择RT-Thread Studio构建方式时，对于已加入编译的文件夹，当文件夹内（第一级）有新增或移除的文件时，会自动更新对应的makefile规则。
选择RT-Thread Env构建方式时，当你修改工作区文件夹中的SConscript或SConstruct文件时，会自动运行scons --target=vsc --silent命令来更新C/C++代码的浏览配置。
可以在扩展设置中关闭。
说明
本扩展开发时参考了eclipse-cdt - gnu2/GnuMakefileGenerator.java自动生成makefile的源码，目前只实现了更新它已经生成的makefile。如果自动更新有问题，可以在扩展设置中关闭此功能，然后在RT-Thread Studio构建项目一次，相关的文件会还原为GnuMakefileGenerator自动生成的值。
RT-Thread Env
先决条件
可以直接选择使用RT-Thread Studio内置的Env（应该是Env Windows v1.3.5），或者转到《ENV-Windows v2.0.0版本发布》安装特点版本的Env。
提示
Ubuntu或MacOS的Env安装方式可参考其它平台。
支持scons方式编译的项目。本扩展支持Env v1.x和v2.x，但取决于BSP能使用的Env版本。
打开BSP的所在文件夹（BSP_DIR），例如：
第一种：已经是RT-Thread标准项目框架的：
stm32f407-atk-explorer/ # BSP_DIR
├── applications/
├── packages/
├── rt-thread/ # RTT_DIR
├── ...
├── Kconfig
├── SConscript
├── SConstruct
├── rtconfig.h
└── rtconfig.py
第二种：是RT-Thread仓库下的某个BSP：
rt-thread/ # RTT_DIR
├── bsp/
│ └── stm32/
│ ├── libraries/
│ ├── ...
│ └── stm32f407-atk-explorer # BSP_DIR
│ ├── applications/
│ ├── packages/
│ ├── ...
│ ├── Kconfig
│ ├── SConscript
│ ├── SConstruct
│ ├── rtconfig.h
│ └── rtconfig.py
├── ...
├── src/
├── tools/
└── Kconfig
导入项目
点击状态栏的“导入”图标按钮，弹出配置面板：
其它选项与RT-Thread Studio的配置方式一致。
点击“生成”按钮并等待生成完毕。
如果操作无误状态栏应显示“配置”和“终端”图标按钮：
说明
RT-Thread Env构建方式的默认产物路径是rt-thread.elf，如果名称不同或路径不同可以在扩展设置jswyll-vscode-rtthread.generate.artifactPath修改下载和调试时所用的产物路径。
菜单配置
说明
对于Env v2.x，安装好依赖后，除非本扩展无法正常使用，否则 无需 运行${ENV_ROOT}/env.ps1或${ENV_ROOT}/.venv/Scripts/Activate.ps1激活虚拟环境。
点击状态栏的“配置”图标按钮，弹出菜单配置面板：
单击菜单项的标题（或最左边侧的图标）可以展开或折叠菜单，有几类配置项：
整数（int）
十六进制数（hex）
字符串（string）
布尔（bool）
单项选择（choice）
可以在搜索框中输入关键词搜索配置项（或菜单项）：
关键词可以是以下之一中的字词：
名称，例如RT_NAME_MAX
标题，例如The maximal size of kernel object name，
帮助，例如Each kernel object, such as thread, timer, semaphore etc, has a name,the RT_NAME_MAX is the maximal size of this object name.
翻译后的标题，例如内核对象名称的最大大小
翻译后的帮助，例如每个内核对象，如线程、定时器、信号量等，都有一个名称。 RT_NAME_MAX是该对象名称的最大大小。
提示
如果修改了Kconfig文件，可以点“重新加载”按钮来刷新菜单配置。
可参考linux内核Kconfig文档了解Kconfig语法。
点击“保存”按钮保存配置，默认自动更新软件包：
说明
提示
RTT_CC的默认值是gcc。
可以在扩展设置中添加环境变量，名称相同的可覆盖扩展生成的。
终端任务
清除、构建、下载、调试的操作方式与RT-Thread Studio类型的一致。本质上是运行定义的tasks.json中的任务，可以通过点击状态栏图标按钮、菜单栏、配置快捷键、使用任务扩展等方式运行终端任务。
集成终端
点击状态栏的“终端”图标按钮，弹出终端面板。可以使用scons、pkgs、sdk、menuconfig命令。
在Win10的vscode终端执行menuconfig有已知问题：
也可以通过点击终端面板右上角的下拉图标来打开终端。
原始方式
可以在vscode资源管理器上（文件或文件夹）右键，选择“在此处打开ConEmu”，使用原始方式开发：
其它平台
切换apt源（非必要项）。参考阿里云 - Ubuntu 镜像修改系统配置，加快下载速度。
GCC工具链。
在https://developer.arm.com/downloads/-/gnu-rm下载预构建的linux的，例如x86/64架构可以下载gcc-arm-none-eabi-10.3-2021.10-x86_64-linux.tar.bz2并解压。
提示
旧版本的gcc-arm-none-eabi-gdb依赖于libncurses.so.5库，而Ubuntu18以后已经移除，可以链接到libncurses.so.6库：
# 例如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.
make。一般是内置的，可以用make -v查看版本，如果小于4.0，建议用sudo apt update && sudo apt install --reinstall make升级到最新版本。
调试服务器。
OpenOCD：
# 安装OpenOCD，安装后openocd会被添加到环境变量PATH。
sudo apt install openocd
Jlink：
在https://www.segger.com/downloads/jlink下载并安装Linux的安装包，例如https://www.segger.com/downloads/jlink/JLink_Linux_x86_64.deb。
安装后位于/opt/SEGGER/JLink/JLinkExe，会将JLinkExe添加到环境变量PATH。
python3、env2.x与pyocd:
可复制以下命令到终端按回车执行一键安装
cat << 'EOF' > install_ubuntu.sh
#!/usr/bin/env bash
sudo apt-get update
sudo apt-get -qq install python3 python3-venv gcc git libncurses5-dev -y
url=https://raw.githubusercontent.com/RT-Thread/env/master/touch_env.sh
if [ $1 ] && [ $1 = --gitee ]; then
url=https://gitee.com/RT-Thread-Mirror/env/raw/master/touch_env.sh
fi
wget $url -O touch_env.sh
chmod 777 touch_env.sh
./touch_env.sh $@
rm touch_env.sh
python3 -m venv ~/.env/.venv
source ~/.env/.venv/bin/activate
pip install scons requests tqdm kconfiglib pyyaml pyocd
python3 -m pip install -U pyocd
EOF
chmod +x install_ubuntu.sh
./install_ubuntu.sh --gitee
rm ./install_ubuntu.sh
说明
此处命令行脚本参考https://github.com/RT-Thread/env/blob/master/install_ubuntu.sh并改为虚拟环境的方式。
安装包管理器
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
或者，参考brew安装文档https://docs.brew.sh/Installation。
GCC工具链。
在https://developer.arm.com/downloads/-/gnu-rm下载预构建的MacOS的，例如下载gcc-arm-none-eabi-10.3-2021.10-mac.pkg然后安装。安装后位于/Applications/ARM/bin/arm-none-eabi-gcc。
make。一般是内置的，可以用make -v查看版本，如果小于4.0，建议用brew install make升级到最新版本。
提示
比较新的版本的GNU“make”可能安装在/usr/local/opt/make/libexec/gnubin/make。
调试服务器
OpenOCD：
# 安装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
python3、env2.x与pyocd:
可复制以下命令到终端按回车执行一键安装
cat << 'EOF' > ./install_macos.sh
#!/usr/bin/env bash
if ! [ -x "$(command -v brew)" ]; then
echo "Installing Homebrew."
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
fi
brew update
brew upgrade
RTT_PYTHON=python3
$RTT_PYTHON --version >/dev/null 2>&1 || {
echo "Installing python3."
brew install python3
}
if ! [ -x "$(command -v git)" ]; then
echo "Installing git."
brew install git
fi
brew list ncurses >/dev/null || {
echo "Installing ncurses."
brew install ncurses
}
if ! [ -x "$(command -v arm-none-eabi-gcc)" ]; then
echo "Installing GNU Arm Embedded Toolchain."
brew install gnu-arm-embedded
fi
url=https://raw.githubusercontent.com/RT-Thread/env/master/touch_env.sh
if [ $1 ] && [ $1 = --gitee ]; then
url=https://gitee.com/RT-Thread-Mirror/env/raw/master/touch_env.sh
fi
curl $url -o touch_env.sh
chmod 777 touch_env.sh
./touch_env.sh $@
rm touch_env.sh
python3 -m venv ~/.env/.venv
source ~/.env/.venv/bin/activate
$RTT_PYTHON -m pip list >/dev/null || {
echo "Installing pip."
$RTT_PYTHON -m ensurepip --upgrade
}
if ! [ -x "$(command -v scons)" ]; then
echo "Installing scons."
$RTT_PYTHON -m pip install scons
fi
if ! [ -x "$(command -v tqdm)" ]; then
echo "Installing tqdm."
$RTT_PYTHON -m pip install tqdm
fi
if ! [ -x "$(command -v kconfiglib)" ]; then
echo "Installing kconfiglib."
$RTT_PYTHON -m pip install kconfiglib
fi
if ! [ -x "$(command -v pyocd)" ]; then
echo "Installing pyocd."
$RTT_PYTHON -m pip install -U pyocd
fi
if ! [[ $($RTT_PYTHON -m pip list | grep requests) ]]; then
echo "Installing requests."
$RTT_PYTHON -m pip install requests
fi
EOF
chmod +x ./install_macos.sh
./install_macos.sh --gitee
rm ./install_macos.sh
说明
此处命令行脚本参考https://github.com/RT-Thread/env/blob/master/install_macos.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
用户主目录下的路径，例如${userHome}/env/.venv/Scripts。
相对于工作区文件夹的路径。例如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。
可以引用环境变量。
说明
优化建议：
虽然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文件夹，则可以：
把D:\gcc-arm-none-eabi-10.3-2021.10追加到环境变量PATH中；
使用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文件夹，则可以：
在系统中新建一个ARM_NONE_EABI_GCC_V10_HOME的环境变量取值为D:\gcc-arm-none-eabi-10.3-2021.10；
使用arm-none-eabi-gcc命令时可以写成${env:ARM_NONE_EABI_GCC_V10_HOME}\bin\arm-none-eabi-gcc.exe。
说明
步骤1的设置存在系统中，步骤2的存在于项目中，这就消除了在项目中的差异。
综上所述，建议：
团队协作中，不同成员的工具安装目录等配置很可能不同。虽然可以通过把.vscode、*.code-workspace加入.gitignore中来屏蔽不同团队成员的配置，但那样也损失了可共享的公用配置，如果没有完善的文档，若干年之后再git clone用起来或许连自己都要折腾几番。个人认为更好的方式是：
不把.vscode、*.code-workspace加入.gitignore忽略规则；
如果在不同项目中是通用的，有差异的设置保存在“用户”域中；
如果在不同项目中不是通用的，每个成员在系统中创建环境变量；
把剩余的小部分不可通用的（没有同步到远程仓库的）所需配置或产生配置的方式写在项目文档中。
例如，stm32f407-atk-explorer-v5.0.0项目决定用Env v2.0版本，每个成员把具体的Env版本的所在文件夹设为环境变量RTT_ENV_V2，然后在生成配置时“Env工具路径”填写${env:RTT_ENV_V2}、“GCC编译器路径”填写${env:RTT_ENV_V2}/tools/gnu_gcc/arm_gcc/mingw/bin/arm-none-eabi-gcc。
扩展设置
扩展设置的作用域分为用户、工作区、工作区文件夹3类。
在生成配置的面板生成配置时，自动保存的相关设置的作用域是工作区文件夹。
vscode设置的优先级是工作区文件夹 > 工作区 > 用户 > 默认值。可以在“用户”域修改默认值，为新的工作区文件夹提供自定义的默认值，就不需要在每次打开新的项目时重复配置。而且，在“用户”域修改的值不会保存到工作区文件夹中，可以提高团队协作时的项目兼容性。例如：
中断检查
检查工作区文件夹下的源文件是否在每个xxx_IRQHandler函数中调用了rt_interrupt_enter()和rt_interrupt_leave()，不符合要求时，发出警告：
可以在问题面板中的警告上右键（或编辑器出现警告波浪线的地方点击快速修复），选择添加所有缺少的调用即可补齐该文件中的所有缺失的调用：
说明
快速修复时，如果有/* USER CODE BEGIN xxx */、/* USER CODE END xxx */则添加到模板之间，否则添加到函数体的开头和结尾。
触发条件
自动诊断：指定的路径（默认为stm32*_it.c）文件（例如Core/Src/stm32f4xx_it.c）中存在以下任意一行之一：
#include <rtthread.h>
#include "rtthread.h"
rt_interrupt_enter();
rt_interrupt_leave();
说明
可以在扩展设置中修改是否启用自动诊断及其路径匹配模式。例：
手动诊断：资源管理器中的.c文件上右键，选择诊断中断函数。
定制任务
如果本扩展生成的配置不满足需求，可以在.vscode/tasks.json、.vscode/c_cpp_properties.json、.vscode/launch.json添加任务，重新导入时不会被覆盖。
任务
{
"tasks": [
// ...
{
"label": "push",
"detail": "推送",
"command": "git",
"args": [
"push",
],
"problemMatcher": []
}
]
}
状态栏按钮
本扩展状态栏按钮的“清除”、“构建”、“下载”、“构建并下载”所执行的任务分别对应.vscode/tasks.json中任务如下label：
jswyll-vscode-rtthread: clean
jswyll-vscode-rtthread: build
jswyll-vscode-rtthread: download
jswyll-vscode-rtthread: build and download
重新导入时这些任务会被覆盖，如果要修改状态栏按钮的任务，可以定义不包含jswyll-vscode-rtthread:前缀的。例如定制“编译并下载”任务
{
"tasks": [
// ...
{
"label": "build and download",
"detail": "构建、下载并暂存",
"dependsOn": [
"jswyll-vscode-rtthread: build and download",
],
"dependsOrder": "sequence",
"command": "git",
"args": [
"add",
".",
],
"problemMatcher": []
}
]
}
这表示先执行本扩展定义的“构建并下载”，然后执行自定义的命令。也可以自由定义依赖和命令，只要label符合要求。
调试
可以自行添加Cortex-Deubg扩展支持的其它调试器，或其它架构的调试配置。
{
"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",
// ...
}
]
}
C/C++配置
例：切换为使用scons --target=vsc生成的
子文件夹
如果想在子文件夹进行本扩展的相关功能，可以按照下面的步骤转换为vscode多根工作区。
假设当前打开的文件夹的目录结构如下：
rt-thread/ # opened this folder
├── bsp/
│ └── stm32/
│ ├── libraries/
│ ├── ...
│ └── stm32f407-atk-explorer # BSP_DIR
│ ├── applications/
│ ├── packages/
│ ├── ...
│ ├── Kconfig
│ ├── SConscript
│ ├── SConstruct
│ ├── rtconfig.h
│ └── rtconfig.py
├── ...
├── src/
├── tools/
└── Kconfig
如果还不是vscode工作区（xxx.code-workspace）：在vscode打开父级目录workspace；点击 vscode菜单栏 -> 文件 -> 将工作区另存为...，在弹出的保存窗口中填工作区的名称和位置，然后点击“保存”按钮就生成了一个vscode工作区（xxx.code-workspace）。
rt-thread/ # .code-workspace root1
├── bsp/
│ └── stm32/
│ ├── libraries/
│ ├── ...
│ └── stm32f407-atk-explorer # BSP_DIR
│ ├── applications/
│ ├── packages/
│ ├── ...
│ ├── Kconfig
│ ├── SConscript
│ ├── SConstruct
│ ├── rtconfig.h
│ └── rtconfig.py
├── ...
├── src/
├── tools/
└── Kconfig
点击 vscode菜单栏 -> 文件 -> 将文件夹添加到工作区...，选择那个子文件夹（BSP_DIR）；
rt-thread/ # .code-workspace root1
├── bsp/
│ └── stm32/
│ ├── libraries/
│ ├── ...
│ └── stm32f407-atk-explorer # BSP_DIR
│ ├── applications/
│ ├── packages/
│ ├── ...
│ ├── Kconfig
│ ├── SConscript
│ ├── SConstruct
│ ├── rtconfig.h
│ └── rtconfig.py
├── ...
├── src/
├── tools/
└── Kconfig
stm32f407-atk-explorer # .code-workspace root2 (BSP_DIR)
├── applications/
├── packages/
├── ...
├── Kconfig
├── SConscript
├── SConstruct
├── rtconfig.h
└── rtconfig.py
点击状态栏的子模块图标来选择当前的工作区文件夹为上一步加入多根工作区的文件夹（.code-workspace root2）。
说明
以后在vscode打开步骤1的xxx.code-workspace。
在.code-workspace root1继续后续操作。（在.code-workspace root2当然是可以的，它的物理路径和.code-workspace root1中的那个子文件夹的是一样的。）
常见问题
error: open failed
in procedure 'program'
** OpenOCD init failed **
shutdown command invoked
调试器已正确连接芯片和电脑？选择的调试器类型正确？已安装调试服务器（驱动）？
** Programming Started **
Error: couldn't open Debug/rtthread.elf
** Programming Failed **
shutdown command invoked
还没构建就点了下载。
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中。
使用限制
已知问题
如果在工作区启用Python扩展激活了虚拟环境且虚拟环境的python版本和选择的RT-Thread Env中的大版本不一致（v1.x是Python2，v2.x是Python3），很可能导致终端出错，因为Python扩展激活的Python的优先级更高。出现错误请修改Python扩展的设置关闭激活虚拟环境，或（在工作区）禁用Python扩展。
终端集成：
在Win10中，RT-Thread Env 2.x的menuconfig不支持用上下左右箭头来移动，进入子菜单请用Enter或L键；返回上一级请用ESC或H键；上、下请用K、J键；RT-Thread Env 1.x的menuconfig如何上下移动尚未清楚。
旧版本RT-Thread Studio内置的J-Link/v7.50a不支持解析elf文件，请使用以下方式之一升级到V7.90（2023-08-02）及以上版本：
生成配置时，如果选择的调试服务器是Segger Jlink，由于Jlink不直接支持--version参数，校验表单时需要多等待约3秒的时间。
如果之前的构建任务启动失败（例如Makefile构建目录不存在），下次运行会一直弹出等待进度（请重启vscode）。
快速连续多次点击状态栏按钮启动构建任务时，如果之前的任务启动失败，任务报告统计可能错乱。
问题反馈
前往github/issues或联系jswyll@qq.com。
如有必要，打开输出面板，把日志等级调到“调试”，复现问题，提供你脱敏处理后的日志。
实现细节
受影响文件的范围：
查看源码：
隐私保护指引
本扩展仅处理实现扩展功能所必要的信息，例如读取Env安装目录的Kconfig文件以生成菜单配置界面、查找选择的RT-Thread Studio目录中的GCC编译器以供选择。
为了便于问题定位与排查，本扩展可能会记录相关日志，vscode可能会将最近的一小段日志存储在电脑本地。本扩展的日志等级与输出面板中jswyll-vscode-rtthread设置的等级一致（详细程度：“跟踪”>“调试”>“信息”>“警告”>“错误”>“关”，默认为“信息”），请仅在需要向开发者反馈问题时临时提高输出等级。
本扩展不会将你的信息上传到开发者服务器或任何第三方平台。若未来新版本变更了信息的使用目的或范围，将先以弹窗的方式告知并征得你的明示同意。
你可以在生成配置文件后禁用此扩展。如果禁用，将使用不了需要扩展运行的功能（例如状态栏按钮、菜单配置界面、右键菜单）。
