6、多模块构建实战:如何组织多个子项目、子目录间的依赖关系、导出与安装。

好,咱们进入实战环节。前面几章讲了 CMake 的基础语法、变量、函数,还有库的创建。但说实话,那些都是「单兵作战」。真正的项目,尤其是 C++ 大型项目,一定是多个模块协同工作。

这一章,我们就来聊聊多模块构建。说白了,就是怎么把一堆子项目、子目录组织起来,让它们互相依赖、互相调用,最后还能干干净净地导出和安装。

6.1 为什么需要多模块?

你想想看,一个大型项目,如果所有代码都堆在一个 CMakeLists.txt 里,那会是什么场景?几千行代码,几十个 target,依赖关系乱成一锅粥。我早期带团队时就踩过这个坑——一个同事改了个底层库的接口,结果上层三个模块全部编译失败,排查了整整一个下午。

多模块的好处很明显:

  • 解耦:每个模块独立开发、独立测试
  • 复用:模块可以跨项目使用
  • 并行编译:模块间依赖清晰,可以并行构建
  • 版本管理:每个模块可以有自己的版本号

核心原则:模块间的依赖关系应该是「有向无环图」。如果出现循环依赖,那你的架构设计一定有问题。

6.2 目录结构设计

我个人习惯用这样的目录结构:

my_project/
├── CMakeLists.txt          # 顶层 CMake
├── cmake/                  # 自定义 CMake 模块
│   └── MyProjectConfig.cmake.in
├── modules/
│   ├── core/               # 核心模块
│   │   ├── CMakeLists.txt
│   │   ├── include/
│   │   │   └── core/
│   │   │       ├── core_api.h
│   │   │       └── core_impl.h
│   │   └── src/
│   │       └── core_impl.cpp
│   ├── network/            # 网络模块
│   │   ├── CMakeLists.txt
│   │   ├── include/
│   │   │   └── network/
│   │   │       └── network_api.h
│   │   └── src/
│   │       └── network_impl.cpp
│   └── ui/                 # UI 模块
│       ├── CMakeLists.txt
│       ├── include/
│       │   └── ui/
│       │       └── ui_api.h
│       └── src/
│           └── ui_impl.cpp
├── tests/                  # 测试模块
│   ├── CMakeLists.txt
│   └── test_core.cpp
└── examples/               # 示例代码
    ├── CMakeLists.txt
    └── example_main.cpp

嗯,这里要注意:每个模块的 include 目录下,我习惯再加一层模块名作为子目录。比如 core/core_api.h,而不是直接 core_api.h。这样做的好处是,当多个模块的头文件被安装到同一个目录时,不会发生命名冲突。

6.3 顶层 CMakeLists.txt 的写法

顶层 CMakeLists.txt 是整个项目的入口。它的职责是:定义项目、设置全局编译选项、然后通过 add_subdirectory 引入各个子模块。

cmake_minimum_required(VERSION 3.16)
project(MyProject VERSION 1.0.0 LANGUAGES CXX)

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

# 设置安装路径(可选)
set(CMAKE_INSTALL_PREFIX "${CMAKE_BINARY_DIR}/install" CACHE PATH "Install directory")

# 添加子模块
add_subdirectory(modules/core)
add_subdirectory(modules/network)
add_subdirectory(modules/ui)

# 可选:测试和示例
option(BUILD_TESTS "Build tests" ON)
option(BUILD_EXAMPLES "Build examples" ON)

if(BUILD_TESTS)
    enable_testing()
    add_subdirectory(tests)
endif()

if(BUILD_EXAMPLES)
    add_subdirectory(examples)
endif()

这里有个小技巧:用 option 来控制是否构建测试和示例。我在项目中遇到过,有些客户只需要核心库,不需要测试代码。用 option 可以灵活控制,避免不必要的编译。

6.4 子模块的 CMakeLists.txt

每个子模块的 CMakeLists.txt 要完成三件事:定义 target、声明依赖、设置导出。

以 modules/core/CMakeLists.txt 为例:

# 定义库 target
add_library(core
    STATIC
    src/core_impl.cpp
    include/core/core_api.h
    include/core/core_impl.h
)

# 指定头文件目录
target_include_directories(core
    PUBLIC
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
        $<INSTALL_INTERFACE:include>
)

# 设置版本号
set_target_properties(core PROPERTIES
    VERSION ${PROJECT_VERSION}
    SOVERSION 1
)

# 导出设置
install(TARGETS core
    EXPORT MyProjectTargets
    ARCHIVE DESTINATION lib
    LIBRARY DESTINATION lib
    RUNTIME DESTINATION bin
    INCLUDES DESTINATION include
)

install(
    DIRECTORY include/
    DESTINATION include
    FILES_MATCHING PATTERN "*.h"
)

# 安装 CMake 配置文件
install(EXPORT MyProjectTargets
    FILE MyProjectTargets.cmake
    NAMESPACE MyProject::
    DESTINATION lib/cmake/MyProject
)

注意看 target_include_directories 的写法。我用的是生成器表达式:

  • $<BUILD_INTERFACE:...>:编译时,头文件路径指向源码目录
  • $<INSTALL_INTERFACE:...>:安装后,头文件路径指向安装目录下的 include

为什么要这么写?因为编译时和安装后,头文件的位置不一样。如果不区分,安装后的项目引用头文件就会找不到路径。我曾经在这个问题上折腾了整整两天,后来才发现是生成器表达式没写对。

6.5 模块间的依赖关系

现在,假设 network 模块依赖 core 模块。那 modules/network/CMakeLists.txt 应该这样写:

add_library(network
    STATIC
    src/network_impl.cpp
    include/network/network_api.h
)

# 依赖 core 模块
target_link_libraries(network
    PUBLIC
        core
)

target_include_directories(network
    PUBLIC
        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
        $<INSTALL_INTERFACE:include>
)

# 同样需要安装
install(TARGETS network
    EXPORT MyProjectTargets
    ARCHIVE DESTINATION lib
    LIBRARY DESTINATION lib
    RUNTIME DESTINATION bin
    INCLUDES DESTINATION include
)

install(
    DIRECTORY include/
    DESTINATION include
    FILES_MATCHING PATTERN "*.h"
)

这里的关键是 target_link_libraries 的 PUBLIC 关键字。它表示:network 不仅自己需要 core,任何链接了 network 的 target 也会自动链接 core。这就是依赖传递。

小提示:依赖传递有三种方式:

  • PUBLIC:传递依赖,接口和实现都需要
  • PRIVATE:不传递,只有自己需要
  • INTERFACE:只传递接口,不传递实现(常用于纯头文件库)

我个人建议:能用 PRIVATE 就用 PRIVATE,尽量减少不必要的依赖传递。否则,一个底层库的改动可能会引发上层所有模块的重新编译。

6.6 导出与安装

导出和安装,说白了就是让其他项目能方便地使用你的库。CMake 提供了 install() 命令和 export() 命令来实现。

完整的导出流程包括:

  1. 安装头文件到 include/ 目录
  2. 安装库文件到 lib/ 目录
  3. 生成并安装 CMake 配置文件(MyProjectConfig.cmake)
  4. 生成并安装 target 导出文件(MyProjectTargets.cmake)

我们需要在顶层 CMakeLists.txt 中编写配置文件模板。创建一个 cmake/MyProjectConfig.cmake.in 文件:

@PACKAGE_INIT@

# 包含导出的 targets
include("${CMAKE_CURRENT_LIST_DIR}/MyProjectTargets.cmake")

# 检查依赖(如果有的话)
check_required_components(MyProject)

然后在顶层 CMakeLists.txt 中添加:

# 配置并安装 CMake 配置文件
configure_package_config_file(
    ${CMAKE_SOURCE_DIR}/cmake/MyProjectConfig.cmake.in
    ${CMAKE_BINARY_DIR}/MyProjectConfig.cmake
    INSTALL_DESTINATION lib/cmake/MyProject
)

install(
    FILES ${CMAKE_BINARY_DIR}/MyProjectConfig.cmake
    DESTINATION lib/cmake/MyProject
)

这样,其他项目就可以通过 find_package(MyProject) 来找到并使用你的库了。

警告:导出时,一定要确保所有依赖的 target 都被导出。如果 network 依赖 core,但 core 没有被导出,那么 find_package 后链接 network 会报错。我曾经在导出时漏掉了一个底层库,结果客户那边编译了三天都没通过,最后发现是导出不完整。

6.7 使用 find_package 引入外部依赖

如果你的项目依赖第三方库,比如 Boost、OpenCV,可以用 find_package 来引入。但要注意,find_package 有两种模式:

  • 模块模式:CMake 自带的 FindXXX.cmake 文件
  • 配置模式:第三方库自己提供的 XXXConfig.cmake 文件

我个人更推荐配置模式,因为它更准确、更完整。比如:

find_package(Boost REQUIRED COMPONENTS filesystem system)
target_link_libraries(my_target PRIVATE Boost::filesystem Boost::system)

如果第三方库没有提供 Config 文件,那就只能用模块模式了。但要注意,模块模式可能找不到某些组件,或者版本信息不准确。

6.8 实战避坑指南

最后,分享几个我踩过的坑:

  • 路径问题:CMAKE_CURRENT_SOURCE_DIR 和 CMAKE_SOURCE_DIR 的区别要搞清楚。前者是当前 CMakeLists.txt 所在的目录,后者是顶层目录。用错了会导致头文件找不到。
  • 命名空间冲突:多个模块如果定义了同名的 target,CMake 会报错。所以 target 命名最好带上模块前缀,比如 core、network_core。
  • 安装路径:默认安装到系统目录(如 /usr/local),但开发阶段建议安装到项目构建目录下的 install 子目录,避免污染系统。
  • 跨平台兼容:Windows 上 DLL 需要导出符号,Linux 上则不需要。可以用 CMake 的 GenerateExportHeader 来生成跨平台的导出宏。

嗯,多模块构建其实不难,但细节很多。只要把依赖关系理清楚,导出安装配置好,后续的维护就会轻松很多。下一章,我们会聊聊测试框架的集成,到时候这些模块就能派上用场了。