CMake指令：find_package()在Qt中的应用

流星雨爱编程

已于 2025-05-26 20:31:50 修改

阅读量977

点赞数 25

分类专栏： #CMake工具 #Qt 文章标签： qt 开发语言 c++ CMake 自动化编译工具自动化构建工具

于 2025-05-25 12:35:09 首次发布

本文链接：https://blog.csdn.net/haokan123456789/article/details/148202960

版权

#Qt 同时被 2 个专栏收录

37 篇文章

订阅专栏

#CMake工具

8 篇文章

订阅专栏

1.简介

在 CMake 中使用 find_package(Qt) 是集成 Qt 库的核心步骤。Qt 从 5.x 版本开始全面支持 配置模式（Config Mode）（通过自带的 Qt5Config.cmake 或 Qt6Config.cmake 文件），现代项目推荐使用此模式。以下是详细用法和最佳实践：

基本语法与版本选择

# 查找 Qt5（或 Qt6，根据项目需求）
find_package(Qt5 [版本号] [REQUIRED] [COMPONENTS 组件1 组件2 ...])
find_package(Qt6 [版本号] [REQUIRED] [COMPONENTS 组件1 组件2 ...])

关键参数：

版本号：可选，指定最低版本（如 5.15 或 6.2）。
REQUIRED：找不到 Qt 或指定组件时终止配置并报错。
COMPONENTS：指定需要的 Qt 模块（如 Core、Widgets、Gui）。

2.Qt 核心组件与常用模块

Qt 提供了丰富的功能模块，常见组件包括：

组件	功能
`Core`	核心功能（基础类、容器、I/O、线程等）
`Widgets`	GUI 组件（窗口、按钮、文本框等）
`Gui`	图形界面基础（绘图、字体、图像等）
`Network`	网络编程（HTTP、TCP、UDP 等）
`Sql`	数据库支持（SQLite、MySQL、PostgreSQL）
`Xml`	XML 解析（SAX、DOM）
`Qml`/`Quick`	QML 与 Qt Quick（现代 UI 开发）
`Test`	单元测试框架

3.配置模式的工作流程

Qt 的配置模式通过以下步骤自动完成依赖解析：

1.查找 Qt 安装路径

默认搜索系统路径（如 /usr/lib/cmake/Qt5、C:/Qt/5.15/msvc2019_64/lib/cmake/Qt5）。
若 Qt 未安装在默认路径，需通过 CMAKE_PREFIX_PATH 或 HINTS 指定：

set(CMAKE_PREFIX_PATH "/path/to/Qt/5.15/gcc_64" ${CMAKE_PREFIX_PATH})
find_package(Qt5 5.15 REQUIRED COMPONENTS Widgets)

2.验证版本与组件

检查 Qt 版本是否满足要求（如 >=5.15）。
确保指定的组件（如 Widgets）已安装。

3.生成导入目标

成功后，CMake 会生成以 Qt5:: 或 Qt6:: 为前缀的导入目标（如 Qt5::Widgets），包含头文件路径、链接库和编译选项。

4.完整示例：构建 Qt GUI 应用

以下是一个典型的 Qt 项目 CMakeLists.txt 配置：

cmake_minimum_required(VERSION 3.16)  # Qt5 需要 CMake 3.16+，Qt6 需要 3.18+
project(MyQtApp LANGUAGES CXX)

# 设置 C++ 标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 启用 Qt 自动处理（MOC、UIC、RCC）
set(CMAKE_AUTOMOC ON)  # 自动处理 Q_OBJECT 宏（生成 moc_*.cpp）
set(CMAKE_AUTOUIC ON)   # 自动处理 .ui 文件（生成 ui_*.h）
set(CMAKE_AUTORCC ON)   # 自动处理 .qrc 资源文件（生成 qrc_*.cpp）

# 查找 Qt5 或 Qt6（此处以 Qt5 为例）
find_package(Qt5 5.15 REQUIRED COMPONENTS Widgets)

# 添加可执行文件（自动包含 .cpp、.ui、.qrc 文件）
add_executable(myapp
    main.cpp
    mainwindow.cpp
    mainwindow.h
    mainwindow.ui  # 自动由 UIC 处理
    resources.qrc  # 自动由 RCC 处理
)

# 链接 Qt 组件（使用导入目标）
target_link_libraries(myapp PRIVATE Qt5::Widgets)

关键特性详解：

1.自动处理 MOC、UIC、RCC

Qt 的 Q_OBJECT 宏、.ui 界面文件和 .qrc 资源文件需要预处理：

CMAKE_AUTOMOC：自动调用 moc 工具生成元对象代码（处理 Q_OBJECT、信号槽等）。
CMAKE_AUTOUIC：自动调用 uic 工具将 .ui 文件转换为 C++ 头文件。
CMAKE_AUTORCC：自动调用 rcc 工具将资源文件编译为可执行文件。

2.导入目标的优势

通过 Qt5::Widgets 链接，CMake 会自动处理：

头文件路径：target_include_directories 无需手动设置。
链接库：Qt5::Widgets 已包含依赖的 Qt5::Core、Qt5::Gui 等。
编译选项：如 QT_NO_KEYWORDS、QT_SHARED 等预定义宏。

3.多版本 Qt 共存

若系统中同时安装了 Qt5 和 Qt6，可通过明确指定版本避免冲突：

# 强制使用 Qt6
find_package(Qt6 6.2 REQUIRED COMPONENTS Widgets)
target_link_libraries(myapp PRIVATE Qt6::Widgets)

自动兼容自动检测系统中安装的 Qt 版本（优先 Qt6，若不存在则回退 Qt5）的另外一种写法：

find_package(QT 
    NAMES Qt6 Qt5               # 按顺序搜索的包名（先 Qt6，后 Qt5）
    REQUIRED                      # 找不到时终止配置并报错
    COMPONENTS Widgets            # 需要的 Qt 组件（此处为 GUI 组件库）
)

解释：

1. QT：逻辑包名

这是用户自定义的 “逻辑包名”，用于在 CMake 中标识当前查找的是 Qt 库。
实际搜索时，CMake 会根据 NAMES 参数替换为 Qt6 或 Qt5。

2.NAMES Qt6 Qt5：搜索顺序

CMake 会按顺序尝试查找 Qt6 和 Qt5 的配置文件（如 Qt6Config.cmake、Qt5Config.cmake）。
优先级：先搜索 Qt6，若未找到（或版本不满足），则尝试 Qt5。

3.REQUIRED：强制要求

若未找到任何版本的 Qt 或 Widgets 组件，CMake 会终止配置并抛出错误：

CMake Error: Found packages 'Qt6' and 'Qt5' are not compatible with requested components 'Widgets'.

4.COMPONENTS Widgets：所需组件

指定需要的 Qt 模块（此处为 Widgets，用于 GUI 开发）。
Qt 的其他常见组件包括 Core、Gui、Network 等，可按需添加。

5.常见问题与解决方案

1.找不到 Qt 安装路径

原因：Qt 未安装在默认路径，或 CMAKE_PREFIX_PATH 未正确设置。
解决：

方法1：手动指定 Qt 安装路径（推荐）

通过 CMAKE_PREFIX_PATH 告诉 CMake Qt 的安装路径（需指向 Qt 安装目录的根路径，而非 lib/cmake/Qt6 子目录）。

1）找到 Qt 的实际安装路径（示例）：

Windows：C:\Qt\6.5.2\msvc2019_64（假设安装了 Qt6.5.2 + MSVC 2019 编译器）。
macOS：/Users/<用户名>/Qt/6.5.2/macos。
Linux：/opt/Qt/6.5.2/gcc_64 或 /usr/lib/x86_64-linux-gnu/cmake/Qt6（通过包管理器安装）。

2）在 CMake 命令中添加 -DCMAKE_PREFIX_PATH 参数：

cmake -DCMAKE_PREFIX_PATH="/path/to/Qt/6.5.2/msvc2019_64" ..

# cmake -DCMAKE_PREFIX_PATH="C:/Qt/Qt5.12.12/5.12.12/msvc2017_64" ..

（将 /path/to/Qt/... 替换为实际安装路径）

方法3：设置 QT_DIR 变量

QT_DIR 直接指向 Qt 配置文件所在的目录（即 lib/cmake/Qt6 或 lib/cmake/Qt5）。

# Windows
cmake -DQT_DIR="C:\Qt\6.5.2\msvc2019_64\lib\cmake\Qt6" ..

# Linux/macOS
cmake -DQT_DIR="/opt/Qt/6.5.2/gcc_64/lib/cmake/Qt6" ..

方法3：在 CMakeLists.txt 中预定义路径

若项目需要固定 Qt 路径，可在 CMakeLists.txt 中添加：

# 手动指定 Qt 安装路径（例如 Qt5 的 GCC 64位版本）
set(CMAKE_PREFIX_PATH "/home/user/Qt/5.15/gcc_64" ${CMAKE_PREFIX_PATH})
#或 set(CMAKE_PREFIX_PATH "C:/Qt/Qt5.12.12/5.12.12/msvc2017_64" ${CMAKE_PREFIX_PATH})
find_package(Qt5 5.15 REQUIRED COMPONENTS Widgets)

# 优先使用用户指定的 QT_DIR，否则设置默认路径
if(NOT QT_DIR)
    set(QT_DIR "/path/to/Qt/6.5.2/gcc_64/lib/cmake/Qt6" CACHE PATH "Qt configuration directory")
endif()

find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Widgets)
find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Widgets)

方法4：检查 Qt 开发组件是否安装

若 Qt 已安装但仍报错，可能是未安装开发组件：

Windows/macOS：
打开 Qt 维护工具（MaintenanceTool），确保勾选了对应版本的 编译器工具链（如 MSVC 2019 64-bit）和 Qt 基础模块（如 Qt Base）。
Linux（以 Ubuntu 为例）：
通过包管理器安装 Qt 开发包（Qt6 或 Qt5）：

# 安装 Qt6 开发包
sudo apt-get install qt6-base-dev qt6-tools-dev

# 安装 Qt5 开发包（旧项目）
sudo apt-get install qt5-default qttools5-dev

方法 5：验证 Qt 配置文件是否存在

手动检查 Qt 安装目录中是否存在配置文件：

# Qt6 配置文件路径示例
<Qt安装路径>/lib/cmake/Qt6/Qt6Config.cmake

# Qt5 配置文件路径示例
<Qt安装路径>/lib/cmake/Qt5/Qt5Config.cmake

#Qt安装路径如： C:\Qt\Qt5.12.12\5.12.12\msvc2017_64\lib

若不存在，说明 Qt 安装不完整，需重新安装开发组件。

2.组件缺失（如 Widgets 未找到）

原因：未安装所需的 Qt 组件（如仅安装了 Core 但未安装 Widgets）。
解决：
- 通过 Qt 维护工具（MaintenanceTool）安装缺失的组件。
- 在 find_package 中添加 QUIET 避免报错（仅用于临时调试）：

find_package(Qt5 5.15 COMPONENTS Widgets QUIET)
if(NOT Qt5_Widgets_FOUND)
    message(FATAL_ERROR "Qt5 Widgets 未安装，请检查 Qt 组件")
endif()

3.MOC/UIC/RCC 未自动触发

原因：CMake 版本过低（Qt5 需要 CMake 3.16+，Qt6 需要 3.18+）。
解决：升级 CMake 到最新版本，并确保 CMAKE_AUTOMOC 等变量设置为 ON

`6.总结`

使用 find_package(Qt) 集成 Qt 库的核心步骤是：

1）通过 CMAKE_PREFIX_PATH 指定 Qt 安装路径；
2）调用 find_package 查找所需版本和组件；
3）通过导入目标（如 Qt5::Widgets）链接库；
4）启用 AUTOMOC、AUTOUIC 等自动处理功能简化开发。

合理配置可大幅提升 Qt 项目的构建效率和跨平台兼容性。

相关链接

CMake 官网 CMake - Upgrade Your Software Build System
CMake 官方文档：CMake Tutorial — CMake 4.0.2 Documentation
CMake 源码：https://github.com/Kitware/CMake
CMake 源码：Sign in · GitLab