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 复制代码

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 添加资源文件

cmake 复制代码

# 启用自动资源编译
set(CMAKE_AUTORCC ON)

# 添加qrc文件
qt_add_resources(MyApp "app_resources"
    PREFIX "/"
    FILES resources.qrc
)

四、Qt模块管理

4.1 常用Qt模块

cmake 复制代码

find_package(Qt6 REQUIRED COMPONENTS
    Core
    Gui
    Widgets
    Quick
    Qml
    Network
    Sql
    Multimedia
)

4.2 条件包含模块

cmake 复制代码

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

cmake 复制代码

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

cmake 复制代码

# 自动启用
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 安装规则

cmake 复制代码

install(TARGETS MyApp
    RUNTIME DESTINATION bin
    BUNDLE DESTINATION .
    LIBRARY DESTINATION lib
)

install(DIRECTORY qml/ DESTINATION qml)

6.2 跨平台配置

cmake 复制代码

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 调试配置

cmake 复制代码

# 启用调试信息
if(CMAKE_BUILD_TYPE STREQUAL "Debug")
    add_compile_options(-g -O0)
    add_definitions(-DQT_QML_DEBUG)
endif()

7.2 优化配置

cmake 复制代码

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 复制代码

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 复制代码

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包

cmake 复制代码

# 指定Qt安装路径
set(Qt6_DIR "C:/Qt/6.2.4/msvc2019_64/lib/cmake/Qt6")

9.2 资源文件未更新

bash 复制代码

# 清理CMake缓存
rm -rf CMakeCache.txt CMakeFiles

9.3 跨平台编译问题

cmake 复制代码

# 确保平台特定文件正确包含
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. 迁移工具

bash 复制代码

# qmake转CMake
qmake2cmake --help

通过本文档，您应该能够掌握使用CMake构建Qt项目的基本和高级技术。随着Qt6的发展，CMake已成为Qt开发的未来方向，建议新项目直接采用CMake构建系统。