第35章 项目结构与构建

当你从学习单个`.cpp`文件转向开发一个包含数十个模块、依赖多个外部库的真实项目时，第一个拦路虎往往不是算法，而是“项目应该怎么放”和“代码怎么编译”。我见过不少团队，初期随意堆放文件，导致后期编译命令复杂得像天书，新人一周都搭不好环境。

项目目录结构：代码的家

一个清晰的项目结构就像图书馆的索引系统，能极大提升开发和维护效率。没有统一标准，但经过多年实践，社区形成了一些最佳实践。

上图展示了一个典型的中型C++项目布局。关键在于分离：头文件与源文件分离，产品代码与测试代码分离，源代码与生成物分离。

实际开发中，我推荐在src/内为每个主要模块创建子目录，并放置一个CMakeLists.txt。例如一个网络库项目：

MyNetworkLib/
├── CMakeLists.txt          # 根构建脚本
├── include/
│   └── mynet/
│       ├── tcp_client.h
│       └── utils.h
├── src/
│   ├── core/               # 核心模块
│   │   ├── CMakeLists.txt
│   │   └── tcp_client.cpp
│   └── utils/              # 工具模块
│       ├── CMakeLists.txt
│       └── logger.cpp
├── tests/
│   ├── CMakeLists.txt
│   └── test_tcp_client.cpp
└── third_party/
    └── googletest/         # Git子模块引入

构建系统：从Makefile到CMake

直接写Makefile管理多目录、多平台的项目是痛苦的。GCC版本差异、库路径不同、依赖关系复杂，都会让Makefile迅速膨胀。CMake是一个元构建系统，它生成平台相关的构建文件（如Unix的Makefile或Windows的Visual Studio项目）。

对于绝大多数C++项目，CMake是当前事实上的标准选择。从3.0版本开始，其现代语法（如target_*命令）让配置更加清晰。

让我们看一个根目录CMakeLists.txt的现代写法示例：

# CMakeLists.txt (项目根目录)
cmake_minimum_required(VERSION 3.15) # 指定最低版本，我推荐至少3.15
project(MyNetworkLib VERSION 1.0.0 LANGUAGES CXX) # 定义项目名、版本和语言

set(CMAKE_CXX_STANDARD 17) # 设置C++标准为C++17
set(CMAKE_CXX_STANDARD_REQUIRED ON) # 要求编译器必须支持该标准

# 添加子目录，每个子目录有自己的CMakeLists.txt
add_subdirectory(src/core)
add_subdirectory(src/utils)
add_subdirectory(third_party/googletest) # 通常第三方库也通过CMake管理
add_subdirectory(tests)

然后，在src/core/CMakeLists.txt中定义库目标：

# src/core/CMakeLists.txt
add_library(mynet_core STATIC # 创建静态库目标‘mynet_core’
    tcp_client.cpp
)

target_include_directories(mynet_core PUBLIC
    "${CMAKE_CURRENT_SOURCE_DIR}/../../include" # 公开头文件目录
)

target_compile_features(mynet_core PUBLIC cxx_std_17) # 公开C++17要求
# 链接其他依赖，如线程库
target_link_libraries(mynet_core PUBLIC Threads::Threads)

依赖管理：引入第三方库

现代C++项目几乎必然依赖外部库。手动下载、编译、配置包含路径和库路径是繁琐且易错的。CMake提供了find_package()和FetchContent等机制来管理依赖。

我推荐对关键依赖使用FetchContent，它能将第三方库的构建直接集成到你的CMake流程中。以下是如何集成jsoncpp库的例子：

# 在CMakeLists.txt中使用FetchContent
include(FetchContent)
FetchContent_Declare(
    jsoncpp
    GIT_REPOSITORY https://github.com/open-source-parsers/jsoncpp.git
    GIT_TAG 1.9.5 # 指定明确的版本标签！
)
FetchContent_MakeAvailable(jsoncpp)

# 之后就可以像使用普通目标一样链接它
target_link_libraries(myapp PUBLIC jsoncpp_lib)

自动化测试集成

将测试作为构建的一部分，是保证代码质量的核心实践。Google Test (gtest) 是C++领域最流行的单元测试框架。通过CMake集成它非常方便。

在tests/CMakeLists.txt中：

# 添加gtest为子目录（已通过FetchContent或子模块引入）
add_subdirectory("${PROJECT_SOURCE_DIR}/third_party/googletest")

# 创建测试可执行文件
add_executable(test_tcp_client test_tcp_client.cpp)
target_link_libraries(test_tcp_client PRIVATE
    mynet_core          # 链接我们自己的核心库
    GTest::gtest_main   # 链接gtest主库
)

# 告诉CTest这个可执行文件是一个测试
include(GoogleTest)
gtest_discover_tests(test_tcp_client)

配置完成后，在构建目录下执行make test（或ninja test）或直接运行ctest命令，即可自动运行所有测试并报告结果。在CI/CD流水线中，这通常是编译后的必做步骤。

实战：一个完整的构建流程

假设你的项目目录已按上述结构组织好，并且写好了CMakeLists.txt。以下是命令行下的标准构建流程：

# 1. 进入项目根目录，创建一个独立的构建目录（推荐）
$ cd /path/to/MyNetworkLib
$ mkdir build && cd build

# 2. 运行cmake生成构建文件。`..`指向包含顶层CMakeLists.txt的目录
#    使用Ninja生成器（比make更快）
$ cmake -G "Ninja" -DCMAKE_BUILD_TYPE=Debug ..

# 3. 执行编译。Ninja使用`ninja`命令，Makefile使用`make -j8`
$ ninja

# 4. 运行测试
$ ninja test
# 或
$ ctest --output-on-failure

# 5. 安装（如果需要）到系统目录或自定义目录
$ ninja install

踩坑提醒：如果你在Windows上使用Visual Studio生成器，步骤2可能是cmake -G "Visual Studio 16 2019" -A x64 ..，然后使用cmake --build . --config Debug来编译。务必查阅CMake生成器文档。