C++ QT之QTCreate创建Qt Subdirs 工程全解析，从0开始构建多模块项目

字数统计: 1.7k字   |   阅读时长≈ 6分

C++ QT之QTCreate创建Qt Subdirs工程全解析

从0开始构建多模块项目

接下来简单介绍介绍QT结构化工程结构，也许初学者对subdirs未曾初识，我们就来一起探讨探讨吧！

一、什么是 Subdirs 工程？

在 Qt 中，TEMPLATE = subdirs 表示这是一个项目容器（Project Container），它本身不生成可执行文件或库，而是用于管理多个子项目（Sub-Projects），例如：

  • 主程序（App）
  • 静态库（StaticLib）
  • 动态库（SharedLib / Plugin）
  • 测试项目（Test）
  • 工具项目（Tool）

换句话说：Subdirs 是「工程的工程」，它能让 Qt Creator 自动管理多个子工程的构建顺序与依赖关系。

二、Qt Creator 创建 Subdirs 工程步骤

  1. 打开 Qt Creator
    → 选择 新建项目 → Other Project → Subdirs Project（子目录项目）

  2. 命名工程（例如：SolutionProject）

  3. Qt Creator 自动生成一个 .pro 文件，内容大概是：

1
2
TEMPLATE = subdirs
SUBDIRS +=

这就是我们的「Solution」文件（类似于 VS 的 solution.sln）。

三、添加子项目

假设我们要创建这样一个结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
SolutionProject/
│
├── SolutionProject.pro     ← 顶层 subdirs 工程
│
├── App/                    ← 主程序（可执行文件）
│   └── App.pro
│
├── CoreLib/                ← 静态库
│   └── CoreLib.pro
│
└── Plugins/                ← 插件目录
    ├── PluginA/
    │   └── PluginA.pro
    └── PluginB/
        └── PluginB.pro

四、顶层 SolutionProject.pro 内容详解

1
2
3
4
5
6
7
8
9
10
11
12
# 顶层工程（Solution）
TEMPLATE = subdirs
CONFIG += ordered   # 按顺序编译子项目（非常重要）

SUBDIRS += \
    CoreLib \
    App \
    Plugins/PluginA \
    Plugins/PluginB

# 指定依赖关系（让主程序在库构建后再编译）
App.depends = CoreLib PluginA PluginB
配置项 说明
TEMPLATE = subdirs 声明这是一个”多工程管理”项目
SUBDIRS += ... 列出所有要包含的子工程路径
CONFIG += ordered 按声明顺序编译
App.depends = CoreLib 让主程序在 CoreLib 编译后构建，避免链接错误

五、子工程的结构和配置

1. CoreLib.pro（静态库）

1
2
3
4
5
6
7
8
9
10
11
TEMPLATE = lib
CONFIG += staticlib c++17
QT += core

TARGET = CoreLib

SOURCES += \
    core.cpp

HEADERS += \
    core.h

2. App.pro（主程序）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
TEMPLATE = app
QT += core gui widgets
CONFIG += c++17

TARGET = App

SOURCES += \
    main.cpp \
    mainwindow.cpp

HEADERS += \
    mainwindow.h

FORMS += \
    mainwindow.ui

# 指定依赖库路径（自动指向 CoreLib 的构建目录）
LIBS += -L$$OUT_PWD/../CoreLib -lCoreLib
INCLUDEPATH += $$PWD/../CoreLib
DEPENDPATH += $$PWD/../CoreLib

OUT_PWD：Qt 自动变量，表示构建输出目录。

3. PluginA.pro（动态库 / 插件）

1
2
3
4
5
6
7
8
9
10
TEMPLATE = lib
CONFIG += plugin c++17
QT += core gui widgets

TARGET = PluginA

SOURCES += pluginA.cpp
HEADERS += pluginA.h

DESTDIR = $$PWD/../build_plugins

插件将被输出到 build_plugins/ 目录。

六、构建顺序与自动依赖解析

当你在 Qt Creator 中点击「运行」或「构建」主工程：

  1. Qt 先解析顶层 .pro

  2. 发现包含子工程：CoreLib、App、PluginA、PluginB

  3. 根据 .depends 指令，确定编译顺序：

    1
    CoreLib → PluginA → PluginB → App

  4. Qt 会自动进入每个子目录执行 qmake → make

  5. 编译完成后，主程序自动链接到前面构建的库

因此，当你修改了子工程（如 CoreLib）代码并重新运行主程序时，Qt Creator 会自动先重新构建 CoreLib，再构建 App —— 不需要手动切换工程。

七、手动控制输出目录（推荐）

为避免不同子项目的 .obj、.moc 混在一起，可以添加：

1
2
3
4
DESTDIR = $$PWD/../bin/$$TARGET
OBJECTS_DIR = $$PWD/../build/.obj/$$TARGET
MOC_DIR = $$PWD/../build/.moc/$$TARGET
RCC_DIR = $$PWD/../build/.rcc/$$TARGET

优点：

  • 所有生成文件集中管理
  • 清晰区分不同模块的构建产物
  • 跨平台一致（不污染源码目录）

八、如何运行 Subdirs 工程？

在 Qt Creator 左上角的「项目树」中：

  • 如果你点击 SolutionProject（顶层），Qt Creator 不会直接运行它（因为它没有可执行文件）
  • 你需要右键点击子项目（如 App） → 设为启动项目（Set as Startup Project）
  • 然后点击 运行，即可自动构建依赖、链接并运行主程序

Qt Creator 会智能分析依赖关系，确保 App 运行前，其依赖的库已最新构建。

九、平台特定子项目（可选）

如果某些库只在特定平台编译，可以写条件：

1
2
win32: SUBDIRS += plugins/PluginWindows
unix:  SUBDIRS += plugins/PluginUnix

十、更复杂的场景

Qt 支持通过配置变量扩展：

1
2
3
4
5
6
7
core.file = CoreLib/CoreLib.pro
core.config = staticlib

app.file = App/App.pro
app.depends = core

SUBDIRS += core app

这种写法功能相同，只是更灵活。

十一、Subdirs 工程的优势总结

优势 说明
✅ 模块化管理 每个模块独立维护、编译、测试
✅ 自动依赖编译 修改库后主工程自动重建
✅ 支持静态库、动态库、插件混合
✅ 跨平台一致 同一结构可在 Windows / Linux / macOS 通用
✅ 清晰的项目结构 适合中大型 Qt 项目（如主程序 + 插件架构）

十二、实际使用建议

场景 建议
仅一个小应用 不需要 subdirs
有多个库或插件 ✅ 强烈建议使用 subdirs
团队开发 使用统一的 SolutionProject.pro 管理所有模块
插件开发 可以使用 DESTDIR 输出到统一的 plugins/ 目录

TEMPLATE = subdirs 是 Qt 项目管理的”上帝视角”：它不会生成文件，但能调度整个工程结构、依赖、构建、清理，是 Qt 中大型工程的标准项目组织方式。

一旦理解这套机制，你的 Qt 项目将更易扩展、更可维护、更专业。

十三、我的示例工程

结构示例

就拿CoreLib来举例，他的插件属性是staticlib库，我想在开发的时候不需要生成静态库，而是直接编译源码，这样更方便调试，那我们就需要.pro和.pri 文件，.pri是自定义的，用于源码加载。

静态库配置（.pro）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
QT -= gui

TEMPLATE = lib
CONFIG += staticlib
CONFIG += c++17

QT += core
# You can make your code fail to compile if it uses deprecated APIs.
# In order to do so, uncomment the following line.
#DEFINES += QT_DISABLE_DEPRECATED_BEFORE=0x060000    # disables all the APIs deprecated before Qt 6.0.0
TARGET = CoreLib

DESTDIR = $$PWD/../plugins/CoreLib  #生成的库放在什么位置
# OBJECTS_DIR = $$DESTDIR/.obj/UIlib
# MOC_DIR = $$DESTDIR/.moc/UIlib
# RCC_DIR = $$DESTDIR/.rcc/UIlib

INCLUDEPATH += $$PWD #因为需要加载头文件
INCLUDEPATH += $$PWD/include  #这里放插件依赖的插件

SOURCES += \
    corelib.cpp

HEADERS += \
    corelib.h

# Default rules for deployment.
unix {
    target.path = $$[QT_INSTALL_PLUGINS]/generic
}
!isEmpty(target.path): INSTALLS += target

# 分发文件（直接复制，不编译）
# DISTFILES += \
#     # 文档
#     README.md \
#     LICENSE \
#     docs/ \

源码引入配置（.pri）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 源码级别的引入
#指定头文件搜索路径
INCLUDEPATH += $$PWD
#指定依赖文件搜索路径
DEPENDPATH += $$PWD
message("$$PWD======CoreLib")
# 添加源文件（源码直接参与编译）
SOURCES += \
    $$PWD/corelib.cpp

HEADERS += \
    $$PWD/myclass.h

# 依赖的 Qt 模块
#QT += network

在App主程序中应用模块

1
2
3
4
5
6
7
8
9
10
11
12
13
14
#引入CoreLib  staticlib
# 根据构建类型选择
CONFIG(debug, debug|release) {
    message("我是CoreLib debug");
    # 调试版本使用 .pri，方便调试
    #include($$PWD/../CoreLib/CoreLib.pri)
} else {
    # 发布版本使用 StaticLib，优化编译速度
     message("我是CoreLib release");
    #INCLUDEPATH += ../CoreLib
    #win32:LIBS += -L$$PWD/../plugins/CoreLib -lCoreLib
    #unix:LIBS += -L$$PWD/../plugins/CoreLib -lCoreLib
}
include(../CoreLib/CoreLib.pri) #这里引入源码啦

OK，清楚了吗？这里不再举例了。我的工程也使用share、plugin其他插件类型的用法，这里不再说明了。上面就是我的subdirs 项目的介绍，有兴趣可以多关注，一起探讨。

我的工程开源地址：https://gitee.com/codeceo_net/qt_solution

扫一扫，分享到微信

tag:

    缺失模块。
    1、请确保node版本大于6.2
    2、在博客根目录（注意不是yilia-plus根目录）执行以下命令：
    npm i hexo-generator-json-content --save

    3、在根目录_config.yml里添加配置： 

      jsonContent:
    meta: false
    pages: false
    posts:
      title: true
      date: true
      path: true
      text: false
      raw: false
      content: false
      slug: false
      updated: false
      comments: false
      link: false
      permalink: false
      excerpt: false
      categories: false
      tags: true

僕は新世界の神となる!