全局模块片段 ​

什么是全局模块片段 ​

全局模块片段(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)
  • 内部链接的实体被附加到模块会导致问题
  • 编译器可能报错或产生意外行为
cpp
// 错误做法:在模块声明后 #include
export module mymodule;
#include <vector>  // vector 的所有声明被附加到 mymodule,这不对

// 正确做法:在全局模块片段中 #include
module;
#include <vector>  // vector 的声明属于全局模块
export module mymodule;
// 现在可以使用 vector,但它不属于 mymodule

基本示例 ​

cpp
// ============================
// 示例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;
}
cpp
// ============================
// 示例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
    }
}
cpp
// ============================
// 示例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

编译器支持情况 ​

编译器最低支持版本
MSVC19.28 (VS 2019 16.8)
GCC11.0
Clang16.0

总结 ​

全局模块片段是 C++20 模块单元中 module; 到模块声明之间的特殊区域,用于安全地 #include 传统头文件。在这个区域中只能放预处理指令,被包含的内容属于全局模块而非当前命名模块。全局模块片段主要用于三种场景:包含需要宏配置的头文件、包含 C 语言头文件、以及在编译器不支持头文件单元导入时包含标准库头文件。如果头文件不依赖预处理宏,优先使用 import <header> 而不是全局模块片段中的 #include。