LVGL Windows 仿真环境搭建方案
| 项目 | 值 |
|---|---|
| 目标 | 在 Windows 上仿真运行 LVGL v8.3 |
| 工具链 | msys2 + UCRT64 + mingw-w64 |
| IDE | VSCode + CMake Tools 扩展 |
| 后端 | SDL2(显示/鼠标/键盘) |
| 决策日期 | 2026-09-28 |
1. 方案结论
采用 msys2 (UCRT64) + mingw-w64 + SDL2 路线,完全替换最初"独立 mingw64"思路。理由:
| 收益 | 缺点 |
|---|---|
| pacman 一键装 SDL2/cmake/gdb,避免手动塞二进制 | 多装一个 msys2,占 ~1.5GB |
| UCRT64 是当前 MSYS2 官方推荐 ABI,兼容性最好 | 终端是 MSYS2 shell,日常用 Windows Terminal 启动 |
与项目CMakeLists.txt(依赖 find_package(SDL2))天然兼容 |
--- |
2. 架构与目录约定
| 角色 | 路径 |
|---|---|
| MSYS2 安装根 | D:\msys64(避开 C 盘,无空格/中文) |
| 工具链 | D:\msys64\ucrt64\bin(gcc/make/SDL2.dll 在此) |
| 项目根 | E:\royogo\lvgl-study\lvgl_template_v8.3 |
| 构建产物 | <项目根>/build/(cmake -B build) |
| 可执行 | <项目根>/build/main.exe |
3. 一次性安装步骤(人工)
W1 ~ W3 必须在 Windows 终端人工执行,后续步骤可由 VSCode 完成。
W1. 安装 msys2
选一条下载(网络不通就换镜像):
| 项 | 操作 |
|---|---|
| 安装到 | D:\msys64 |
| 注意 | 路径无空格、无中文,否则 SDL2/gcc 会报奇怪错误 |
W1.5. 换清华源(国内网络必做,否则 pacman 极慢)
打开 MSYS2 UCRT64,执行:
bash
sed -i "s#https\?://mirror.msys2.org/#https://mirrors.tuna.tsinghua.edu.cn/msys2/#g" \
/etc/pacman.d/mirrorlist*
pacman -Sy清华源同时覆盖 msys2 / mingw64 / ucrt64 三组仓库。镜像列表备份: https://mirrors.tuna.tsinghua.edu.cn/msys2/
W2. 在 MSYS2 UCRT64 终端初始化与装包
打开 MSYS2 UCRT64(开始菜单里的 "MSYS2 UCRT64"),依次执行:
bash
pacman -Syu # 全量更新基础包,完成后会提示关闭窗口
# 重新打开 UCRT64 终端
pacman -Su # 完成剩余更新
pacman -S --needed \
mingw-w64-ucrt-x86_64-toolchain \
mingw-w64-ucrt-x86_64-cmake \
mingw-w64-ucrt-x86_64-ninja \
mingw-w64-ucrt-x86_64-SDL2 \
mingw-w64-ucrt-x86_64-gdb验证:
bash
gcc --version # 应输出 x86_64-w64-windows-gnu
cmake --version
pkg-config --modversion sdl2 # 应输出 2.x.x
W3. 加入 Windows PATH
把以下加入 系统环境变量 PATH(用户级即可):
D:\msys64\ucrt64\bin顺序很重要:放在
C:\ProgramData\mingw64\mingw64\bin前面,避免 VSCode 抓到旧 gcc。
验证(新开 PowerShell):
powershell
where gcc # 必须是 D:\msys64\ucrt64\bin\gcc.exe
4. 项目侧配置(本仓库内可一键完成)
| 文件 | 作用 |
|---|---|
.vscode/settings.json |
指定 CMake 工具链/生成器 |
.vscode/tasks.json |
提供 build / clean 任务 |
.vscode/launch.json |
提供 gdb 调试入口 |
.vscode/cmake-kits.json |
让 CMake Tools 识别 UCRT64 |
.gitignore |
忽略 build/ 与缓存 |
详见 §6 文件清单。
5. 构建与运行流程
在项目根目录
E:\lvgl-study\lvgl_template_v8.3下操作。
方式 A:命令行(脚本)
powershell
Remove-Item -Recurse -Force build -ErrorAction SilentlyContinue
cmake -G "MinGW Makefiles" -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j
.\bin\main.exe
方式 B:VSCode
- 安装扩展:
CMake Tools、C/C++ - 底部状态栏:
[No Kit]→ 选GCC for UCRT64 - 状态栏:
[No Build]→ 选Debug Ctrl+Shift+P→CMake: Build→ 终端出现[100%] Built target mainF5启动调试,弹出 SDL 窗口
6. 文件清单与变更点
| 路径 | 类型 | 说明 |
|---|---|---|
.vscode/settings.json |
新增 | CMake generator / build dir |
.vscode/tasks.json |
新增 | build / clean 任务 |
.vscode/launch.json |
新增 | gdb 调试 |
.vscode/cmake-kits.json |
新增 | UCRT64 kit |
.gitignore |
新增 | 忽略 build/、CMakeFiles/ |
CMakeLists.txt/main.c不改动,已验证与 SDL2 兼容。
7. 故障速查
| 现象 | 根因 | 解决 |
|---|---|---|
Could NOT find SDL2 (missing: SDL2_DIR) |
PATH 没指向ucrt64\bin |
重做 W3,新开终端 |
undefined reference to WinMain |
SDL_MAIN_HANDLED 未定义 |
检查main.c 第 13 行 |
链接报缺SDL2.dll |
运行时 PATH 没 SDL2.dll | 把D:\msys64\ucrt64\bin\SDL2.dll 加入 PATH |
| 编译超慢 | 用了默认 MSVC generator | 强制-G "MinGW Makefiles" |
gcc 抓到 C:\ProgramData\mingw64\mingw64\bin\gcc.exe |
PATH 顺序 | 把 ucrt64 路径前移并重开终端 |
8. 回滚方案
如需彻底清除 msys2 方案:
powershell
Remove-Item -Recurse D:\msys64 # 卸载 msys2
[Environment]::SetEnvironmentVariable("Path", ($env:Path -replace "[^;]*ucrt64\\bin;?", ""), "User")
Remove-Item -Recurse .vscode # 还原 IDE 配置