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() 命令来实现。
完整的导出流程包括:
- 安装头文件到
include/目录 - 安装库文件到
lib/目录 - 生成并安装 CMake 配置文件(
MyProjectConfig.cmake) - 生成并安装 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来生成跨平台的导出宏。
嗯,多模块构建其实不难,但细节很多。只要把依赖关系理清楚,导出安装配置好,后续的维护就会轻松很多。下一章,我们会聊聊测试框架的集成,到时候这些模块就能派上用场了。