C / C++ / 系统课时
建立可复现的 CMake 工程
建立可复现的 CMake 工程
这一课把网络库先搭成一个能重复构建、运行和测试的最小工程:源码、公开头文件、示例与测试各归其位,并用目标级 CMake 配置锁定 C++20、编译告警和调试行为,避免“在我机器上能编”的隐患。
学习目标
- 划分
include、src、examples、tests的职责,避免库代码与演示代码相互污染。 - 用目标级 CMake 配置 C++20、告警和调试构建,不依赖全局编译器状态。
- 从空目录完成配置、编译、运行与测试,确认工程可复现。
先把目录边界固定下来
一个可维护的网络库,最重要的不是目录多,而是每类文件只有一个明确去处。这里使用四个边界:include/netlib 放对外头文件,src 放库实现,examples 放可运行示例,tests 放自动化测试。示例和测试都依赖库目标,但库目标绝不能反向依赖它们。
工程最小结构如下,文件名也会直接对应后面的 CMake 配置。
netlib/
CMakeLists.txt
include/netlib/version.h
src/version.cpp
examples/hello_server.cpp
tests/version_test.cpp这类目录结构用文本已经足够清楚,不需要额外配图。真正重要的是依赖方向:netlib 是核心目标,hello_server 与 version_test 都只通过链接 netlib 获得头文件和实现。
配置目标级 CMake
根目录的 CMakeLists.txt 直接创建静态库、示例和测试。C++ 标准通过 target_compile_features 绑定到具体目标,告警也通过 target_compile_options 绑定,避免把选项泄漏给未来可能引入的第三方依赖。
cmake_minimum_required(VERSION 3.20)
project(netlib VERSION 0.1.0 LANGUAGES CXX)
add_library(netlib STATIC
src/version.cpp
)
target_include_directories(netlib
PUBLIC
${CMAKE_CURRENT_SOURCE_DIR}/include
)
target_compile_features(netlib PUBLIC cxx_std_20)
if (MSVC)
target_compile_options(netlib PRIVATE /W4 /permissive-)
else()
target_compile_options(netlib PRIVATE -Wall -Wextra -Wpedantic)
endif()
add_executable(hello_server examples/hello_server.cpp)
target_link_libraries(hello_server PRIVATE netlib)
enable_testing()
add_executable(version_test tests/version_test.cpp)
target_link_libraries(version_test PRIVATE netlib)
add_test(NAME version_test COMMAND version_test)这里没有强行修改 CMAKE_CXX_FLAGS,因为那会把全局选项扩散到所有目标。调试信息也不写死在源码目标里,而是在配置阶段选择 Debug 构建类型;对于 Visual Studio、Xcode 这类多配置生成器,则在构建阶段指定 --config Debug。
写入最小可运行代码
先给库提供一个稳定的公开接口,用它验证头文件路径、链接关系和测试链路是否都正确。
// include/netlib/version.h
#pragma once
#include <string_view>
namespace netlib {
std::string_view version() noexcept;
}// src/version.cpp
#include "netlib/version.h"
namespace netlib {
std::string_view version() noexcept {
return "0.1.0";
}
}示例程序只消费公开头文件,不直接包含 src 中的任何实现文件。
// examples/hello_server.cpp
#include "netlib/version.h"
#include <iostream>
int main() {
std::cout << "netlib " << netlib::version() << " ready\n";
return 0;
}测试同样只通过公开接口判断结果,这样以后重构内部实现时,不会被测试代码绑死。
// tests/version_test.cpp
#include "netlib/version.h"
#include <iostream>
int main() {
if (netlib::version() != "0.1.0") {
std::cerr << "unexpected version\n";
return 1;
}
std::cout << "version ok\n";
return 0;
}这些源码属于一个完整可运行示例,文件路径必须与前面的目录结构一致。
配置、编译并验证
在项目根目录执行下面命令。-S . -B build 把源码目录和构建目录分开,后续生成的缓存、目标文件和可执行文件都留在 build 中,不污染源码树。
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
./build/hello_server
ctest --test-dir build --output-on-failure预期输出会因编译器和 CMake 版本不同而包含额外日志,但关键结果应包含:
netlib 0.1.0 ready
100% tests passed, 0 tests failed out of 1如果使用 Visual Studio 或 Xcode 生成器,CMAKE_BUILD_TYPE 通常不会决定最终配置,应改用 cmake --build build --config Debug,运行文件路径也可能位于 build/Debug/。实际生成路径以当前生成器为准。
让构建问题尽早暴露
如果出现“头文件找不到”,先检查 target_include_directories(netlib PUBLIC ...) 与真实目录是否一致;如果示例能编译但测试不能,检查测试目标是否链接了 netlib。若 Debug 断点无法命中,则先确认实际构建的是 Debug 配置,而不是仅在命令行写了一个没有被多配置生成器使用的变量。
到这里,工程已经具备可复现构建的最小闭环:同一份源码可以从干净目录重新配置、编译、运行并通过测试,后续新增 Reactor 或 RPC 模块时只需要继续扩展目标和依赖,而不必推翻工程骨架。