如何使用g++的-fmodule-mapper选项映射编译头单元？

头单元的模块映射规则和普通C++模块不一样，核心是要把头文件名用引号或尖括号包裹作为映射键，而不是直接写裸文件名。以下是具体操作步骤和注意事项：

1. 确认头单元的编译产物路径 #

先确保你已经正确编译头单元生成了.gcm文件，比如把my_headers.hpp编译到自定义目录./my_modules/下：

g++ -std=c++20 -c my_headers.hpp -o ./my_modules/my_headers.hpp.gcm

2. 正确编写模块映射文件mm.txt #

映射文件里，头单元的键必须用引号（对应源文件里import "header";）或尖括号（对应import <header>;）包裹，示例如下：

# 针对带引号的import语句的映射
"my_headers.hpp" = "./my_modules/my_headers.hpp.gcm"

# 如果源文件用尖括号import，映射键也要对应
# <my_headers.hpp> = "./my_modules/my_headers.hpp.gcm"

注意：不要省略引号/尖括号，否则g++会把它识别为普通模块名，而非头单元——这就是你之前报错找不到模块的核心原因。

3. 编译源文件的正确参数 #

编译引用头单元的代码时，除了指定-fmodule-mapper=mm.txt，还要确保C版本是C20及以上，同时源文件里的import语句要和映射键完全匹配：
比如main.cpp里的代码：

import "my_headers.hpp"; // 和映射里的"my_headers.hpp"完全对应

int main() {
    // 使用头单元中的内容
    return 0;
}

编译命令：

g++ -std=c++20 -fmodule-mapper=mm.txt main.cpp -o main

常见排查点 #

• 映射文件里的.gcm路径要正确：用相对路径时，是相对于编译时的工作目录，而非映射文件所在目录；也可以直接写绝对路径避免路径混淆。
• 源文件的import语句格式必须和映射键一致：映射用"my_headers.hpp"，就不能写import my_headers.hpp;（无引号）。
• 检查.gcm文件是否存在且编译正确：可以重新编译头单元，确保没有编译错误导致产物缺失。

内容的提问来源于stack exchange，提问作者programmer