CMakeLists.txt 文件解析

关注

原创最新推荐文章于 2026-10-16 13:17:40 发布 241 阅读 AI 写同款· GEO 优化 ›

CMake 3.28 实战：从单文件到多模块项目，5个CMakeLists.txt模板解析本文详细解析了CMake 3.28在单文件到多模块项目中的5种CMakeLists.txt模板配置实践。从极简单文件项目到复杂多库依赖管理，涵盖跨平台编译和现代依赖管理方案，帮助开发者高效构建C++项目。特别推荐使用CMake 3.28新特性如`CONFIGURE_DEPENDS`和`$<PLATFORM_ID>`实现更优雅的工程配置。阅读详情

使用 Qt Creator 创建 Qt 项目时，通常会自动生成一个 CMakeLists.txt 文件。它是 CMake 项目的配置文件，用于描述项目的基本信息、依赖库、源文件以及构建和安装方式。

下面对这份 CMakeLists.txt 进行逐行分析。

1. 指定 CMake 最低版本

cmake_minimum_required(VERSION 3.19)

cmake_minimum_required() 用于指定项目所要求的最低 CMake 版本。

这里的：

VERSION 3.19

表示该项目要求 CMake 版本不低于 3.19。

如果当前系统中的 CMake 版本低于这个要求，CMake 在配置项目时会给出相应提示或错误。

2. 定义项目

project(RadarSimulation LANGUAGES CXX)

project() 用于定义一个 CMake 项目。

其中：

RadarSimulation

表示项目名称。

LANGUAGES CXX

表示该项目使用 C++。

CMake 中常见的语言标识包括：

C       C语言
CXX     C++
ASM     汇编

因此：

project(RadarSimulation LANGUAGES CXX)

可以理解为：

创建一个名为 RadarSimulation、使用 C++ 语言的 CMake 项目。

3. 查找 Qt6

find_package(Qt6 6.5 REQUIRED COMPONENTS Core Widgets)

find_package() 用于查找项目所依赖的软件包或库。

这里表示查找 Qt6。

其中：

Qt6

表示需要 Qt6。

6.5

表示要求 Qt 版本至少为 6.5。

REQUIRED

表示 Qt 是项目运行所必需的依赖。如果找不到满足要求的 Qt，CMake 配置过程将无法正常继续。

COMPONENTS Core Widgets

表示除了 Qt6 本身之外，还需要 Qt6 的两个组件：

Core
Widgets

所以这一整行可以理解为：

查找版本不低于 6.5 的 Qt6，并且要求其中的 Core 和 Widgets 模块可用。

4. Qt 标准项目配置

qt_standard_project_setup()

这是 Qt 提供的 CMake 函数，用于对 Qt 项目进行标准化配置。

它可以帮助项目设置 Qt 推荐的构建方式，并处理一些 Qt 项目常见的自动化配置。

使用 Qt6 和 CMake 创建项目时，这通常是 Qt Creator 自动生成的标准配置。

一般情况下不需要修改这一行。

5. 创建可执行程序

qt_add_executable(RadarSimulation
    WIN32 MACOSX_BUNDLE
    main.cpp
    mainwindow.cpp
    mainwindow.h
    mainwindow.ui
)

qt_add_executable() 用于创建一个可执行程序目标。

这里：

RadarSimulation

是生成的可执行程序目标名称。

后面的文件：

main.cpp
mainwindow.cpp
mainwindow.h
mainwindow.ui

表示这些文件属于这个可执行程序。

也就是说，CMake 会根据这些源文件和配置，最终构建出一个名为 RadarSimulation 的可执行程序。

6. WIN32

WIN32

WIN32 是 CMake 提供的一个选项。

在 Windows 平台上，它表示将该目标作为 Windows GUI 应用程序处理，而不是控制台程序。

例如普通的 Windows 图形界面程序通常不希望启动时出现一个额外的控制台窗口，这个选项就是相关配置之一。

需要注意的是：

WIN32 并不表示这个程序只能在 Windows 上运行。

它只是针对 Windows 平台生效。

7. MACOSX_BUNDLE

MACOSX_BUNDLE

这个选项用于 macOS 平台。

它表示将生成的 macOS 应用程序作为 Bundle 进行处理。

macOS 中常见的：

xxx.app

就是一种应用程序 Bundle。

因此：

WIN32 MACOSX_BUNDLE

主要是在告诉 CMake：

Windows 和 macOS 平台下，都按照相应的图形界面应用程序形式处理这个可执行程序。

8. 源文件

main.cpp
mainwindow.cpp
mainwindow.h
mainwindow.ui

这些是 Qt Creator 创建项目时常见的几个文件。

其中：

main.cpp

通常是 C++ 程序入口。

mainwindow.cpp

通常存放窗口类的实现代码。

mainwindow.h

通常存放窗口类的声明。

mainwindow.ui

是 Qt Designer 使用的 UI 文件，用于描述图形界面的布局和控件。

CMake 将这些文件作为可执行程序目标的一部分进行构建。

9. 链接库

target_link_libraries(RadarSimulation
    PRIVATE
        Qt::Core
        Qt::Widgets
)

target_link_libraries() 用于指定目标程序需要链接的库。

这里的目标是：

RadarSimulation

需要使用：

Qt::Core
Qt::Widgets

两个 Qt 模块。

也就是说：

RadarSimulation
       │
       ├── Qt::Core
       │
       └── Qt::Widgets

这样在程序中使用 Qt 提供的相关类和功能时，链接器才能正确完成最终的程序构建。

10. PRIVATE 是什么意思？

这里有：

PRIVATE

CMake 中的库依赖通常可以使用：

PRIVATE
PUBLIC
INTERFACE

进行描述。

简单理解：

PRIVATE

表示这个依赖只属于当前目标内部使用。

PUBLIC

表示当前目标需要使用，同时依赖当前目标的其他目标也需要这个依赖。

INTERFACE

表示当前目标本身不需要，但依赖当前目标的其他目标需要。

对于一个普通的 Qt 应用程序：

target_link_libraries(RadarSimulation
    PRIVATE
        Qt::Core
        Qt::Widgets
)

使用 PRIVATE 是非常常见的写法。

11. install() 安装配置

install(TARGETS RadarSimulation
    BUNDLE  DESTINATION .
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
)

install() 用于指定项目执行安装操作时，各类文件应该被安装到什么位置。

这里：

TARGETS RadarSimulation

表示对 RadarSimulation 这个目标进行安装配置。

12. DESTINATION

例如：

RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}

表示运行时文件应该安装到指定的 bin 目录。

而：

LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}

表示库文件安装到指定的 lib 目录。

BUNDLE DESTINATION .

则主要针对 macOS Bundle。

这里使用的：

${CMAKE_INSTALL_BINDIR}
${CMAKE_INSTALL_LIBDIR}

是 CMake 中的变量，用于表示相应的安装目录。

13. 生成 Qt 部署脚本

qt_generate_deploy_app_script(
    TARGET RadarSimulation
    OUTPUT_SCRIPT deploy_script
    NO_UNSUPPORTED_PLATFORM_ERROR
)

这是 Qt6 提供的部署相关功能。

它用于生成一个应用程序部署脚本。

其中：

TARGET RadarSimulation

表示针对 RadarSimulation 这个目标生成部署配置。

OUTPUT_SCRIPT deploy_script

表示生成的部署脚本名称保存到：

deploy_script

这个 CMake 变量中。

NO_UNSUPPORTED_PLATFORM_ERROR

表示在某些不支持该部署方式的平台上，不直接因为该原因产生错误。

14. 执行部署脚本

最后：

install(SCRIPT ${deploy_script})

表示在安装阶段执行前面生成的部署脚本。

前面的代码：

qt_generate_deploy_app_script(
    TARGET RadarSimulation
    OUTPUT_SCRIPT deploy_script
)

负责生成脚本。

这里：

install(SCRIPT ${deploy_script})

负责在安装过程中执行这个脚本。

两者结合起来，就形成了：

生成部署脚本
      ↓
保存到 deploy_script
      ↓
install()
      ↓
安装时执行部署脚本

15. 整个 CMakeLists.txt 的结构

把整个文件串起来，可以得到一个比较清晰的结构：

CMakeLists.txt
│
├── cmake_minimum_required()
│      ↓
│   指定最低 CMake 版本
│
├── project()
│      ↓
│   定义项目名称和语言
│
├── find_package()
│      ↓
│   查找 Qt 依赖
│
├── qt_standard_project_setup()
│      ↓
│   设置 Qt 项目的标准配置
│
├── qt_add_executable()
│      ↓
│   创建可执行程序并指定源文件
│
├── target_link_libraries()
│      ↓
│   链接所需要的 Qt 库
│
├── install()
│      ↓
│   设置安装规则
│
├── qt_generate_deploy_app_script()
│      ↓
│   生成 Qt 部署脚本
│
└── install(SCRIPT ...)
       ↓
    执行部署脚本

因此，这份 CMakeLists.txt 本质上是在回答几个问题：

这个项目叫什么？

project(...)

需要什么环境和依赖？

find_package(...)

需要编译哪些文件？

qt_add_executable(...)

需要链接哪些库？

target_link_libraries(...)

安装和部署时应该怎么处理？

install(...)
qt_generate_deploy_app_script(...)

对于刚接触 Qt 和 CMake 的开发者来说，首先理解这几个核心部分，就已经能够读懂大多数 Qt Creator 自动生成的基础 CMakeLists.txt。

标签

#qt6

DuckDB：详细解析CMakeLists.txt CMake（Cross-Platform Make）是一种跨平台的构建系统生成器，用于管理和自动化软件的构建过程。它通过编写配置文件（通常是 CMakeLists.txt）来定义项目的构建规则，支持多种编译器和操作系统，能够生成本地化的构建文件（如 Makefile、Visual Studio 解决方案等）。跨平台项目：需要在多种操作系统上构建和部署的项目。大型项目：包含多个模块和依赖的复杂项目。团队开发：需要统一构建流程和配置的团队开发环境。阅读详情

CMakeLists.txt 文件解析

1. 指定 CMake 最低版本

2. 定义项目

3. 查找 Qt6

4. Qt 标准项目配置

5. 创建可执行程序

6. WIN32

7. MACOSX_BUNDLE

8. 源文件

9. 链接库

10. PRIVATE 是什么意思？

11. install() 安装配置

12. DESTINATION

13. 生成 Qt 部署脚本

14. 执行部署脚本

15. 整个 CMakeLists.txt 的结构

相关推荐