全局模块片段
什么是全局模块片段
全局模块片段(Global Module Fragment)是 C++20 模块单元中模块声明之前的一个特殊区域。它以 module; 开头,到 export module M;(或 module M;)结束。在这个区域中,只能放置预处理指令——主要是 #include 和 #define。
全局模块片段的存在是为了解决一个实际问题:模块单元中不应该直接使用 #include(因为被包含的内容会被附加到当前模块),但有些旧头文件无法作为头文件单元导入(比如依赖预处理宏配置的头文件)。全局模块片段提供了一个安全的位置来 #include 这些头文件,让它们的声明属于全局模块而不是当前命名模块。
语法结构
module; // 全局模块片段开始
// 这里只能放预处理指令
#define 宏定义
#include <头文件>
#include "头文件"
export module 模块名; // 全局模块片段结束,模块内容开始
// 模块的正常内容
export void foo();为什么需要全局模块片段
如果在模块声明之后使用 #include,被包含的所有声明和定义都会被附加到当前模块,这会导致:
- 头文件中的声明变成模块的一部分
- 可能违反 ODR(One Definition Rule)
- 内部链接的实体被附加到模块会导致问题
- 编译器可能报错或产生意外行为
// 错误做法:在模块声明后 #include
export module mymodule;
#include <vector> // vector 的所有声明被附加到 mymodule,这不对
// 正确做法:在全局模块片段中 #include
module;
#include <vector> // vector 的声明属于全局模块
export module mymodule;
// 现在可以使用 vector,但它不属于 mymodule基本示例
// ============================
// 示例1:包含标准库头文件
// ============================
// 文件:mylib.cppm
module; // 全局模块片段开始
#include <string> // string 的声明属于全局模块
#include <vector> // vector 的声明属于全局模块
#include <iostream> // iostream 的声明属于全局模块
export module mylib; // 全局模块片段结束
// 可以在模块中使用 string、vector、iostream
// 但它们不是 mylib 模块的一部分
export std::string greet(const std::string& name) {
return "你好, " + name;
}
export std::vector<int> make_range(int n) {
std::vector<int> result;
for (int i = 0; i < n; ++i) {
result.push_back(i);
}
return result;
}
// ============================
// 文件:main.cpp
// ============================
import mylib;
#include <iostream> // main.cpp 不是模块单元,可以正常 #include
int main() {
std::cout << greet("C++20") << std::endl;
auto nums = make_range(5);
for (int n : nums) {
std::cout << n << " ";
}
std::cout << std::endl;
return 0;
}// ============================
// 示例2:使用宏配置的第三方头文件
// ============================
// 文件:platform.cppm
module; // 全局模块片段开始
// 某些头文件需要在包含前定义宏来配置行为
#define WIN32_LEAN_AND_MEAN // 减少 Windows 头文件的内容
#define NOMINMAX // 避免 min/max 宏冲突
// #include <windows.h> // Windows 头文件(实际使用时取消注释)
// POSIX 头文件配置
#define _POSIX_C_SOURCE 200809L
// #include <unistd.h> // POSIX 头文件(实际使用时取消注释)
#include <cstdint> // 标准类型定义
export module platform; // 全局模块片段结束
// 导出平台相关的封装
export namespace platform {
// 获取当前时间戳(简化示例)
std::uint64_t get_timestamp() {
return 0; // 实际实现会调用平台 API
}
// 平台信息
const char* os_name() {
#ifdef _WIN32
return "Windows";
#elif defined(__linux__)
return "Linux";
#elif defined(__APPLE__)
return "macOS";
#else
return "Unknown";
#endif
}
}// ============================
// 示例3:包含 C 语言头文件
// ============================
// 文件:c_wrapper.cppm
module; // 全局模块片段开始
// C 语言头文件通常不能作为头文件单元导入
#include <cstdlib>
#include <cstring>
#include <cmath>
#include <cstdio>
export module c_wrapper; // 全局模块片段结束
// 用 C++ 风格封装 C 函数
export namespace cwrap {
// 安全的字符串复制
char* safe_strdup(const char* src) {
if (!src) return nullptr;
std::size_t len = std::strlen(src) + 1;
char* dst = static_cast<char*>(std::malloc(len));
if (dst) {
std::memcpy(dst, src, len);
}
return dst;
}
// 数学运算封装
double hypotenuse(double a, double b) {
return std::sqrt(a * a + b * b);
}
// 安全释放
void safe_free(void* ptr) {
if (ptr) std::free(ptr);
}
}全局模块片段中的规则
| 规则 | 说明 |
|---|---|
| 只能包含预处理指令 | #include、#define、#ifdef、#pragma 等 |
| 不能有普通声明 | 不能在全局模块片段中写函数、类、变量声明 |
| 声明属于全局模块 | 被 #include 的内容不属于当前命名模块 |
module; 必须是第一行 | 全局模块片段的 module; 必须出现在文件最开头 |
| 宏在全局模块片段内有效 | #define 的宏会影响后续 #include 的头文件 |
全局模块片段 vs 头文件单元导入
| 方面 | 全局模块片段(#include) | 头文件单元导入(import <header>) |
|---|---|---|
| 宏配置 | 可以先 #define 再 #include | 不能,导入前的宏不影响头文件处理 |
| 宏导出 | 不导出(宏在全局模块片段内有效) | 导出头文件中定义的宏 |
| 编译速度 | 慢(每次重新解析头文件) | 快(头文件编译一次) |
| 兼容性 | 好(几乎所有头文件都能用) | 一般(部分头文件不能作为头文件单元) |
| 推荐场景 | 需要宏配置的头文件、C 头文件 | 标准库头文件、不依赖宏的头文件 |
适用场景
- 包含需要预处理宏配置的第三方库头文件
- 包含 C 语言头文件(如 POSIX API、Windows API)
- 包含不兼容模块导入的旧头文件
- 在模块中使用标准库(当编译器不支持
import <header>时) - 从传统代码向模块迁移的过渡期
常见问题
全局模块片段中的 #include 和模块声明后的 #include 有什么区别?
全局模块片段中 #include 的内容属于全局模块,不附加到当前命名模块。模块声明后 #include 的内容会附加到当前模块,可能导致 ODR 违反和其他问题。所以在模块单元中,#include 应该放在全局模块片段中。
全局模块片段中 #define 的宏在模块内容中还有效吗?
有效。全局模块片段中定义的宏在整个翻译单元中都有效(直到被 #undef)。但这些宏不会被导出到导入方。
全局模块片段是必须的吗?
不是。如果模块不需要 #include 任何头文件(比如只用 import 导入其他模块),就不需要全局模块片段。
全局模块片段中可以写 import 吗?
不能。全局模块片段中只能放预处理指令。import 语句要写在模块声明之后。
不用全局模块片段,直接在模块声明后 import 标准库可以吗?
可以,如果编译器支持对应的头文件单元导入。比如 import <iostream>; 在支持的编译器上可以直接写在模块声明之后。但如果头文件需要宏配置,就必须用全局模块片段。
注意事项
module;必须是翻译单元的第一个非空非注释行- 全局模块片段中只能有预处理指令
- 全局模块片段中
#include的声明属于全局模块,不能被当前模块导出 - 如果需要导出某个头文件中的类型,考虑用
export using重新导出 - 宏在全局模块片段定义后在整个文件中有效,但不导出
- 尽量减少全局模块片段中的
#include数量——优先用import
编译器支持情况
| 编译器 | 最低支持版本 |
|---|---|
| MSVC | 19.28 (VS 2019 16.8) |
| GCC | 11.0 |
| Clang | 16.0 |
总结
全局模块片段是 C++20 模块单元中 module; 到模块声明之间的特殊区域,用于安全地 #include 传统头文件。在这个区域中只能放预处理指令,被包含的内容属于全局模块而非当前命名模块。全局模块片段主要用于三种场景:包含需要宏配置的头文件、包含 C 语言头文件、以及在编译器不支持头文件单元导入时包含标准库头文件。如果头文件不依赖预处理宏,优先使用 import <header> 而不是全局模块片段中的 #include。