C / C++ / 系统课时

建立可复现的 CMake 工程

建立可复现的 CMake 工程

这一课把网络库先搭成一个能重复构建、运行和测试的最小工程:源码、公开头文件、示例与测试各归其位,并用目标级 CMake 配置锁定 C++20、编译告警和调试行为,避免“在我机器上能编”的隐患。

学习目标

  • 划分 include、src、examples、tests 的职责,避免库代码与演示代码相互污染。
  • 用目标级 CMake 配置 C++20、告警和调试构建,不依赖全局编译器状态。
  • 从空目录完成配置、编译、运行与测试,确认工程可复现。

先把目录边界固定下来

一个可维护的网络库,最重要的不是目录多,而是每类文件只有一个明确去处。这里使用四个边界:include/netlib 放对外头文件,src 放库实现,examples 放可运行示例,tests 放自动化测试。示例和测试都依赖库目标,但库目标绝不能反向依赖它们。

工程最小结构如下,文件名也会直接对应后面的 CMake 配置。

text
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
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。

写入最小可运行代码

先给库提供一个稳定的公开接口,用它验证头文件路径、链接关系和测试链路是否都正确。

cpp
// include/netlib/version.h
#pragma once

#include <string_view>

namespace netlib {
std::string_view version() noexcept;
}
cpp
// src/version.cpp
#include "netlib/version.h"

namespace netlib {
std::string_view version() noexcept {
    return "0.1.0";
}
}

示例程序只消费公开头文件,不直接包含 src 中的任何实现文件。

cpp
// examples/hello_server.cpp
#include "netlib/version.h"

#include <iostream>

int main() {
    std::cout << "netlib " << netlib::version() << " ready\n";
    return 0;
}

测试同样只通过公开接口判断结果,这样以后重构内部实现时,不会被测试代码绑死。

cpp
// 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 中,不污染源码树。

bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
./build/hello_server
ctest --test-dir build --output-on-failure

预期输出会因编译器和 CMake 版本不同而包含额外日志,但关键结果应包含:

text
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 模块时只需要继续扩展目标和依赖,而不必推翻工程骨架。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立可复现的 CMake 工程

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通