预处理和翻译单元：include、宏、条件编译与编译输入 / Preprocessing And Translation Unit

本文属于 C++ 环境与工具链模块。

本文只站在整条工程链的一个环节上，把这个环节的输入、输出、工具、配置、错误和验证方法讲清楚。

C++ 编译器前端并不是直接处理你脑子里理解的“项目”。它一次处理一个翻译单元。翻译单元可以粗略理解为：一个 .cpp 文件经过 include、宏展开、条件编译之后得到的完整文本。

1. 为什么这一环节重要

头文件找不到、宏污染、平台分支选错，都是在正式语法和类型检查之前就可能发生的问题。

你写的 main.cpp
  |
  +-- include 展开
  +-- macro 替换
  +-- 条件编译选择
  |
  v
编译器真正看到的翻译单元

C++ 工程排错最怕把所有问题都叫“环境问题”。

更好的方式是先判断阶段，再看这个阶段的输入、输出和搜索规则。

现象
  |
  v
判断阶段
  |
  v
确认输入
  |
  v
确认工具和搜索路径
  |
  v
确认输出
  |
  v
做最小实验

2. 最小心智模型

source file
  |
  v
preprocessor
  |
  +-- include search
  +-- macro expansion
  +-- conditional compilation
  |
  v
translation unit
  |
  v
compiler frontend

这个模型不要求你马上背住所有工具细节。

学习时只要反复回答五个问题：

谁负责这一层？
输入是什么？
输出是什么？
它调用谁？
失败时错误长什么样？

3. 本文基础词小注释

include：预处理指令，通常把另一个文件的内容展开到当前文件中。它不是链接，也不是运行时导入。

macro：宏。预处理阶段的文本替换规则，没有 C++ 类型系统保护。

conditional compilation：条件编译。根据宏条件选择保留或删除某些源码文本。

translation unit：翻译单元。一个源文件经过预处理后交给编译器前端的输入单位。

include search path：头文件搜索路径。编译器处理 include 时会按一组目录查找文件。

preprocessed file：预处理输出文件，常见扩展名 .i 或 .ii，能帮助观察编译器实际看到的文本。

4. 它在整条工程链里的位置

编译器工具链
  |
  v
预处理和翻译单元  <--- 本文
  |
  v
目标文件、符号和 ABI

这张图的价值在于：当你看到一个工具名或报错时，不要马上把它孤立理解。

例如一个“找不到库”的问题，可能发生在链接阶段，也可能发生在运行装载阶段。

前者通常要看链接器参数、库文件格式和搜索路径；后者通常要看动态库部署、运行时 PATH、rpath 或系统 loader 规则。

5. 命令和实验入口

只运行预处理

当你怀疑 include 或宏有问题时，先停在预处理阶段。

g++ -std=c++17 -E main.cpp -o main.ii

拆开看：

-E
  只做预处理，不继续编译

main.cpp
  输入源文件

-o main.ii
  保存预处理结果

成功时观察：

生成 main.ii，可以搜索宏展开后的代码和 include 进来的声明

失败时先判断：

头文件找不到 -> include 搜索路径问题
宏语法错误 -> 预处理阶段问题

增加头文件搜索路径

第三方库头文件不在默认路径时，需要明确告诉编译器。

g++ -std=c++17 -Ithird_party/foo/include -c main.cpp -o main.o

拆开看：

-Ithird_party/foo/include
  把这个目录加入头文件搜索路径

-c
  只生成目标文件，不链接

main.cpp
  输入源文件

成功时观察：

编译器能找到 foo 相关头文件

失败时先判断：

路径层级不对 -> 仍然找不到头文件
找到了错误版本头文件 -> 后续类型或 ABI 问题

定义条件编译宏

平台、特性开关和 Debug 配置常用宏控制。

g++ -std=c++17 -DAPP_DEBUG=1 -E main.cpp -o main.ii

拆开看：

-DAPP_DEBUG=1
  在命令行中定义宏 APP_DEBUG，值为 1

-E
  观察条件编译后的结果

成功时观察：

预处理输出中保留 APP_DEBUG 对应分支

失败时先判断：

宏名拼错 -> 条件分支没有进入
多个宏冲突 -> 生成意外源码

6. 工程边界和取舍

这一层的工具选择没有绝对答案。个人学习项目更需要透明和可观察；团队项目更需要一致配置、CI 可复现和明确依赖边界；大型工程更关心增量构建、缓存、远程执行和严格依赖图。

少量平台差异
  可以用条件编译隔离

大量平台差异
  应该提高抽象层，拆分平台实现文件

公共头文件
  应尽量少放宏和可变配置

模板和 inline
  经常需要定义在头文件中

不要先问哪个工具“最好”。

先问你的项目约束是什么：

是否跨平台？
是否要给别人构建？
是否要进入 CI？
依赖来自源码还是二进制？
是否要发布给没有开发环境的机器？
是否要保留可调试性？

7. 常见错误和误解

1. 把 include 当成链接

include
  只让当前翻译单元看到声明或定义文本

link
  才把目标文件和库连接成程序

头文件找到了，不代表链接库也找到了。

2. 滥用宏

macro
  +-- 先于类型检查
  +-- 可能重复求值
  +-- 可能污染名字
  +-- 可能改变报错位置

能用 constexpr、inline、enum class、template 解决的事，优先考虑语言机制。

3. 忽略条件编译分支

Windows 分支能编
Linux 分支长期没人编
  |
  v
跨平台时才爆炸

平台分支需要在 CI 或至少本地矩阵里验证。

8. 排查方法：从现象回到阶段

排查时先保留完整证据，不要只截最后一行。

完整命令
完整错误信息
当前工作目录
工具版本
构建目录
目标架构
Debug / Release
依赖来源
最近改动

然后把错误放回阶段：

fatal error: xxx.h not found
  查 include search path

宏展开后语法奇怪
  生成预处理文件检查

平台代码没进入预期分支
  查预定义宏和 -D 参数

重复定义
  查头文件中是否放了非 inline 定义

这个过程看起来慢，但它能避免最浪费时间的做法：一次改很多参数，然后问题变化了却不知道是哪一个参数起作用。

9. 实践任务

实验 1：观察预处理输出

生成 main.ii 后搜索自己写的函数和宏。

g++ -E main.cpp -o main.ii
打开 main.ii
搜索宏名和 include 进来的声明。

实验 2：制造 include 路径错误

删除 -I 参数，观察错误从哪里出现。

先编译成功
删除 -Ithird_party/foo/include
再次编译
确认错误属于预处理阶段。

实验 3：验证条件编译

用 -D 切换一个 APP_DEBUG 分支。

编译时加 -DAPP_DEBUG=1
生成预处理输出
确认对应分支被保留。

10. 小检查表

• 能解释翻译单元是什么。
• 能用 -E 观察预处理结果。
• 能区分 include 路径问题和链接库问题。
• 能解释宏为什么容易制造隐蔽错误。

11. 阶段对照表

下面这张表不是为了背概念，而是为了把一个错误放回正确位置。

阶段
  你正在学习的这一层

上游输入
  上一层交给它的源码、目标文件、构建描述、包配置或调试信息

本层工具
  实际读取输入并做转换或诊断的程序

本层配置
  命令行参数、环境变量、缓存、IDE 设置、构建类型、目标架构

下游输出
  下一层会继续使用的产物

失败信号
  本层工具输出的第一条有意义错误

套到本文主题，可以这样问：

我现在看到的是哪一种失败？
  |
  +-- 工具没启动
  +-- 输入没找到
  +-- 配置没生效
  +-- 输出缺失
  +-- 下游消费失败
  |
  v
分别回到环境、路径、缓存、产物、接口边界检查

很多 C++ 工程问题之所以难，是因为报错的位置和根因的位置不一定相同。

例如运行时动态库缺失，可能源于依赖管理阶段没有复制 DLL；也可能源于发布阶段没有写清运行目录；还可能源于调试时 IDE 设置了 PATH，而命令行没有。

所以每次排查都要把“现象层”和“根因层”分开。

现象层
  程序或工具最终告诉你的失败

根因层
  最早导致环境、输入、配置或产物不一致的位置

修复层
  真正应该修改的项目文件、构建配置、依赖声明或发布脚本

12. 和其他工具的关系

这一层通常不会单独出现。

它会被 IDE、构建系统、包管理器或 CI 间接调用。

IDE
  |
  +-- 设置工作目录
  +-- 选择工具链
  +-- 调用 CMake 或 MSBuild
  +-- 启动调试器

CMake / Meson / GN
  |
  +-- 探测编译器
  +-- 生成构建图
  +-- 查找包配置

Ninja / Make / MSBuild
  |
  +-- 执行编译命令
  +-- 执行链接命令
  +-- 执行复制或生成命令

vcpkg / Conan / Xmake packages
  |
  +-- 提供依赖路径
  +-- 提供库和运行时文件
  +-- 影响构建配置

这就是为什么同一个项目在不同入口下可能表现不同：

命令行入口
  使用当前 shell 的 PATH 和环境变量

IDE 入口
  使用 IDE profile、kit、run configuration

CI 入口
  使用脚本声明的工具链和依赖缓存

包管理器入口
  使用自己的 triplet、profile、toolchain file 或 package cache

排查时要问：

我现在是从哪个入口启动构建？
这个入口给工具传了什么环境？
这个入口是否和另一个入口使用同一个 build 目录？
这个入口是否复用了旧缓存？

13. 复盘模板

当你解决一个环境或工具链问题后，建议按下面模板记录。

问题标题
  用一句话描述现象，不要只写“编译失败”

发生阶段
  环境 / 编译 / 预处理 / 链接 / 装载 / 构建生成 / 依赖 / 调试 / 发布

最小命令
  能稳定复现问题的最短命令

关键错误
  第一条有意义错误，不是最后一条总结

根因
  哪个输入、路径、配置、版本或产物不一致

修复
  修改了哪个文件、参数、环境变量或依赖声明

验证
  用哪条命令证明修复有效

防复发
  是否需要写进 CMake、README、CI、脚本或项目模板

这份复盘会慢慢变成你自己的工程经验库。

C++ 环境问题非常依赖上下文，只靠记忆搜索结果很难迁移；但如果你每次都记录阶段、输入、输出和验证命令，下一次遇到类似问题就能快速定位。

14. 扩展练习

练习不要追求一次做大。

每次只改变一个变量。

练习 A：换入口
  同一个项目分别从命令行、IDE、CI 脚本入口构建
  比较工具版本、工作目录、环境变量和构建目录

练习 B：换配置
  同一个项目分别构建 Debug 和 Release
  比较编译选项、产物路径、调试信息和运行库

练习 C：换依赖来源
  同一个小库分别用系统包、FetchContent、vcpkg、Conan 或 Xmake package 接入
  比较 include、link、runtime 三阶段差异

练习 D：换平台
  如果有条件，在 Windows 和 Linux 上构建同一项目
  记录动态库命名、搜索路径、调试信息和错误文本差异

这些练习的重点不是掌握所有工具。

重点是形成一种稳定动作：

改变一个条件
  |
  v
观察一个阶段
  |
  v
记录一个证据
  |
  v
修正一个判断

15. 本篇总结

预处理决定编译器真正看到什么。你写的源码和编译器输入之间隔着 include、宏和条件编译。

源码
  |
  v
include / macro / condition
  |
  v
translation unit
  |
  v
编译器前端

下一篇会看预处理之后生成的目标文件，以及目标文件中的符号、节和 ABI 线索。