3. LVGL 9.3 跨平台模拟器实战：VSCode + CMake + SDL2 一站式环境构建指南

1. 为什么选择 LVGL PC 模拟器从嵌入式到桌面的开发革命如果你正在开发智能手表、智能家居中控屏或者任何带屏幕的嵌入式设备那你大概率听说过 LVGL。它是一个用 C 语言编写的、资源占用极低、功能却异常强大的开源图形库是嵌入式 UI 开发的“瑞士军刀”。但嵌入式开发有个老毛病每次修改一个按钮的颜色、测试一个动画效果都得编译、烧录、上板子看结果一套流程下来几分钟就没了调试效率低得让人抓狂。这时候一个能在你电脑上直接运行的 LVGL 模拟器就显得无比珍贵。它让你能像开发普通桌面应用一样写完代码一键编译运行立马在电脑屏幕上看到 UI 效果用鼠标就能点击交互。这不仅仅是省下了烧录的时间更是将开发-调试的循环从“分钟级”缩短到了“秒级”体验上有质的飞跃。在众多 LVGL 的 PC 端移植方案中lv_port_pc_vscode这个项目是我目前最推荐的一个没有之一。我尝试过好几种搭建方式有的配置复杂有的对 LVGL 版本支持滞后还有的跨平台性不好。而这个项目完美地避开了这些坑。首先它紧跟 LVGL 的主版本我们这次用的 9.3 就是最新稳定版你能用到所有新特性和优化。其次它基于 CMake 和 SDL2这意味着你可以在 Windows、macOS 和 Linux 上使用几乎相同的流程搭建环境真正做到了“一次学习到处使用”。最后它的工程结构非常清晰把 LVGL 核心库、驱动层和你的应用代码分得明明白白既方便学习也便于后续把你调试好的 UI 代码移植到真实的硬件上。所以无论你是 LVGL 的初学者想找个地方练手而不必着急买开发板还是经验丰富的嵌入式工程师急需一个高效的桌面仿真环境来加速 UI 迭代这套 VSCode CMake SDL2 的组合拳都能为你提供一个稳定、强大且现代化的开发基地。接下来我就手把手带你走通从零开始的全过程我会把每一步的原理、操作和可能遇到的“坑”都讲清楚确保你能一次搭建成功。2. 战前准备搞定所有必需资源的下载搭建环境就像拼乐高第一步是把所有正确的零件找齐。这里我们需要四样东西lv_port_pc_vscode工程模板、CMake 构建工具、MinGW 编译工具链、SDL2 图形库以及 LVGL 9.3 的核心源码。别担心我会给你提供最直接的获取路径和版本选择建议。2.1 获取工程模板lv_port_pc_vscode这是我们的“施工图纸”。访问它在 GitHub 上的仓库https://github.com/lvgl/lv_port_pc_vscode。这里有个关键点我们要使用对应 LVGL 9.3 的版本以确保兼容性。不要直接下载默认的main分支代码。操作步骤进入仓库页面后点击分支切换按钮通常显示为main或master。在分支列表中找到并选择release/v9.3这个分支。切换后网页显示的代码就是为 9.3 版本适配好的。点击绿色的 “Code” 按钮选择 “Download ZIP”将整个项目模板下载到你的电脑上。解压到一个你容易找到的目录比如D:\Projects\lvgl_simulator。我建议路径中不要有中文或空格避免一些不必要的麻烦。如果你熟悉 Git用命令git clone -b release/v9.3 https://github.com/lvgl/lv_port_pc_vscode.git克隆指定分支会更方便。拿到这个模板我们环境的基础框架就有了。2.2 安装构建与编译核心CMake 和 MinGW这是我们的“工具链”。CMake 是一个跨平台的构建系统生成器它读取我们写的CMakeLists.txt文件然后为你当前的操作系统和编译器生成对应的构建脚本比如 Makefile 或 Visual Studio 项目。MinGW 则是 Windows 下的一个 GNU 开发环境它提供了 GCC 编译器、GDB 调试器等一套工具让我们能在 Windows 上编译出原生程序。CMake 安装前往 CMake 官网下载安装程序。选择最新稳定版的Windows x64 Installer。安装时记得勾选 “Add CMake to the system PATH for all users” 或 “Add CMake to the system PATH” 选项。这非常重要它允许你在命令行或 VSCode 中直接调用cmake命令。安装完成后打开命令提示符CMD或 PowerShell输入cmake --version如果能看到版本号说明安装和 PATH 配置成功。MinGW 安装 我推荐使用 MSYS2 来安装 MinGW因为它自带强大的包管理器pacman管理依赖库非常方便。访问 MSYS2 官网下载并安装 MSYS2。安装完成后从开始菜单打开MSYS2 MinGW 64-bit这个终端注意不是 MSYS2 UCRT64也不是 MSYS2 MSYS。在终端中输入命令pacman -S mingw-w64-x86_64-toolchain然后按回车。它会询问你安装哪些包直接按回车选择全部安装即可。安装完成后同样需要将 GCC 添加到系统 PATH。通常MinGW 的 GCC 编译器位于 MSYS2 安装目录下的mingw64\bin文件夹内例如C:\msys64\mingw64\bin。将这个路径添加到你的系统环境变量 PATH 中。打开一个新的命令提示符输入gcc --version确认能看到 GCC 版本信息。2.3 下载图形后端SDL2 开发库SDLSimple DirectMedia Layer是一个跨平台的多媒体库它封装了不同操作系统的音视频、输入设备等底层接口。lv_port_pc_vscode项目使用 SDL2 来创建窗口、处理鼠标键盘事件、并在屏幕上绘制像素充当了 LVGL 在 PC 上的“显示器”和“输入设备”。关键选择由于我们使用 MinGW 作为编译器必须下载与之匹配的 SDL2 开发库。你需要下载SDL2 的 MinGW 预编译版本。前往 SDL 的官方发布页面https://github.com/libsdl-org/SDL/releases。在最新的发布版本中例如 SDL2-2.30.x找到名为SDL2-devel-2.30.x-mingw.zip的文件注意是mingw后缀。下载这个压缩包。将其解压到一个目录比如D:\Libraries\SDL2-2.30.x-mingw。解压后的文件夹里会包含include,lib,bin等子文件夹这就是我们需要的全部内容。2.4 获取引擎核心LVGL 9.3 源码最后是 LVGL 图形库本身的源代码。它才是我们真正要“驾驶”的引擎。访问 LVGL 的 GitHub 仓库https://github.com/lvgl/lvgl。同样我们需要切换到release/v9.3分支。在仓库页面点击 “Branch”选择release/v9.3。点击 “Code” - “Download ZIP”下载 LVGL 9.3 的完整源码。解压备用。至此所有“乐高零件”已经准备就绪。下一章我们开始动手组装。3. 工程初始化将源码整合到 VSCode 项目中现在我们要把下载好的各部分资源按照正确的结构组织起来形成一个完整的、可构建的 VSCode 项目。这一步是搭建成功的关键结构错了后面编译肯定会出问题。3.1 导入 LVGL 核心源码首先用 VSCode 打开你之前解压的lv_port_pc_vscode工程目录。在左侧的资源管理器里你会看到项目自带的lvgl文件夹但里面可能是空的或者只有一些占位文件。我们需要用真正的 LVGL 9.3 源码替换它。操作步骤打开你解压的lvgl-release-v9.3文件夹。选中里面所有的文件和文件夹包括src,examples,lv_conf.h等。将它们全部复制。回到 VSCode 中在资源管理器里点击项目自带的lvgl文件夹然后粘贴。如果系统询问是否覆盖或合并选择覆盖或全部替换。这样LVGL 完整的源代码就集成到我们的项目里了。这个lvgl目录就是图形库的本体后续我们自己的 UI 代码会调用这里的函数。3.2 集成 SDL2 依赖库接下来要把 SDL2 库引入项目。lv_port_pc_vscode项目已经通过 CMake 脚本写好了寻找 SDL2 的逻辑我们只需要告诉它 SDL2 放在哪里。操作步骤在你项目的根目录下与lvgl文件夹同级新建一个文件夹可以命名为sdl2或libs我习惯用libs这样更清晰。将你之前解压的 SDL2 MinGW 开发包例如SDL2-2.30.x-mingw里的所有内容复制到这个新建的libs文件夹内。最终你的项目里应该有一个libs\include、libs\lib、libs\bin这样的结构。现在需要修改 CMake 的配置让它知道去哪里找 SDL2。在项目根目录找到CMakeLists.txt文件用 VSCode 打开。寻找其中设置SDL2_PATH的语句。通常模板里会有一行类似set(SDL2_PATH “”)的代码引号里是空的。我们需要把它修改为 SDL2 在我们项目中的相对路径。例如如果你把 SDL2 放在了libs文件夹里就修改为set(SDL2_PATH “${CMAKE_SOURCE_DIR}/libs”)这里的${CMAKE_SOURCE_DIR}是一个 CMake 变量代表你项目根目录的绝对路径。这样设置后CMake 就会去你的项目/libs下面寻找 SDL2 的头文件和库文件。3.3 配置项目并触发首次构建一切就绪现在可以开始配置和构建项目了。VSCode 本身并不直接管理 C/C 项目的构建我们需要借助扩展。这里我强烈推荐使用微软官方的CMake Tools扩展它和 VSCode 的集成度最高用起来最顺手。操作步骤在 VSCode 的扩展商店中搜索并安装 “CMake Tools”。安装后VSCode 底部状态栏会多出一排按钮。首先我们需要选择“工具链”也就是编译器。点击状态栏上显示 “No Kit Selected” 或类似字样的地方或者按CtrlShiftP打开命令面板输入 “CMake: Select a Kit” 并选择。在弹出的列表中找到你安装的 MinGW GCC 编译器例如 “GCC x.x.x mingw-w64 x86_64”。选中它。接下来选择“构建目标”。点击状态栏上 “No Configure” 旁边的齿轮按钮或者使用命令 “CMake: Configure”。CMake Tools 会自动读取根目录的CMakeLists.txt并根据你选择的 Kit 生成构建文件。这个过程会在项目根目录下生成一个build文件夹里面存放所有中间文件和最终的生成配置。配置成功后状态栏会显示构建目标通常是 “lv_port_pc_vscode (Executable)”。此时你可以点击状态栏上的“构建”锤子图标按钮或者按F7键开始编译整个项目。如果一切依赖路径都设置正确编译应该会顺利进行。但第一次搭建很可能会遇到一些编译或链接错误别慌这很正常。下一章我们就来专门解决这些常见的“拦路虎”。4. 排坑指南解决编译与运行中的典型问题即使按照步骤操作由于系统环境差异你很可能还是会遇到一两个错误。我把最常见的问题和解决方案整理出来你遇到问题时可以来这里对照排查。4.1 错误一找不到glob.h头文件在编译过程中你可能会看到类似这样的报错fatal error: glob.h: No such file or directory这个错误通常出现在main.c文件里。glob.h是 POSIX 标准下的一个头文件用于文件名扩展模式匹配但在 Windows 的 MinGW 环境下可能不完整或缺失。lv_port_pc_vscode的模板代码可能在某些版本中使用了它来扫描示例文件。解决方案在 VSCode 中打开项目根目录下的main.c文件。搜索#include “glob.h”这行代码。最简单直接的办法是将其注释掉。在这行前面加上//// #include “glob.h”同时搜索文件中所有使用glob()和globfree()函数的地方。通常它们被用来遍历lvgl/examples目录。你可以暂时将这些代码块也注释掉或者用一个简单的文件遍历逻辑替换如果你不需要动态加载示例。对于初次搭建以跑通环境为目标注释掉是最快的方法。保存文件后重新触发 CMake 配置在CMakeLists.txt上按CtrlS并再次构建。4.2 错误二链接器报错undefined reference to ‘SDL_main’编译通过但在链接阶段你可能会遇到这个错误undefined reference to SDL_main’这个错误非常典型。SDL2 库要求你的程序入口点不是标准的main而是一个由 SDL 宏包装过的SDL_main。但在我们的main.c里我们写的函数名就是main。解决方案 这个问题通常不是代码写错了而是链接时缺少了 SDL2 库的正确链接。我们需要确保 CMake 找到了 SDL2 库并正确链接。请按以下步骤检查检查SDL2_PATH再次确认CMakeLists.txt中的SDL2_PATH变量是否指向了正确的、包含lib和include文件夹的 SDL2 根目录。检查 CMake 输出在 VSCode 的输出面板选择 “CMake/Build” 或 “CMake/Config”查看配置阶段的输出日志。寻找是否有 “Found SDL2” 这样的成功信息。如果显示 “Could NOT find SDL2”说明路径设置不对。手动指定库路径如果 CMake 的自动查找失败可以在CMakeLists.txt中find_package(SDL2 REQUIRED)语句附近手动指定库文件。在set(SDL2_PATH …)语句后可以添加include_directories(${SDL2_PATH}/include) link_directories(${SDL2_PATH}/lib)然后在target_link_libraries语句中确保链接了SDL2main和SDL2。完整的链接语句应该类似target_link_libraries(${PROJECT_NAME} PRIVATE lvgl lvgl_drivers SDL2::SDL2 SDL2::SDL2main)注意SDL2::SDL2main必须放在SDL2::SDL2的后面这是链接顺序的要求。4.3 错误三程序一闪而过或运行无窗口这是最让人困惑的情况编译成功了没有报错点击运行后终端窗口可能闪了一下或者程序看起来执行了但什么窗口都没弹出来。根本原因运行时缺少SDL2.dll动态链接库。我们的程序在编译时链接了 SDL2 的导入库.a或.lib文件但实际运行时需要调用SDL2.dll这个动态库文件。解决方案 我们需要将SDL2.dll复制到生成的可执行文件.exe所在的目录。找到你下载的 SDL2 MinGW 开发包中的bin文件夹里面应该有一个SDL2.dll文件。在你的项目build目录下找到最终生成的可执行文件。通常路径类似build/lv_port_pc_vscode.exe。将SDL2.dll文件复制到与这个.exe文件相同的目录下。一个更一劳永逸的方法是让 CMake 在构建过程中自动完成拷贝。在你的CMakeLists.txt文件中找到构建目标之后的部分添加以下命令# 假设你的 SDL2.dll 在之前设置的 SDL2_PATH 的 bin 目录下 add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy “${SDL2_PATH}/bin/SDL2.dll” “$TARGET_FILE_DIR:${PROJECT_NAME}” )这样每次编译成功后CMake 会自动将SDL2.dll拷贝到输出目录。重新构建并运行程序此时应该能看到一个灰色的 SDL2 窗口成功弹出并且终端可能打印出 LVGL 的初始化信息。恭喜你环境搭建成功了5. 探索与进阶运行示例与开发自己的 UI环境搭建完成只是万里长征第一步。接下来我们要让这个模拟器真正为我们所用。5.1 运行内置示例验证环境lv_port_pc_vscode项目模板的main.c里默认可能已经包含了一些调用 LVGL 示例的代码。如果之前你因为glob.h错误注释掉了示例加载部分现在可以尝试恢复一个简单的示例来测试。打开main.c找到main函数。在 LVGL 初始化 (lv_init())、驱动初始化 (lv_port_disp_init()等) 之后你可以直接调用 LVGL 内置的示例函数。例如在while(1)主循环开始之前添加一行lv_demo_widgets(); // 运行 widgets 示例lv_demo_widgets()是 LVGL 自带的一个非常丰富的控件演示。重新编译运行你应该能看到一个包含按钮、滑块、图表、下拉列表等各式各样控件的精美 UI 界面并且可以用鼠标进行交互。这彻底证明了你的 PC 模拟器环境完全正常工作和你在官方文档或视频里看到的效果一模一样。5.2 开始你的第一个 LVGL 项目清空示例代码让我们从零创建一个自己的窗口。在main.c的合适位置驱动初始化之后主循环之前编写你的第一个 UI// 创建一个简单的按钮 lv_obj_t * btn lv_btn_create(lv_scr_act()); // 在默认屏幕上创建按钮 lv_obj_set_size(btn, 100, 50); // 设置大小 lv_obj_center(btn); // 居中显示 // 为按钮添加一个标签 lv_obj_t * label lv_label_create(btn); lv_label_set_text(label, “Click Me!”); lv_obj_center(label); // 给按钮添加一个点击事件 lv_obj_add_event_cb(btn, my_btn_event_handler, LV_EVENT_CLICKED, NULL);同时你需要定义事件处理函数my_btn_event_handlerstatic void my_btn_event_handler(lv_event_t * e) { lv_event_code_t code lv_event_get_code(e); if(code LV_EVENT_CLICKED) { static uint8_t cnt 0; cnt; // 获取按钮上的标签并修改文字 lv_obj_t * label lv_obj_get_child(e-target, 0); lv_label_set_text_fmt(label, “Clicked: %d”, cnt); } }编译运行你会看到一个居中的按钮点击它按钮上的文字会变化。这就是 LVGL 开发的基本范式创建对象、设置属性、添加事件回调。在 PC 模拟器上你可以飞快地迭代这个界面调整颜色、位置、动画而无需等待任何硬件。5.3 高效开发技巧与调试拥有了这个环境你的开发效率可以大幅提升。首先善用 VSCode 的智能感知。由于 CMake 正确配置了包含路径VSCode 的 C/C 扩展能对 LVGL 的 API 进行自动补全和函数提示这比在嵌入式 IDE 里手动查手册方便太多。其次结合 LVGL 的在线文档和示例。LVGL 官方文档非常详细几乎所有函数都有说明。当你想实现一个复杂控件比如列表、图表时先去lvgl/examples目录下找对应的示例代码把它复制到你的项目里稍作修改这是最快的学习方式。最后不要忽视模拟器的调试能力。你可以在 VSCode 中配置 CMake Tools 进行调试。在状态栏选择 “Debug” 目标然后按F5就可以设置断点、单步执行、查看变量这对于理解 LVGL 内部运行机制、排查复杂 UI 逻辑问题至关重要。这是真实硬件调试难以比拟的优势。从痛苦的交叉编译、烧录、调试循环中解放出来在舒适的桌面环境下享受秒级的代码修改和效果反馈这正是搭建 LVGL PC 模拟器的最大意义。它不仅仅是一个“模拟器”更是你探索 LVGL 强大功能、打磨完美 UI 交互的创意工坊和试验场。