C++20 模块化：从头开始构建一个可复用模块化库

作者

在 C++20 之后，模块化成为了 C++ 生态中一大热点。相比传统的预编译头文件（PCH），模块化在编译速度、命名空间污染以及二进制接口（ABI）可维护性方面都拥有明显优势。本文将从零开始，演示如何创建一个简单的 C++20 模块化库，并提供完整的构建脚本与常见陷阱分析，帮助你快速落地实际项目。

一、项目结构

/modlib
├─ src
│  ├─ math.cpp        # 模块实现
│  └─ math.hpp        # 纯声明头文件（可选）
├─ mod
│  ├─ math.ixx        # 模块接口文件
│  └─ math.h          # 传统头文件（兼容旧代码）
├─ test
│  └─ main.cpp        # 使用模块的客户端
├─ CMakeLists.txt
└─ README.md
  • math.ixx：C++20 模块的核心文件，定义模块接口（export module math;）以及导出的实体。
  • math.h：可选的“shim”头文件，用于在不支持模块的编译器或老代码中继续使用 #include "math.h"。它内部使用 export import math; 进行模块导入。
  • math.cpp：实现文件，用于编译生成模块对象文件（math.pcm）和静态/动态库。

二、模块接口文件（math.ixx）

#pragma once
export module math;           // ① 声明模块名
export namespace math {       // ② 创建导出的命名空间

    export inline double add(double a, double b) {
        return a + b;
    }

    export struct Vector2D {
        double x, y;
        export double length() const {
            return std::hypot(x, y);
        }
    };
}
  • export module math;：模块声明，所有文件共同属于此模块。
  • export namespace math：通过 export 标记，模块内的实体对外可见。
  • inline 函数：C++20 允许在模块接口中直接定义（inline）函数，不需要单独的实现文件。

小技巧：如果你想在模块中使用第三方库（如 std::hypot），记得在模块接口顶部添加 `import

;` 或 `export import ;`。

三、传统头文件（math.h）

#pragma once
export import math;   // 让旧代码仍然能 `#include "math.h"`

这份头文件仅是为了兼容不支持模块的编译器或旧项目。它不含任何实现，所有内容都来自 math.ixx。

四、实现文件（math.cpp）

如果你需要在模块中实现非 inline 的函数或类成员，你可以在实现文件中包含模块接口：

module math;          // ① 必须先引入模块接口

export double multiply(double a, double b) {
    return a * b;
}

编译后将得到 math.pcm（模块对象文件）以及可供链接的 math.lib / libmath.so。

五、CMake 构建脚本

cmake_minimum_required(VERSION 3.22)
project(ModLib LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 1. 编译模块对象
add_library(math_obj OBJECT src/math.cpp mod/math.ixx)
target_compile_options(math_obj PRIVATE -fmodules-ts)   # 对于 GCC/Clang
target_link_libraries(math_obj PRIVATE math_obj)       # 对于 MSVC，自动处理

# 2. 创建静态库
add_library(math STATIC $<TARGET_OBJECTS:math_obj>)
target_include_directories(math PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/mod)

# 3. 生成共享库（可选）
add_library(math_shared SHARED $<TARGET_OBJECTS:math_obj>)
set_target_properties(math_shared PROPERTIES OUTPUT_NAME "math")

# 4. 测试可执行文件
add_executable(mod_test test/main.cpp)
target_link_libraries(mod_test PRIVATE math)

# 5. 生成旧头文件兼容版本
add_custom_target(math_header ALL
    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/mod/math.h
            ${CMAKE_CURRENT_BINARY_DIR}/include/math.h
    DEPENDS mod/math.h)

说明

  • add_library(math_obj OBJECT ...) 用来生成模块对象文件。
  • -fmodules-ts 是 Clang / GCC 的实验性模块支持标志，MSVC 不需要。
  • math.h 的生成是可选的，只在你需要兼容旧项目时使用。

六、客户端代码（test/main.cpp）

#include <iostream>
import math;     // C++20 模块导入

int main() {
    double a = 3.14, b = 2.71;
    std::cout << "add: " << math::add(a, b) << '\n';
    std::cout << "multiply: " << math::multiply(a, b) << '\n';

    math::Vector2D v{3, 4};
    std::cout << "vector length: " << v.length() << '\n';
}

如果你使用的是旧编译器或没有模块支持的 IDE，只需改为：

#include "math.h"   // 旧头文件

七、常见问题与最佳实践

场景 常见错误 解决方案
模块依赖 多模块间互相引用导致循环 使用 `export import
;` 前先确保模块已完整编译，避免循环依赖，或拆分模块
编译缓存 旧对象文件残留导致不一致 每次改动模块接口后清理 CMakeCache.txt 并执行 cmake --build . --clean-first
ABI 兼容 直接将模块编译为静态库，跨编译器链接出现错误 采用 -fvisibility=hidden 并显式导出 export，或者使用 -fvisibility-inlines-hidden
头文件兼容 `#include
在模块中导致符号冲突 | 在模块内部使用import ;，在旧头文件中直接包含math.h` 以隐藏冲突
IDE 支持 Visual Studio 2022 仅支持 export 关键字，旧版不识别 在项目中使用 CMake 并确保生成的 .vcxproj 采用 ModuleDefinitionFile
编译器差异 Clang 与 GCC 对模块实现细节不同 使用 -fmodules-ts，并根据不同编译器调整 CMAKE_CXX_FLAGS

八、总结

C++20 模块化为现代 C++ 开发带来了前所未有的性能与可维护性提升。通过本文的完整示例，你可以：

  1. 快速上手：了解模块的核心语法与实现方式。
  2. 构建规范：借助 CMake 脚本实现模块编译、兼容性与可链接性。
  3. 解决常见陷阱：提前规避循环依赖、编译缓存与 ABI 兼容性等问题。

下一步，你可以尝试扩展 math 模块，添加更多子模块（如 geometry、algebra）并实现更复杂的模板元编程特性。祝你编码愉快，模块化之路畅通无阻！

发表评论