当 CMake 在主目录的 CMakeLists.txt 中执行到 add_subdirectory() 命令时，它会跳转到对应子目录中的 CMakeLists.txt，并按照子目录中的指令来构建子项目。这一过程在整个项目的配置阶段（即运行 cmake 命令时）完成，确保所有子目录的构建规则和目标被正确地集成到最终的构建系统中。

以下是对 add_subdirectory() 工作机制的详细解释：

add_subdirectory() 的工作流程

1. 配置阶段（CMake 配置过程）

当你运行 cmake 命令（例如 cmake .. 或 cmake .）来配置你的项目时，CMake 会从顶层目录的 CMakeLists.txt 开始解析。在解析过程中，遇到 add_subdirectory() 命令时，CMake 会：

1. 定位子目录：根据 add_subdirectory(<subdir>) 中指定的子目录路径，定位到该子目录。

2. 读取子目录的 CMakeLists.txt：进入子目录，读取并解析该目录下的 CMakeLists.txt 文件。

3. 执行子目录的 CMake 指令：按照子目录中的指令（如定义变量、添加库或可执行文件、设置编译选项等）来配置子项目。

4. 返回并继续主目录的配置：完成子目录的配置后，返回主目录的配置流程，继续解析后续的 CMake 指令。

2. 构建系统的生成阶段

配置完成后，CMake 会根据解析的指令生成相应的构建系统文件（如 Makefile、Visual Studio 解决方案文件等）。这些构建系统文件包含了所有主目录和子目录中定义的目标及其依赖关系。

3. 构建阶段

在执行构建命令（如 make 或通过 IDE 构建项目）时，构建系统会根据生成的文件按顺序构建所有目标，包括主目录和所有通过 add_subdirectory() 添加的子目录中的目标。

详细示例

让我们通过一个具体的示例来说明 add_subdirectory() 的作用和流程。

项目结构

假设你的项目结构如下：

MyProject/
├── CMakeLists.txt
├── src/
│   ├── CMakeLists.txt
│   ├── main.cpp
│   ├── utils.cpp
│   └── app.cpp
├── lib/
│   ├── CMakeLists.txt
│   ├── lib1.cpp
│   └── lib2.cpp
└── include/
    ├── utils.h
    └── app.h

主目录的 CMakeLists.txt

cmake_minimum_required(VERSION 3.10)
project(MyProject)

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

# 添加包含目录
include_directories(${PROJECT_SOURCE_DIR}/include)

# 添加子目录
add_subdirectory(lib)
add_subdirectory(src)

# 定义最终的可执行文件，并链接子目录生成的库
add_executable(MyApp ${SRC_FILES})
target_link_libraries(MyApp PRIVATE mylib)

# 输出配置信息
message(STATUS "Source files: ${SRC_FILES}")
message(STATUS "Library files: ${LIB_SOURCES}")

lib 子目录的 CMakeLists.txt

# lib/CMakeLists.txt

# 定义库的源文件列表
set(LIB_SOURCES
    lib1.cpp
    lib2.cpp
)

# 创建静态库或动态库
add_library(mylib STATIC ${LIB_SOURCES})
# 或者创建动态库
# add_library(mylib SHARED ${LIB_SOURCES})

# 指定库的包含目录
target_include_directories(mylib PUBLIC ${PROJECT_SOURCE_DIR}/include)

# 将库源文件传递到父作用域
set(LIB_SOURCES ${LIB_SOURCES} PARENT_SCOPE)

src 子目录的 CMakeLists.txt

# src/CMakeLists.txt

# 定义源文件列表，包含当前目录的源文件
set(SRC_FILES
    main.cpp
    utils.cpp
    app.cpp
)

# 将源文件传递到父作用域
set(SRC_FILES ${SRC_FILES} PARENT_SCOPE)

执行过程解析

1. 配置主目录：

   • CMake 读取主目录的 CMakeLists.txt。
   • 设置 C++ 标准和包含目录。
   • 执行 add_subdirectory(lib)：
     • 进入 lib 子目录，读取并解析 lib/CMakeLists.txt。
     • 定义库源文件 lib1.cpp 和 lib2.cpp。
     • 创建名为 mylib 的静态库。
     • 设置库的包含目录。
     • 将 LIB_SOURCES 变量传递回父作用域。
   • 执行 add_subdirectory(src)：
     • 进入 src 子目录，读取并解析 src/CMakeLists.txt。
     • 定义源文件 main.cpp、utils.cpp 和 app.cpp。
     • 将 SRC_FILES 变量传递回父作用域。
   • 回到主目录，定义可执行文件 MyApp，并将 SRC_FILES 作为其源文件。
   • 链接 MyApp 与 mylib 库。

2. 生成构建系统：

   • CMake 根据配置生成对应的构建系统文件（如 Makefile）。
   • 构建系统包含主目录和所有子目录的构建规则和依赖关系。

3. 构建项目：

   • 运行 make（或其他构建命令）时，构建系统会按顺序构建 mylib 库和 MyApp 可执行文件，确保依赖关系正确。

关键点总结

1. 递归处理：

   • add_subdirectory() 允许 CMake 递归地处理子目录中的 CMakeLists.txt，使得每个子目录可以独立定义其构建规则和目标。

2. 模块化管理：

   • 通过将不同功能模块放在独立的子目录中，项目结构更加清晰，便于维护和扩展。

3. 作用域管理：

   • 子目录可以访问父目录的变量，但默认情况下，父目录无法访问子目录中定义的变量。通过使用 PARENT_SCOPE 选项，可以将子目录中的变量传递到父作用域。

4. 构建顺序：

   • CMake 按照 add_subdirectory() 命令的顺序处理子目录，确保构建顺序符合依赖关系。例如，库通常在可执行文件之前构建，以便可执行文件可以正确链接库。

5. 独立配置：

   • 每个子目录可以有自己独立的编译选项、包含目录和链接库，提供了高度的灵活性。

进一步的示例和注意事项

多级子目录

如果项目中有多级子目录，例如 src/module1 和 src/module2，可以在 src/CMakeLists.txt 中进一步使用 add_subdirectory(module1) 和 add_subdirectory(module2) 来递归处理这些子目录。

# src/CMakeLists.txt

add_subdirectory(module1)
add_subdirectory(module2)

# 定义 src 目录下的源文件
set(SRC_FILES
    main.cpp
    utils.cpp
    app.cpp
)

# 将源文件传递到父作用域
set(SRC_FILES ${SRC_FILES} PARENT_SCOPE)

使用相对路径和全局变量

在子目录的 CMakeLists.txt 中，路径通常是相对于子目录本身的。例如，lib/CMakeLists.txt 中的 lib1.cpp 实际上指的是 lib/lib1.cpp。

如果需要在多个子目录中共享变量或路径，可以在主目录中定义全局变量或使用 CMake 的全局范围选项（如 CACHE 变量）来传递信息。

错误处理

如果 add_subdirectory() 指定的子目录不存在或没有 CMakeLists.txt 文件，CMake 会报错并中止配置过程。因此，确保所有子目录中都存在有效的 CMakeLists.txt 文件。

条件添加子目录

有时，你可能希望根据某些条件（如选项或平台）来决定是否添加某个子目录。可以结合 if() 语句使用 add_subdirectory()。

# 主目录的 CMakeLists.txt

option(USE_LIB "Use the lib module" ON)

if(USE_LIB)
    add_subdirectory(lib)
endif()

add_subdirectory(src)

在这个示例中，只有在 USE_LIB 选项为 ON 时，才会添加 lib 子目录。

总结

add_subdirectory() 是 CMake 中用于模块化和结构化项目的关键命令。它允许你将项目划分为多个子目录，每个子目录可以独立定义其构建规则和目标。这不仅提高了项目的可维护性和可扩展性，还使得团队协作更加高效。

优点

• 结构清晰：项目目录层次分明，便于导航和理解。
• 模块化：每个模块或组件可以独立开发和测试。
• 灵活性：每个子目录可以有不同的编译选项和依赖关系。
• 可扩展性：轻松添加新的模块或组件，无需修改主 CMakeLists.txt。

最佳实践

1. 合理组织目录结构：将相关功能的源文件和头文件放在同一子目录中。
2. 保持 CMakeLists.txt 简洁：每个子目录的 CMakeLists.txt 应该只包含与该子目录相关的配置，避免不必要的复杂性。
3. 使用变量传递：通过 PARENT_SCOPE 或其他机制，合理传递需要共享的变量。
4. 避免全局变量冲突：使用命名规范，确保不同子目录中的变量不会互相覆盖或冲突。
5. 利用 CMake 的功能：充分利用 CMake 提供的命令和功能，如 target_include_directories()、target_link_libraries() 等，来管理依赖关系和编译选项。