【兆易创新GD32VW553开发板试用】 BSP 从 GitHub 下载与编译指南

[📌 概述](#📌 概述)

[🛠 环境准备](#🛠 环境准备)

[1. 安装 Git](#1. 安装 Git)

[2. 安装 RISC‑V 工具链](#2. 安装 RISC‑V 工具链)

[3. 安装 RTT-Thread ENV](#3. 安装 RTT-Thread ENV)

[⬇️ 下载BSP步骤](#⬇️ 下载BSP步骤)

[🔹 方法一：稀疏检出（强烈推荐）](#🔹 方法一：稀疏检出（强烈推荐）)

[🔸 方法二：完整克隆](#🔸 方法二：完整克隆)

[⚙️ 编译步骤](#⚙️ 编译步骤)

[1. 进入 BSP 目录](#1. 进入 BSP 目录)

[2. 安装软件包依赖](#2. 安装软件包依赖)

[3. 执行编译](#3. 执行编译)

[🪟 Windows CMD](#🪟 Windows CMD)

[🪟 Windows PowerShell](#🪟 Windows PowerShell)

[4. 清理构建产物](#4. 清理构建产物)

[📦 编译输出](#📦 编译输出)

[❓ 常见问题](#❓ 常见问题)

[Q1：scons: *** missing SConscript file](#Q1：scons: *** missing SConscript file)

[Q2：Error: the toolchain path ... is not exist](#Q2：Error: the toolchain path ... is not exist)

[Q3：pkgs --update 下载失败](#Q3：pkgs --update 下载失败)

[Q4：RAM 占用显示 100%](#Q4：RAM 占用显示 100%)

[🔗 参考链接](#🔗 参考链接)

本文详细讲解如何仅下载 RT-Thread 官方仓库中 gd32vw553h-eval 开发板支持包（BSP）及其依赖，并完成 RISC-V 工具链编译。通过稀疏检出技巧，可大幅节省磁盘空间和下载时间。

📌 概述

最近参加了RT-Thread和电子发烧友组织的评测活动，特在CSDN记录一下测试的过程。

RT-Thread 官方 GitHub 仓库包含了数百个 BSP，完整克隆体积巨大。本文针对 GD32VW553H-EVAL 这一款 RISC‑V 评估板，介绍使用 Git 稀疏检出（sparse checkout） 的方式，只拉取所需文件并顺利完成工程编译。

✅ 适用对象：GD32VW553H-EVAL 开发者
✅ 开发环境：Windows / Linux / macOS 均可
✅ 编译器：RISC‑V GCC 工具链
✅ 构建系统：SCons

🛠 环境准备

1. 安装 Git

请确保 Git 版本不低于 2.25 ，以支持完整的稀疏检出功能。

👉 Git 官网下载

2. 安装 RISC‑V 工具链

本项目需要 RISC‑V GCC 工具链，我使用的是兆易创新官方提供的。从工具链下载链接下载应用软件选项中的GD32 Embedded Builder。从压缩文件GD32EB_v1.5.8_Rel.7z中查找\GD32EB_v1.5.8_Rel\GD32EB\plugins\com.gd.tools_1.0.0.202512091458\Tools目录下查找RISC-V Embedded GCC即可，其他文件都不需要。

示例安装路径：D:\gd32\RISCVEmbeddedGCC\bin

工具链前缀：riscv-none-embed-

3. 安装 RTT-Thread ENV

GD32VW553开发板的BSP在RT-Thread Studio中无法使用，必须使用RTT-Thread ENV构建。可以从RT-Thread官方网站下载RTT-Thread ENV。如果已经安装了RT-Thread Studio，也可以直接使用RT-ThreadStudio\platform\env_released\env-new目录下的ENV环境。

⬇️ 下载BSP步骤

🔹 方法一：稀疏检出（强烈推荐）

此方法仅下载约几十 MB 的必要文件，非常适合网络或存储受限的场景。

bash 复制代码

# 1. 创建并进入工作目录
mkdir rt-thread && cd rt-thread

# 2. 初始化仓库并启用稀疏检出
git init
git remote add origin https://github.com/RT-Thread/rt-thread.git
git config core.sparseCheckout true

# 3. 配置稀疏检出规则
echo "/*" >> .git/info/sparse-checkout
echo "!/bsp/*" >> .git/info/sparse-checkout
echo "/bsp/gd32/risc-v/gd32vw553h-eval/" >> .git/info/sparse-checkout
echo "/bsp/gd32/risc-v/libraries/" >> .git/info/sparse-checkout
echo "/libcpu/" >> .git/info/sparse-checkout
echo "/src/" >> .git/info/sparse-checkout
echo "/include/" >> .git/info/sparse-checkout
echo "/components/" >> .git/info/sparse-checkout
echo "/tools/" >> .git/info/sparse-checkout

# 4. 拉取代码（以 master 分支为例）
git pull origin master

稀疏检出规则说明：

规则	作用
`/*`	包含根目录下所有文件
`!/bsp/*`	排除全部 BSP 子目录
`/bsp/gd32/risc-v/gd32vw553h-eval/`	仅包含目标 BSP
`/bsp/gd32/risc-v/libraries/`	包含 BSP 依赖的库文件
`/libcpu/`	包含 CPU 架构相关代码
`/src/` `/include/` `/components/` `/tools/`	RT‑Thread 内核与构建工具

🔸 方法二：完整克隆

如果网络和硬盘空间充足，可以直接克隆整个 RT‑Thread 仓库：

bash 复制代码

git clone https://github.com/RT-Thread/rt-thread.git

⚙️ 编译步骤

1. 进入 BSP 目录

bash 复制代码

cd rt-thread/bsp/gd32/risc-v/gd32vw553h-eval

2. 安装软件包依赖

执行以下命令自动下载 gd32-riscv-series 软件包（含 GD32VW55x 标准外设库）：

bash 复制代码

pkgs --update

3. 执行编译

根据不同操作系统和习惯，选择一种方式设置工具链路径：

🪟 Windows CMD

bash 复制代码

set RTT_EXEC_PATH=D:\gd32\RISCVEmbeddedGCC\bin
scons -j%NUMBER_OF_PROCESSORS%

🪟 Windows PowerShell

bash 复制代码

$env:RTT_EXEC_PATH="D:\gd32\RISCVEmbeddedGCC\bin"
scons -j$env:NUMBER_OF_PROCESSORS

小贴士 ：若工具链已安装在 rtconfig.py 的默认路径下，则无需额外设置 RTT_EXEC_PATH。

4. 清理构建产物

如需重新编译，可先执行清理命令：

bash 复制代码

scons -c

📦 编译输出

构建成功后，BSP 根目录会生成以下文件：

文件	说明
`rtthread.elf`	ELF 可执行文件（含调试信息）
`rtthread.bin`	裸二进制文件（用于烧录）
`rtthread.map`	链接映射文件（查看内存布局）

典型输出示例：

bash 复制代码

Memory region         Used Size  Region Size  %age Used
           flash:       72404 B         4 MB      1.73%
             ram:        288 KB       288 KB    100.00%
   text    data     bss     dec     hex   filename
  71156   1200    7620   79976   13868   rtthread.elf

❓ 常见问题

Q1：`scons: *** missing SConscript file`

原因：稀疏检出遗漏了必需的依赖目录。
解决：检查 .git/info/sparse-checkout 是否包含 /bsp/gd32/risc-v/libraries/ 和 /libcpu/，然后执行 git read-tree -mu HEAD 更新工作区。

Q2：`Error: the toolchain path ... is not exist`

原因：rtconfig.py 中预设的工具链路径与实际不符。
解决：通过 RTT_EXEC_PATH 环境变量指定正确路径，或直接修改 rtconfig.py 文件中的 EXEC_PATH 变量。

Q3：`pkgs --update` 下载失败

原因：网络无法正常访问 GitHub。
解决：

为 Git 配置代理：git config --global http.proxy http://proxy:port
或手动下载 gd32-riscv-series 软件包并解压至 packages/ 目录。

Q4：RAM 占用显示 100%

原因：默认配置中 RAM 大小为 288 KB，若启用了较多驱动或组件可能接近上限。
解决：运行 menuconfig 裁剪不需要的功能，然后重新编译。

bash 复制代码

menuconfig

🔗 参考链接

🎉 至此，已成功拉取并编译了 GD32VW553H-EVAL 的 RT-Thread BSP，可以开始进行固件开发和调试了！