1. 为什么选择 ImGUI + CMake + MinGW64 这套组合?
如果你是一个 C++ 开发者,想给自己的小工具、游戏编辑器或者某个内部应用做个图形界面,但又不想去折腾那些庞大复杂的 GUI 框架,那 ImGUI 绝对是你的“梦中情库”。我第一次接触它的时候,感觉就像发现了一个宝藏——它太轻量了,直接把源码拖进项目就能用,没有一堆依赖和繁琐的配置。但问题来了,很多新手教程要么只讲 ImGUI 本身,要么环境搭建步骤语焉不详,特别是对于 Windows 平台下喜欢用 MinGW(也就是 GCC 的 Windows 移植版)的朋友,经常卡在编译和链接这一步。
所以,我决定写一份真正“从零开始”的指南。我们不依赖任何现成的项目模板,就用手头最基础的工具:CMake 作为项目构建的管理者,MinGW64 作为我们的编译器,GLFW 负责创建窗口和处理输入,OpenGL 负责渲染。这套组合的优势非常明显:完全开源、跨平台潜力大、构建过程透明可控。你跟着走一遍,不仅能跑起来一个 ImGUI 窗口,更能彻底理解每个文件是干什么的,CMake 每一行命令背后的意义。以后无论项目怎么变,你都能自己调整,这才是真正的“上手”。
我见过不少朋友,直接克隆别人的 CMake 项目,虽然能运行,但一旦需要添加新库或者修改结构,就一头雾水。咱们这个指南,就是要解决这个问题。我们会从下载每一个原材料开始,像搭积木一样,亲手组装起整个开发环境。放心,过程我会讲得非常细,包括我踩过的那些坑,比如 MinGW 的路径问题、CMake 生成器选择、静态库的链接顺序等等,都会一一说明白。目标只有一个:让你在 Windows 上,拥有一个干净、健壮、可扩展的 ImGUI 项目起点。
2. 兵马未动,粮草先行:准备你的“武器库”
在开始写代码之前,我们需要把所有的工具和库都准备好。这就像做饭前要备好菜和调料,缺一样都开不了火。别担心,我会提供详细的下载链接和验证方法。
2.1 安装编译器和构建工具
首先,我们需要 MinGW-w64 和 CMake。
- MinGW-w64:这是我们的核心编译器。不要去下载老旧的 MinGW,一定要找 MinGW-w64。我推荐直接从 SourceForge 下载离线包。选择
x86_64-posix-seh这个版本,它对 C++ 线程支持更好,性能也更优。下载下来是一个压缩包,解压到你喜欢的目录,比如D:\Dev\mingw64。然后,最关键的一步:把这个目录下的bin文件夹(例如D:\Dev\mingw64\bin)添加到系统的PATH环境变量里。添加完后,打开一个新的命令行窗口,输入g++ --version和make --version,如果能看到版本信息,就说明安装成功了。 - CMake:从官网下载安装程序,安装时记得勾选 “Add CMake to the system PATH for all users” 这个选项,这样在命令行里就能直接用了。同样,安装完后在命令行输入
cmake --version验证一下。
2.2 获取 ImGUI 与 GLFW 源码
我们不用任何包管理器,就手动下载源码,这样最清晰。
- ImGUI:访问 ImGUI 的 GitHub 发布页面,下载最新的
Source code (zip)。解压后,你会看到一个结构清晰的文件夹。我们主要关心根目录下的那些.cpp和.h文件,以及backends/文件夹。 - GLFW:访问 GLFW 官网,下载 64-bit Windows pre-compiled binaries。这就是已经用 MinGW 编译好的库文件,省去了我们自己编译的麻烦。下载后解压,你会看到
include文件夹和lib-mingw-w64文件夹。
现在,你的“粮草”应该包括:一个配置好 PATH 的 MinGW-w64、CMake、ImGUI 的源码 zip、GLFW 的预编译包。接下来,我们开始创建项目结构。
3. 打造清晰的项目目录结构
一个清晰的项目结构是良好开发习惯的开始,它能让你和你的队友(或者未来的你)一眼就明白项目的构成。我们来创建一个全新的项目文件夹,就叫 MyImGuiApp 吧。
在你的工作区(比如 D:\Projects)创建这个文件夹,然后按照下面的结构建立子文件夹和文件。先不要放任何内容,只是创建空文件夹和空文件。
MyImGuiApp/
├── CMakeLists.txt # 项目总的构建脚本
├── lib/ # 存放所有第三方库
│ ├── glfw/ # GLFW 库
│ │ ├── include/ # (稍后放入 GLFW 的头文件)
│ │ └── lib/ # (稍后放入 GLFW 的库文件 .a)
│ └── imgui/ # ImGUI 库
│ ├── backend/ # (稍后放入 ImGUI 的后端实现文件)
│ └── # (稍后放入 ImGUI 的核心文件)
└── src/ # 存放我们自己的源代码
└── main.cpp # 我们的主程序文件
现在,我们来填充这个骨架。
- 填充 GLFW:把之前下载的 GLFW 预编译包里的
include/GLFW/整个文件夹,复制到lib/glfw/include/下。然后把lib-mingw-w64/文件夹下的libglfw3.a文件,复制到lib/glfw/lib/下。这个.a文件就是 MinGW 使用的静态链接库。 - 填充 ImGUI 核心:从 ImGUI 源码的根目录,复制以下文件到
lib/imgui/下:imconfig.himgui.cppimgui.himgui_demo.cpp(这个文件包含了所有控件的演示代码,对于学习和调试非常有用,建议保留)imgui_draw.cppimgui_internal.himgui_tables.cppimgui_widgets.cppimstb_rectpack.himstb_textedit.himstb_truetype.h
- 填充 ImGUI 后端:因为我们决定使用 GLFW + OpenGL3 这个后端组合,所以需要从 ImGUI 源码的
backends/文件夹里,复制以下文件到lib/imgui/backend/下:imgui_impl_glfw.himgui_impl_glfw.cppimgui_impl_opengl3.himgui_impl_opengl3.cppimgui_impl_opengl3_loader.h(这个文件帮助我们在 Windows 上动态加载 OpenGL 函数)
至此,你的 lib 文件夹应该被填满了。接下来,我们需要一个 main.cpp 来让一切动起来。
4. 编写第一个 ImGUI 程序:Hello, World!
现在,我们来编写 src/main.cpp。这个文件的内容可以直接从 ImGUI 源码仓库的 examples/example_glfw_opengl3/ 目录下的 main.cpp 复制过来。它是官方提供的一个完美可用的示例。为了让你理解每一部分在做什么,我在这里贴出核心代码并加上详细注释:
// 引入必要的头文件
#include "imgui.h"
#include "imgui_impl_glfw.h"
#include "imgui_impl_opengl3.h"
#include <stdio.h>
#define GL_SILENCE_DEPRECATION
#if defined(IMGUI_IMPL_OPENGL_ES2)
#include <GLES2/gl2.h>
#endif
#include <GLFW/glfw3.h> // 注意:这里包含的是我们放在 lib/glfw/include/ 下的头文件
// 一个简单的错误回调函数,如果GLFW出问题,错误信息会打印到控制台
static void glfw_error_callback(int error, const char* description)
{
fprintf(stderr, "GLFW Error %d: %s\n", error, description);
}
int main(int, char**)
{
// 1. 初始化GLFW库
glfwSetErrorCallback(glfw_error_callback);
if (!glfwInit())
return 1;
// 决定使用哪个版本的OpenGL (这里我们使用OpenGL 3.3,一个广泛支持的现代版本)
const char* glsl_version = "#version 130";
glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 3);
glfwWindowHint(GLFW_OPENGL_PROFILE, GLFW_OPENGL_CORE_PROFILE); // 使用核心模式,移除了旧的固定管线函数
// 2. 创建应用窗口
GLFWwindow* window = glfwCreateWindow(1280, 720, "我的第一个ImGUI程序", NULL, NULL);
if (window == NULL)
return 1;
glfwMakeContextCurrent(window); // 将OpenGL上下文绑定到当前窗口
glfwSwapInterval(1); // 开启垂直同步,防止画面撕裂
// 3. 初始化ImGUI上下文
IMGUI_CHECKVERSION();
ImGui::CreateContext();
ImGuiIO& io = ImGui::GetIO(); (void)io;
io.ConfigFlags |= ImGuiConfigFlags_NavEnableKeyboard; // 启用键盘控制
// 设置ImGUI样式(这里使用经典的深色风格)
ImGui::StyleColorsDark();
// 4. 初始化ImGUI的后端:GLFW和OpenGL3
ImGui_ImplGlfw_InitForOpenGL(window, true);
ImGui_ImplOpenGL3_Init(glsl_version);
// 主循环的状态变量
bool show_demo_window = true; // 控制是否显示ImGUI强大的演示窗口
bool show_another_window = false; // 控制是否显示我们自定义的另一个窗口
ImVec4 clear_color = ImVec4(0.45f, 0.55f, 0.60f, 1.00f); // 清屏颜色
// 5. 主渲染循环
while (!glfwWindowShouldClose(window))
{
// 处理系统事件(如鼠标、键盘、窗口大小改变)
glfwPollEvents();
// 开始新一帧的ImGUI绘制
ImGui_ImplOpenGL3_NewFrame();
ImGui_ImplGlfw_NewFrame();
ImGui::NewFrame();
// 1) 绘制ImGUI自带的演示窗口(强烈建议新手保留,它是学习所有控件用法的宝典)
if (show_demo_window)
ImGui::ShowDemoWindow(&show_demo_window);
// 2) 绘制一个我们自己定义的简单窗口
{
static float f = 0.0f;
static int counter = 0;
ImGui::Begin("你好,ImGUI!"); // 创建一个窗口
ImGui::Text("这是一个简单的文本。"); // 显示文本
ImGui::Checkbox("显示演示窗口", &show_demo_window); // 复选框,控制演示窗口
ImGui::SliderFloat("浮点数", &f, 0.0f, 1.0f); // 滑动条
ImGui::ColorEdit3("清屏颜色", (float*)&clear_color); // 颜色选择器
if (ImGui::Button("点击计数")) // 按钮
counter++;
ImGui::SameLine(); // 让下一个控件在同一行显示
ImGui::Text("按钮被点击了 %d 次", counter);
ImGui::Text("应用平均帧率: %.3f ms/frame (%.1f FPS)",
1000.0f / io.Framerate, io.Framerate);
ImGui::End();
}
// 3) 绘制第二个自定义窗口
if (show_another_window)
{
ImGui::Begin("另一个窗口", &show_another_window);
ImGui::Text("你好,这是另一个窗口!");
if (ImGui::Button("关闭我"))
show_another_window = false;
ImGui::End();
}
// ImGUI渲染准备完成,开始实际的OpenGL渲染
ImGui::Render();
int display_w, display_h;
glfwGetFramebufferSize(window, &display_w, &display_h);
glViewport(0, 0, display_w, display_h);
glClearColor(clear_color.x * clear_color.w, clear_color.y * clear_color.w,
clear_color.z * clear_color.w, clear_color.w);
glClear(GL_COLOR_BUFFER_BIT);
ImGui_ImplOpenGL3_RenderDrawData(ImGui::GetDrawData()); // 将ImGUI绘制数据交给OpenGL渲染
// 交换前后缓冲区,将渲染好的图像显示到屏幕上
glfwSwapBuffers(window);
}
// 6. 程序退出前的清理工作
ImGui_ImplOpenGL3_Shutdown();
ImGui_ImplGlfw_Shutdown();
ImGui::DestroyContext();
glfwDestroyWindow(window);
glfwTerminate();
return 0;
}
把这个文件保存到 src/main.cpp。现在,万事俱备,只欠 CMake 这个“总指挥”来把它们组织起来了。
5. 编写 CMakeLists.txt:项目的构建蓝图
CMakeLists.txt 是 CMake 的构建脚本,它告诉 CMake 如何编译我们的项目。在项目根目录 MyImGuiApp/ 下创建这个文件。下面我逐段解释一个完整、健壮的配置:
# 1. 指定CMake的最低版本要求
cmake_minimum_required(VERSION 3.10)
# 2. 定义项目名称和使用的编程语言
project(MyImGuiApp LANGUAGES CXX)
# 3. 设置C++标准为C++11(ImGUI和大多数现代库都兼容)
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
# 4. 告诉编译器去哪里找头文件(.h)
# 这相当于在代码里写 `#include <...>` 时,编译器会去这些目录搜索
include_directories(
lib/glfw/include # GLFW的头文件
lib/imgui # ImGUI核心头文件
lib/imgui/backend # ImGUI后端(GLFW/OpenGL3)的头文件
)
# 5. 告诉链接器去哪里找库文件(.a)
# 这里我们把GLFW的静态库路径加进来
link_directories(lib/glfw/lib)
# 6. 收集ImGUI的所有核心源码文件
# 使用 GLOB_RECURSE 可以自动递归地找到所有 .cpp 文件,非常方便
file(GLOB_RECURSE IMGUI_SRCS
lib/imgui/*.cpp
lib/imgui/backend/*.cpp
)
# 注意:GLOB 在文件新增时需要重新运行 CMake,但对于我们这种稳定的库文件,完全没问题。
# 7. 定义我们要生成的可执行文件
# `WIN32` 参数在Windows下特别重要,它告诉链接器生成一个图形界面程序(而不是控制台程序)。
# 如果没有它,运行时会弹出一个黑乎乎的控制台窗口。
add_executable(${PROJECT_NAME} WIN32 src/main.cpp ${IMGUI_SRCS})
# 8. 为生成的可执行文件链接所需的库
# `glfw3` 对应我们之前复制的 `libglfw3.a` 文件。
# `opengl32` 是Windows系统自带的OpenGL库,链接它才能调用OpenGL函数。
target_link_libraries(${PROJECT_NAME} glfw3 opengl32)
这个 CMakeLists.txt 已经具备了很好的结构。它清晰地定义了头文件路径、库文件路径、源文件集合以及最终的链接依赖。保存好这个文件,我们的项目蓝图就画完了。
6. 使用 CMake 生成并构建项目
这是最后一步,也是见证奇迹的时刻。我们全程在命令行操作,这能让你对构建流程有最直观的理解。
- 打开终端:在 Windows 上,你可以使用
PowerShell或者CMD。确保你已经按照第一步的要求,将 MinGW 的bin目录添加到了PATH。 - 进入项目目录并创建构建文件夹:一个好的习惯是进行“外部构建”(Out-of-source build),即不在源码目录里编译,避免污染源码。
cd D:\Projects\MyImGuiApp mkdir build cd build - 运行 CMake 生成 Makefile:这是最关键的一步。我们需要告诉 CMake 使用我们安装的 MinGW 编译器。
cmake -G "MinGW Makefiles" ..-G "MinGW Makefiles":指定生成器为 MinGW 使用的 Makefile。如果不加这个参数,CMake 可能会默认使用 Visual Studio 的生成器,导致后续make命令失败。..:表示 CMakeLists.txt 在上一级目录。 运行成功后,你会在build目录下看到生成的一大堆文件,其中最重要的就是Makefile。
- 使用 make 进行编译:
如果一切配置正确,你会看到编译器(g++)开始工作,一行行编译信息滚动。这个过程应该没有任何错误。编译完成后,在makebuild目录下(或者build/Debug/下,取决于 CMake 配置)会生成一个MyImGuiApp.exe文件。 - 运行程序:直接在命令行输入:
一个漂亮的窗口应该会弹出来!左边是功能强大的 ImGUI 演示窗口,右边是你自己创建的带有按钮、滑动条和颜色选择器的窗口。你可以随意点击、拖拽、修改,感受一下 ImGUI 的即时响应和流畅交互。.\MyImGuiApp.exe
7. 进阶配置与常见问题排坑
一次成功固然可喜,但实际开发中总会遇到各种问题。这里我分享几个常见的坑和对应的解决方案,以及一些让项目更完善的进阶配置。
7.1 静态库链接顺序问题
有时你可能会遇到链接错误,提示 undefined reference to ...,这常常是库的链接顺序不对。在 target_link_libraries 中,依赖项应该放在被依赖项的后面。我们的例子中,MyImGuiApp 依赖 glfw3 和 opengl32,所以把它们放在最后是正确的。如果未来你添加了更多库(比如 GLEW),也需要考虑顺序。
7.2 处理控制台窗口
我们的 CMakeLists.txt 中使用了 WIN32 参数,这会生成一个纯粹的图形界面程序,没有控制台。这在发布应用时是好的。但在开发调试阶段,你可能需要看到 printf 或 std::cout 输出的日志。有两种方法:
- 临时去掉 WIN32:在
add_executable行暂时移除WIN32参数,重新 CMake 和 make,运行的程序就会附带控制台。 - 使用日志文件或 IDE 输出:更专业的方法是使用日志库将信息输出到文件,或者利用 IDE(如 VS Code、CLion)集成的调试控制台。
7.3 添加更多源码文件和资源
当你的项目变大,需要添加新的 .cpp/.h 文件时,只需将它们放入 src/ 或其子目录,然后在 add_executable 命令中像添加 main.cpp 一样把它们列出来即可。对于资源文件(如图片、字体),你可以创建一个 assets/ 文件夹,并在代码中使用相对路径来访问。为了在构建后能正确找到资源,一个常见的做法是在 CMake 中将资源目录复制到构建输出目录:
# 在 add_executable 之后添加
file(COPY assets DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
7.4 使用 ImGUI 的字体功能
ImGUI 默认的字体是 ProggyClean.ttf,一种小像素字体。要使用中文或其他漂亮字体,你需要在初始化后加载 .ttf 文件。将字体文件(如 msyh.ttc 微软雅黑)放入项目,然后在 main.cpp 的 ImGui::CreateContext() 之后添加类似代码:
ImGuiIO& io = ImGui::GetIO();
io.Fonts->AddFontFromFileTTF("assets/msyh.ttc", 18.0f, nullptr, io.Fonts->GetGlyphRangesChineseFull());
记得在 CMake 中配置资源文件的复制,确保程序运行时能找到字体文件。
走到这里,你已经拥有了一个完全在自己掌控之下的、结构清晰的 ImGUI 开发环境。从编译器安装、库文件配置、项目结构设计、CMake 脚本编写到最终构建运行,每一步你都亲手完成。这个项目模板就像你亲手打造的一把瑞士军刀,干净、锋利、可扩展。接下来,你就可以基于它,去尽情探索 ImGUI 那琳琅满目的控件库,开发出属于你自己的图形界面工具了。如果在后续开发中遇到新的问题,比如想集成其他库(如 OpenCV 做图像处理),或者打包发布程序,思路都是一样的:准备好库的头文件和二进制文件,在 CMakeLists.txt 中正确设置包含路径、链接路径和链接库。
157



被折叠的 条评论
为什么被折叠?



