Qt CMake 学习文档
一、CMake与Qt基础
1.1 CMake简介
CMake是一个跨平台的构建系统生成工具，可以生成Makefile、Visual Studio项目文件等。
1.2 Qt中的CMake支持
- Qt6开始，CMake成为官方推荐构建系统
- 提供专门的Qt CMake API简化Qt项目配置
- 比qmake更灵活，功能更强大
二、环境准备
2.1 安装要求
- CMake 3.16或更高版本
- Qt6开发环境
- 编译器(GCC/MSVC/Clang)
2.2 推荐工具
- Qt Creator(内置CMake支持)
- CLion
- Visual Studio(带CMake支持)
三、基础Qt CMake项目
3.1 最小CMake配置
cmake_minimum_required(VERSION 3.16)
project(MyQtApp LANGUAGES CXX)
# 查找Qt包
find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets)
# 创建可执行文件
add_executable(MyApp main.cpp)
# 链接Qt模块
target_link_libraries(MyApp PRIVATE Qt6::Core Qt6::Gui Qt6::Widgets)
3.2 添加资源文件
# 启用自动资源编译
set(CMAKE_AUTORCC ON)
# 添加qrc文件
qt_add_resources(MyApp "app_resources"
PREFIX "/"
FILES resources.qrc
)
四、Qt模块管理
4.1 常用Qt模块
find_package(Qt6 REQUIRED COMPONENTS
Core
Gui
Widgets
Quick
Qml
Network
Sql
Multimedia
)
4.2 条件包含模块
option(WITH_NETWORK "Include network support" ON)
if(WITH_NETWORK)
find_package(Qt6 COMPONENTS Network REQUIRED)
target_link_libraries(MyApp PRIVATE Qt6::Network)
add_definitions(-DWITH_NETWORK)
endif()
五、Qt特殊功能集成
5.1 集成QML
qt_add_qml_module(MyApp
URI MyApp
VERSION 1.0
QML_FILES
Main.qml
components/Button.qml
RESOURCES
images/logo.png
)
5.2 使用MOC、UIC和RCC
# 自动启用
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTORCC ON)
# 手动指定
qt_wrap_cpp(MyApp_MOC_SRCS header.h)
qt_wrap_ui(MyApp_UIC_SRCS form.ui)
六、高级配置
6.1 安装规则
install(TARGETS MyApp
RUNTIME DESTINATION bin
BUNDLE DESTINATION .
LIBRARY DESTINATION lib
)
install(DIRECTORY qml/ DESTINATION qml)
6.2 跨平台配置
if(WIN32)
# Windows特定配置
add_definitions(-DQT_QML_DEBUG)
elseif(APPLE)
# macOS特定配置
set(MACOSX_BUNDLE_GUI_IDENTIFIER "com.example.myapp")
elseif(UNIX AND NOT APPLE)
# Linux特定配置
set(CMAKE_INSTALL_PREFIX "/usr/local")
endif()
七、调试与优化
7.1 调试配置
# 启用调试信息
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
add_compile_options(-g -O0)
add_definitions(-DQT_QML_DEBUG)
endif()
7.2 优化配置
if(NOT CMAKE_BUILD_TYPE)
set(CMAKE_BUILD_TYPE "RelWithDebInfo")
endif()
if(CMAKE_BUILD_TYPE STREQUAL "Release")
add_compile_options(-O3)
endif()
八、实战示例
8.1 完整Qt Widgets项目示例
cmake_minimum_required(VERSION 3.16)
project(MyWidgetApp LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets)
set(SOURCES
main.cpp
mainwindow.cpp
dialog.cpp
)
set(HEADERS
mainwindow.h
dialog.h
)
set(FORMS
mainwindow.ui
dialog.ui
)
add_executable(MyWidgetApp ${SOURCES} ${HEADERS} ${FORMS})
target_link_libraries(MyWidgetApp PRIVATE Qt6::Core Qt6::Gui Qt6::Widgets)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTORCC ON)
if(WIN32)
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} /SUBSYSTEM:WINDOWS")
endif()
8.2 Qt Quick项目示例
cmake_minimum_required(VERSION 3.16)
project(MyQuickApp LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
find_package(Qt6 REQUIRED COMPONENTS Quick QuickControls2)
qt_add_executable(MyQuickApp
MANUAL_FINALIZATION
SOURCES
main.cpp
)
qt_add_qml_module(MyQuickApp
URI MyQuickApp
VERSION 1.0
QML_FILES
Main.qml
components/Button.qml
pages/HomePage.qml
RESOURCES
assets/icons/home.png
)
target_link_libraries(MyQuickApp PRIVATE
Qt6::Quick
Qt6::QuickControls2
)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
九、常见问题解决
9.1 找不到Qt包
# 指定Qt安装路径
set(Qt6_DIR "C:/Qt/6.2.4/msvc2019_64/lib/cmake/Qt6")
9.2 资源文件未更新
# 清理CMake缓存
rm -rf CMakeCache.txt CMakeFiles
9.3 跨平台编译问题
# 确保平台特定文件正确包含
if(UNIX AND NOT APPLE)
find_package(X11 REQUIRED)
endif()
十、最佳实践
- 模块化组织项目：将大型项目分解为多个CMake子项目
- 版本控制：在CMake中定义项目版本
- 依赖管理：使用
find_package或FetchContent管理依赖 - 构建类型：明确设置
CMAKE_BUILD_TYPE - 现代CMake：使用target-based命令而非全局命令
附录
A. 常用Qt CMake变量
Qt6_DIR: Qt安装路径Qt6_VERSION: Qt版本号Qt6_COMPONENTS_FOUND: 找到的Qt组件列表
B. 推荐学习资源
C. 迁移工具
# qmake转CMake
qmake2cmake --help
通过本文档，您应该能够掌握使用CMake构建Qt项目的基本和高级技术。随着Qt6的发展，CMake已成为Qt开发的未来方向，建议新项目直接采用CMake构建系统。