C++20 中的模块化编程：从头到尾的实战指南

作者

在 C++20 里，模块化编程被正式纳入标准，旨在取代传统的头文件方式，解决编译依赖、编译时间和符号冲突等痛点。本文将从概念入手，逐步搭建一个完整的模块化项目，帮助你快速上手并体验 C++20 模块化的优势。

一、模块化编程的背景与意义

  • 头文件缺陷：重复包含导致编译时间膨胀；宏冲突、预编译单元的复杂性；符号泄漏导致链接错误。
  • 模块化优势：编译单元隔离、编译时间缩短、符号可见性更清晰、支持更强类型的接口定义。

二、基础概念

  • module interface partition：模块接口文件，使用 export module 声明。
  • module implementation partition：模块实现文件，使用 module 声明但不 export。
  • export：仅对外公开的符号。
  • import：引入模块接口。

三、环境准备

  1. 编译器：GCC 11+、Clang 13+、MSVC 19.28+ 均已支持 C++20 模块。
  2. 项目结构：
/modular-demo
├─ src/
│   ├─ math/
│   │   ├─ arithmetic.cppm   // interface
│   │   └─ arithmetic_impl.cppm // implementation
│   └─ main.cpp
├─ build/
└─ CMakeLists.txt

四、实现步骤

1. 编写模块接口

arithmetic.cppm：

export module arithmetic;

export
namespace math {
    export int add(int a, int b);
    export int subtract(int a, int b);
}

这里 export module arithmetic; 表明这是一个模块；export 关键字暴露了接口。

2. 编写模块实现

arithmetic_impl.cppm：

module arithmetic;

namespace math {
    int add(int a, int b) { return a + b; }
    int subtract(int a, int b) { return a - b; }
}

实现文件不使用 export，符号仅在模块内部可见。

3. 在主程序中使用模块

main.cpp：

import arithmetic;
#include <iostream>

int main() {
    std::cout << "5 + 3 = " << math::add(5, 3) << std::endl;
    std::cout << "5 - 3 = " << math::subtract(5, 3) << std::endl;
    return 0;
}

注意，C++20 模块不再使用 #include 来引用模块接口，只需要 import。

五、CMake 配置

CMakeLists.txt：

cmake_minimum_required(VERSION 3.20)
project(ModularDemo LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_library(math STATIC
    src/math/arithmetic.cppm
    src/math/arithmetic_impl.cppm
)

target_sources(math PUBLIC FILE_SET CXX_MODULES FILES
    src/math/arithmetic.cppm
)

add_executable(main src/main.cpp)
target_link_libraries(main PRIVATE math)

CMake 3.20+ 开始支持 FILE_SET CXX_MODULES，用于声明模块源文件。

六、编译与运行

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
./main

输出：

5 + 3 = 8
5 - 3 = 2

七、进阶话题

1. 预编译模块（PMI）

使用编译器特定选项将模块接口编译为预编译文件，后续编译可直接引用，进一步提升构建速度。

2. 与旧代码兼容

在同一项目中，可以在需要的地方继续使用传统头文件，C++20 模块与传统方式共存。

3. 模块的可见性控制

  • export 暴露给外部使用。
  • inline 修饰符可以在模块内部多处定义同名实体，避免重复定义错误。

八、常见问题与排查

现象 可能原因 解决方案
编译报错 error: export keyword only allowed in a module interface export 放在实现文件 移到接口文件
import 报错 module not found CMake 未正确注册模块 检查 FILE_SET CXX_MODULES 配置
链接错误 undefined reference 对外符号未 export 在接口文件加 export

九、总结

C++20 模块化编程为现代 C++ 提供了更高效、可维护的编译体系。通过本文的示例，你可以：

  • 了解模块的基本结构；
  • 在 CMake 项目中集成模块；
  • 体验模块化带来的编译速度提升和符号管理优势。

接下来，你可以尝试将更复杂的库（如 STL、Boost 等）迁移到模块化，或使用模块化构建更大的项目架构，进一步探索 C++20 的强大潜力。祝你编码愉快！

发表评论