模块导入语法 ​

什么是模块导入 ​

import 是 C++20 引入的关键字,用来导入一个模块或头文件单元。导入后,被导入模块中所有导出的声明在当前翻译单元中变得可见,可以直接使用。import 是一个 C++ 语句(不是预处理指令),以分号结尾。

与 #include 不同,import 不会把被导入模块的源代码文本复制到当前文件中,而是让编译器读取预先编译好的模块接口(BMI),因此速度更快,也不会引入宏污染。

导入的三种形式 ​

形式语法说明
导入命名模块import 模块名;导入指定模块的所有导出声明
导入模块分区import :分区名;导入当前模块的指定分区(只能在同一模块内使用)
导入头文件单元import <头文件>; 或 import "头文件";将头文件作为模块导入

基本示例 ​

cpp
// ============================
// 文件:greet.cppm(模块接口单元)
// ============================
export module greet;  // 声明模块 greet

import <string>;      // 导入头文件单元(如果编译器支持)

// 导出的函数
export std::string hello(const std::string& name) {
    return "你好, " + name + "!";
}

export std::string goodbye(const std::string& name) {
    return "再见, " + name + "!";
}

// ============================
// 文件:main.cpp
// ============================
import greet;         // 导入命名模块 greet

#include <iostream>   // 传统头文件仍然可用

int main() {
    // 使用导入模块中导出的函数
    std::cout << hello("C++20") << std::endl;
    std::cout << goodbye("旧时代") << std::endl;
    return 0;
}

导入命名模块 ​

这是最常用的导入形式。导入一个命名模块后,该模块中所有导出的声明都变得可见。

cpp
// ============================
// 模块 math_utils
// ============================
export module math_utils;

export namespace math {
    int abs(int x) { return x < 0 ? -x : x; }
    int max(int a, int b) { return a > b ? a : b; }
    int min(int a, int b) { return a < b ? a : b; }
}

// ============================
// 使用方
// ============================
import math_utils;  // 导入模块

#include <iostream>

int main() {
    std::cout << math::abs(-5) << std::endl;   // 5
    std::cout << math::max(3, 7) << std::endl; // 7
    return 0;
}

导入模块分区 ​

模块分区是模块内部的组织方式。分区名用冒号 : 前缀表示。分区只能在同一模块内导入,外部使用者不能直接导入分区。

cpp
// ============================
// 文件:math-add.cppm(分区接口单元)
// ============================
export module math:add;  // 模块 math 的分区 add

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

// ============================
// 文件:math-mul.cppm(分区接口单元)
// ============================
export module math:mul;  // 模块 math 的分区 mul

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

// ============================
// 文件:math.cppm(主接口单元)
// ============================
export module math;      // 主接口单元

// 导入分区并重新导出
export import :add;      // 导入并导出分区 add
export import :mul;      // 导入并导出分区 mul

// 主接口单元也可以添加自己的导出
export int square(int x) {
    return multiply(x, x);  // 可以使用分区中的函数
}

// ============================
// 文件:main.cpp(使用方)
// ============================
import math;  // 导入模块 math,自动获得所有重新导出的分区

#include <iostream>

int main() {
    std::cout << add(3, 4) << std::endl;       // 来自分区 add
    std::cout << multiply(3, 4) << std::endl;  // 来自分区 mul
    std::cout << square(5) << std::endl;       // 来自主接口
    return 0;
}

重新导出(export import) ​

一个模块可以导入另一个模块并重新导出它。这样外部使用者只需导入"聚合模块",就能访问所有被重新导出的模块中的声明。

cpp
// ============================
// 子模块 graphics.shapes
// ============================
export module graphics.shapes;

export struct Circle {
    double radius;
    double area() const { return 3.14159 * radius * radius; }
};

export struct Rect {
    double width, height;
    double area() const { return width * height; }
};

// ============================
// 子模块 graphics.colors
// ============================
export module graphics.colors;

export struct Color {
    unsigned char r, g, b;
};

export const Color Red{255, 0, 0};
export const Color Green{0, 255, 0};
export const Color Blue{0, 0, 255};

// ============================
// 聚合模块 graphics
// ============================
export module graphics;

// 重新导出两个子模块
export import graphics.shapes;
export import graphics.colors;

// 也可以添加自己的导出
export void draw_info() {
    // ...
}

// ============================
// 使用方
// ============================
import graphics;  // 一次导入获得 shapes + colors + graphics 自身

#include <iostream>

int main() {
    Circle c{5.0};
    std::cout << "面积: " << c.area() << std::endl;

    Color bg = Blue;
    std::cout << "蓝色 R=" << (int)bg.r
              << " G=" << (int)bg.g
              << " B=" << (int)bg.b << std::endl;
    return 0;
}

导入头文件单元 ​

头文件单元允许用 import 语法导入传统头文件。编译器把头文件转换成一个合成的模块接口。

cpp
// 用 import 代替 #include
import <iostream>;    // 导入标准头文件单元
import <vector>;
import <string>;
import "my_header.h"; // 导入用户头文件单元(如果编译器支持)

int main() {
    std::vector<std::string> names{"Alice", "Bob"};
    for (const auto& name : names) {
        std::cout << name << std::endl;
    }
    return 0;
}

头文件单元导入和普通 #include 的区别:

方面#includeimport <header>
宏导出头文件中的宏在包含者中可见头文件中的宏在导入者中可见(特例)
编译速度每次包含都要解析编译器可以缓存接口
符号隔离无隔离部分隔离

注意:头文件单元导入是一个特例——它确实会导出宏(和 #include 一样),这与命名模块不同。

import 声明的位置规则 ​

规则说明
必须在全局命名空间作用域不能在函数内部或类内部写 import
在模块单元中必须在其他声明之前import 语句要写在所有非 import/export 声明之前
可以和 #include 混用但 import 要写在 #include 之前或之后,具体取决于编译器

适用场景 ​

  • 导入自定义模块使用其导出的 API
  • 通过 export import 构建聚合模块,简化外部使用
  • 用模块分区组织大型模块的内部结构
  • 用头文件单元逐步将旧项目迁移到模块

常见问题 ​

import 和 #include 可以在同一个文件中混用吗?

可以,但顺序有讲究。一般建议把 import 写在文件顶部,#include 在 import 之后。不同编译器对混用的支持程度不同。

import 会导入模块中的宏吗?

命名模块不会——这是模块的设计目标之一。但头文件单元(import <header>)会导入宏,因为头文件单元需要和 #include 行为兼容。

可以循环导入吗?

不可以。模块之间不能有循环的接口依赖。如果 A 导入 B,B 就不能直接或间接导入 A 的接口。

import 一个模块时,它传递导入的模块也可见吗?

只有被 export import 重新导出的模块才对导入者可见。普通 import(不带 export)导入的模块不会传递给导入者。

分区可以被模块外部直接导入吗?

不可以。分区只能在同一模块内导入(用 import :分区名;)。外部使用者只能导入主模块,通过主模块重新导出的分区来间接访问分区中的声明。

注意事项 ​

  • import 是 C++ 语句,不是预处理指令,必须以分号结尾
  • import 必须写在全局命名空间作用域
  • 模块不能有循环接口依赖
  • 被导入模块必须先被编译——构建顺序很重要
  • export import 会把被导入模块的导出声明传递给导入者
  • 普通 import(不带 export)不会传递导出声明
  • 头文件单元导入是编译器支持的可选特性,不是所有编译器都完整支持

编译器支持情况 ​

编译器最低支持版本头文件单元支持
MSVC19.28 (VS 2019 16.8)支持
GCC11.0有限支持
Clang16.0有限支持

总结 ​

C++20 的 import 语句用于导入命名模块、模块分区或头文件单元。导入命名模块后,其所有导出声明在当前翻译单元中可见。模块分区用 import :分区名 导入,但只能在同一模块内使用。export import 可以将导入的模块重新导出,让外部使用者通过聚合模块一次性获取多个子模块的声明。头文件单元用 import <header> 导入传统头文件,作为从 #include 向模块迁移的过渡方案。import 和 #include 可以混用,但需要注意顺序和编译器的支持程度。