模块声明与导出
什么是 C++20 模块
C++20 模块是一种替代传统头文件 #include 机制的新特性。传统头文件的工作方式是文本替换——预处理器把头文件的内容原封不动地复制到每个包含它的源文件中,这导致编译缓慢、宏污染、符号重复定义等问题。模块从根本上改变了这个机制:模块被编译一次,生成一个二进制接口文件(BMI),其他翻译单元导入这个接口即可使用其中导出的声明。
模块和命名空间是正交的概念——模块控制可见性(哪些声明能被外部看到),命名空间控制名字的作用域(避免命名冲突)。
模块 vs 头文件
| 方面 | 头文件(#include) | 模块(import) |
|---|---|---|
| 工作方式 | 文本替换(复制粘贴) | 编译一次,导入接口 |
| 编译速度 | 慢(重复解析) | 快(接口只编译一次) |
| 宏隔离 | 无(宏会泄漏) | 有(模块内的宏不泄漏) |
| 声明顺序 | 有影响(先声明后使用) | 无影响(导出的名字都可见) |
| 符号可见性 | 默认全部可见 | 只有导出的才可见 |
| ODR 违反风险 | 高(多次包含可能重复定义) | 低(模块接口唯一) |
| 构建依赖 | 需要 include guard 或 #pragma once | 自动处理 |
模块声明语法
每个模块单元(Module Unit)的开头必须有一个模块声明:
[export] module 模块名 [:分区名] ;export module M;—— 声明模块接口单元(对外可见)module M;—— 声明模块实现单元(内部使用)- 模块名由标识符和点号组成,如
math、graphics.shapes、my_lib.utils - 点号没有语义含义(不表示层次关系),只是命名约定
导出声明
模块中的声明默认是模块内部的(不可见)。要让外部使用,需要显式导出。导出有三种形式:
直接导出
// math.cppm(模块接口单元)
export module math;
// 导出函数
export int add(int a, int b) {
return a + b;
}
// 导出类
export class Calculator {
public:
int compute(int a, int b) const {
return a + b;
}
};
// 导出常量
export constexpr double pi = 3.14159265358979;
// 导出模板
export template<typename T>
T square(T x) {
return x * x;
}
// 未导出的函数——模块外部不可见
int internal_helper(int x) {
return x * 2;
}导出块
// geometry.cppm
export module geometry;
// 用花括号包裹,块内的所有声明都被导出
export {
struct Point {
double x, y;
};
struct Line {
Point start, end;
};
double distance(const Point& a, const Point& b);
constexpr int dimensions = 2;
}
// 导出块外的声明不导出
double distance_impl(double dx, double dy) {
return /* ... */ 0.0;
}导出命名空间
// shapes.cppm
export module shapes;
// 导出整个命名空间——命名空间内的所有声明都被导出
export namespace shapes {
class Circle {
public:
Circle(double r) : radius_(r) {}
double area() const { return 3.14159 * radius_ * radius_; }
private:
double radius_;
};
class Rectangle {
public:
Rectangle(double w, double h) : width_(w), height_(h) {}
double area() const { return width_ * height_; }
private:
double width_, height_;
};
double total_area(const Circle& c, const Rectangle& r) {
return c.area() + r.area();
}
}
// 同一命名空间但不在 export 块内——不导出
namespace shapes {
// 这个函数模块外部看不到
void internal_validate() {}
}基本示例
// ============================
// 文件:mymath.cppm(模块接口单元)
// ============================
export module mymath; // 模块声明:声明这是模块 mymath 的接口单元
// 导出块:块内所有声明对外可见
export {
// 导出的命名空间
namespace mymath {
// 基本算术函数
int add(int a, int b) {
return a + b;
}
int subtract(int a, int b) {
return a - b;
}
int multiply(int a, int b) {
return a * b;
}
// 安全除法,除数为零时返回默认值
double divide(double a, double b, double default_val = 0.0) {
if (b == 0.0) return default_val;
return a / b;
}
// 导出的常量
constexpr double pi = 3.14159265358979;
constexpr double e = 2.71828182845905;
}
}
// 未导出的辅助函数——只在模块内部可用
namespace mymath {
bool is_valid_divisor(double d) {
return d != 0.0;
}
}
// ============================
// 文件:main.cpp(使用模块的翻译单元)
// ============================
import mymath; // 导入模块
#include <iostream>
int main() {
// 使用导出的函数
std::cout << "3 + 4 = " << mymath::add(3, 4) << std::endl;
std::cout << "10 / 3 = " << mymath::divide(10.0, 3.0) << std::endl;
std::cout << "pi = " << mymath::pi << std::endl;
// mymath::is_valid_divisor(3.0); // 编译错误:未导出,不可见
return 0;
}导出规则
| 规则 | 说明 |
|---|---|
| 只能导出命名空间作用域的声明 | 不能导出局部变量或块作用域的声明 |
| 不能导出具有内部链接的实体 | static 函数/变量、匿名命名空间中的实体不能导出 |
| 导出的类自动导出其成员 | 导出 class Foo 就导出了它的所有公有成员 |
| 导出的命名空间导出其中的声明 | export namespace N { ... } 导出 N 中的所有声明 |
| 不能重复导出同一声明 | 一个声明只能被导出一次 |
| 导出声明必须在模块接口单元中 | 模块实现单元中不能使用 export |
不能导出的情况
export module example;
// 错误:不能导出 static(内部链接)
// export static int x = 0;
// 错误:不能导出匿名命名空间中的实体
// namespace { export int y = 0; }
// 错误:不能在模块实现单元中导出
// (模块实现单元用 module example; 而不是 export module example;)文件扩展名约定
不同编译器对模块接口文件的扩展名有不同约定:
| 编译器 | 推荐扩展名 | BMI 扩展名 |
|---|---|---|
| MSVC | .ixx | .ifc |
| GCC | .cppm 或 .cpp | .gcm |
| Clang | .cppm | .pcm |
这些扩展名不是标准规定的,只是各编译器的约定。
适用场景
- 新项目中替代头文件组织代码
- 大型项目中减少编译时间
- 库的接口定义(只导出公开 API)
- 避免宏污染和头文件顺序问题
常见问题
模块名中的点号有什么含义?
没有任何语义含义。std.core 不表示 std 是 core 的父模块。点号只是命名约定,用来表达逻辑上的层次关系,编译器不会因为名字中有点号而建立模块间的层次依赖。
模块中的宏会泄漏到导入者吗?
不会。这是模块和头文件的一个重要区别。模块内部定义的宏不会被导入者看到。如果你需要共享宏,仍然要用头文件。
export 可以用于 using 声明吗?
可以。export using SomeType = int; 是合法的。你也可以用 export using 把未导出的名字重新导出。
模块可以导出模板吗?
可以。函数模板、类模板、变量模板都可以导出。模板的定义会包含在模块接口中,导入者可以实例化模板。
注意事项
- 模块声明必须是翻译单元中的第一个声明(全局模块片段除外)
- 同一模块的主接口单元只能有一个
- 模块内未导出的声明对导入者不可见,但在模块内部的其他单元中可见
- 编译顺序很重要——被导入的模块必须先编译
- 当前构建系统(CMake 等)对模块的支持仍在改进中
- 模块不能替代所有头文件场景(如宏、条件编译等仍需头文件)
编译器支持情况
| 编译器 | 最低支持版本 | 支持程度 |
|---|---|---|
| MSVC | 19.28 (VS 2019 16.8) | 较好 |
| GCC | 11.0 | 基本支持 |
| Clang | 16.0 | 基本支持 |
总结
C++20 模块通过 export module 声明模块接口单元,用 export 关键字控制哪些声明对外可见。导出有三种形式:直接在声明前加 export、用 export { ... } 块导出多个声明、用 export namespace 导出整个命名空间。未导出的声明只在模块内部可见,这提供了比头文件更精细的可见性控制。模块编译一次生成二进制接口,导入者不需要重复解析源代码,编译速度因此得到提升。模块内的宏不会泄漏到导入者,避免了传统头文件的宏污染问题。