3. Qt开发环境搭建
工业组态与HMI项目往往需要同时面向桌面调试和嵌入式目标机运行，因此Qt开发环境并不是“装一个IDE”这么简单，而是由Qt Creator、Qt库、编译器、调试器、Kit、交叉编译工具链、版本控制共同组成的一套可复现工程体系。环境搭建的目标是：同一份源码，在PC上能快速仿真验证，在目标HMI屏上能一键交叉编译并部署。
一、核心原理：Kit是Qt环境的“装配清单”
Qt Creator本身只是壳，真正决定“用什么编译、编译给谁、如何调试”的是Kit（构建套件）。一个Kit至少绑定四类对象：Qt版本（qmake或CMake使用的Qt库）、编译器（GCC/MinGW/MSVC/交叉g++）、调试器（gdb/lldb）、设备（Desktop或远程Linux设备）。当Kit中任意一项与目标平台不匹配，就会出现“能编译不能运行”“链接报错找不到libQt5Core.so”等典型问题。
工业现场常见两类Kit：Desktop Kit用于PC端UI逻辑验证，Cross Kit用于ARM工控板/HMI。两者共享同一套工程文件，但构建目录、Qt库路径、sysroot必须严格隔离，避免桌面库污染交叉产物。
二、方法流程：从安装到可运行的最小闭环
- 安装Qt Creator与Qt库：推荐使用Qt Online Installer，选择Qt 5.15 LTS或Qt 6.x LTS。工业项目若目标板Qt版本固定，应选择与目标板一致的Qt版本，避免ABI差异。
- 配置编译器与调试器：在“工具→选项→Kits”中确认Desktop Kit的编译器为MinGW或GCC，调试器为gdb。交叉编译时需手动添加交叉g++和gdb路径。
- 创建Kit：分别建立Desktop Kit和Cross Kit，指定Qt版本、编译器、调试器、sysroot和设备。
- 验证Kit：新建Qt Widgets工程，分别用两个Kit构建，确认Desktop可运行、Cross可生成ARM可执行文件。
- 接入版本控制：初始化Git仓库，添加.gitignore，提交初始工程。
# 交叉编译工具链示例（Ubuntu）
sudo apt install g++-arm-linux-gnueabihf gdb-multiarch
# 验证交叉编译器
arm-linux-gnueabihf-g++ -v
# 在Qt Creator中配置qmake路径
/home/user/qt-arm/bin/qmake
# 构建ARM版本
mkdir build-arm && cd build-arm
qmake ../HmiDemo.pro -spec linux-arm-gnueabihf-g++
make -j4
# 部署到目标机
scp HmiDemo root@192.168.1.50:/opt/hmi/
ssh root@192.168.1.50 "export LD_LIBRARY_PATH=/opt/qt/lib; /opt/hmi/HmiDemo"三、工程目录规范与版本控制
工业HMI工程通常包含界面、通信、报警、历史数据、配置等多个模块。若目录混乱，后期维护成本极高。建议采用“源码与构建分离、资源与配置分离、部署脚本独立”的结构。
| 目录 | 用途 | 是否纳入Git |
|---|---|---|
| src/ | 核心业务源码，如通信、报警、数据采集 | 是 |
| include/ | 公共头文件与接口定义 | 是 |
| ui/ | .ui界面文件与QML文件 | 是 |
| resources/ | 图片、字体、qrc资源 | 是 |
| config/ | 设备参数、通信配置、报警阈值 | 是 |
| deploy/ | 部署脚本、systemd服务、启动脚本 | 是 |
| build-desktop/ | PC构建产物 | 否 |
| build-arm/ | ARM构建产物 | 否 |
# .gitignore 示例
build-*/
*.user
*.pro.user
*.o
*.so
*.a
moc_*.cpp
ui_*.h
qrc_*.cpp
.DS_Store
建议在工程根目录放置 README.md，记录Qt版本、交叉工具链版本、目标板IP、部署路径和启动命令。这样换一台电脑或换一位同事，也能在半小时内复现环境。
四、常见误区与复盘
- 误区一：Desktop和Cross共用一个构建目录。会导致moc文件、目标文件混用，出现“桌面能跑、ARM报错”的诡异问题。应使用build-desktop和build-arm两个独立目录。
- 误区二：交叉编译只换编译器，不换Qt库。目标板上的Qt库必须与交叉编译时链接的Qt版本一致，否则运行时报“version `Qt_5' not found”。
- 误区三：把build目录提交到Git。构建产物体积大且与机器相关，应通过.gitignore排除。
- 误区四：忽略sysroot。交叉编译时头文件和库路径应指向目标板sysroot，而不是宿主机的/usr/include。
在工业现场，目标板Qt库版本往往由厂商镜像决定。搭建环境前，先在目标板执行
qmake -v 和 ldd --version，确认Qt版本、glibc版本和编译器ABI，再反向选择宿主机工具链，可避免大量兼容性问题。
完成本章环境搭建后，应达到以下验收标准：Qt Creator能正常启动；Desktop Kit可编译运行示例工程；Cross Kit可生成ARM可执行文件；Git仓库已初始化并完成首次提交；工程目录符合规范且build目录未被跟踪。这套环境是后续组态界面开发、通信驱动集成和现场部署的基础，建议在项目开始前就固定下来，并形成团队统一的环境配置文档。