桌面应用 / 系统课时

用 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
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)

预期结果

text
CMake 配置阶段能够找到 Qt6 Widgets 模块,并生成 QtDemo 构建目标。

其中 COMPONENTS Widgets 表示项目需要 Qt Widgets 功能。如果后续使用网络、数据库等能力,需要额外添加对应模块。

使用 target_link_libraries 连接 Qt

声明依赖并不代表程序已经能够调用 Qt API,还需要通过 target_link_libraries 将库链接到目标程序。

例如:

cmake
target_link_libraries(QtDemo PRIVATE Qt6::Widgets)

这里的 QtDemo 是由 add_executable 创建的目标名称,Qt6::Widgets 是 Qt 提供的 CMake 导入目标。

PRIVATE 表示该依赖只供当前目标使用,不会传递给其他目标。

构建并验证项目

完成 CMake 文件后,可以通过命令行生成构建目录并编译:

bash
cmake -S . -B build
cmake --build build

预期输出

text
构建过程完成,没有 CMake 配置错误,并生成 QtDemo 可执行程序。

实际生成文件位置会根据操作系统和生成器不同而变化。

常见配置错误

Qt CMake 项目中常见问题包括:

  • find_package 找不到 Qt:通常是 Qt 安装路径没有被 CMake 发现。
  • 忘记链接模块:代码可以包含头文件,但链接阶段失败。
  • 源文件未加入 add_executable:编译时不会生成对应代码。

排查时应先确认 CMake 配置阶段,再检查链接阶段,最后检查代码编译错误。

管理多个 Qt 模块

随着应用功能增加,项目可能需要多个模块,例如 Widgets 和 Network:

cmake
find_package(Qt6 REQUIRED COMPONENTS Widgets Network)

target_link_libraries(QtDemo PRIVATE
    Qt6::Widgets
    Qt6::Network
)

预期结果

text
项目同时获得 Qt Widgets 界面能力和 Qt Network 网络能力。

合理管理 CMake 配置,可以让 Qt 项目在不同开发环境和部署环境中保持稳定构建。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 CMake 管理 Qt 构建

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通