系列 《C++ 在 AI-Infra:从对象模型到算子扩展》 第 1 / 10 篇 进阶
系列总览 — 为什么这样组织、读它需要什么、读完能做什么 · 幻灯片 — 整个系列的精华,一份可分享的 deck
学习地图 — AI-Infra 工程师学习地图 第 2 / 14 个系列
上一个系列:Python 在 AI-Infra下一篇:工程布局——命名空间、库的分层与 CMake
import torch 背后,Python 解释器真正加载的第一个 C 语言文件只有 15 行。先说清楚一件事:import 导入的不一定是 .py 文件。目录里如果放的是一个编译好的共享库 _C.cpython-312-x86_64-linux-gnu.so,同一条 import 语句会 dlopen 它并调用其中一个名为 PyInit__C 的 C 函数拿到模块对象——这是 Python 系列《模块与导入系统》讲的 ExtensionFileLoader。本篇从 C++ 这一侧接着讲:那个 PyInit__C 在哪、它编成了什么、又拉起了什么。它在 torch/csrc/stub.c,全文如下:
#include <Python.h>
extern PyObject* initModule(void);
#ifndef _WIN32
#ifdef __cplusplus
extern "C"
#endif
__attribute__((visibility("default"))) PyObject* PyInit__C(void);
#endif
PyMODINIT_FUNC PyInit__C(void)
{
return initModule();
}
这个文件看起来简单到不需要解释,但对一个 Java 工程师来说,几乎每一行都有陌生的东西:
extern PyObject* initModule(void);——这只是一个声明,函数体在哪里?编译器怎么知道去哪儿找?1- 为什么
PyInit__C要先声明一次再定义一次?visibility("default")是什么,不写会怎样?2 #ifndef _WIN32、#ifdef __cplusplus——这是代码还是配置?3- 这个文件编出来是什么?它怎么和
torch/csrc/Module.cpp里那个真正的initModule()接上?4
如果打开 torch/csrc/Module.cpp 找到 initModule 的定义,会发现它前面还有一行 extern "C" TORCH_PYTHON_API PyObject* initModule();——TORCH_PYTHON_API 又是什么?
这些问题都不是 PyTorch 的问题,而是 C++ 编译模型的问题。Java 工程师第一次面对 C++ 项目时,最陌生的往往不是语法,而是它是怎么编译出来的:为什么有 .h 和 .cpp 两种文件?为什么改一个头文件要重编半个项目?什么是”未定义的引用”?为什么同一个函数在两个文件里定义会报错?为什么一个 pip 包里有 libc10.so、libtorch_cpu.so、libtorch_python.so 好几个二进制?
本文要回答的核心问题是:
一个
.cpp文件是怎么变成机器码、再变成一个能被加载的.so的?每个阶段各做什么,”找不到”的错误分别发生在哪个阶段?5
本篇讲编译模型本身——四个阶段、翻译单元、ODR、符号与库、动态链接——最后手写一遍编译命令把一个程序链接到 PyTorch 的库上。几千个翻译单元怎么组织成 libc10.so、libtorch_cpu.so、libtorch_python.so 这几个库、import torch 到底加载了什么、自定义扩展该链接到哪一个,是下篇的内容。
一、总览
以后文反复使用的两个源文件为例:Version.cpp 编成动态库 libminic10.so,hello.cpp 调用库里的 version_string()。从源文件到进程里一次能跳过去的函数调用,中间经过的产物如下:
%%{init: {"flowchart": {"wrappingWidth": 300, "rankSpacing": 34}}}%%
%% 图:从 .cpp 到进程里可调用的函数:构建期的产物链与运行期的加载
flowchart TB
subgraph BUILD["构建期:每个 .cpp 各走一遍 ① ② ③,④ 把结果合起来"]
SRC["<b>源文件 Version.cpp</b><br/>#include 头文件 Version.h"]
TU["<b>翻译单元</b><br/>头文件已经粘贴进来的一整段文本"]
OBJ["<b>目标文件 Version.o</b><br/>机器码 + 符号表:<br/>定义了的标 T,引用了没定义的标 U"]
SO["<b>动态库 libminic10.so</b><br/>导出符号表 + 自己的 DT_NEEDED"]
HOBJ["<b>目标文件 hello.o</b><br/>hello.cpp 同样经过 ① ② ③,<br/>version_string 标 U"]
EXE["<b>可执行文件 hello</b><br/>DT_NEEDED: libminic10.so + 导入符号,<br/>没有库的代码"]
SRC -- "① 预处理(第二、三章)" --> TU
TU -- "② 编译、③ 汇编(第二章)<br/>一个名字能有几份定义:ODR(第四章)" --> OBJ
OBJ -- "④ 链接成库(第五章)" --> SO
HOBJ -- "④ 链接:符号解析 + 重定位(第二章)" --> EXE
SO -. "链接期只检查符号存在并记账(第六章)" .-> EXE
end
subgraph RUN["运行期:程序启动或 dlopen 时"]
LDSO["<b>动态加载器 ld.so</b><br/>按 RPATH、LD_LIBRARY_PATH、RUNPATH<br/>为每个 DT_NEEDED 找到文件"]
PROC["<b>进程地址空间</b><br/>hello 与各个 .so 都已映射,<br/>version_string 的调用处填上真实地址"]
LDSO -- "映射库,第二次符号解析(第六章)" --> PROC
end
EXE -- "⑤ 加载(第六章)" --> LDSO
classDef art fill:#eef4fb,stroke:#5b8dc9,color:#222
classDef rt fill:#fde7c8,stroke:#c98a00,color:#222
class SRC,TU,OBJ,SO,HOBJ,EXE art
class LDSO,PROC rt
- 翻译单元:预处理器把
#include的头文件原地粘贴、宏展开之后的一整段文本,是编译器真正的输入。每次编译一个.cpp时临时产生,平时不单独保存;编译器一次只看一个。 - 目标文件
.o:一个翻译单元编译、汇编后的产物,在构建目录里。里面是机器码和一张符号表——本文件定义了哪些符号、还缺哪些要别人提供。 - 静态库
.a/ 动态库.so:多个.o的两种打包方式。.a只是归档,链接时把用到的.o拷进最终产物;.so是链接过的镜像,带导出符号表和它自己依赖的库列表(DT_NEEDED),代码留在库里。 - 可执行文件:链接器把各个
.o的符号引用对上、地址定下来的结果。对动态库里的符号,它只记下「运行时需要哪个库」和「要哪个符号」。 - 动态加载器
ld.so:操作系统提供的运行时组件,不是构建产物。程序启动或dlopen时,它按搜索路径找到每个依赖库、映射进进程,再把导入符号解析成地址。 - 进程地址空间:程序和它依赖的全部
.so映射之后的样子;到这一步,hello里对version_string的调用才有真实地址可跳。
与 Java 对照:一种产物与多种产物
Java 的构建只产出 .class,打包成 .jar,类之间的引用由 JVM 在运行时第一次用到时解析。C++ 的链上多出翻译单元、目标文件、两种库和链接器,「找不到」的错误也因此分散在预处理、编译、链接、加载四个时刻,都早于业务代码开始运行。后文在每个机制旁边单独给出对照。
1. 本文的章节安排
本篇只讲”一个翻译单元怎么变成一个 .so“:前五章是编译模型的五个阶段与它们各自的规则,第七章把这些规则落到一次真实的手工编译上。
| 章 | 主题 | 内容 |
|---|---|---|
| 二 | 四个阶段 | 一个 .cpp 怎么经预处理、编译、汇编、链接变成机器码;加载是运行时的第五步 |
| 三 | 翻译单元、声明与定义、头文件 |
|
| 四 | One Definition Rule |
|
| 五 | 目标文件、库与符号 |
|
| 六 | 动态链接与加载 |
|
| 七 | 实践一 | 手写编译命令把一个 libtorch 程序链接到 PyTorch 的库,用 ldd / otool 和 nm 观察 |
| 八 | 本文小结 | |
| 九 | 自测 | 5 道题 |
二、四个阶段:一个 .cpp 是怎么变成机器码的
1. 四个阶段与运行时的加载
C++ 的构建流程有四个阶段——预处理、编译、汇编、链接——每个阶段都是独立的程序,有自己的输入和输出;对动态库来说,运行时还有第五步加载(§6):
%% 图:C++ 构建的四个阶段与运行时的加载:预处理、编译、汇编、链接各有独立的输入输出
flowchart LR
SRC[Version.cpp<br/>源文件] -->|① 预处理 -E| I[Version.i<br/>翻译单元]
I -->|② 编译 -S| S[Version.s<br/>汇编]
S -->|③ 汇编 -c| O[Version.o<br/>目标文件]
O -->|④ 链接| OUT[libminic10.so<br/>或可执行文件]
OTHER[其他 .o / .a / .so] --> OUT
OUT -.->|⑤ 加载:运行时,ld.so| RUN[进程地址空间]
平时用 g++ -c foo.cpp 或者 CMake 构建时,前四步是被驱动程序(g++/clang++)串起来一次跑完的,所以初学者往往感觉不到它们的存在。但每一类错误只会出现在某一个阶段:
| 阶段 | 由谁执行、什么时候 | 输入 → 产物 | 典型报错 | Java 对照 |
|---|---|---|---|---|
| ① 预处理 | 预处理器;构建期,每个 .cpp 一次 |
.cpp 与它包含的头文件 → 翻译单元(-E 可输出成 .i,平时不单独保存) |
fatal error: xxx.h: No such file or directory——找不到头文件 |
无:Java 没有文本级预处理 |
| ② 编译 | 编译器;构建期 | 翻译单元 → 汇编 .s(-S 可输出,平时不单独保存) |
类型不匹配、未声明的名字、语法错误 | javac;它能从 classpath 读到别的类的签名,C++ 编译器只看当前翻译单元 |
| ③ 汇编 | 汇编器;构建期 | .s → 目标文件 .o,留在构建目录 |
几乎不会出错(输入是编译器生成的) | 无:javac 直接产出 .class |
| ④ 链接 | 链接器;构建期,每个库或可执行文件一次 | 多个 .o、.a、.so → 可执行文件或 .so |
undefined reference to ...、multiple definition of ... |
构建期没有对应步骤:.class 之间的引用由 JVM 在运行时解析 |
| ⑤ 加载 | 动态加载器 ld.so;程序启动或 dlopen 时 |
可执行文件与它依赖的 .so → 进程地址空间里的映像 |
cannot open shared object file、undefined symbol(运行时才发现) |
类加载器加载 .class,最接近;差别见第六章 |
分清阶段,是排错的第一步。
与 Java 对照:链接发生在什么时候
javac 一步把 .java 编成 .class,文件里带着类型信息、方法签名、常量池和字节码,对别的类的引用以名字的形式记在常量池里。JVM 规范里也有「链接」(验证、准备、解析),但它在运行时由 JVM 完成,没有单独的构建步骤。C++ 的链接是构建期的独立程序,对不上符号时构建就失败。
下面用下篇要建的 mini-c10 里的三个文件走一遍(下篇第五章会解释设计):一个头文件 Version.h、实现它的 Version.cpp,以及一个调用它的小程序 examples/hello.cpp。前两个编成库 libminic10.so,第三个链接这个库:
// minic10/core/Version.h
#pragma once
#include <cstdint>
#include <string>
namespace minic10 {
constexpr int kVersionMajor = 0;
constexpr int kVersionMinor = 1;
std::string version_string();
inline int version_number() {
return kVersionMajor * 1000 + kVersionMinor;
}
} // namespace minic10
// minic10/core/Version.cpp
#include <minic10/core/Version.h>
namespace minic10 {
namespace {
const char* build_flavor() {
#ifdef NDEBUG
return "release";
#else
return "debug";
#endif
}
} // namespace
std::string version_string() {
return std::to_string(kVersionMajor) + "." + std::to_string(kVersionMinor) +
" (" + build_flavor() + ")";
}
} // namespace minic10
// examples/hello.cpp
#include <minic10/core/Version.h>
#include <iostream>
int main() {
std::cout << "mini-c10 " << minic10::version_string()
<< ", number=" << minic10::version_number() << '\n';
}
2. 预处理:把文本拼成翻译单元
预处理器(preprocessor)只做文本处理,不懂 C++:
#include <x>把文件x的内容原地粘贴进来(递归地);#define A B之后,所有出现的A被替换成B;#ifdef/#ifndef/#if/#else/#endif按条件保留或删除一段文本;#pragma once告诉编译器这个文件在同一次编译里只粘贴一次。
用 -E 可以只跑预处理:
clang++ -std=c++17 -I. -E minic10/core/Version.cpp | wc -l
实际输出(macOS,Apple clang 21)是 40222:一个 20 行的源文件,加上 <string> 和 <cstdint> 展开后,变成四万行。这就是翻译单元(translation unit)——预处理器输出的那一整段文本,是编译器真正看到的输入。
stub.c 里那些 #ifndef _WIN32、#ifdef __cplusplus 就在这个阶段生效。_WIN32 是 Windows 编译器预定义的宏,__cplusplus 是 C++ 编译器预定义的宏(C 编译器不定义它)。stub.c 是一个 .c 文件,用 C 编译器编译时 __cplusplus 不存在,extern "C" 那行被删掉;如果有人用 C++ 编译器编它,extern "C" 保留,保证 PyInit__C 的符号名不被 C++ 修饰(第五章讲修饰)。
被 #ifdef 删掉的分支在翻译单元里不存在,编译器看不到它,二进制里也没有它——所以那个分支可以引用本平台根本没有的头文件和类型。宏与条件编译的更多用法是《宏、静态注册与代码生成》的主题,这里只需要知道:预处理之后,头文件就不存在了,只剩一个巨大的翻译单元。
与 Java 对照:条件编译
Java 没有预处理器。按平台或配置走不同分支,通常写成运行时判断(如读 System.getProperty(...)),或用 static final boolean 常量做开关;无论哪种,两个分支都必须是能通过编译的 Java 代码。C++ 的 #ifdef 在编译之前按文本删行,被删的分支不需要能编译。
3. 编译:把翻译单元变成汇编
编译器(严格说是编译器前端 + 优化器 + 后端)读入翻译单元,做词法分析、语法分析、语义分析(类型检查、重载决议、模板实例化),然后生成汇编代码。用 -S 可以停在这一步:
clang++ -std=c++17 -I. -S minic10/core/Version.cpp -o Version.s
grep -n "version_string" Version.s | head -3
输出(macOS 上符号名多一个前导下划线,Mach-O 的惯例):
3: .globl __ZN7minic1014version_stringEv ; -- Begin function _ZN7minic1014version_stringEv
5:__ZN7minic1014version_stringEv: ; @_ZN7minic1014version_stringEv
minic10::version_string() 在汇编里变成了 _ZN7minic1014version_stringEv(macOS 上还多一个前导下划线)。这个名字是符号(symbol),第五章讲它的编码规则。
背景:这里的汇编是真的汇编,而且跟 CPU 有关
.s 是某一种 CPU 指令集的汇编文本,一行指令对应一条机器指令。同一个函数 int add(int a, int b) { return a + b; },用 -O1 分别为两种 CPU 生成(Apple clang 14,-arch x86_64 与 -arch arm64),函数体完全不同:
| 目标 CPU | 生成的指令 |
|---|---|
| x86-64(Intel 和 AMD 的 64 位处理器用的是同一套指令集) |
|
| ARM64(Apple M 系列、AWS Graviton) |
|
所以从编译这一步起,产物就绑定了 CPU 架构和操作系统:.s、.o、.so 都只能用在对应的平台上,PyTorch 的 wheel 也因此按平台分别发布,文件名里带 x86_64、aarch64、arm64 这样的标记。Java 的 .class 是与 CPU 无关的字节码,翻成机器码的事由 JVM 在运行时做。
编译器一次只看一个翻译单元。 用 hello.cpp 来看:它调用了 version_string(),而函数体在 Version.cpp 里。只编译 hello.cpp,看调用处生成了什么:
clang++ -std=c++17 -I. -arch arm64 -S examples/hello.cpp -o hello.s
grep -n "version_string" hello.s
25: bl __ZN7minic1014version_stringEv
bl 是 ARM64 的函数调用指令(x86-64 上这一行是 callq __ZN7minic1014version_stringEv)。整个 hello.s 里没有 version_string 的函数体,只有这一条「跳到名叫 _ZN7minic1014version_stringEv 的地方」。两次编译各自看到的东西:
%% 图:两个翻译单元各自编译:hello.cpp 只拿到声明,Version.cpp 才有函数体,链接器第一次同时看到两边
flowchart TB
H["<b>Version.h</b><br/>std::string version_string();<br/>只有声明,没有函数体"]
subgraph TU1["编译 hello.cpp:看不到 Version.cpp"]
direction TB
A1["<b>hello.cpp 的翻译单元</b><br/>version_string 的声明<br/>+ main 的函数体"]
A2["<b>hello.o</b><br/>main:已定义<br/>version_string:只有一条调用,地址留空"]
A1 --> A2
end
subgraph TU2["编译 Version.cpp:看不到 hello.cpp"]
direction TB
B1["<b>Version.cpp 的翻译单元</b><br/>version_string 的声明<br/>+ version_string 的函数体"]
B2["<b>Version.o</b><br/>version_string:已定义"]
B1 --> B2
end
L["<b>链接器</b><br/>第一次同时看到两个 .o,<br/>把 hello.o 的调用对到 Version.o 的定义"]
H -- "#include 粘贴" --> TU1
H -- "#include 粘贴" --> TU2
TU1 --> L
TU2 --> L
classDef art fill:#eef4fb,stroke:#5b8dc9,color:#222
classDef lk fill:#fde7c8,stroke:#c98a00,color:#222
class H,A1,A2,B1,B2 art
class L lk
- 编译
hello.cpp时,编译器不会去找Version.cpp。它对version_string的全部了解,就是Version.h粘贴进来的那一行声明:有这么一个函数,不带参数,返回std::string。凭这一行就能生成调用指令。 - 编译
Version.cpp时,编译器同样不知道hello.cpp的存在,也不知道有没有人调用version_string。 - 声明和定义对不对得上,要等链接器把两个
.o放到一起才知道。
stub.c 里的 extern PyObject* initModule(void); 是同一回事:它相当于 hello.cpp 里那行声明,让编译器能生成 return initModule(); 这条调用;函数体在 torch/csrc/Module.cpp,编译 stub.c 时编译器没看过它。
与 Java 对照:编译器能看到多少
javac 编译 A.java 时如果引用了 B,会去 classpath 或源码路径上找 B.class 或 B.java,自己读出签名。C++ 编译器只能看到当前翻译单元:声明写错了(与真正的定义不一致),编译这一步发现不了,要到链接期甚至运行时才暴露。
4. 汇编:生成目标文件
这一步的名字容易误解:”汇编”(assemble)不是生成汇编语言,而是把汇编语言翻成机器码:汇编器(assembler)把上一步的 .s 文本逐条翻成二进制机器指令,写进目标文件 .o(object file)。目标文件的格式随操作系统而定:Linux 是 ELF,macOS 是 Mach-O,Windows 是 COFF。-c 让驱动程序停在这一步:
clang++ -std=c++17 -Wall -fPIC -I. -c minic10/core/Version.cpp -o Version.o
目标文件里有机器码、数据,以及一张符号表:本文件定义了哪些符号(可以给别人用)、引用了哪些别处的符号(需要别人提供)。第五章会用 nm 看它。
5. 链接:把符号对上
链接器(ld、lld、gold、macOS 的 ld64)收集所有 .o 和库,做两件事:
- 符号解析(symbol resolution):每个”引用了 X 但没定义”的地方,都要找到唯一一个”定义了 X”;
- 重定位(relocation):确定每段代码和数据的最终地址,把所有引用处的占位地址改成真实地址。
上面这张图画出这两件事。左边是链接前的两个 .o:各自的代码从地址 0 开始排,hello.o 的符号表里 version_string 标着 U(引用了、没定义),Version.o 里标着 T(定义了、对外可见)。右边是链接后的样子:可执行文件被装进进程的虚拟地址空间——每个进程一份,从低到高依次是代码段(.text)、全局变量(.data / .bss)、向上生长的堆、动态库的映射区、向下生长的栈;链接器给 main 和 version_string 各定下一个最终地址,再把 hello.o 里 call ??? 的占位改成 version_string 的真实地址。第五章会用 nm 看这些字母。图里画的是 version_string 直接链进可执行文件的情况;它在 .so 里时,② 重定位这一步要推迟到运行时,见下面「第五个阶段:加载」一节。
clang++ -std=c++17 -shared -o libminic10.so Version.o
clang++ -std=c++17 -I. examples/hello.cpp -L. -lminic10 -o hello
第一条把 Version.o 链接成动态库;第二条编译 hello.cpp,并把它对 minic10::version_string() 的引用解析到 libminic10.so 里的定义。两条命令里的每个选项:
| 选项 | 含义 | 出现在 |
|---|---|---|
-std=c++17 |
按 C++17 标准编译 | 两条 |
-shared |
输出动态库(.so),而不是可执行文件 |
第一条 |
-o <文件> |
输出文件名 | 两条 |
-I. |
头文件搜索路径加上当前目录:#include <minic10/core/Version.h> 在这里找 |
第二条 |
-L. |
库文件搜索路径加上当前目录:-lminic10 在这里找 |
第二条 |
-lminic10 |
链接名为 libminic10.so(或 .a)的库——-l 后面写去掉 lib 前缀和后缀的名字 |
第二条 |
-c |
只编译到 .o,不链接(§4) |
前面 |
-fPIC |
生成位置无关代码:动态库会被装到任意地址,代码里不能写死绝对地址(§4) | 前面 |
-Wall |
打开常用警告 | 前面 |
两类最常见的链接错误都发生在符号解析阶段:
undefined reference to `helper()' # 有人引用了,没人定义
multiple definition of `helper()' # 不止一个人定义了
(以上是 Linux GNU ld 的措辞;macOS ld64 分别说 Undefined symbols for architecture arm64 和 duplicate symbol。本文的命令行输出以 Linux 为准,macOS 差异随文标注。)
6. 第五个阶段:加载
对动态库来说还有一个阶段在运行时:加载(loading)。上一节的图里,链接器对 version_string 做了 ① 符号解析和 ② 重定位两件事。version_string 在动态库里时,第 ② 件事在链接期做不了:库要到运行时才装进进程,装在哪个地址那时才知道。两件事于是拆到了两个时刻:
version_string 在 .o 或 .a 里 |
version_string 在 libminic10.so 里 |
|
|---|---|---|
| ① 符号解析 | 链接器,构建期 | 链接器先查一次,确认库里有这个符号,然后在 hello 里记下两条:运行时需要 libminic10.so、要用其中的 version_string |
| ② 重定位:填上真实地址 | 链接器,构建期 | 动态加载器,程序启动或 dlopen 时:把库映射进进程,按名字再查一次,填上地址 |
| 函数的机器码在哪 | 拷进了可执行文件 | 留在 .so 里,hello 里没有 |
动态加载器是操作系统提供的程序,Linux 上是 ld-linux-x86-64.so.2,也叫 ld.so。第六章专门讲它怎么找库、怎么填地址。
三、翻译单元、声明与定义、头文件
1. 为什么要分 .h 和 .cpp
既然编译器一次只看一个翻译单元,而 hello.cpp 想调用 Version.cpp 里的函数,就必须有一种办法让 hello.cpp 的翻译单元里出现 version_string 的签名,同时不出现它的函数体(否则两个翻译单元各有一份函数体,链接时就是 multiple definition)。
这个办法就是声明与定义分离:
- 声明(declaration):告诉编译器一个名字的类型/签名。
std::string version_string();是声明;extern PyObject* initModule(void);是声明;class Tensor;是声明。 - 定义(definition):给出实体本身。带函数体的函数是定义;带大括号的类是定义;不带
extern的全局变量是定义。
头文件(.h/.hpp)放声明,源文件(.cpp/.cc)放定义,所有需要用这个名字的 .cpp 都 #include 这个头文件。一个声明可以出现任意多次(每个翻译单元一次),一个定义在整个程序里只能有一次——这就是第四章的 ODR。
头文件因此就是一份手写的签名文件:编译器不会替使用者去别的 .cpp 里提取签名,这件事交给了程序员。C++20 引入的 modules 试图改变这一点,但 PyTorch 和 vLLM 都还没用,本系列不讨论。
与 Java 对照:.java 与 .h + .cpp
一个 .java 文件就是类的完整定义,没有声明与定义之分;别的类引用它时,javac 自己从 .class 或源码里读出签名。C++ 的一个类通常拆在两个文件里,而一个 .cpp 也不对应一个类——它是一个翻译单元,里面可以有任意多个类和函数的定义。
2. 真实例子:c10/core/Device.h 与 Device.cpp
c10::Device 是 PyTorch 里表示”设备”的小类型(cpu、cuda:0 这些)。它的头文件 c10/core/Device.h 开头是:
#pragma once
#include <c10/core/DeviceType.h>
#include <c10/macros/Export.h>
#include <c10/util/Exception.h>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <iosfwd>
#include <string>
namespace c10 {
using DeviceIndex = int8_t;
struct C10_API Device final {
using Type = DeviceType;
/* implicit */ Device(DeviceType type, DeviceIndex index = -1)
: type_(type), index_(index) {
validate();
}
/* implicit */ Device(const std::string& device_string);
// ...
bool is_cuda() const noexcept {
return type_ == DeviceType::CUDA;
}
// ...
/// Same string as returned from operator<<.
std::string str() const;
private:
DeviceType type_;
DeviceIndex index_ = -1;
void validate() {
// ...
}
};
C10_API std::ostream& operator<<(std::ostream& stream, const Device& device);
} // namespace c10
先认几个 Java 里没有的记号,后文会反复出现:
| 记号 | 含义 | Java 里 |
|---|---|---|
using DeviceIndex = int8_t; |
类型别名:给 int8_t 起一个新名字 DeviceIndex,两者是同一个类型(老写法是 typedef int8_t DeviceIndex;);类内的 using Type = DeviceType; 同理 |
没有类型别名;用一个 record 包一层得到的是新类型 |
C10_API |
一个宏,展开成”这个符号要从 libc10.so 导出给别人用”(Linux 上是 __attribute__((visibility("default"))));第五章和《宏、静态注册与代码生成》展开 |
没有逐符号的导出标记;public 类默认就能被别的 jar 使用 |
constexpr int kVersionMajor = 0; |
编译期常量:值在编译时就确定,可以用在数组长度、模板参数这些必须编译期已知的地方;比 const 严格 |
最接近用常量表达式初始化的 static final int;constexpr 还能修饰函数和自定义类型,Java 没有对应 |
final |
类不能被继承 | final class |
noexcept |
函数承诺不让异常传给调用方。编译器不检查函数体是否真的不抛;运行时如果有异常要从这个函数里传出去,程序调用 std::terminate,默认结果是整个进程异常退出。它不是 try/catch:异常没有被接住处理,程序也不会继续往下跑 |
没有对应。throws 是反方向:声明可能抛什么,由编译器检查 |
Device::str() |
作用域限定:.cpp 里定义头文件声明过的成员函数时写类名前缀 |
方法只能写在类体内 |
注意三种成员:
- ①
Device(DeviceType, DeviceIndex)、is_cuda()、validate()在类内直接给出函数体。类内定义的成员函数隐含inline(第四章解释为什么这样就不违反 ODR)。它们一两行就完,放在头文件里让编译器可以内联。 - ②
Device(const std::string&)和str()只有声明。它们的定义在c10/core/Device.cpp(代码里标 ②):
#include <c10/core/Device.h>
#include <c10/util/Exception.h>
// ...
namespace c10 {
namespace { // ③ 匿名命名空间:只在本文件可见
DeviceType parse_type(const std::string& device_string) { // ③ 实现细节,头文件里没有它
// ...
}
// ...
} // namespace
Device::Device(const std::string& device_string) : Device(Type::CPU) { // ② 头文件里只声明、这里定义
TORCH_CHECK(!device_string.empty(), "Device string must not be empty");
// ... 解析 "cuda:0" 这类字符串
validate();
}
std::string Device::str() const { // ② 同上
std::string str = DeviceTypeName(type(), /* lower case */ true);
if (has_index()) {
str.push_back(':');
str.append(std::to_string(index()));
}
return str;
}
std::ostream& operator<<(std::ostream& stream, const Device& device) {
stream << device.str();
return stream;
}
} // namespace c10
字符串解析有几十行,不适合放头文件(放了会让每个包含 Device.h 的翻译单元都编一遍,而 Device.h 几乎被所有文件间接包含)。所以只在头文件里声明,定义放 .cpp,编进 libc10.so。
- ③
parse_type只在.cpp里,头文件里没有它。它是实现细节,被匿名命名空间包住(第四章讲)。
3. 头文件的职责与 #pragma once
一个头文件通常包含:
| 内容 | 例子(c10/core/Device.h) |
说明 |
|---|---|---|
| 类型定义 | struct Device { ... }; |
类的定义本身(成员列表)必须在头文件里,否则使用者不知道它多大 |
| 函数声明 | std::string str() const; |
定义在 .cpp |
| 小函数的 inline 定义 | bool is_cuda() const noexcept { ... } |
允许内联 |
| 类型别名 | using DeviceIndex = int8_t; |
|
| 常量 | constexpr int kX = 1; |
|
| 模板 | 《模板与泛型编程》 | 模板几乎必须全部放头文件 |
| 宏 | C10_API |
《宏、静态注册与代码生成》 |
头文件会被间接包含很多次。Device.h 包含 Exception.h,ScalarType.h 也包含 Exception.h,一个同时包含 Device.h 和 ScalarType.h 的文件里 Exception.h 就被粘贴两次——第二次会因为重复定义 class Error 而编译失败。#pragma once 解决这个问题:同一个文件在同一个翻译单元里只展开一次。
传统写法是 include guard:
#ifndef C10_MACROS_EXPORT_H_
#define C10_MACROS_EXPORT_H_
// ...
#endif // C10_MACROS_EXPORT_H_
torch/headeronly/macros/Export.h 两种都用了(#pragma once 在第一行,紧接着 #ifndef C10_MACROS_EXPORT_H_),这是历史遗留。PyTorch 新代码统一用 #pragma once。#pragma once 不是标准 C++,但所有主流编译器都支持;它按文件身份判重,include guard 按宏名判重,实际效果一样。
4. 为什么改一个头文件要重编半个项目
现在可以回答开头的问题了。#include 是文本粘贴,Device.h 的内容是每一个包含它的翻译单元的一部分。改了 Device.h,所有包含它的翻译单元的输入都变了,构建系统(CMake/Ninja 通过编译器生成的依赖文件 .d 追踪这种关系)必须把它们全部重编。
看看 c10/core/ScalarType.h 开头包含了多少东西:
#pragma once
#include <c10/util/BFloat16.h>
#include <c10/util/Exception.h>
#include <c10/util/Float4_e2m1fn_x2.h>
#include <c10/util/Float8_e4m3fn.h>
#include <c10/util/Float8_e4m3fnuz.h>
#include <c10/util/Float8_e5m2.h>
#include <c10/util/Float8_e5m2fnuz.h>
#include <c10/util/Float8_e8m0fnu.h>
#include <c10/util/Half.h>
#include <c10/util/bits.h>
#include <c10/util/complex.h>
#include <c10/util/qint32.h>
#include <c10/util/qint8.h>
#include <c10/util/quint2x4.h>
#include <c10/util/quint4x2.h>
#include <c10/util/quint8.h>
#include <array>
// ...
ScalarType 是 dtype,几乎每一个 ATen 文件都要用它。改一下 c10/util/Half.h,ScalarType.h 的所有包含者都要重编,也就是几乎整个 libtorch_cpu.so——上千个翻译单元,一小时级别。这就是 PyTorch 开发者对”往 c10 头文件里加东西”极其谨慎的原因,也是 c10/CMakeLists.txt 开头那段注释的背景(下篇「三个命名空间对应三个层次」一节)。
Java 里改一个类,Gradle 这类构建工具的增量编译按类之间的依赖和对外签名(ABI)是否变化决定重编范围,通常到直接依赖它的类为止。C++ 的粒度是”文本包含”,粗得多——两边画出来:
%% 图:同一个改动在两种语言里的重编范围:Java 增量编译到直接依赖就停,C++ 所有 #include 它的翻译单元全部重编
flowchart LR
subgraph J["Java:改 Half.java"]
JH["Half.java ✎"] --> JS["<b>ScalarType.java</b><br/>直接引用了 Half"]
JS -.->|"ABI 没变就不重编"| JA["add.java"]
JS -.-> JB["mul.java"]
JS -.-> JC["… 上千个用到 ScalarType 的类"]
end
subgraph C["C++:改 Half.h"]
CH["Half.h ✎"] --> CS["<b>ScalarType.h</b><br/>#include <Half.h>"]
CS --> CA["add.cpp ✎ 重编"]
CS --> CB["mul.cpp ✎ 重编"]
CS --> CC["… 上千个 #include 它的 .cpp 全部重编"]
end
classDef edit fill:#fde7c8,stroke:#c98a00,color:#222
classDef skip fill:#eefaf0,stroke:#4d9a5c,color:#222
class JH,CH,CA,CB,CC edit
class JA,JB,JC skip
同一个改动在两种语言里的重编范围。Java 里 Half 的改动只要不改它对外的签名,增量编译到 ScalarType 就停了;C++ 里 Half.h 的文本是每个间接包含它的翻译单元的一部分,改一个字节,上千个 .cpp 的输入都变了。这带来了 C++ 项目特有的两个工程习惯:
1、前向声明(forward declaration)。 一行 class Tensor; 只告诉编译器「有一个叫 Tensor 的类」,不说它有哪些成员、多大。够不够用,看编译器需不需要知道它的大小:
头文件里怎么用 Tensor |
前向声明够吗 | 原因 |
|---|---|---|
Tensor*、const Tensor& 做参数、返回值或成员 |
够 | 指针和引用的大小是固定的,与 Tensor 多大无关 |
Tensor t_; 按值做成员 |
不够,要 #include |
要知道 Tensor 占多少字节 |
调用成员函数、sizeof(Tensor) |
不够,要 #include |
要知道完整的成员列表 |
头文件里能用前向声明就不 #include,包含者就不必因为 Tensor.h 变了而重编。aten/src/ATen/templates/TensorBody.h(生成 ATen/core/TensorBody.h 的模板)开头就是一串前向声明:
namespace c10 {
template <class T> class List; // 前向声明一个类模板
template <class T> class IListRef;
}
namespace at {
struct Generator; // 前向声明:struct 与 class 在这里等价
struct Type;
class DeprecatedTypeProperties;
class Tensor; // Tensor 自己也被前向声明——TensorBody.h 后面才定义它
} // namespace at
namespace torch { namespace autograd {
struct Node; // Tensor 只持有 Node 的指针,不需要 Node 的定义
}} // namespace torch::autograd
这是《值、引用与所有权》会反复用到的规则。
2、只包含够用的最小头文件。 Device.h 包含的是 <iosfwd>(只有 std::ostream 的前向声明)而不是 <ostream>(完整定义),因为它只需要声明 operator<<。
5. extern 与全局变量
对函数来说,不带函数体就是声明,所以 stub.c 里 extern PyObject* initModule(void); 的 extern 其实可以省略——函数声明默认就是 extern。对变量则不同:
int counter; // 定义(分配存储)
extern int counter; // 声明(别处有定义)
头文件里放变量时必须写 extern,否则每个包含者都定义一份,链接时 multiple definition。PyTorch 源码里全局变量很少直接暴露,多半用函数包装(如 c10::DeviceTypeName(...)),或者用 thread_local(《并发、内存模型、TLS 与守卫》)。
四、One Definition Rule:同一个名字只能有一个定义
1. 规则本身
ODR 的核心可以概括为两句话:
- 任何翻译单元里,一个变量、函数、类、枚举、模板最多只能有一个定义;
- 整个程序里,每个非 inline 的函数和变量恰好一个定义(用到了却没有 → undefined reference;多于一个 → multiple definition)。
第二条有一个”非 inline”的限定,反过来说:类、inline 函数、模板允许在多个翻译单元里各有一份定义。 这是头文件机制的直接结果。Device.h 里的 is_cuda() 是类内定义的 inline 函数,每个包含 Device.h 的 .cpp 编出来的 .o 里都有一份它的机器码:编译器一次只看一个翻译单元,不知道别的 .o 里已经有了。
%% 图:inline 函数的多份定义与链接器的合并:每个翻译单元各编一份,链接器按逐字相同的假定合并
flowchart LR
H["<b>Device.h</b><br/>inline bool is_cuda() { return type_ == CUDA; }"]
H --> A["<b>a.cpp → a.o</b><br/>含一份 is_cuda(W)"]
H --> B["<b>b.cpp → b.o</b><br/>含一份 is_cuda(W)"]
A --> L["<b>链接器:两份 W 逐字相同</b><br/>任选一份留下,另一份丢掉"]
B --> L
L --> OUT["<b>libc10.so</b><br/>一份 is_cuda"]
classDef box fill:#eef4fb,stroke:#5b8dc9,color:#222
class H,A,B,L,OUT box
规则于是改成:多份可以,但所有定义必须逐字相同(token-for-token identical)。链接器假定它们相同,任选一份、丢掉其余;下一章 nm 里标 W 的就是这种可合并的弱定义。
危险在于违反”逐字相同”不会报错:如果 a.cpp 编译时定义了某个宏让 is_cuda 的函数体多了一行,两份就不同了,链接器照样任选一份——这是未定义行为,程序可能用了 A 文件的版本,也可能用了 B 文件的版本,也可能崩溃。
与 Java 对照:同名定义出现两份时
Java 里一个类只编出一份 .class,不会像 inline 函数那样每个使用者各带一份。classpath 上两个 jar 带了同一个全限定名的类时同样不报错,但结果是确定的:默认的委派模型下父加载器优先,同一个加载器按 classpath 顺序取先找到的那份,整个类来自同一处。C++ 的 ODR 违反是未定义行为,而且两份机器码可能已经分别内联进各自的调用处,连「统一用了哪一份」都保证不了。
2. 两种链接错误
用两个最小文件复现:
// dup1.cpp
int helper() { return 1; }
// dup2.cpp
int helper() { return 2; }
int main() { return helper(); }
g++ -std=c++17 dup1.cpp dup2.cpp -o dup
GNU ld 的报错:
/usr/bin/ld: /tmp/ccXXXX.o: in function `helper()':
dup2.cpp:(.text+0x0): multiple definition of `helper()'; /tmp/ccYYYY.o:dup1.cpp:(.text+0x0): first defined here
反过来:
// undef.cpp
int helper();
int main() { return helper(); }
GNU ld 的报错:
/usr/bin/ld: /tmp/ccXXXX.o: in function `main':
undef.cpp:(.text+0x5): undefined reference to `helper()'
(macOS 的 ld64 对这两种错误的措辞分别是 duplicate symbol 和 Undefined symbols for architecture arm64,意思相同。)
注意错误信息里的 helper()——链接器本来看到的是修饰后的 _Z6helperv,现代链接器会自动”反修饰”(demangle)给人看。第五章讲修饰。
读 PyTorch 扩展的构建日志时,undefined reference to ‘at::empty_like(...)’ 和 undefined symbol: _ZN2at10empty_like...(这是加载期的版本)是最常见的两类,分别说明”链接时少了 -ltorch_cpu“和”运行时找到了错误版本的 libtorch_cpu.so“。
3. inline:允许多份相同定义
头文件里放函数定义,被 N 个翻译单元包含,就有 N 份定义——违反 ODR 第二条。inline 关键字把这个函数变成”允许多份,但必须相同,链接器任选一份”的类别:
// minic10/core/Version.h
inline int version_number() {
return kVersionMajor * 1000 + kVersionMinor;
}
现代 C++ 里 inline 的主要含义就是这个链接属性,”建议编译器内联展开”只是次要含义(编译器基本不听建议,自己决定)。三种情况隐含 inline:
- 类内定义的成员函数(
Device::is_cuda()那种); - 模板(函数模板、类模板的成员),因为模板本来就在每个用到它的翻译单元里各实例化一份;
constexpr函数;C++17 起constexpr静态数据成员和inline变量也是。
c10/core/ScalarType.h 里一串工具函数就是显式 inline:
inline size_t elementSize(ScalarType t) {
#define CASE_ELEMENTSIZE_CASE(ctype, name) \
case ScalarType::name: \
return sizeof(ctype);
switch (t) {
AT_FORALL_SCALAR_TYPES_WITH_COMPLEX_AND_QINTS(CASE_ELEMENTSIZE_CASE)
default:
TORCH_CHECK(false, "Unknown ScalarType");
}
#undef CASE_ELEMENTSIZE_CASE
}
inline bool isFloatingType(ScalarType t) {
return t == ScalarType::Double || t == ScalarType::Float ||
isReducedFloatingType(t);
}
它们被上千个翻译单元包含,每个翻译单元里都有一份 elementSize 的机器码(如果编译器没把它内联掉),链接器最后保留一份。在 nm 输出里这类符号标记为 W(weak),下一节会看到。
inline 的陷阱:如果同一个 inline 函数在两个翻译单元里编出来的代码不一样,链接器保留哪一份是不确定的。caffe2/CMakeLists.txt 里有一段真实的踩坑记录:
# NOTE [ Linking AVX and non-AVX files ]
#
# Regardless of the CPU capabilities, we build some files with AVX2, and AVX512
# instruction set. If the host CPU doesn't support those, we simply ignore their
# functions at runtime during dispatch.
#
# We must make sure that those files are at the end of the input list when
# linking the torch_cpu library. Otherwise, the following error scenario might
# occur:
# 1. A non-AVX2 and an AVX2 file both call a function defined with the `inline`
# keyword
# 2. The compiler decides not to inline this function
# 3. Two different versions of the machine code are generated for this function:
# one without AVX2 instructions and one with AVX2.
# 4. When linking, the AVX2 version is found earlier in the input object files,
# so the linker makes the entire library use it, even in code not guarded by
# the dispatcher.
# 5. A CPU without AVX2 support executes this function, encounters an AVX2
# instruction and crashes.
源码相同、编译选项不同(-mavx2 与否)→ 机器码不同 → ODR 违反 → 在不支持 AVX2 的机器上非法指令崩溃。PyTorch 的解法是控制链接顺序,让非 AVX 版本先被链接器看到。这个注释值得记住:ODR 关心的是”定义相同”,而”相同”包括编译方式。
4. static 与匿名命名空间:内部链接
另一条路是反过来:不让符号被其他翻译单元看见。static 修饰的全局函数/变量,以及匿名命名空间 namespace { ... } 里的所有东西,都是内部链接(internal linkage)——只在本翻译单元可见,不进入全局符号表,不参与跨翻译单元的符号解析。两个 .cpp 各有一个 static int helper() 互不冲突。
c10/core/Device.cpp 用匿名命名空间:
namespace c10 {
namespace {
DeviceType parse_type(const std::string& device_string) {
// ...
}
enum DeviceStringParsingState { START, INDEX_START, INDEX_REST, ERROR };
} // namespace
Device::Device(const std::string& device_string) : Device(Type::CPU) {
// ...
}
c10/core/DeviceType.cpp 用 static:
static std::atomic<bool> privateuse1_backend_name_set;
static std::string privateuse1_backend_name;
static std::mutex privateuse1_lock;
两种写法效果一样,C++ 风格指南倾向匿名命名空间(能包住类型和模板,static 不能)。PyTorch 的 kernel 文件大量使用这个模式——aten/src/ATen/native/cpu/BinaryOpsKernel.cpp 的整个 kernel 实现都在匿名命名空间里,文件末尾只有一排 REGISTER_DISPATCH(...) 把函数指针注册出去:
namespace at::native {
namespace {
// ... 一千四百行 kernel 实现 ...
} // namespace
REGISTER_DISPATCH(add_clamp_stub, &add_clamp_kernel)
REGISTER_DISPATCH(mul_stub, &mul_kernel)
REGISTER_DISPATCH(div_true_stub, &div_true_kernel)
// ...
这样做有两个好处:不同 kernel 文件里同名的辅助函数不会冲突;符号不导出,.so 的符号表更小,加载更快。《宏、静态注册与代码生成》讲静态注册时会重看这个文件。
内部链接是真的没有外部可见的名字:别的翻译单元即使写了一行同名的声明,链接时也对不上这个符号。
与 Java 对照:private 与内部链接
private 和包私有是访问权限:成员的名字仍然记在 .class 里,编译器和 JVM 拒绝越权访问,反射在允许时还能拿到它。内部链接不是权限检查,而是符号不参与跨文件的解析;也因此两个 .cpp 可以各有一个同名的 static 函数而互不相干,这在 Java 的同一个类里做不到。
5. 小结:四种链接属性
| 写法 | 链接属性 | 多个翻译单元定义会怎样 | 典型用途 | Java 对照 |
|---|---|---|---|---|
| 普通函数/变量 | 外部链接 | multiple definition 错误 | .cpp 里的实现 |
类的非 private 成员:别的类按全限定名引用。同名类出现两份不报错,取类加载器先找到的那份 |
inline、类内成员函数、模板、constexpr |
外部链接 + 允许重复(vague linkage) | 合法,链接器任选一份,必须逐字相同 | 头文件里的小函数、模板 | 无:一个方法的字节码只在自己的 .class 里有一份,内联由 JIT 在运行时做 |
static、匿名命名空间 |
内部链接 | 互不相干 | .cpp 里的私有辅助 |
最接近 private static 方法,但那是访问权限检查,名字仍记在 .class 里 |
extern 声明 |
声明而非定义 | 不算定义 | 头文件里引用别处的变量 | 无:Java 没有单独的声明,签名由 javac 从 .class 或源码里读 |
五、目标文件、库与符号
1. 用 nm 看目标文件里的符号表
编译好 Version.o 之后:
nm -C Version.o
-C 让 nm 反修饰名字。输出(Linux,g++,节选):
0000000000000000 t minic10::(anonymous namespace)::build_flavor()
0000000000000000 T minic10::version_string()
U std::__cxx11::basic_string<char, ...>::append(char const*)
U std::__cxx11::to_string(int)
U __cxa_begin_catch
每行三列:地址、类型字母、名字。类型字母最常用的几个:
| 字母 | 全称 | 含义 | 本例 |
|---|---|---|---|
T |
Text:代码段 .text |
本文件定义的函数,别的文件可以引用 | version_string() |
t |
同上,小写 | 本文件定义的函数,只在本文件可见(内部链接) | build_flavor()——匿名命名空间的效果 |
U |
Undefined | 未定义:本文件引用了,需要别人提供 | std::to_string、__cxa_begin_catch(异常运行时) |
W |
Weak | 弱定义:inline 函数、模板生成的可重复定义,链接器遇到多份时留一份 | 下面 hello.o 里的 version_number() |
D / d |
Data:数据段 .data |
有初始值的全局变量 | |
B / b |
BSS:.bss 段,名字来自早期汇编器的指令 Block Started by Symbol |
没有初始值的全局变量,在文件里不占空间 | |
R / r |
Read-only:只读数据段 .rodata |
字符串字面量、const 全局常量 |
T、D、B、R 的大小写是同一条规则:大写表示外部可见(global),小写表示只在本文件可见(local)。
再看 hello.o(只编译不链接 examples/hello.cpp):
clang++ -std=c++17 -I. -c examples/hello.cpp -o hello.o
nm -C hello.o | grep minic10
输出(Linux):
0000000000000000 W minic10::version_number()
U minic10::version_string()
version_number() 是 inline,在 hello.o 里有一份定义,标 W;version_string() 只有声明,标 U。链接 hello 时,链接器要为这个 U 找到一个 T——它在 libminic10.so 里。(macOS 的 nm 把 version_number() 标 T 而非 W——Mach-O 用另一套机制标记可合并的弱定义,nm -m 能看到 weak;符号名多一个前导下划线;语义相同。)
与 Java 对照:.class 与 .o
两者都是编译产物的最小单位,都记着「我定义了什么、引用了谁」。差别在自描述程度:.class 带完整的类型信息(字段、方法签名、继承关系),版本兼容的 JVM 拿到就能加载、校验、执行;.o 的符号表只有名字和地址,类型信息只剩修饰名里编码的参数类型(下一节),而且地址还没定,不经过链接不能运行。
2. Name mangling:符号名为什么长得像乱码
C 的符号名就是函数名:initModule。C++ 支持重载、命名空间、模板,几个同名函数必须得到不同的符号,所以编译器把命名空间、函数名、参数类型都编码进符号名,这叫名字修饰(name mangling)。把四个同名函数写进一个文件,编译后用 nm 看(Apple clang 14;表里去掉了 macOS 多出的前导下划线):
| 源码里的函数 | 修饰后的符号 | 与第一行的差别 |
|---|---|---|
std::string minic10::version_string() |
_ZN7minic1014version_stringEv |
|
std::string minic10::version_string(int) |
_ZN7minic1014version_stringEi |
重载:末尾的参数从 v(void)变成 i(int) |
int minic10::version_string(double) |
_ZN7minic1014version_stringEd |
重载:参数是 d(double)。返回值从 std::string 换成了 int,符号里看不出来 |
std::string other::version_string() |
_ZN5other14version_stringEv |
另一个命名空间:7minic10 变成 5other |
重载在链接器眼里就是几个名字不同的普通符号,链接器不需要懂重载。普通函数的返回值类型不进修饰名(C++ 也不允许只靠返回值类型重载)。第一行逐段拆开:
| 片段 | 含义 |
|---|---|
_Z |
修饰名前缀:Itanium ABI 的修饰名都以它开头 |
N |
嵌套名开始 |
7minic10 |
长度 7 的标识符 minic10 |
14version_string |
长度 14 的标识符 version_string |
E |
嵌套名结束 |
v |
参数列表为 void |
这是 Itanium C++ ABI 的规则,GCC 和 Clang 在 Linux/macOS 上都用它;MSVC 用另一套(?version_string@minic10@@YA...)。c++filt 可以手工反修饰:
echo _ZN7minic1014version_stringEv | c++filt
# minic10::version_string()
两个直接后果:
- C++ 编译器之间的二进制兼容取决于修饰规则一致。GCC 和 Clang 一致,和 MSVC 不一致,所以 Linux 上编的
.so不可能被 Windows 用,反之亦然。更细的问题——同一编译器不同版本、不同标准库配置(_GLIBCXX_USE_CXX11_ABI)——是《与 Python 之间》里「ABI」一章的主题。上面输出里的std::__cxx11::basic_string就是 libstdc++ 新 ABI 的痕迹。 - 要给 C 或 Python 调用的函数必须关掉修饰,写法是
extern "C"。这就是torch/csrc/Module.cpp里那一行:
extern "C" TORCH_PYTHON_API PyObject* initModule();
// separate decl and defn for msvc error C2491
PyObject* initModule() {
HANDLE_TH_ERRORS
// ...
| 文件与写法 | 目标文件里的符号 | 类型 | 链接结果 |
|---|---|---|---|
stub.c(C 编译器):extern PyObject* initModule(void); |
initModule |
U |
需要别处提供一个同名的 T |
Module.cpp:extern "C" TORCH_PYTHON_API PyObject* initModule(); |
initModule |
T |
与 stub.o 的 U 同名,解析成功 |
Module.cpp 假如去掉 extern "C" |
_Z10initModulev |
T |
名字不同,undefined reference to initModule |
链接器只比较符号名的字符串:表里第一行的 U 只能由第二行那个未修饰的 T 满足。initModule 是 C++ 函数,但被 C 文件 stub.c 引用,stub.c 编译时只会生成对 initModule 这个未修饰符号的引用;如果 Module.cpp 不加 extern "C",导出的会是 _Z10initModulev,两边对不上,链接失败。同理,PyInit__C 是 Python 解释器用 dlsym 按名字查找的入口,名字必须精确为 PyInit__C,Python 的 PyMODINIT_FUNC 宏在 C++ 编译时会展开出 extern "C"。
与 Java 对照:JNI 的名字约定
JNI 解决的是同一个问题:JVM 按 Java_com_example_Foo_bar 这样的固定规则拼出名字,到本地库里找未修饰的 C 符号。所以用 C++ 实现 native 方法时同样要 extern "C"(javac -h 生成的头文件已经带上)。两边都是在两个运行时之间约定一个不依赖 C++ 修饰规则的名字。
3. 静态库与动态库
多个 .o 可以打包成库。两种库的差别决定了 PyTorch 的整个发布形态:
静态库 .a |
动态库 .so(macOS .dylib,Windows .dll) |
|
|---|---|---|
| 是什么 | .o 文件的归档(ar 打包),没有链接过 |
已经链接过的、可被加载的镜像 |
| 链接到程序时 | 需要的 .o 被拷贝进最终产物 |
只记录一条依赖(DT_NEEDED),代码留在 .so 里 |
| 运行时 | 无外部依赖 | 需要 ld.so 找到并加载 .so |
| 多个程序共享 | 各自一份 | 内存中共享同一份只读代码页 |
| 符号解析发生在 | 链接期 | 链接期检查一次,加载期再解析一次 |
| 更新库 | 必须重新链接程序 | 替换 .so 即可(ABI 兼容的前提下) |
未被引用的 .o |
不会被拉进来(下一段) | 整个库都加载 |
静态库有一个让很多人踩坑的性质:链接器从 .a 里只取被引用了的 .o。
%% 图:链接器从静态库里只取被引用的目标文件(示意)
flowchart LR
M["<b>main.o</b><br/>引用 add()"] --> LK["<b>链接器</b><br/>扫描 libops.a,<br/>只取能补上未定义符号的 .o"]
O1["<b>add.o</b><br/>定义 add()"] -->|"main.o 要它:取"| LK
O2["<b>mul.o</b><br/>定义 mul()"] -.->|"没人引用:不取"| LK
O3["<b>register_relu.o</b><br/>只有一个全局对象,<br/>构造时把 relu 注册进全局表"] -.->|"没人引用:不取"| LK
LK --> OUT["<b>可执行文件</b><br/>main.o + add.o,<br/>relu 的注册代码不在里面"]
classDef in fill:#eef4fb,stroke:#5b8dc9,color:#222
classDef drop fill:#f6f6f6,stroke:#999,color:#666
classDef lk fill:#fde7c8,stroke:#c98a00,color:#222
class M,O1,OUT in
class O2,O3 drop
class LK lk
图里的 register_relu.o 是典型的受害者:它只靠静态初始化把自己注册进全局表,没有任何符号被别人引用,于是被整个丢掉,注册代码不在最终产物里(《宏、静态注册与代码生成》的「静态库:没被引用的目标文件会被丢掉」一节)。cmake/TorchConfig.cmake.in 里 append_wholearchive_lib_if_found(torch torch_cpu) 用 -Wl,--whole-archive 强制链接器把 libtorch_cpu.a 全部拉进来,就是为了这个。PyTorch 的默认发布形态是动态库(BUILD_SHARED_LIBS=ON),不存在这个问题;vLLM、TorchServe 等下游一律链接动态库。
与 Java 对照:.jar 与两种库
Java 没有静态库与动态库之分。.jar 只是 .class 的 zip 包,没有链接过,运行时由类加载器从里面按需取类——在「运行时才加载、可以单独替换」这一点上像 .so。JVM 只加载真正用到的类,又有点像「.a 只取被引用的 .o」,但那是运行期的惰性,不是链接期的裁剪:没被引用的类仍在 jar 里,反射或 ServiceLoader 随时能把它加载出来,不会出现「注册代码被裁掉」的问题。
4. 符号可见性:.so 导出了什么
动态库有自己的”公开/私有”概念。默认情况下,.so 里所有外部链接的符号都被导出(nm -D 能看到),任何人都能链接到它们。这有两个问题:符号表巨大(libtorch_cpu.so 有几十万个符号),加载慢;内部实现细节被人依赖,无法改动。
GCC/Clang 用 -fvisibility=hidden 把默认改成”全部不导出”,再用 __attribute__((visibility("default"))) 逐个标出要导出的。一个最小的例子,库里三个函数,只有一个标了导出:
// lib.h
#define MY_API __attribute__((visibility("default")))
MY_API int exported();
int unmarked();
// lib.cpp
#include "lib.h"
namespace { int helper() { return 1; } }
int exported() { return helper(); }
int unmarked() { return 2; }
用 -fvisibility=hidden 把它编成动态库,再让另一个程序同时调用 exported() 和 unmarked()(macOS,Apple clang 14):
| 函数 | 写法 | lib.o 里的类型字母 |
动态库导出了吗 | 库外的程序链接它 |
|---|---|---|---|---|
exported() |
标了 MY_API |
T |
导出 | 成功 |
unmarked() |
头文件里有声明,没有标记 | T |
没有 | 失败:Undefined symbols: "unmarked()"(GNU ld 的措辞是 undefined reference) |
helper() |
匿名命名空间 | t |
没有 | 头文件里没有它,调用都写不出来 |
unmarked() 这一行最容易踩:头文件里有声明,编译能过;库内部的其他 .o 也能调用它;只有库外的程序在链接期找不到它。
PyTorch 就是这么做的。cmake/public/utils.cmake 里 torch_compile_options 函数对每个库目标:
if(NOT WIN32 AND NOT USE_ASAN)
# Enable hidden visibility by default to make it easier to debug issues with
# TORCH_API annotations. Hidden visibility with selective default visibility
# behaves close enough to Windows' dllimport/dllexport.
# ...
target_compile_options(${libname} PRIVATE
$<$<COMPILE_LANGUAGE:CXX>: -fvisibility=hidden>)
endif()
然后 torch/headeronly/macros/Export.h(c10/macros/Export.h 现在只是 #include 它——PyTorch 2.x 中的变化:2.8 前后引入了 torch/headeronly/ 目录,把不依赖 libtorch 的头文件搬了过去)定义:
#if defined(__GNUC__)
#define C10_EXPORT __attribute__((__visibility__("default")))
#define C10_HIDDEN __attribute__((__visibility__("hidden")))
#else // defined(__GNUC__)
#define C10_EXPORT
#define C10_HIDDEN
#endif // defined(__GNUC__)
#define C10_IMPORT C10_EXPORT
// This one is being used by libc10.so
#ifdef C10_BUILD_MAIN_LIB
#define C10_API C10_EXPORT
#else
#define C10_API C10_IMPORT
#endif
// This one is being used by libtorch.so
#ifdef CAFFE2_BUILD_MAIN_LIB
#define TORCH_API C10_EXPORT
#else
#define TORCH_API C10_IMPORT
#endif
struct C10_API Device 里的 C10_API 展开成 __attribute__((__visibility__("default"))),意思是”Device 的成员函数要从 libc10.so 导出”。TORCH_API 是 libtorch_cpu.so 的,TORCH_CUDA_CPP_API/TORCH_CUDA_CU_API 是 libtorch_cuda.so 的,TORCH_PYTHON_API(定义在 torch/csrc/Export.h)是 libtorch_python.so 的。C10_BUILD_MAIN_LIB、CAFFE2_BUILD_MAIN_LIB、THP_BUILD_MAIN_LIB 这些宏由 CMake 在编译对应库时定义(c10/CMakeLists.txt 里的 target_compile_options(c10 PRIVATE "-DC10_BUILD_MAIN_LIB"),下篇「小工程的每条命令在 PyTorch 里的写法」一节会看到),在 Windows 上区分 dllexport/dllimport,在 Linux 上两者一样。
回到 stub.c:__attribute__((visibility("default"))) PyObject* PyInit__C(void); 那行就是在说”这个符号必须导出”——Python 解释器要 dlsym 它。如果 _C.so 用 -fvisibility=hidden 编译而没有这行,import torch 会报 dynamic module does not define module export function (PyInit__C)。_C 是由 setup.py 的 setuptools Extension 编译的(下篇「stub.c 与 setup.py:_C 是怎么编出来的」一节),走的是默认可见性,但 PyTorch 仍显式写了这一行,保证换成 -fvisibility=hidden 也不会出问题。
《宏、静态注册与代码生成》的「符号可见性:注册为什么会消失」一章会详细讨论可见性如何影响静态注册。这里只需要建立一个直觉:一个符号在 PyTorch 的 .so 里能不能被扩展链接到,取决于它的声明上有没有 C10_API/TORCH_API。没有这个宏的函数,即使在头文件里声明了,链接扩展时也会 undefined reference。这是给 PyTorch 加新 API 时最常见的遗漏之一。
与 Java 对照:public 与符号可见性
两者都在回答「对库外暴露什么」,层次不同。Java 的 public / 包私有写在语言里,由编译器和 JVM 检查。C++ 的 public / private 只管类成员的访问,与导出无关:一个 public 成员函数如果没有 C10_API 这类标记,在 -fvisibility=hidden 下就不进 .so 的动态符号表,别的库在链接期找不到它。Java 9 模块的 exports 是包一级的导出声明,比 public 更接近这里的可见性。
5. 工具箱
| 工具 | 用途 | 常用命令 |
|---|---|---|
nm |
列符号表 |
|
c++filt |
反修饰 | echo _ZN... | c++filt |
objdump |
反汇编、看段 |
|
readelf |
读 ELF 结构 | readelf -d libfoo.so(动态段:NEEDED、RPATH、RUNPATH、SONAME);readelf -Ws libfoo.so(符号) |
ldd |
列运行时会加载的库及解析到的路径 | ldd hello;ldd torch/lib/libtorch_python.so |
strings |
找字符串 | strings libtorch_cpu.so | grep GLIBCXX 看依赖的 libstdc++ 版本 |
macOS 对应:nm、c++filt 一样;otool -L 代替 ldd;otool -l 代替 readelf -d;dyld_info 代替部分 objdump -p。Windows 用 dumpbin。
这些工具在《构建、调试与测试工具链》讲调试时会再次出现。本篇最后的实践一会用 ldd 和 nm 看真实的 PyTorch 库。
六、动态链接与加载
1. 链接期与加载期的两次解析
链接 hello 时写 -L. -lminic10,链接器找到 libminic10.so,检查 version_string 确实在里面,然后在 hello 里记录两件事:
DT_NEEDED: libminic10.so——运行时需要这个库(记录的是库的 SONAME,不是路径);version_string是一个需要在运行时解析的导入符号。
运行 ./hello 时,内核把控制权交给动态加载器 ld.so,它读 hello 的 DT_NEEDED 列表,按一套搜索规则找到每个库,递归加载它们的依赖,然后做第二次符号解析——把 hello 里 version_string 的调用地址填成 libminic10.so 里的实际地址(通常是惰性的:第一次调用时才解析,RTLD_LAZY)。
同一个符号 version_string 被解析了两次,一次在构建时、一次在运行时:
%% 图:version_string 的两次解析:链接期只检查并记账,加载期才找到库并填地址
sequenceDiagram
participant LK as 链接器
participant H as hello
participant LD as ld.so
participant SO as libminic10.so
Note over LK,SO: 链接期(构建时):库用 -L. 找到
LK->>SO: 动态符号表里有 version_string 吗
SO-->>LK: 有,类型 T
LK->>H: 写入 DT_NEEDED<br/>和导入符号,<br/>地址留空
Note over LK,SO: 加载期(运行 ./hello):库按 ld.so 的搜索规则找
LD->>H: 读 DT_NEEDED
LD->>SO: 找到文件,<br/>映射进进程
H->>LD: 第一次调用<br/>version_string
LD->>SO: 按名字查地址
LD-->>H: 填好地址,<br/>以后直接跳转
加载期的这一次有两个性质,和链接期不同,也和 Java 的直觉不同。
1、库是一次加载全的。 ld.so 加载一个二进制时会递归加载它 DT_NEEDED 的全部库,不管这次运行用不用得到;找不到任何一个就整个失败,import torch 直接报 ImportError: libcudart.so.12: cannot open shared object file。惰性绑定(RTLD_LAZY)只推迟”填函数地址”,不推迟”加载库”。
与 Java 对照:按需加载类与一次加载全部依赖库
类加载器加载 A 时不会立刻加载 A 引用的 B,通常等到第一次真正用到 B 才加载、链接、初始化;找不到是一个可以捕获的错误,而且可能在程序运行很久之后第一次走到某条路径时才出现。C++ 的「找不到」分散在编译期、链接期和加载期,都在业务逻辑开始之前:
| Java 的错误 | C++ 里最接近的 | 差别 |
|---|---|---|
ClassNotFoundException / NoClassDefFoundError |
undefined reference(链接期)、cannot open shared object file(加载期) |
Java 在用到那个类时抛出,可捕获;C++ 是构建失败或进程起不来 |
NoSuchMethodError |
undefined symbol: _ZN...(加载期;惰性绑定时可能晚到第一次调用) |
都是「找到了库 / 类,但里面没有要的那个成员」;C++ 这边通常是 ABI 或版本不匹配 |
2、只对名字,不对类型。 ld.so 按符号名查表,名字对上就填地址。修饰名里只有参数类型的名字,返回值类型、结构体里有哪些字段都不检查,靠的是两边用同一份头文件编译。下面是一个可以照着跑的例子,库和程序共用一个头文件:
// Options.h
struct Options {
int threads;
int batch;
};
int batch_of(const Options& o);
// Options.cpp:编成动态库
#include "Options.h"
int batch_of(const Options& o) { return o.batch; }
// app.cpp:链接这个库
#include "Options.h"
#include <iostream>
int main() {
Options o{4, 32};
std::cout << "batch = " << batch_of(o) << '\n';
}
先正常编译运行;然后把 Options.h 里两个字段换个顺序(batch 挪到 threads 前面),只重编库、不重编 app,再运行同一个 app(macOS,Apple clang 14):
clang++ -std=c++17 -shared -o libopt.dylib Options.cpp
clang++ -std=c++17 app.cpp -L. -lopt -Wl,-rpath,@loader_path -o app
./app # batch = 32
# 编辑 Options.h:把 int batch; 挪到 int threads; 前面
clang++ -std=c++17 -shared -o libopt.dylib Options.cpp
./app # batch = 4
第二次运行没有任何报错,结果却从 32 变成了 4。库里 batch_of 的符号改动前后都是 _Z8batch_ofRK7Options:里面只有类型的名字 Options,没有它的字段布局,加载器照常填地址。两边对同一块 8 字节内存的理解却不一样了:
| 偏移 | 内存里的值 | app(按旧头文件编)写入时认为这是 |
库(按新头文件编)读取时认为这是 |
|---|---|---|---|
| 0 | 4 | threads |
batch,batch_of 读的就是这里 |
| 4 | 32 | batch |
threads |
这个例子里读到的还是一个合法的整数;字段类型或结构体大小变了的时候,读到的是无关的内存。真实项目里它表现为:升级了 PyTorch 却没有重编自己的扩展,程序不报错地算错或崩溃。这是《与 Python 之间》里「ABI」一章的核心。
与 Java 对照:字节码校验与只对名字
.class 带完整的类型信息,JVM 在链接时做校验和解析,签名对不上会报 NoSuchMethodError、IncompatibleClassChangeError 这类错误。ld.so 没有类型信息可查:同样是「改了一个类却没重编使用者」,Java 多半得到一个明确的链接错误,C++ 得到的是没有任何提示的内存错读。
回到链接期:那次只是检查和记账——hello 里没有库的代码,也没有库的路径,只有库名和符号名。两次解析各用各的搜索路径——链接期是 -L,加载期是下一小节的那套规则——所以会出现”链接成功、运行时找不到库”的情况:
ldd hello
Linux 上的输出形如:
linux-vdso.so.1 (0x00007ffd...)
libminic10.so => not found
libstdc++.so.6 => /lib/x86_64-linux-gnu/libstdc++.so.6 (0x00007f...)
libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f...)
...
libminic10.so => not found——链接期用 -L. 找到了它,但加载期 ld.so 不知道去当前目录找。这就是下一小节。
2. 搜索路径:LD_LIBRARY_PATH、RPATH、RUNPATH、$ORIGIN
ld.so 按下面的顺序找 DT_NEEDED 里的库(Linux glibc;细节以 man ld.so 为准):
- 可执行文件(或正在加载的
.so)里的DT_RPATH(如果没有DT_RUNPATH); - 环境变量
LD_LIBRARY_PATH; DT_RUNPATH;/etc/ld.so.cache(由ldconfig从/etc/ld.so.conf生成);- 默认目录
/lib、/usr/lib(及 64 位变体)。
第 1 条和第 3 条容易看混:老式的 DT_RPATH 排在 LD_LIBRARY_PATH 之前,新式的 DT_RUNPATH 排在它之后,而且二进制里一旦有 DT_RUNPATH,DT_RPATH 就整个被忽略。画成判断流程:
%% 图:ld.so 为一个 DT_NEEDED 库找文件的顺序:DT_RPATH 只在没有 DT_RUNPATH 时生效,LD_LIBRARY_PATH 夹在两者之间
flowchart TB
S["<b>要加载 DT_NEEDED 里的 libminic10.so</b>"] --> Q{"这个二进制有 DT_RUNPATH 吗?"}
Q -->|"没有"| RP["1. 搜 DT_RPATH"]
Q -->|"有:DT_RPATH 被忽略"| LD
RP -->|"没找到"| LD["2. 搜 LD_LIBRARY_PATH"]
LD -->|"没找到"| RU["3. 搜 DT_RUNPATH"]
RU -->|"没找到"| C["4. 查 /etc/ld.so.cache"]
C -->|"没找到"| D["5. 搜 /lib、/usr/lib"]
D -->|"没找到"| NF["报 not found,加载失败"]
RP & LD & RU & C & D -->|"找到"| OK["映射进进程,继续处理它自己的 DT_NEEDED"]
所以设 LD_LIBRARY_PATH 能盖过 DT_RUNPATH,却盖不过老式的 DT_RPATH——同一个环境变量在两个二进制上效果不同,通常就是这个原因(readelf -d 看它写的是哪一种)。
三个可控的手段:
LD_LIBRARY_PATH:最省事,也最脏——它影响进程里所有库的查找,经常导致”设了 CUDA 路径结果 libstdc++ 也被换掉了”这种事故。torch/__init__.py 里有一段注释提到过这类问题(_load_global_deps 函数里关于 nvjitlink 的注释:设了 LD_LIBRARY_PATH 后系统会选到错误/旧版本的库)。适合调试,不适合部署。
RPATH/RUNPATH:把搜索路径烧进二进制。链接时加 -Wl,-rpath,/path/to/lib。现代链接器默认写的是 DT_RUNPATH(可以被 LD_LIBRARY_PATH 覆盖,且不传递给依赖的依赖),加 -Wl,--disable-new-dtags 才写老的 DT_RPATH。
$ORIGIN:RPATH 里的特殊标记,表示”这个二进制自己所在的目录”。-Wl,-rpath,'$ORIGIN/lib' 让程序无论被拷到哪里都能找到它旁边 lib/ 目录里的库。这正是 pip 包能工作的原因。setup.py 里 _C 扩展的链接参数:
def make_relative_rpath_args(path: str) -> list[str]:
if IS_DARWIN:
return ["-Wl,-rpath,@loader_path/" + path]
elif IS_WINDOWS:
return []
else:
return ["-Wl,-rpath,$ORIGIN/" + path]
# ...
C = Extension(
"torch._C",
libraries=main_libraries, # ["torch_python"]
sources=main_sources, # ["torch/csrc/stub.c"]
language="c",
# ...
library_dirs=library_dirs, # [torch/lib]
extra_link_args=[
*extra_link_args,
*main_link_args,
*make_relative_rpath_args("lib"),
],
)
装好之后,各个文件的位置和它们烧进去的搜索路径:
site-packages/torch/
├── _C.cpython-312-x86_64-linux-gnu.so $ORIGIN/lib:到 lib/ 找 libtorch_python.so
└── lib/
├── libtorch_python.so $ORIGIN:到同目录找 libtorch_cpu.so
├── libtorch_cpu.so $ORIGIN:到同目录找 libc10.so
└── libc10.so
每个文件都只说「相对我自己的位置去哪找」,整个 torch/ 目录装在哪里都能互相找到,所以 import torch 不需要用户设任何环境变量。
查看一个二进制的 RPATH:
readelf -d torch/_C.cpython-312-x86_64-linux-gnu.so | grep -E 'RPATH|RUNPATH|NEEDED'
Linux wheel 上的输出形如(macOS 对应 otool -l _C.cpython-312-darwin.so | grep -A2 LC_RPATH,看到 path @loader_path/lib):
0x0000000000000001 (NEEDED) Shared library: [libtorch_python.so]
0x0000000000000001 (NEEDED) Shared library: [libc.so.6]
0x000000000000001d (RUNPATH) Library runpath: [$ORIGIN/lib]
修好上面 hello 的方法:
clang++ -std=c++17 -I. examples/hello.cpp -L. -lminic10 -Wl,-rpath,'$ORIGIN' -o hello
(macOS 上 $ORIGIN 对应 @loader_path,ldd 对应 otool -L,LD_LIBRARY_PATH 对应 DYLD_LIBRARY_PATH。)
与 Java 对照:classpath 与两套搜索路径
相同处:Java 也分两次给路径——javac -cp 和 java -cp——两次不一致时同样是「编译通过、运行时找不到」。不同处有两点。其一,classpath 只能在启动时由命令行或环境给出;C++ 的加载期路径除了环境变量 LD_LIBRARY_PATH,还能用 RPATH / RUNPATH 写进二进制,随文件一起分发。其二,classpath 上缺一个 jar,要到用到其中的类才出错;DT_NEEDED 里缺一个库,进程启动时就失败。
3. dlopen:运行时显式加载
除了启动时按 DT_NEEDED 自动加载,程序还可以调 dlopen("libfoo.so", flags) 手工加载一个库,用 dlsym 按名字取符号。Python 的 import 一个 C 扩展就是 dlopen 它,然后 dlsym("PyInit__C")。
dlopen 有一个重要的 flag:RTLD_LOCAL(默认)还是 RTLD_GLOBAL。RTLD_LOCAL 加载的库的符号只对这个库自己及它的依赖可见;RTLD_GLOBAL 让它的符号进入全局命名空间,之后加载的任何库都能解析到它们。Python 默认用 RTLD_LOCAL 加载扩展,这就产生了一个问题:libtorch_python.so 依赖 MKL/OpenMP/CUDA runtime,而这些库自己又会 dlopen 插件并假定全局能看到它们的符号。
caffe2/CMakeLists.txt 里有专门的注释和一个专门的空库解决这个问题:
# Note [Global dependencies]
# Some libraries (e.g. OpenMPI) like to dlopen plugins after they're initialized,
# and they assume that all of their symbols will be available in the global namespace.
# On the other hand we try to be good citizens and avoid polluting the symbol
# namespaces, so libtorch is loaded with all its dependencies in a local scope.
# That usually leads to missing symbol errors at run-time, so to avoid a situation like
# this we have to preload those libs in a global namespace.
if(BUILD_SHARED_LIBS)
add_library(torch_global_deps SHARED ${TORCH_SRC_DIR}/csrc/empty.c)
# ...
if(CAFFE2_USE_MKL)
target_link_libraries(torch_global_deps caffe2::mkl)
endif()
if(USE_CUDA)
target_link_libraries(torch_global_deps ${Caffe2_PUBLIC_CUDA_DEPENDENCY_LIBS})
target_link_libraries(torch_global_deps torch::cudart)
# ...
endif()
install(TARGETS torch_global_deps DESTINATION "${TORCH_INSTALL_LIB_DIR}")
endif()
libtorch_global_deps.so 是一个由空文件 torch/csrc/empty.c 编出来的库,自己没有任何代码,只有一串 DT_NEEDED(MKL、cudart 等)。torch/__init__.py 在 import torch._C 之前先用 RTLD_GLOBAL 加载它:
# See Note [Global dependencies]
def _load_global_deps() -> None:
if platform.system() == "Windows":
return
# Determine the file extension based on the platform
lib_ext = ".dylib" if platform.system() == "Darwin" else ".so"
lib_name = f"libtorch_global_deps{lib_ext}"
here = os.path.abspath(__file__)
global_deps_lib_path = os.path.join(os.path.dirname(here), "lib", lib_name)
try:
ctypes.CDLL(global_deps_lib_path, mode=ctypes.RTLD_GLOBAL)
# ...
except OSError as err:
# Can happen for wheel with cuda libs as PYPI deps
# As PyTorch is not purelib, but nvidia-*-cu12 is
_preload_cuda_deps(err)
ctypes.CDLL(global_deps_lib_path, mode=ctypes.RTLD_GLOBAL)
else:
# Easy way. You want this most of the time, because it will prevent
# C++ symbols from libtorch clobbering C++ symbols from other
# libraries, leading to mysterious segfaults.
# ...
if USE_GLOBAL_DEPS:
_load_global_deps()
from torch._C import * # noqa: F403
%% 图:import torch 时两种符号作用域:运行时依赖库进全局作用域,libtorch 自己留在局部作用域
flowchart TB
PY["<b>torch/__init__.py</b><br/>1. _load_global_deps()<br/>2. from torch._C import *"]
subgraph GS["全局作用域(RTLD_GLOBAL)"]
GD["<b>libtorch_global_deps.so</b><br/>空文件 empty.c 编成,<br/>只有 DT_NEEDED"]
DEPS["MKL、cudart 等运行时库"]
GD -->|"DT_NEEDED"| DEPS
end
subgraph LS["局部作用域(RTLD_LOCAL)"]
EXT["<b>torch/_C.cpython-312-….so</b><br/>stub.c 编成,导出 PyInit__C"]
TP["libtorch_python.so"]
TC["libtorch_cpu.so"]
C10["libc10.so"]
EXT -->|"DT_NEEDED"| TP
TP -->|"DT_NEEDED"| TC
TC -->|"DT_NEEDED"| C10
end
PY -->|"第 1 步:ctypes.CDLL(…, RTLD_GLOBAL)"| GD
PY -->|"第 2 步:import 按 RTLD_LOCAL 做 dlopen"| EXT
TC -.->|"已加载,直接复用"| DEPS
DEPS --> PLUG["<b>MKL、OpenMPI 等自己 dlopen 的插件</b><br/>在全局作用域里找宿主库的符号:找得到"]
C10 ~~~ OTHER["<b>进程里其他带 C++ 符号的库(如 OpenCV)</b><br/>解析不到 libtorch 的符号,互不覆盖"]
classDef glob fill:#fde7c8,stroke:#c98a00,color:#222
classDef loc fill:#eef4fb,stroke:#5b8dc9,color:#222
classDef note fill:#f6f6f6,stroke:#999,color:#222
class GD,DEPS glob
class EXT,TP,TC,C10 loc
class PLUG,OTHER note
图里两个框就是两种 dlopen flag 的效果:橙色框里只有那几个”插件要回头找”的运行时库,蓝色框里是 libtorch 的整棵依赖树;底部两个灰框是各自的受益方。这样 MKL、cudart 的符号全局可见(它们的插件能工作),而 libtorch 自己的几十万个 C++ 符号仍是 RTLD_LOCAL(不会和别的库——比如另一个也带了自己 libstdc++ 的扩展——打架)。注释里”mysterious segfaults”是真实的历史:早期 PyTorch 用 RTLD_GLOBAL 加载整个 libtorch,和其他同样导出 C++ 符号的库(如 OpenCV)冲突导致崩溃。
这一个设计把本节的所有概念用在了同一个工程决策上:DT_NEEDED、加载顺序、RTLD_GLOBAL vs RTLD_LOCAL、符号污染。
与 Java 对照:类加载器与 dlopen
相像的地方:都能由程序在运行时显式加载代码(Class.forName、URLClassLoader 对 dlopen、dlsym),都有命名空间隔离——不同类加载器加载的同名类是两个不同的类,RTLD_LOCAL 让一个库的符号不被后加载的库解析到。不像的地方:类加载器是普通的 Java 对象,可以自己写一个从网络或数据库取字节码;ld.so 是操作系统的组件,dlopen 按文件路径加载,搜索规则固定为上一节那套顺序。隔离的粒度也不同:Java 按加载器隔离整个类,这里只有全局与局部两个符号作用域。
七、实践一:手写编译命令链接一个 libtorch 程序
这一节在一台 pip 安装了 PyTorch CPU wheel 的机器上做。下面的输出来自 macOS(Apple clang 21,torch==2.14.0 的 CPU wheel)——与 Linux 的差别只在文件名与工具名:.so ↔ .dylib、g++ ↔ clang++、ldd ↔ otool -L、readelf -d ↔ otool -l、RUNPATH ↔ LC_RPATH、LD_LIBRARY_PATH ↔ DYLD_LIBRARY_PATH。每一步先给 Linux 的写法,再给 macOS 实际跑出来的结果。
1. 程序
// hello_torch.cpp
#include <torch/torch.h>
#include <iostream>
int main() {
torch::Tensor t = torch::ones({2, 3});
torch::Tensor u = t * 2.5 + 1.0;
std::cout << u << '\n';
std::cout << "sum = " << u.sum().item<float>() << '\n';
std::cout << "device = " << u.device() << ", dtype = " << u.dtype() << '\n';
return 0;
}
<torch/torch.h> 在 torch/csrc/api/include/torch/torch.h,它包含 torch/all.h,后者包含 torch/types.h(下篇「torch:: 如何”包含”at::」一节的 using namespace at)等。torch::ones、torch::Tensor、u.device() 分别落在 libtorch_cpu.so(算子和 Tensor 方法)和 libc10.so(c10::Device 的 operator<<)。
2. 找到头文件和库
TORCH_DIR=$(python -c 'import torch, os; print(os.path.dirname(torch.__file__))')
echo $TORCH_DIR
ls $TORCH_DIR/include | head -5
ls $TORCH_DIR/lib
/Users/.../.venv/lib/python3.12/site-packages/torch
ATen c10 caffe2 clog.h cpuinfo.h
libc10.dylib libomp.dylib libshm.dylib libtorch.dylib libtorch_cpu.dylib
libtorch_global_deps.dylib libtorch_python.dylib
include/ 下有 ATen/、c10/、torch/、pybind11/ 等;lib/ 下是下篇「import torch 时加载了什么」一节列的那些库(Linux 上后缀是 .so,CUDA wheel 多出 libtorch_cuda、libc10_cuda)。
3. 编译(只编译)
g++ -std=c++17 -c hello_torch.cpp -o hello_torch.o \
-I$TORCH_DIR/include \
-I$TORCH_DIR/include/torch/csrc/api/include
两个 -I:第一个让 #include <c10/...>、<ATen/...>、<torch/csrc/...> 能找到;第二个让 #include <torch/torch.h> 能找到(C++ 前端头文件在 torch/csrc/api/include/ 下,和 torch/csrc/ 是两套路径前缀)。torch/CMakeLists.txt 的 TORCH_PYTHON_INCLUDE_DIRECTORIES 和 cpp_extension.py 的 include_paths() 加的就是这两个。
-std=c++17 是本系列基线 v2.10.0 的要求(下篇「小工程的每条命令在 PyTorch 里的写法」一节)。版本提醒:2.14.0 的头文件已经要求 C++20——用 -std=c++17 编这一步会在 torch/all.h 第 5 行停住:
torch/include/torch/csrc/api/include/torch/all.h:5:2: error: C++20 or later compatible compiler is required to use PyTorch.
换成 -std=c++20 即可。这正是”编译扩展时的 -std= 要跟 PyTorch 保持一致”的实例:标准由你装的那个 wheel 决定,不由文章决定。下面的输出用 -std=c++20 编出,4.7 秒——一个 12 行的程序,因为 torch/torch.h 展开后是几十万行的翻译单元。
这一步只需要头文件,不需要任何库。看一下它引用了什么:
nm -C hello_torch.o | grep ' U ' | grep -E 'at::|c10::|torch::' | head -8
U at::_ops::add_Scalar::call(at::Tensor const&, c10::Scalar const&, c10::Scalar const&)
U at::_ops::mul_Scalar::call(at::Tensor const&, c10::Scalar const&)
U at::_ops::sum::call(at::Tensor const&, std::optional<c10::ScalarType>)
U at::_ops::ones::call(c10::ArrayRef<c10::SymInt>, std::optional<c10::ScalarType>, std::optional<c10::Layout>, std::optional<c10::Device>, std::optional<bool>)
U at::print(std::ostream&, at::Tensor const&, long long)
U c10::TensorImpl::set_autograd_meta(std::unique_ptr<c10::AutogradMetaInterface>)
U c10::UndefinedTensorImpl::_singleton
U c10::AutogradMetaInterface::~AutogradMetaInterface()
(为了可读,去掉了 libc++ 的 std::__1:: 前缀。)torch::ones、t * 2.5、+ 1.0、.sum() 这四个源码里的调用,变成了四个 at::_ops::*::call 的 U——torch::ones 是头文件里的 inline 函数,最终调到 at::_ops::ones::call;后三个 c10:: 符号来自 Tensor 构造与析构走过的头文件里的 inline 代码。这就是”自定义扩展依赖哪些符号”的精确答案:前五个在 libtorch_cpu,后三个在 libc10。
4. 链接
g++ hello_torch.o -o hello_torch \
-L$TORCH_DIR/lib \
-ltorch -ltorch_cpu -lc10 \
-Wl,-rpath,$TORCH_DIR/lib
-L$TORCH_DIR/lib:链接期去哪找库;-ltorch -ltorch_cpu -lc10:libtorch.so(空壳,可省,但写上和 CMake 行为一致)、libtorch_cpu.so、libc10.so。-l顺序原则上是”引用者在前、被引用者在后”,动态库对顺序不敏感,静态库敏感;-Wl,-rpath,$TORCH_DIR/lib:把库路径烧进hello_torch,运行时不用设LD_LIBRARY_PATH。
如果省掉 -lc10,链接器为上面那三个 c10:: 的 U 找不到 T(macOS ld64 的措辞;GNU ld 说 undefined reference to):
Undefined symbols for architecture arm64:
"c10::TensorImpl::set_autograd_meta(std::unique_ptr<c10::AutogradMetaInterface>)", referenced from:
torch::autograd::make_variable(at::Tensor, bool, bool) in hello_torch.o
...
(现代 GNU ld 默认 --no-copy-dt-needed-entries,macOS ld64 也一样:不会通过 libtorch_cpu 的依赖间接满足 hello_torch.o 对 libc10 符号的引用,必须显式 -lc10。这是新手常见的一个坑:链接错误提示的符号明明在 libc10 里,却因为没写 -lc10 而找不到。)
如果省掉 -Wl,-rpath:链接成功,运行报错——
dyld[69854]: Library not loaded: @rpath/libtorch.dylib
Referenced from: /tmp/hello_torch/hello_torch_norpath
Reason: no LC_RPATH's found
Linux 上是 ./hello_torch: error while loading shared libraries: libtorch.so: cannot open shared object file: No such file or directory。这是加载期错误,不是链接期。用 LD_LIBRARY_PATH=$TORCH_DIR/lib ./hello_torch(macOS:DYLD_LIBRARY_PATH)可以临时绕过。
把这一节手写命令里的参数按”少了它在哪个阶段出错”排一遍,正好走过第二章的四个出错阶段:
| 少了什么 | 出错的阶段 | 报错(GNU 工具链 / macOS) |
|---|---|---|
-I$TORCH_DIR/include/torch/csrc/api/include |
预处理 | fatal error: torch/torch.h: No such file or directory / 'torch/torch.h' file not found |
-std= 低于头文件要求 |
预处理(torch/all.h 开头的 #error 指令) |
error: C++20 or later compatible compiler is required to use PyTorch.(v2.10.0 的头文件写的是 C++17) |
-ltorch_cpu 或 -lc10 |
链接 | undefined reference to ... / Undefined symbols for architecture arm64 |
-Wl,-rpath,$TORCH_DIR/lib |
加载(链接成功,运行才报) | cannot open shared object file / Library not loaded: @rpath/libtorch.dylib |
-I 和 -std= 的错误在编译这一步就出现,-l 的错误要到链接命令,-rpath 的错误要到 ./hello_torch 启动——越靠后的阶段,离写错的那一行越远。
5. 运行与观察
./hello_torch
3.5000 3.5000 3.5000
3.5000 3.5000 3.5000
[ CPUFloatType{2,3} ]
sum = 21
device = cpu, dtype = float
ldd hello_torch | grep -E 'torch|c10' # macOS: otool -L hello_torch
@rpath/libtorch.dylib (compatibility version 0.0.0, current version 0.0.0)
@rpath/libtorch_cpu.dylib (compatibility version 0.0.0, current version 0.0.0)
@rpath/libc10.dylib (compatibility version 0.0.0, current version 0.0.0)
三个库正是 -l 的三个;Linux 的 ldd 会直接印出解析后的绝对路径 libtorch.so => /.../torch/lib/libtorch.so。CUDA wheel 还会多出 libtorch_cuda、libc10_cuda、libcudart.so.12 等——虽然程序一行 CUDA 代码都没有,但 libtorch 的 DT_NEEDED 把它们全拉进来了(第六章「链接期与加载期的两次解析」一节说的”递归加载 DT_NEEDED 的全部库,不管用不用”)。
readelf -d hello_torch | grep -E 'NEEDED|RUNPATH' # macOS: otool -l hello_torch | grep -A2 LC_RPATH
nm -DC $TORCH_DIR/lib/libc10.so | grep 'c10::Device::str' # macOS: nm -C libc10.dylib
path /Users/.../site-packages/torch/lib (offset 12)
000000000000da78 T c10::Device::str() const
第一行是 -Wl,-rpath 烧进去的路径(Linux 上是 (RUNPATH) Library runpath: [/.../torch/lib],前面还有三行 (NEEDED));第二行是 c10::Device::str 在 libc10 里的定义,T——第五章那张符号表的字母。Linux 的 wheel 上这一行会带 [abi:cxx11] 标签:T c10::Device::str[abi:cxx11]() const,那是 libstdc++ 新 ABI 的痕迹(《与 Python 之间》)。如果扩展编译时用了 -D_GLIBCXX_USE_CXX11_ABI=0,它引用的会是没有这个标签的 c10::Device::str() const,加载时报 undefined symbol——这是 PyTorch 2.6 之前 Linux wheel 用旧 ABI 时最常见的事故;PyTorch 2.x 中的变化:2.6 起 Linux wheel 切换到 CXX11 ABI,cpp_extension.py 不再显式传这个宏。macOS 用 libc++,没有这个标签,也就没有这个坑。
6. 与 CMake 的对应
上面手写的每个参数在 CMake 里都有对应物:
| 手写 g++ | CMake(vLLM cmake/utils.cmake 的写法) |
|---|---|
-I$TORCH_DIR/include ... |
find_package(Torch) 后 target_link_libraries(x PRIVATE torch) 自动带上 TORCH_INCLUDE_DIRS |
-L$TORCH_DIR/lib -ltorch -ltorch_cpu -lc10 |
同上,torch 目标的 INTERFACE_LINK_LIBRARIES |
-Wl,-rpath,... |
CMAKE_INSTALL_RPATH / BUILD_RPATH,或 set_target_properties(... INSTALL_RPATH ...) |
-std=c++17 |
CMAKE_CXX_STANDARD 17;TorchConfig.cmake 也给导入目标 torch 设了 CXX_STANDARD 17 |
《构建、调试与测试工具链》会系统讲 CMake。这里的目的是让读者知道:CMake 生成的最终命令和手写的没有本质区别,出了链接问题可以把 ninja -v 打出的命令拿出来单独跑。
八、本文小结
回到开头 stub.c 的那几个问题。extern PyObject* initModule(void); 的函数体在哪?在另一个翻译单元里;编译器不需要知道,它只生成一条”引用未定义符号”的记录,把符号解析成地址是链接器的事(第三、五章)。为什么先声明再定义、visibility("default") 是什么?声明是为了挂属性;PyTorch 全局 -fvisibility=hidden,不标 default 的符号不进动态符号表,dlsym 找不到入口(第五章)。#ifndef、#ifdef 是代码还是配置?是预处理指令,决定编译器能看到哪些行(第二章)。这个文件编成什么、怎么接上 initModule?编成一个 .o,链进 torch/_C.*.so,链接期解析到 libtorch_python.so,加载期由动态链接器沿 DT_NEEDED 接上(第五、六章)。
支撑这些答案的 C++ 机制:
| 机制 | 一句话 | 在 PyTorch 里的体现 |
|---|---|---|
| 四阶段编译 | 预处理拼文本、编译看单个翻译单元、汇编出 .o、链接对符号;加载是运行时的第五步 |
每类错误只在一个阶段出现 |
| 声明与定义 | 头文件放声明和 inline 小函数,.cpp 放定义 |
c10/core/Device.h / Device.cpp |
#pragma once |
一个翻译单元里头文件只展开一次 | 所有头文件第一行 |
| ODR | 非 inline 实体全程序一个定义;inline/模板/类可多份但必须相同 | ScalarType.h 的 inline 工具函数;AVX 链接顺序注释 |
| 内部链接 | static/匿名命名空间的符号不出翻译单元 |
Device.cpp 的 parse_type;kernel 文件的大匿名命名空间 |
| 符号与修饰 | C++ 把命名空间和参数类型编进符号名;extern "C" 关掉它 |
initModule 的 extern "C";[abi:cxx11] 标签 |
| 可见性 | -fvisibility=hidden + C10_API/TORCH_API 决定 .so 导出什么 |
torch_compile_options;Export.h |
| 静态库 vs 动态库 | .a 链接期裁剪拷贝,.so 记依赖加载期解析 |
--whole-archive;BUILD_SHARED_LIBS |
RPATH / $ORIGIN |
把库搜索路径烧进二进制 | setup.py 给 _C 传的 -Wl,-rpath,$ORIGIN/lib |
dlopen / RTLD_GLOBAL |
运行时显式加载,符号是否全局可见 | libtorch_global_deps.so;_load_global_deps() |
Java 工程师需要放弃的两个直觉:“编译器能看到整个项目”(不能,只能看到一个翻译单元,头文件是手写的接口);“找不到类是运行时异常”(在 C++ 里它是构建失败或进程起不来,三个阶段都在业务代码运行之前)。第三个直觉——”一个包就是一个 jar”——留给下篇:命名空间、目录、库是三个独立的维度。
下篇把镜头从一个翻译单元拉远到整个 PyTorch:几千个 .cpp 怎么分层成几个库、import torch 加载了哪些 .so、自定义扩展链接到哪一个。
九、自测
-
undefined reference to at::foo(...)、error: 'foo' was not declared in this scope、symbol lookup error: undefined symbol各出现在编译的哪个阶段?答案
分别是链接期(找不到定义)、编译期(找不到声明——头文件没包含)、加载期(运行时动态链接器在
.so依赖链里找不到符号,常见于 ABI 不匹配或库没导出)。四阶段加加载是第五步,每类错误只在一个阶段出现。 -
一个
inline函数写在头文件里被十个.cpp包含,ODR 允许吗?一个普通函数呢?答案
inline(以及模板、类定义)允许多个翻译单元各一份定义,但必须完全相同,链接器任选一份;普通非 inline 函数多份定义是 ODR 违规,链接报 multiple definition。所以头文件放声明与 inline 小函数,.cpp放定义。 -
extern "C"关掉了什么?PyInit__C为什么必须用它?答案
关掉 C++ 的名字修饰(namespace、参数类型编进符号名)与重载。CPython 用
dlsym按字符串PyInit__C查符号,修饰后的名字查不到。 -
-fvisibility=hidden之后,一个类要跨.so使用需要做什么?只标函数不标类会怎样?答案
在类声明上加
class C10_API Foo(展开为__attribute__((visibility("default")))),成员函数、vtable、typeinfo 一起导出;只标函数不标类,dynamic_cast、异常捕获(typeinfo 不同)与虚调用会跨库失败。 -
静态库里一个只有静态注册、没被任何符号引用的
.o会怎样?PyTorch 怎么处理?答案
链接器裁掉它,注册消失——算子“不存在”。用
--whole-archive(PyTorch 的append_wholearchive_lib_if_found)强制把整个.a拉进来,或改用动态库(.so加载时全部静态初始化都执行)。
-
函数体在另一个翻译单元(
torch/csrc/Module.cpp)里。编译器不需要知道它在哪:编译阶段只要看到声明就能生成一条「调用未定义符号initModule」的记录,把这个符号解析成地址是链接器的事——它在所有目标文件和库里找唯一一个定义。详见第三章、第五章。 ↩ -
先声明是为了给它加属性(
extern "C"、可见性),定义时就不用重复写。visibility("default")表示这个符号要导出到动态符号表;PyTorch 全局用-fvisibility=hidden编译,不写的话PyInit__C会被藏起来,Python 的dlopen之后dlsym找不到入口,import torch._C直接失败。详见第五章、第六章。 ↩ -
都不是——是预处理器指令,在编译之前按文本处理:
#ifdef __cplusplus让同一个头文件被 C 与 C++ 编译器都能读,#ifndef _WIN32按平台裁掉不适用的代码。它们决定「哪些行会被编译器看到」,属于构建配置在源码里的投影。详见第二章。 ↩ -
这个文件编成一个目标文件,再链接成扩展模块
torch/_C.cpython-*.so——一个只含很薄的入口的动态库。它对initModule的引用在链接时解析到libtorch_python.so(Module.cpp编进了那里),加载时由动态链接器沿DT_NEEDED把两者接上。详见第五章、第六章、下篇第四章。 ↩ -
四个阶段:预处理(
#include展开、宏替换,产出一个翻译单元)→ 编译(翻译单元 → 汇编 / 目标文件.o,每个函数与变量变成符号,引用外部的留作未定义符号)→ 链接(把多个.o与库合并,解析未定义符号;-shared产出.so,导出符号表与依赖的NEEDED列表)→ 加载(dlopen/ 程序启动时动态链接器按RPATH/LD_LIBRARY_PATH找到依赖库、重定位并解析符号)。「找不到」分别发生在:头文件找不到——预处理期(fatal error: xxx.h: No such file);标识符未声明——编译期;undefined reference/undefined symbol——链接期(声明了没定义或没链接那个库);cannot open shared object file与运行时undefined symbol——加载期(库路径或 ABI / 版本不匹配)。 ↩
系列 《C++ 在 AI-Infra:从对象模型到算子扩展》 第 1 / 10 篇 进阶
系列总览 — 为什么这样组织、读它需要什么、读完能做什么 · 幻灯片 — 整个系列的精华,一份可分享的 deck
学习地图 — AI-Infra 工程师学习地图 第 2 / 14 个系列
上一个系列:Python 在 AI-Infra下一篇:工程布局——命名空间、库的分层与 CMake
下一个系列:PyTorch 深度实践:从 Tensor 到深度学习运行时 深入 · 11 篇,约 6.4 小时
本文由 arganzheng 创作,采用 CC BY 4.0 许可协议。在保留原文作者、署名以及完整原文链接(https://arganzheng.life/cpp-compilation-model-from-cpp-to-shared-object.html)的前提下,欢迎各种形式的转载、翻译或商业引用。
COMMENTS
评论存放在 GitHub Discussions, 用 GitHub 账号登录即可发表,支持 Markdown。 想针对正文某句话说?选中那段文字,点浮出的「评论」即可划线评论;觉得哪里写错了,发表时勾上「同时提交 Issue」。 有人回复你时 GitHub 会按你的通知设置发邮件,不用守在这里。