桌面应用 / 系统课时
用 CMake 管理 Qt 构建
用 CMake 管理 Qt 构建
本篇解决 Qt 6 项目如何通过 CMake 找到 Qt 模块并生成可运行程序的问题。完成学习后,你能够理解基础 CMake 配置,并知道项目依赖、源文件和链接关系如何组合起来。
学习目标
- 理解 Qt 项目中 CMakeLists.txt 的核心职责。
- 掌握 find_package 和 target_link_libraries 的基本用途。
- 能够编写并验证一个最小 Qt 6 CMake 项目。
CMake 在 Qt 项目中的作用
Qt 6 默认使用 CMake 作为主要构建工具。CMake 不直接编译代码,而是根据配置文件生成适合当前平台的构建文件,例如 Ninja 或 Makefile。
Qt 项目的 CMakeLists.txt 主要描述三类信息:
- 项目名称和使用的 CMake 版本。
- 需要使用哪些 Qt 模块。
- 哪些源文件组成最终程序,以及程序需要链接哪些库。
一个 Qt 应用能否成功构建,很大程度取决于这些关系是否配置正确。
使用 find_package 查找 Qt 模块
find_package 用于让 CMake 定位已经安装的 Qt 组件。例如窗口应用通常需要 Qt Widgets 模块。
最小配置示例:
cmake_minimum_required(VERSION 3.16)
project(QtDemo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
find_package(Qt6 REQUIRED COMPONENTS Widgets)
add_executable(QtDemo
main.cpp
mainwindow.cpp
mainwindow.h
)
target_link_libraries(QtDemo PRIVATE Qt6::Widgets)预期结果
CMake 配置阶段能够找到 Qt6 Widgets 模块,并生成 QtDemo 构建目标。其中 COMPONENTS Widgets 表示项目需要 Qt Widgets 功能。如果后续使用网络、数据库等能力,需要额外添加对应模块。
使用 target_link_libraries 连接 Qt
声明依赖并不代表程序已经能够调用 Qt API,还需要通过 target_link_libraries 将库链接到目标程序。
例如:
target_link_libraries(QtDemo PRIVATE Qt6::Widgets)这里的 QtDemo 是由 add_executable 创建的目标名称,Qt6::Widgets 是 Qt 提供的 CMake 导入目标。
PRIVATE 表示该依赖只供当前目标使用,不会传递给其他目标。
构建并验证项目
完成 CMake 文件后,可以通过命令行生成构建目录并编译:
cmake -S . -B build
cmake --build build预期输出
构建过程完成,没有 CMake 配置错误,并生成 QtDemo 可执行程序。实际生成文件位置会根据操作系统和生成器不同而变化。
常见配置错误
Qt CMake 项目中常见问题包括:
find_package找不到 Qt:通常是 Qt 安装路径没有被 CMake 发现。- 忘记链接模块:代码可以包含头文件,但链接阶段失败。
- 源文件未加入 add_executable:编译时不会生成对应代码。
排查时应先确认 CMake 配置阶段,再检查链接阶段,最后检查代码编译错误。
管理多个 Qt 模块
随着应用功能增加,项目可能需要多个模块,例如 Widgets 和 Network:
find_package(Qt6 REQUIRED COMPONENTS Widgets Network)
target_link_libraries(QtDemo PRIVATE
Qt6::Widgets
Qt6::Network
)预期结果
项目同时获得 Qt Widgets 界面能力和 Qt Network 网络能力。合理管理 CMake 配置,可以让 Qt 项目在不同开发环境和部署环境中保持稳定构建。