MCUQuickStart：一键生成 STM32 / GD32 的 Keil、CMake、RTOS 工程

关键词：STM32、GD32、Keil、CMake、FreeRTOS、RT-Thread Nano、嵌入式工程模板、PyQt6

做嵌入式开发时，很多时间并不是花在业务代码上，而是花在“把工程先搭起来”这件事上。

新建一个 STM32 / GD32 工程，通常要做这些事：

• 找 SDK、CMSIS、启动文件、标准外设库源码
• 新建 Keil 工程并配置文件分组
• 配 include path、设备宏、Flash 下载算法、RAM / ROM 地址
• 复制 main.c、中断文件、系统时钟文件
• 想用 FreeRTOS 或 RT-Thread Nano 时，还要处理移植文件、SysTick、PendSV、heap、编译器兼容问题
• 想用 CLion / VS Code 时，还要额外准备 GCC、CMake、链接脚本和启动文件

这些事情本身不一定难，但非常重复，而且小细节很多。

所以我做了一个小工具：MCUQuickStart。

它的目标很直接：把 STM32 / GD32 工程初始化这件重复劳动，变成几个选项，然后一键生成可编译工程。

1. MCUQuickStart 是什么

MCUQuickStart 是一个面向 STM32 / GD32 的 MCU 工程生成器。

它可以根据你选择的芯片型号、工程模板、可选库和构建方式，自动生成一个完整工程。

目前支持：

• Keil MDK .uvprojx 工程
• GCC + CMake 工程
• 裸机工程模板
• FreeRTOS 工程模板
• RT-Thread Nano 工程模板
• STM32F10x / STM32F4xx
• GD32F10x / GD32F4xx
• 8 MHz / 25 MHz 外部晶振选择
• 中英文界面
• 亮色 / 暗色主题

一句话概括：它不是 IDE，也不是 CubeMX 替代品，而是一个更轻量的工程脚手架。

适合那些你已经有官方 SDK，但不想每次都手动搭 Keil / CMake 工程的场景。

2. 支持的芯片系列

当前版本支持 4 个系列，共 37 个型号：

系列	内核	厂商	型号数
STM32F10x	Cortex-M3	STMicroelectronics	9
STM32F4xx	Cortex-M4	STMicroelectronics	6
GD32F10x	Cortex-M3	GigaDevice	8
GD32F4xx	Cortex-M4	GigaDevice	14

注意：MCUQuickStart 不内置、不分发芯片厂商 SDK。你需要先在本机准备好对应的官方 SDK 包，工具会从你指定的 SDK 根目录里自动匹配。

3. 准备 SDK 根目录

第一步是准备一个 SDK 根目录，把相关 SDK 放在同一个目录下。

例如可以是：

SDK_ROOT/
  GD32F10x_Firmware_Library_V2.3.0/
  GD32F4xx_Firmware_Library/
  STM32F10x_StdPeriph_Lib/
  STM32F4xx_DSP_StdPeriph_Lib/
  FreeRTOS-Kernel/
  rt-thread/

工具会自动匹配常见命名，也支持在首次使用时自动解压 SDK 根目录下的 .zip / .7z 包。

界面顶部的 SDK 根目录 区域会显示当前匹配结果：

![外

图中可以看到，工具已经匹配到：

GD32F10x_Firmware_Library_V2.3.0

这说明当前选择 GD32F10x 系列时，工具可以正常找到芯片库。

4. 选择芯片和工程参数

工程设置区域主要包含：

• 芯片系列
• 芯片型号
• 项目名称
• 外部晶振
• 输出目录

例如这里选择：

芯片系列：GD32F10x
芯片型号：GD32F103C8T6
项目名称：MCUQuickStartDemo
外部晶振：8 MHz
输出目录：blog_demo_output

这些信息会影响生成工程中的：

• 设备头文件
• 设备宏定义
• 启动文件
• system 文件
• Keil Flash 下载算法
• RAM / ROM 地址
• 时钟配置相关宏
• CMake 和链接脚本配置

这里比较重要的是 外部晶振。很多板子是 8 MHz，也有一些板子是 25 MHz。如果这个地方选错，工程虽然可能能编译，但系统时钟、串口波特率、定时器频率都可能不对。

5. 选择代码模板和可选库

下半部分是模板和可选库：

目前内置了三个代码模板：

模板	说明
空工程	最小 main()，适合从干净入口开始写
LED 闪烁	GPIO + 延时，适合新板点灯验证
串口打印	USART printf 重定向，适合调试输出

可选库目前包含：

选项	说明
FreeRTOS	生成 FreeRTOS 工程
RT-Thread Nano	生成 RT-Thread Nano 工程
GCC + CMake	在 Keil 工程之外，同时生成 CMake 工程

FreeRTOS 和 RT-Thread Nano 属于 RTOS 选项，一般二选一。GCC + CMake 可以和裸机或 RTOS 工程一起使用。

本文示例选择的是：

LED 闪烁
GCC + CMake

也就是生成一个 GD32F103C8T6 的 LED 示例工程，同时输出 Keil 和 CMake 两套构建入口。

6. 点击生成工程

参数选好后，点击 生成工程。

生成成功后，界面会出现绿色结果面板：

![外链图片转存

这个面板会显示：

项目创建成功 - 校验全部通过
检查：10 项通过，0 个警告，0 个错误

右侧还有 打开输出目录 按钮，方便直接进入生成后的工程文件夹。

本次示例生成出的目录结构大致如下：

MCUQuickStartDemo/
  APP/
  CMSIS/
  DRIVER/
  FIRMWARE/
  HARDWARE/
  MDK-ARM/
  STARTUP/
  SYSTEM/
  USER/
  CMakeLists.txt
  MCUQuickStartDemo.ld

其中：

目录 / 文件	作用
CMSIS/	CMSIS 相关头文件、设备文件、启动文件
FIRMWARE/	厂商标准外设库源码和头文件
USER/	用户入口代码、中断文件、main 文件
MDK-ARM/	Keil MDK 工程
STARTUP/	GCC 启动文件
CMakeLists.txt	CMake 构建入口
.ld	GCC 链接脚本

也就是说，生成完成后可以直接打开：

MDK-ARM/MCUQuickStartDemo.uvprojx

用 Keil 编译。

如果勾选了 GCC + CMake，也可以用 CLion / VS Code 打开整个工程目录。

7. 日志和校验报告

我觉得这个工具里比较实用的一个点是：不是只告诉你“生成完成”，还会把检查项写进日志。

日志区会显示类似这些内容：

[DONE] [CHECK] OK Project directory
[DONE] [CHECK] OK USER main.c
[DONE] [CHECK] OK Firmware headers - 23 files
[DONE] [CHECK] OK Firmware sources - 23 files
[DONE] [CHECK] OK Device header - CMSIS/GD/GD32F10x/Include/gd32f10x.h
[DONE] [CHECK] OK Keil startup - CMSIS/GD/GD32F10x/Source/ARM/startup_gd32f10x_md.s
[DONE] [CHECK] OK Keil project - MDK-ARM/MCUQuickStartDemo.uvprojx
[DONE] [CHECK] OK CMakeLists.txt - CMakeLists.txt
[DONE] [CHECK] OK Linker script - MCUQuickStartDemo.ld
[DONE] [CHECK] OK GCC startup - STARTUP/startup_gd32f10x_md.s

这些检查项主要用于确认：

• 工程目录是否创建成功
• USER/main.c 是否生成
• 标准外设库头文件是否复制
• 标准外设库源码是否复制
• 设备头文件是否存在
• Keil 启动文件是否存在
• Keil 工程是否生成
• CMakeLists 是否生成
• 链接脚本是否生成
• GCC 启动文件是否找到

日志区右上角还有几个按钮：

按钮	作用
复制诊断信息	把当前工程参数、检查结果复制到剪贴板
保存日志	将日志保存成文本文件
清空	清空当前日志显示

如果生成失败，比如 SDK 没找到、输出目录不可写、缺少 FreeRTOS 包，日志里也会显示对应错误。这样排查问题会比弹一个简单报错框舒服很多。

8. FreeRTOS 和 RT-Thread Nano 做了什么

如果勾选 FreeRTOS，工具会根据芯片配置自动处理：

• FreeRTOS kernel 源码
• Cortex-M3 / Cortex-M4F port
• heap 文件，例如 heap_4.c
• FreeRTOSConfig.h
• RTOS 版本的中断文件
• SysTick 相关配置

如果勾选 RT-Thread Nano，工具会处理：

• Nano 内核源码
• Cortex-M port 文件
• rtconfig.h
• board.c
• 中断适配文件
• ARMCC V5 / C90 兼容问题

这部分的价值在于：你不需要每次都手工确认 port 文件和中断入口，也不需要重复处理编译器兼容细节。

当然，生成出来的工程仍然是普通 C 工程，你可以继续按自己的项目风格修改。

9. 亮色 / 暗色主题和中英文界面

工具支持亮色和暗色主题。

也支持中文和英文界面。

这个项目不是一个复杂 IDE，但我希望它至少是一个愿意长期打开的小工具。所以界面上也做了一些细节，比如：

• 下拉框弹层贴合控件位置
• 下拉选项数量少时自动收缩高度
• 选项多时只显示部分并滚动
• 主题化圆角和边框
• 中英文切换后语言项同步本地化
• 日志区区分成功、警告、错误信息

这些东西看起来小，但对工具手感影响很明显。

10. 适合哪些人

我觉得 MCUQuickStart 比较适合这些人：

• 经常新建 STM32 / GD32 工程
• 经常需要快速验证新板子
• 喜欢标准外设库，不想每次手搭 Keil
• 想快速生成 LED / UART / RTOS 示例
• 想同时保留 Keil 和 CMake 工作流
• 团队里有新人，需要给他一个可编译的工程起点
• 不想把半天时间花在复制文件和配 include path 上

它不追求大而全，核心目标就是把“起工程”这件事做快、做稳。

11. 下载和源码运行

项目地址：

GitHub: https://github.com/Majie-xixi/MCUQuickStart
Gitee : https://gitee.com/mj_yyfddca/mcu_quick_start

如果这个工具刚好帮你省掉了搭工程的时间，也欢迎顺手在 GitHub 点个 Star。Star 对这种个人开源小工具很有帮助，可以让更多嵌入式开发者发现它。

如果使用打包版本，可以下载 MCUQuickStart.exe 直接运行。

如果从源码运行：

pip install -r requirements.txt
python main.py

GUI 基于 PyQt6。

12. 注意事项

使用前需要注意几点：

1. 本工具不分发厂商 SDK。
2. 需要你自己准备 STM32 / GD32 官方 SDK。
3. 如果要生成 FreeRTOS 工程，需要准备 FreeRTOS Kernel。
4. 如果要生成 RT-Thread Nano 工程，需要准备 RT-Thread Nano。
5. 生成工程中复制出的厂商 SDK 文件，仍然受原 SDK 的许可证约束。

13. 后续计划

后续可以继续做的方向包括：

• 支持更多芯片系列
• 增加更多板级模板
• 增加 lwIP 等中间件集成
• 增加更多 RTOS 示例工程
• 增加工程体检功能
• 输出更详细的生成报告
• 增加更多适配芯片的 linker script 和 startup 规则

结语

MCUQuickStart 不是一个庞大的平台，它更像是嵌入式开发里的一个小型加速器。

每次新建 STM32 / GD32 工程时，少配几次路径，少找几次启动文件，少踩几个 RTOS 移植坑，节省下来的时间就可以直接拿来写真正的业务代码。

如果你也经常被工程初始化打断节奏，可以试试这个工具。

如果它对你有用，欢迎到 GitHub 给 MCUQuickStart 点一个 Star。这个小动作对项目继续维护和传播都很有帮助。