同事把一个小工具发过来,功能很朴素:把配置文件里几行 key=value 读出来打印。他说编辑器里没有一条红波浪线,代码看着完全正常,可编译命令跑完之后,终端里是这样一段:
ld.exe: main.cpp:(.text+0xa7): undefined reference to `add(int, int)'
collect2.exe: error: ld returned 1 exit status
他用的命令是 g++ -std=c++20 main.cpp -o app.exe。问题不在代码,在命令:add 这个函数写在另一个 .cpp 文件里,而这条命令只把 main.cpp 交给了编译器。于是流程前面几步都顺利走完,最后一步——把各个目标文件拼在一起——找不到 add 的实现,只好报错。
这件小事值得单独开一篇,因为它把「编译」这个词的模糊之处暴露得很清楚。很多人以为「编译」是一次性的动作:通过就是成功了,不通过就是代码写错了。实际上它是一条流水线,四个阶段各管一件事,报错信息里的措辞、退出码、甚至程序跑起来崩不崩,都能对应到其中某一段。
这篇要解决的问题:一条 g++ 命令到底做了什么;编译错误和链接错误怎么一眼分开;退出码 0、1、139 各意味着什么;多文件项目里声明和定义为什么必须分开;编译选项里哪些是必须加的,哪些加了要付代价。读完你能自己判断:这次的失败是语法问题、符号问题、动态库问题,还是程序真的在内存里踩了雷。
「编译过了」这句话本身就不准确
把一条命令拆开看,g++ 从 .cpp 到可执行文件,中间要经过四个阶段。每个阶段都有明确的输入和输出,也都有自己的一套报错方式。
各阶段的具体职责:
- 预处理只是文本替换。
#include <iostream>会把整份标准库头文件抄进来,一行变几千行;#define原样展开;#ifdef决定哪些代码留下。这一步出错通常是找不到头文件。 - 编译才是大家熟悉的「写错了」阶段:类型不匹配、漏分号、调用了不存在的成员,都在这里报。输出是汇编代码,注意此时还没有任何具体地址。
- 汇编把汇编翻成机器码,生成一个目标文件(object file,Linux 上是
.o,Windows 上是.obj)。目标文件里有一张符号表,记录「这个文件提供了哪些函数、还缺哪些函数」。 - 链接把多个目标文件和库合并,逐个解决「谁提供、谁引用」。只有到这一步,函数调用才会被填上真实地址。
关键概念是编译单元(translation unit):一个 .cpp 加上它包含的所有头文件,构成一次独立编译的范围。编译器一次只看一个编译单元,所以 main.cpp 里调用 add 时,只要看到声明就放行,它不负责去别处找实现——找实现是链接器的活儿。这就是「编辑器没报红,链接却失败」的原因:这两件事根本不在同一个阶段。
完整走查:两个文件相加
把上面那个场景补成能跑的版本。目录里三个文件:
// add.h —— 只放声明,让调用方知道有这个东西
#pragma once
int add(int a, int b);
// add.cpp —— 放定义,真正干活
#include "add.h"
int add(int a, int b) {
return a + b;
}
// main.cpp
#include <iostream>
#include <string>
#include "add.h"
int main(int argc, char** argv) {
std::string name = argc > 1 ? argv[1] : "world";
std::cout << "hello, " << name << "\n";
std::cout << "1 + 2 = " << add(1, 2) << "\n";
return 0;
}
正确的构建命令要把两个源文件都列上,并打开常用的警告:
g++ -std=c++20 -Wall -Wextra main.cpp add.cpp -o app.exe
运行结果(本机实测):
hello, world
1 + 2 = 3
退出码是 0。程序正常结束就是要返回 0,这是后续所有「怎么判断失败」的基础:shell 里用 echo $? 看,PowerShell 里看 $LASTEXITCODE,CI 里直接看这一步是否变红。
再看错误版本,只喂一个文件:
g++ -std=c++20 main.cpp -o app.exe
本机输出(原样,路径省略):
ld.exe: main.cpp:(.text+0xa7): undefined reference to `add(int, int)'
collect2.exe: error: ld returned 1 exit status
细看这段话:报错前缀是 ld.exe,也就是链接器,不是编译器;undefined reference 直译是「未定义的引用」,意思是有地方调用了 add(int, int),但没有任何目标文件提供它;collect2.exe: error: ld returned 1 exit status 是编译器驱动转述链接器的失败。看到 ld 这个词,就该往「文件没参与编译、库没链接、签名对不上」这三个方向查,而不是盯着语法。
顺带一个真实存在的小坑:本机把中文当命令行参数传进去,打印出来是 ����。这不是 C++ 把字符串弄坏了,而是控制台代码页(GBK)和程序按 UTF-8 输出之间的错位。系统编程里这类「字节没问题、显示不对」的情况会反复出现,后面讲文件与 I/O 时会专门处理。
现象、原因、先查什么
下面这张表是排错时最省时间的部分。拿到一条报错,先按「哪一段出的问题」分类,再看具体原因,不要一上来就翻代码。
| 你看到的现象 | 真实原因 | 第一步查什么 |
|---|---|---|
error: expected ';' before ... | 语法错误,编译器在某个记号处卡住了 | 看报错行和它上一行的结尾,漏分号、全角括号、字符串没闭合都常见 |
undefined reference to `add(int, int)' | 链接器找不到符号:实现没参与编译,或签名不一致 | 确认该 .cpp 在命令里;确认声明和定义的参数、const、命名空间完全一致 |
cannot find -lxxx 或 library not found | 库名或库路径不对,链接器找不到库文件 | 查 -L 路径是否存在、-l 名字是否少了前缀(Linux 上 libxxx.so 对应 -lxxx) |
一运行就报 No such file or directory(Linux)或 0xc0000135(Windows) | 动态库在运行环境里找不到,不是源码问题 | Linux 用 ldd ./app 看缺哪个;Windows 查同目录和 PATH 里有没有对应 DLL |
| 程序直接崩,退出码 139(Linux)或 -1073741819 / 0xC0000005(Windows) | 访问了非法内存:空指针、越界、对象已释放 | 用 -g 重新编译,拿 gdb 或 ASan 定位;先查指针生命周期而不是业务逻辑 |
GLIBCXX_3.4.29 not found 之类 | 运行机器的 libstdc++ 比构建机器旧 | 在目标环境构建,或了解静态链接的代价(体积、许可证、依然依赖 glibc) |
这张表里最值得注意的是「退出码」。它比任何日志都直接:进程没有正常收尾,才会出现非 0;139 在 Linux 上等于收到 SIGSEGV(11)后加上 128,Windows 上则是访问违例的异常码。先拿到退出码,再决定是查逻辑还是查内存布局。
多文件项目:声明和定义为啥要分开
上面三个文件的分工不是形式主义,它对应着编译模型本身。
三个必须知道的规则:
- 头文件只放声明。如果把普通函数定义写进头文件,被两个
.cpp包含,链接时就会出现multiple definition。想让函数定义待在头文件里,必须加inline,或者用模板——它们允许在多个编译单元里重复出现。 - 每个头文件要能独立编译,加
#pragma once防重复包含。更稳的检查方式是让一个空的.cpp只包含它,单独编译一次;能过,说明头文件没有隐式依赖别的头文件。 - 只想给本文件用的函数,放进匿名命名空间或声明为
static,给它内部链接,别的编译单元就看不到,也不会撞名。
单文件一把梭
写 demo、刷算法题没问题。文件一过几百行,改一处就全量重编,类与函数的依赖全挤在一起,复用只能靠复制。
按接口分文件
前期多写一个头文件,换来改实现时只重编一个单元、调用方不用关心内部细节。代价是头文件要维护,包含关系要干净。
编译选项:默认值不够用
新手最常见的做法是只写 g++ main.cpp,能跑就行。但在系统编程里,默认配置会漏掉大量警告,也不带调试信息,出事后几乎没法查。几个真正该加的:
| 选项 | 作用 | 代价 |
|---|---|---|
-std=c++20 | 固定语言标准,避免换机器后行为漂移 | 旧编译器不支持;团队要统一 |
-Wall -Wextra | 打开常见警告:未使用变量、符号比较、隐式转换等 | 警告会变多,需要真的去处理,而不是关掉 |
-g | 保留调试符号,gdb、ASan 的输出才有行号和变量名 | 二进制变大,生产包通常另存符号文件 |
-O2 | 优化,运行快,内联和常量传播都在这一档 | 编译变慢;单步调试会跳行;未定义行为的后果更难预测 |
-fsanitize=address | 在运行时抓越界、重复释放、悬垂访问,是查内存问题最有效的工具 | 程序变慢、内存占用变大;不能用于生产;本机 MinGW 不支持,未实测 |
-O0 下可能只是读到一个垃圾值,-O2 下可能被编译器直接优化成「不可能发生」,于是整个分支消失。别用「Release 版没问题」来证明代码正确,那可能只是症状被藏起来了。边界与代价:这套编译模型的问题
说清楚代价,才知道什么时候该忍、什么时候该换工具。
- 编译慢。文本包含意味着每个
.cpp都要把<iostream>这类头文件重新解析一遍。工程一大,几分钟的增量编译很常见,这也是预编译头、模块(C++20 modules)被推出来的原因。模块在 GCC 16 上的支持程度建议按项目实测,本文不展开,标为待确认。 - 没有稳定的 ABI。同一个库,用不同编译器或不同标准库版本编出来的二进制,未必能互相链接。C++ 的二进制分发比 C 难得多,跨语言接口一般退回到
extern "C"加纯 C 结构。 - 自由度换来的是责任。语言不替你管内存、不检查越界、默认不拦数据竞争。系统编程选 C++,通常是看中「零成本抽象」:容器和算法写得出来,运行时开销又能控到接近手写 C。代价是上面每一项都要自己兜底。
- 构建系统是另一层复杂度。文件一多,命令行就管不过来了,迟早要引入 CMake 之类的工具。这不在本篇展开,后面有专门一篇讲构建流程。
换个角度看,这些「缺点」也是 C++ 能待在这个位置的原因:它能直接生成接近操作系统调用的代码,又提供足够的抽象能力写业务逻辑。问题不在语言,在用它的人有没有把边界当回事。
当天能验证的练习
下面几条都可以在本机直接跑,做完再往下读,印象会深很多。
- 把上面的三个文件建好,分别执行「只编译 main.cpp」和「两个都编译」,把两次报错原文抄下来,标出哪一段是链接器说的。
- 用
g++ -E main.cpp -o main.i生成预处理结果,看文件有多大(本机实测:包含<iostream>和<string>后,main.i有 32229 行、约 1.2MB,而源文件只有二十来行)。再体会一次「头文件被完整抄进来」是什么意思。 - 用
g++ -c add.cpp -o add.o单独编译一次,然后用nm add.o(或objdump -t)看符号表,找到add那一条。工具是否随编译器安装因环境而异,没有就装 binutils。 - 写一个空指针写入的程序,分别在
-O0和-O2下编译运行,记录退出码。本机-O0实测退出码是-1073741819(0xC0000005),先打印的内容能看到,之后的语句没执行。 - 把
add的定义搬进add.h,让两个.cpp都包含它,观察multiple definition报错,再给它加inline看报错是否消失。
小结
记住三件事:g++ 不是一步到位,预处理、编译、汇编、链接各有分工;undefined reference 是链接阶段的符号问题,和语法无关;退出码和报错前缀是最快的分流线索,先分类再动手。
知道了代码怎么变成可执行文件,下一个问题就浮出来了:程序跑起来以后,那些变量到底被放在哪、占多大、为什么两个字段相同的结构体 sizeof 不一样。下一篇从类型和对象布局讲起,把这层「看不见的内存摆放」摊开。