上篇讲的是一个翻译单元怎么变成一个 .so:预处理、编译、汇编、链接四个阶段,声明与定义、ODR、符号与可见性、动态链接。PyTorch 有几千个翻译单元,最终编成的不是一个 .so 而是十几个——libc10.so、libtorch_cpu.so、libtorch_cuda.so、libtorch.so、libtorch_python.so、torch/_C.cpython-*.so……本篇讲几千个翻译单元怎么组织成几个库:靠什么划分层次(命名空间)、每一层编成什么(库的分层)、谁来描述这些规则(CMake),以及自己动手搭一个同样结构的最小骨架。

Java 工程师在这里要放弃的直觉是“一个包就是一个 jar”。Java 里包名决定目录,一个构建模块的源码又通常打成一个 .jar,名字、目录、产物大体对齐;C++ 里命名空间、目录、库是三个独立的维度——torch:: 命名空间横跨两个 .so,c10/ 目录编成一个库但 aten/ 目录编进 torch_cpu,而库与库之间的依赖写在 CMake 里而不是源码里。PyTorch 只是让这三个维度大致对齐,读懂它的目录结构就是读懂这三个维度各自的规则。

上篇开头那个 15 行的 torch/csrc/stub.c 在这里再贴一遍——它是 import torch 加载的第一个 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();
}

本文要回答的核心问题是:

import torch 时加载了哪些 .so?1 它们之间是什么依赖关系?2 自定义扩展链接到哪一个?3

PyTorch 在本篇里是被拆开看的样本,与系列其他篇一样——目的不是记住它的目录,而是学会看任何一个大 C++ 项目的目录时该问的三个问题:这个命名空间对应哪些库?这个目录编进哪个 .so?代码要用它,得链接哪一个?

一、总览

%%{init: {"flowchart": {"wrappingWidth": 320}}}%%
%% 图:一个翻译单元的名字、目录与库:从源码到 wheel 再到下游扩展
flowchart TB
    TU["<b>翻译单元(一个 .cpp)</b><br/>• 代码写在哪个 namespace 里<br/>• 文件放在哪个目录下"]
    SYM["<b>修饰后的符号名</b><br/>c10::、at::、torch:: 只留下名字前缀"]
    TGT["<b>CMake target</b><br/>• add_library 的源文件清单<br/>• target_link_libraries 的依赖"]
    subgraph LIBS["torch/lib/ 里的库与扩展模块:每一层只依赖右边更低的层"]
        direction LR
        CEXT["_C.cpython-*.so"] --> LPY["libtorch_python.so"]
        LPY --> LCPU["libtorch_cpu.so<br/>(经空壳 libtorch.so)"]
        LCPU --> LC10["libc10.so"]
    end
    WHEEL["<b>wheel:site-packages/torch/</b><br/>_C.cpython-*.so、lib/、include/、share/cmake/"]
    RUN["<b>import torch</b><br/>dlopen _C,ld.so 沿 DT_NEEDED 把整条链加载进来"]
    EXT["<b>下游扩展</b><br/>cpp_extension、vLLM 的 find_package(Torch)"]
    TU -- "namespace 关键字(第二章)" --> SYM
    TU -- "目录由谁收进清单(第三章)" --> TGT
    SYM -- "符号进哪个库与前缀无关(第二章)" --> LIBS
    TGT -- "编译、链接(第四章)" --> LIBS
    LIBS -- "setup.py 打包(第四章)" --> WHEEL
    WHEEL -- "加载(第三章)" --> RUN
    WHEEL -- "链接哪一个库(第三章)" --> EXT
  • 翻译单元:一个 .cpp 连同它包含的头文件。它身上有两个互不相关的属性:代码写在哪个命名空间里,文件放在哪个目录下。PyTorch 有几千个。
  • 修饰后的符号名:命名空间是语言特性,编译后只剩符号名里的一段前缀(c10::GetCPUAllocator() 修饰成 _ZN3c1015GetCPUAllocatorEv)。它不决定这个符号进哪个库。
  • CMake target:add_library(名字 源文件清单) 定义一个库,清单里列了哪些文件,哪些翻译单元就进这个库;target_link_libraries 写它依赖哪些别的 target。目录本身不决定任何事,决定的是哪个 target 把它收进了清单。
  • 库的分层:libc10.so 在最底层,libtorch_cpu.so(CUDA 构建还有 libtorch_cuda.so)依赖它,libtorch.so 是把 CPU 与 CUDA 两个库包在一起的空壳,libtorch_python.so 是 Python 绑定。依赖关系在链接时写进每个 .so 的 DT_NEEDED。
  • torch/_C.cpython-*.so:Python 扩展模块,由 15 行的 stub.c 编成,只依赖 libtorch_python.so。它是这条链上唯一不由 CMake 而由 setuptools 编译的二进制。
  • wheel:setup.py 先运行 CMake 把库装进 torch/lib/,再编 _C,最后连同 include/、share/cmake/ 一起打包。装好之后的 site-packages/torch/ 就是一份完整的 C++ SDK。
  • import torch 与下游扩展:wheel 的两种用法。import torch 是加载:dlopen _C,动态链接器沿 DT_NEEDED 把整条链拉起来。扩展是链接:按自己用到的符号在哪个库,决定链 libc10.so、libtorch_cpu.so 还是 libtorch_python.so。

1. 三个独立的维度:命名空间、目录、库

总览图左右两条支路对应三套互不相关的机制:命名空间是语言特性,只影响名字(与修饰后的符号名);目录是构建系统的约定,CMake 决定哪些目录编进哪个库;库是链接器的产物,依赖关系写在 target_link_libraries 里。本篇按这个顺序展开,最后用 mini-c10 把三者亲手搭一遍。

与 Java 对照:一个维度与三个维度

Java 的 package com.foo.bar 一句声明同时给出类的全名和 class 文件的目录 com/foo/bar/,按 Maven / Gradle 的惯例,一个模块目录又打成一个 jar。C++ 里名字、目录、库各由一套机制决定:知道一个类型叫 torch::autograd::Node,推不出它在哪个目录,也推不出要链接哪个 .so。

2. 本文的章节安排

前三章是 PyTorch 的三个维度各是怎么划的,第五章动手搭一个同样结构的骨架,第六章是读任何大 C++ 项目时的定位技巧。

本文的章节安排
章 主题 内容
二 命名空间 c10::、at::、torch:: 的分工;一个命名空间可以横跨多个库
三 PyTorch 的源码布局与库布局
  • 目录怎样编成库:用一个小工程实现
  • PUBLIC 与 PRIVATE
  • import torch 加载了什么
  • 扩展链接到哪一个
四 回到源码
  • 小工程的每条命令在 PyTorch 三个 CMake 文件里的写法
  • stub.c 与 setup.py
  • wheel
五 实践二 mini-c10 的目录结构与第一个可链接的库
六 工程实践建议与常见错误 按阶段定位错误、头文件卫生、链接与部署、读源码的定位技巧
七 本文小结  
八 自测 5 道题

二、命名空间:c10::、at::、torch:: 的分工

1. 命名空间的语法

namespace 的作用是避免名字冲突、给名字分层:

namespace c10 {
struct Device { /* ... */ };
}                          // 可以在任意文件、任意多次“重新打开”同一个命名空间

namespace at::native {     // C++17:嵌套命名空间的简写
Tensor add(const Tensor& self, const Scalar& other, const Scalar& alpha);
}

c10::Device d(c10::DeviceType::CPU);   // 限定名
using c10::Device;                      // using 声明:引入一个名字
using namespace at;                     // using 指令:引入整个命名空间的所有名字
namespace ptx = ::cuda::ptx;            // 命名空间别名

这段代码里有三条规则:

  1. 命名空间与文件、目录无关。 一个文件可以打开任意多个命名空间,一个命名空间可以在任意多个文件里重新打开。PyTorch 让 c10:: 的代码大致都在 c10/ 下,这是约定,编译器不检查。
  2. using 是纯编译期的名字查找规则。 using 声明、using 指令和命名空间别名只改变”这个名字去哪里找”,不产生任何代码,不影响二进制。
  3. 命名空间在运行时不存在。 它只进入修饰后的符号名:c10::GetCPUAllocator() 的符号是 _ZN3c1015GetCPUAllocatorEv,其中 3c10 就是命名空间留下的全部痕迹。运行时没有”命名空间”这种对象可以查询或遍历。

与 Java 对照:package 与文件、目录

Java 的一个源文件只能有一条 package 声明,class 文件必须放在与包名对应的目录下,否则类加载器找不到它。C++ 的 namespace 是一个可以随处打开的代码块,和文件路径没有任何约束关系:#include <c10/core/Device.h> 里的 c10/ 是头文件搜索路径下的目录,c10::Device 里的 c10:: 是命名空间,两者同名只是 PyTorch 的约定。

与 Java 对照:名字在运行时还在不在

Java 的全限定类名是运行时身份的一部分:Class.getName() 能拿到,Class.forName("com.foo.Bar") 能按名字加载,反射可以列出成员。C++ 的命名空间编译完只剩符号名前缀,没有按名字加载或枚举的运行时入口;PyTorch 要”按名字找到算子”,靠的是自己建的注册表(《宏、静态注册与代码生成》)。

匿名命名空间(上篇第四章)是 Java 完全没有的:它的目的不是组织名字,而是控制链接属性。

2. 三个命名空间对应三个层次

PyTorch 的 C++ 源码分三层,每层一个主命名空间、一个主目录、一个(或一组).so:

PyTorch 的三个命名空间、目录与库
命名空间 目录 库 职责 典型类型
c10:: c10/ libc10.so(CUDA 部分 libc10_cuda.so) 最底层的核心抽象:Tensor 的元数据实现、设备、dtype、分配器、Dispatcher 的键、智能指针、错误处理。不依赖任何算子,不知道 add 是什么 c10::TensorImpl、c10::StorageImpl、c10::Device、c10::ScalarType、c10::intrusive_ptr、c10::DispatchKey、c10::Error
at:: aten/src/ATen/ libtorch_cpu.so(CUDA 部分 libtorch_cuda.so) “A Tensor library”:Tensor 句柄类、所有算子(at::add、at::empty_like)、Dispatcher 本体、CPU/CUDA kernel at::Tensor、at::TensorIterator、at::native::*、at::parallel_for、at::Dispatcher(实际定义在 c10:: 里,at:: 有别名)
torch:: torch/csrc/ libtorch_cpu.so(Python 无关部分)+ libtorch_python.so(Python 绑定) 面向用户的 C++ API(torch::nn、torch::optim)、Autograd 引擎、JIT、分布式、Python 绑定 torch::Tensor(就是 at::Tensor)、torch::autograd::Node、torch::jit::Graph、torch::Library

名字里的历史:c10 是 “Caffe2 + ATen → C-ten” 的谐音(Caffe2 是 PyTorch 1.0 时期合并进来的另一个框架),caffe2/CMakeLists.txt 这个文件名也是那时留下的——今天它是构建 libtorch_cpu.so 的主 CMake 文件,和 Caffe2 框架已经没有关系。

依赖方向是单向的:torch:: 依赖 at:: 依赖 c10::。c10/CMakeLists.txt 开头的注释说得很直接:

# Main build file for the C10 library.
#
# Note that the C10 library should maintain minimal dependencies - especially,
# it should not depend on any library that is implementation specific or
# backend specific. It should in particular NOT be dependent on any generated
# protobuf header files, because protobuf header files will transitively force
# one to link against a specific protobuf version.

3. torch:: 如何”包含”at::

读 libtorch C++ 代码时会看到 torch::Tensor、torch::ones、torch::kFloat,读 ATen 代码时看到的是 at::Tensor、at::ones、at::kFloat。它们是同一个东西。torch/csrc/api/include/torch/types.h:

namespace torch {

// NOTE [ Exposing declarations in `at::` to `torch::` ]
//
// The following line `using namespace at;` is responsible for exposing all
// declarations in `at::` namespace to `torch::` namespace.
//
// ...
// This means that if both `at::` and `torch::` namespaces have a function with
// the same signature (e.g. both `at::func()` and `torch::func()` exist), after
// `namespace torch { using namespace at; }`, when we call `torch::func()`, the
// `func()` function defined in `torch::` namespace will always be called, and
// the `func()` function defined in `at::` namespace is always hidden.
using namespace at; // NOLINT

// ...

using Dtype = at::ScalarType;

/// Fixed width dtypes.
constexpr auto kUInt8 = at::kByte;
constexpr auto kInt8 = at::kChar;
// ...
constexpr auto kFloat32 = at::kFloat;
constexpr auto kFloat64 = at::kDouble;

namespace torch { using namespace at; } 让所有 at:: 里的名字可以通过 torch:: 找到。注释解释了一个微妙之处:如果 torch:: 自己也定义了同名函数,torch::func() 优先——这被用来让 torch::ones(...) 指向 torch/csrc/autograd/generated/variable_factories.h 里带 Autograd 支持的版本,而不是 at::ones。这是 using namespace 作为接口分层手段的用法。

与 Java 对照:import 与 using 指令

Java 的 import 和 C++ 的 using 都只在编译期简化名字,但 import 的效果只限于写它的那个源文件,别的文件不会因此”通过你的包”看到那些类。namespace torch { using namespace at; } 写在头文件里,改的是 torch 这个命名空间的查找规则:任何包含这个头文件的代码写 torch::Tensor,在 torch:: 里找不到同名声明时就会继续到 at:: 里找。Java 没有把一个包的全部名字再经另一个包暴露出去的手段,只能逐个写转发类或转发方法。

类似地,c10/core/DeviceType.h 末尾:

namespace torch {
// NOLINTNEXTLINE(misc-unused-using-decls)
using c10::DeviceType;
} // namespace torch

以及 torch/csrc/autograd/variable.h 里 using Variable = at::Tensor;——早年 Variable 和 Tensor 是两个类,合并后留下这个别名。读老代码看到 Variable 就当 Tensor。

4. 其他常见子命名空间

其他常见子命名空间
命名空间 含义
at::native:: 算子的”原生”实现(aten/src/ATen/native/),即 native_functions.yaml 里 dispatch: 指向的函数
at::cuda::、c10::cuda:: CUDA 相关(stream、guard、allocator)
c10::impl::、at::impl::、torch::detail:: 实现细节,用户不应直接依赖
torch::autograd:: Autograd 引擎
torch::jit:: TorchScript
torch::nn::、torch::optim::、torch::data:: C++ 前端
torch::headeronly:: 2.x 新增,不依赖 libtorch 的纯头文件工具(torch/headeronly/)
torch::stable:: 2.x 新增的稳定 ABI 层(torch/csrc/stable/),供扩展跨 PyTorch 版本使用;vLLM 0.15 尚未使用

vLLM 的 csrc/ 没有自己的顶层命名空间约定,大部分 kernel 直接写在 namespace vllm { ... } 里,调用 PyTorch 时用 torch::Tensor。

5. 一个命名空间可以横跨多个库

命名空间和库没有对应关系,这一点必须明确。torch:: 命名空间里的 torch::autograd::Engine 在 libtorch_cpu.so(torch/csrc/autograd/engine.cpp 在 build_variables.bzl 的 libtorch_core_sources 列表里),而 torch::autograd::PyNode 在 libtorch_python.so(torch/csrc/autograd/python_function.cpp 在 libtorch_python_core_sources 里)。同一个目录 torch/csrc/autograd/、同一个命名空间,两个库。区分它们的规则是是否 #include <Python.h>:碰 Python 对象的进 libtorch_python.so,不碰的进 libtorch_cpu.so。torch/csrc/README.md 开头一句话说明了这个分界:

The csrc directory contains all of the code concerned with integration
with Python.  This is in contrast to lib, which contains the Torch
libraries that are Python agnostic.  csrc depends on lib, but not vice
versa.

(这段话是老的:如今 torch/csrc/ 里也有大量 Python 无关代码,但”Python 相关依赖 Python 无关,反之不成立”这条原则没变。)

与 Java 对照:名字找不到对应的库时

Java 的一个包也可以分散在 classpath 上的几个 jar 里(JPMS 模块才禁止),所以”命名空间横跨多个库”本身并不陌生。不同的是后果出现的位置:Java 代码只写类名,少放一个 jar 要到运行时首次用到那个类才报 NoClassDefFoundError;C++ 在链接时就必须为每个符号指明库,用了 torch::autograd::PyNode 却只链了 -ltorch_cpu,得到的是链接期的 undefined reference。所以读 PyTorch 代码要多记一件 Java 里不用记的事:这个名字的定义编进了哪个 .so。

三、PyTorch 的源码布局与库布局

1. 目录 → 库

%% 图:PyTorch 源码目录到 torch/lib 里的 .so:实线是编进哪个库,虚线是库依赖哪个库
flowchart TD
    subgraph SRC[源码目录]
        C10[c10/]
        ATEN[aten/src/ATen/]
        CSRC_CPP[torch/csrc/ 中不含 Python.h 的部分<br/>autograd 引擎、jit、api/、distributed 核心]
        CSRC_PY[torch/csrc/ 中含 Python.h 的部分<br/>Module.cpp、autograd/python_*.cpp、utils/pybind.h]
        STUB[torch/csrc/stub.c]
    end
    subgraph LIB[torch/lib/ 里的 .so]
        LC10[libc10.so]
        LC10CUDA[libc10_cuda.so]
        LCPU[libtorch_cpu.so]
        LCUDA[libtorch_cuda.so]
        LTORCH[libtorch.so<br/>空壳,只有 DT_NEEDED]
        LPY[libtorch_python.so]
        LGD[libtorch_global_deps.so<br/>空壳,只有 DT_NEEDED]
    end
    CEXT[torch/_C.cpython-*.so]
    C10 --> LC10
    C10 -->|c10/cuda/| LC10CUDA
    ATEN --> LCPU
    ATEN -->|aten/src/ATen/cuda/、native/cuda/| LCUDA
    CSRC_CPP --> LCPU
    CSRC_PY --> LPY
    STUB --> CEXT
    LC10CUDA -.->|NEEDED| LC10
    LCPU -.->|NEEDED| LC10
    LCUDA -.->|NEEDED| LCPU
    LCUDA -.->|NEEDED| LC10CUDA
    LTORCH -.->|NEEDED| LCPU
    LTORCH -.->|NEEDED| LCUDA
    LPY -.->|NEEDED| LTORCH
    CEXT -.->|NEEDED| LPY

实线是”源码编进哪个库”,虚线是”库依赖哪个库”(DT_NEEDED)。图中省略了 libshm.so(torch/lib/libshm/,共享内存管理,libtorch_python.so 依赖它)以及 MKL、OpenMP、cudart、cuDNN、NCCL 等第三方库。

与 Java 对照:目录与构建产物

Maven / Gradle 的惯例是一个模块目录(带一份 pom.xml 或 build.gradle)产出一个 jar,看目录树基本就知道有哪些产物。CMake 的产物由 add_library 的源文件清单定义,清单可以来自任何目录:图里 aten/ 与 torch/csrc/ 的一部分合进同一个 libtorch_cpu.so,torch/csrc/ 自己又被拆进两个库,而 aten/src/ATen/CMakeLists.txt 只把 ATen 的源文件收进 ATen_CPU_SRCS 交给上层,torch_cpu 这个库定义在 caffe2/CMakeLists.txt 里。判断一个 .cpp 进哪个库,要看哪个 target 的清单里有它,不能看它在哪个目录。

2. 用 CMake 实现这张图

上图的两种箭头各对应一条 CMake 命令:add_library(库名 源文件清单) 画实线,target_link_libraries(库 关键字 被依赖的库) 画虚线。下面用一个只有五个源文件的小工程,把图里出现的每一种情况都做一遍。

layers/
├── CMakeLists.txt
├── base/device.cpp     # base::device_name():返回 "cpu"
├── ops/add.cpp         # ops::add(a, b)
├── front/engine.cpp    # front::run():调用上面两个函数
├── front/bind.cpp      # front::print_result():打印 run() 的结果
└── main.cpp            # main():只调用 front::print_result()

每个 .cpp 旁边有一个同名的 .h,里面只有一行声明。

五个源文件和四个头文件的完整内容
// ---- base/device.h ----
#pragma once
#include <string>
namespace base { std::string device_name(); }

// ---- base/device.cpp ----
#include <base/device.h>
namespace base { std::string device_name() { return "cpu"; } }

// ---- ops/add.h ----
#pragma once
namespace ops { int add(int a, int b); }

// ---- ops/add.cpp ----
#include <ops/add.h>
namespace ops { int add(int a, int b) { return a + b; } }

// ---- front/engine.h ----
#pragma once
#include <string>
namespace front { std::string run(); }

// ---- front/engine.cpp ----
#include <front/engine.h>
#include <base/device.h>
#include <ops/add.h>
namespace front {
std::string run() {
  return "1 + 2 = " + std::to_string(ops::add(1, 2)) + " on " + base::device_name();
}
}

// ---- front/bind.h ----
#pragma once
namespace front { void print_result(); }

// ---- front/bind.cpp ----
#include <front/bind.h>
#include <front/engine.h>
#include <iostream>
namespace front { void print_result() { std::cout << run() << '\n'; } }

// ---- main.cpp ----
#include <front/bind.h>
int main() { front::print_result(); }

整个构建规则是一份二十来行的 CMakeLists.txt:

cmake_minimum_required(VERSION 3.18)
project(layers CXX)
set(CMAKE_CXX_STANDARD 17)
set(BUILD_SHARED_LIBS ON)

add_library(base base/device.cpp)
target_include_directories(base PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})

add_library(core ops/add.cpp front/engine.cpp)
target_link_libraries(core PUBLIC base)

file(WRITE ${CMAKE_BINARY_DIR}/empty.cpp "")
add_library(shell ${CMAKE_BINARY_DIR}/empty.cpp)
target_link_libraries(shell PUBLIC core)

add_library(binding front/bind.cpp)
target_include_directories(binding PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
target_link_libraries(binding PRIVATE shell)

add_executable(app main.cpp)
target_link_libraries(app PRIVATE binding)

把这份文件画出来,每条边上标的是产生它的那条命令:

%% 图:小工程 layers:每条边由哪一条 CMake 命令产生
flowchart TD
    subgraph SRC["源码目录"]
        F1["base/device.cpp"]
        F2["ops/add.cpp"]
        F3["front/engine.cpp"]
        F4["front/bind.cpp"]
        F5["main.cpp"]
    end
    subgraph OUT["build/ 里的产物"]
        L1["libbase"]
        L2["libcore"]
        L3["<b>libshell</b><br/>空壳,没有符号"]
        L4["libbinding"]
        APP["app"]
    end
    F1 -->|"add_library(base …)"| L1
    F2 -->|"add_library(core …)"| L2
    F3 -->|"add_library(core …)"| L2
    F4 -->|"add_library(binding …)"| L4
    F5 -->|"add_executable(app …)"| APP
    L2 -.->|"core PUBLIC base"| L1
    L3 -.->|"shell PUBLIC core"| L2
    L4 -.->|"binding PRIVATE shell"| L3
    APP -.->|"app PRIVATE binding"| L4

图里的五种情况:

  1. 一个目录编成一个库:add_library(base …) 的清单里只有 base/ 的文件。库里有什么只由这份清单决定;BUILD_SHARED_LIBS ON 让没写 SHARED / STATIC 的库都编成动态库。
  2. 两个目录合进一个库:add_library(core …) 的清单里一个文件来自 ops/,一个来自 front/。
  3. 一个目录拆进两个库:front/ 的另一个文件写在 add_library(binding …) 的清单里,于是 front:: 这一个命名空间也横跨了两个库。
  4. 库依赖库:target_link_libraries(core PUBLIC base) 让链接 libcore 的命令带上 libbase,这条依赖被记进 libcore 的依赖表(Linux 上就是 DT_NEEDED)。
  5. 空壳:shell 的源文件是一个空文件,库里没有任何符号,只有一条对 core 的依赖。

配置、构建、运行:

cmake -S . -B build
cmake --build build
./build/app

在一台 Intel Mac(macOS 12.7、Apple clang 14、CMake 4.4)上实际运行,app 输出 1 + 2 = 3 on cpu。再看每个产物记录的依赖(macOS 的 otool -L 相当于 Linux 的 ldd;下面删掉了系统库和每个库自己的名字,也删掉了行尾的版本号):

$ otool -L build/libcore.dylib
	@rpath/libbase.dylib
$ otool -L build/libshell.dylib
	@rpath/libcore.dylib
	@rpath/libbase.dylib
$ otool -L build/libbinding.dylib
	@rpath/libshell.dylib
	@rpath/libcore.dylib
	@rpath/libbase.dylib
$ otool -L build/app
	@rpath/libbinding.dylib
$ nm -g build/libshell.dylib
libshell.dylib: no symbols

依赖表和图上的虚线一一对上,libshell 确实一个符号都没有。libshell、libbinding 的依赖表比 CMakeLists.txt 里写的多出几行,app 却只有一行,原因在下一节。

PyTorch 的库布局就是这个小工程放大几千倍:

小工程 layers 与 PyTorch 库布局的对应
小工程 PyTorch 情况
base/ → libbase c10/ → libc10.so 一个目录一个库(c10/cuda/ 不在清单里,另编成 libc10_cuda.so)
ops/ + front/engine.cpp → libcore aten/ + torch/csrc/ 里不含 Python.h 的部分 → libtorch_cpu.so 两个目录合进一个库
front/bind.cpp → libbinding torch/csrc/ 里含 Python.h 的部分 → libtorch_python.so 一个目录拆进两个库
libshell libtorch.so 空壳:下游只写一个 -ltorch,就同时拿到 libtorch_cpu.so 和 libtorch_cuda.so,不用关心装的是哪种 build
main.cpp → app stub.c → torch/_C.cpython-*.so 只依赖最上层的一个库

3. 依赖怎么传给下游:PUBLIC 与 PRIVATE

构建 layers 时加 VERBOSE=1(cmake --build build -- VERBOSE=1),能看到 CMake 实际发出的链接命令。下面是其中两条,删掉了与依赖无关的参数:

c++ -dynamiclib -o libbinding.dylib bind.cpp.o  libshell.dylib libcore.dylib libbase.dylib
c++ main.cpp.o -o app  libbinding.dylib

CMakeLists.txt 里 binding 只写了 shell,命令里却有三个库;app 写了 binding,命令里只有一个。规则是:一个 target 的 PUBLIC 依赖会传给链接它的下游,PRIVATE 依赖不传。

  • binding 链接 shell,shell PUBLIC core、core PUBLIC base 一路传上来,所以 binding 的命令里是三个库。
  • app 链接 binding,而 binding PRIVATE shell 到此为止,所以 app 的命令里只有 libbinding。

把这一个关键字改掉再构建一次:

binding 对 shell 的依赖从 PRIVATE 改成 PUBLIC 前后,app 链接了哪些库(实测)
binding 对 shell 的关键字 app 的链接命令里的库 otool -L build/app 里的库
PRIVATE(上面的写法) libbinding libbinding
改成 PUBLIC libbinding、libshell、libcore、libbase 同左,四个

传下去的不只是链接项,还有头文件搜索路径和编译定义。base 的 target_include_directories(… PUBLIC …) 沿 PUBLIC 边传给了 core、shell、binding,它们都不用再写;传到 app 之前被 PRIVATE 挡住,所以 binding 自己又声明了一次。去掉那一行,main.cpp 就编不过:

main.cpp:1:10: error: 'front/bind.h' file not found with <angled> include; use "quotes" instead

关键字一共三个,区别只在两个问题上:

target_link_libraries 三个关键字的传播规则
关键字 构建本目标时使用 传给链接本目标的下游 PyTorch 里的例子
PRIVATE 是 否
  • c10 PRIVATE fmt::fmt-header-only
  • torch_python PRIVATE ${TORCH_LIB}
INTERFACE 否 是
  • torch_cuda INTERFACE torch::cudart
  • add_library(headeronly INTERFACE ...)(整个库没有自己要编的东西)
PUBLIC 是 是
  • c10 PUBLIC headeronly
  • torch_cpu PUBLIC c10

关键字只管构建期,不管加载期。 app 的依赖表里只有 libbinding,运行时四个库照样全部加载,因为动态加载器会沿每个库自己的依赖表递归下去:

dyld[26693]: layers/build/app
dyld[26693]: layers/build/libbinding.dylib
dyld[26693]: layers/build/libshell.dylib
dyld[26693]: layers/build/libcore.dylib
dyld[26693]: layers/build/libbase.dylib
1 + 2 = 3 on cpu

(只留了 layers 自己的库,删掉了每行的 UUID 和路径前缀。Linux 上对应的是 LD_DEBUG=libs ./build/app。)

三个关键字的完整语义在《构建、调试与测试工具链》。

与 Java 对照:target 传播与 Maven / Gradle 的依赖范围

最接近的是 Gradle java-library 插件的 api(≈ PUBLIC)与 implementation(≈ PRIVATE):都在回答”我的依赖要不要出现在使用者的编译环境里”。Maven 的 compile / provided / runtime / test 划分的是另一件事:依赖在哪个阶段的 classpath 上。套用时有三处对不上:

  Maven / Gradle CMake target
传播的内容 构件(jar)本身 链接项,加上头文件搜索路径、编译定义、编译选项
依赖从哪来 按坐标和版本从仓库下载,冲突时做版本仲裁 不下载、不仲裁:target 必须已在本工程里定义,或由 find_package 从已安装的位置找到
运行期是否需要 由 scope 决定是否进运行时 classpath 与关键字无关:PRIVATE 链接的动态库照样记进依赖表,加载时照样要找到

4. import torch 时加载了什么

%% 图:import torch 的加载时序
sequenceDiagram
    participant PY as Python 解释器
    participant LD as ld.so
    participant CEXT as torch/_C.*.so
    participant LPY as libtorch_python.so
    PY->>LD: dlopen libtorch_global_deps.so,RTLD_GLOBAL
    Note over LD: 递归加载 DT_NEEDED:MKL、OpenMP、CUDA runtime
    PY->>LD: dlopen torch/_C.*.so,RTLD_LOCAL
    Note over LD: 按 RPATH $ORIGIN/lib 递归加载<br/>libtorch_python → libtorch → libtorch_cpu、libtorch_cuda → libc10、libc10_cuda、libshm
    LD->>LPY: 运行各库的静态初始化(算子注册进 Dispatcher)
    LD-->>PY: 返回 _C 的句柄
    PY->>CEXT: dlsym PyInit__C 并调用
    CEXT->>LPY: initModule()
    LPY-->>PY: torch._C 模块对象

torch/__init__.py 里有两次 dlopen,分工不同:

  1. 第一次(_load_global_deps()):以 RTLD_GLOBAL 加载空壳 libtorch_global_deps.so,只为把 MKL、OpenMP、CUDA runtime 这些第三方库放进全局符号空间。
  2. 第二次(from torch._C import *):以 RTLD_LOCAL 加载 _C,PyTorch 自己的库全部挂在它的依赖链上,和小工程里 app 拉起四个库是同一件事。

静态初始化发生在第二次 dlopen 返回之前,几千个算子就在这时注册进 Dispatcher(《宏、静态注册与代码生成》),所以 PyInit__C 被调用时算子已经注册完。

在一台装了 CPU wheel 的 Linux 机器上可以这样验证:

cd $(python -c 'import torch, os; print(os.path.dirname(torch.__file__))')
ls lib/
ldd _C.cpython-*.so
ldd lib/libtorch_python.so | grep torch
readelf -d lib/libtorch.so | grep NEEDED

在一份 macOS 的 CPU wheel(torch==2.14.0)上实际看到的(ldd 换成 otool -L;Linux 上文件名是 .so、ldd 会直接印出解析后的绝对路径,其余相同):

$ ls lib/
libc10.dylib  libomp.dylib  libshm.dylib  libtorch.dylib  libtorch_cpu.dylib
libtorch_global_deps.dylib  libtorch_python.dylib

$ otool -L _C.cpython-312-darwin.so
	@loader_path/lib/libtorch_python.dylib
	/usr/lib/libSystem.B.dylib

$ otool -L lib/libtorch_python.dylib | grep -E 'torch|c10|shm'
	@loader_path/libtorch.dylib
	@loader_path/libshm.dylib
	@loader_path/libtorch_cpu.dylib
	@loader_path/libc10.dylib

$ otool -L lib/libtorch.dylib | grep -E 'torch|c10'
	@loader_path/libtorch_cpu.dylib
	@loader_path/libc10.dylib

$ nm -C _C.cpython-312-darwin.so | grep -E 'PyInit|initModule'
0000000000000d48 T _PyInit__C
                 U _initModule

三段 otool -L 和小工程的输出是同一个形状:

PyTorch wheel 与小工程 layers 的依赖表对照
PyTorch wheel 依赖表里的库 小工程里的对应
_C 只有 libtorch_python app 只有 libbinding
libtorch_python libtorch、libtorch_cpu、libc10(另有 libshm) libbinding 有 libshell、libcore、libbase
libtorch(空壳) libtorch_cpu、libc10 libshell 有 libcore、libbase

_C 的符号表里只有一个定义 PyInit__C 和一个引用 initModule,就是 stub.c 那 15 行。@loader_path/lib 是 macOS 上的 $ORIGIN/lib(上篇「搜索路径」一节)。CUDA wheel 会多出 libtorch_cuda.so、libc10_cuda.so,以及指向独立的 nvidia-*-cu12 包的 libcudart.so.12 等条目。

5. 自定义扩展链接到哪一个

一个 C++ 扩展(用 torch.utils.cpp_extension 编出来的 .so)会引用四类符号:

C++ 扩展引用的四类符号所在的库
用到的东西 符号在哪个库 需要的 -l
c10::Device、c10::intrusive_ptr、TORCH_CHECK 抛的 c10::Error libc10.so -lc10
at::Tensor 的方法、at::empty_like、at::parallel_for、torch::Library(TORCH_LIBRARY 宏) libtorch_cpu.so -ltorch_cpu(或 -ltorch 间接)
CUDA stream、c10::cuda::CUDAGuard libc10_cuda.so、libtorch_cuda.so -lc10_cuda -ltorch_cuda
pybind11 的 at::Tensor 类型转换器、THPVariable_Wrap libtorch_python.so -ltorch_python

torch/utils/cpp_extension.py 的 CppExtension 函数替你把前两类和第四类加上(CUDAExtension 再加 cudart、c10_cuda、torch_cuda):

    libraries = kwargs.get('libraries', [])
    libraries.append('c10')
    libraries.append('torch')
    libraries.append('torch_cpu')
    if not kwargs.get('py_limited_api', False):
        # torch_python uses more than the python limited api
        libraries.append('torch_python')

torch_python 是有条件的:扩展声明了 py_limited_api=True(只用 Python 稳定 ABI,一个 .so 能跑在多个 Python 版本上)就不能链接 libtorch_python.so,因为后者用了非稳定 API。代价是扩展里不能用 pybind11 的 at::Tensor 转换器,只能用 TORCH_LIBRARY 注册算子、由 torch.ops 调用。

vLLM 走的就是这条路。它的 CMakeLists.txt 先 find_package(Torch REQUIRED),在 wheel 的 share/cmake/ 下找到 TorchConfig.cmake,得到导入目标 torch;然后 cmake/utils.cmake 的 define_extension_target 只链接这一个目标:

  Python_add_library(${MOD_NAME} MODULE USE_SABI ${ARG_USE_SABI} ${SOABI_KEYWORD} "${ARG_SOURCES}")
  # ...
  target_link_libraries(${MOD_NAME} PRIVATE torch ${ARG_LIBRARIES})

torch 的 PUBLIC 依赖把 libtorch_cpu.so、libtorch_cuda.so、libc10.so 带进来,libtorch_python.so 不在其中。所以 vLLM 的 _C.abi3.so 和 PyTorch 的交互只有 TORCH_LIBRARY 注册算子这一条路(《与 Python 之间》)。

PyTorch 2.8 之后还多了一个不产生 .so 的层 torch/headeronly/:它是一个只有头文件的 INTERFACE 库,扩展可以在不链接任何 PyTorch 库的前提下使用其中的 ScalarType、Half 等工具。

四、回到源码

小工程的每一条命令,在 PyTorch 的 CMake 文件里都有对应的一行。本章先把它们对上,再看 CMake 之外的两样东西:_C 怎么编出来,这些 .so 怎么进 wheel。

1. 小工程的每条命令在 PyTorch 里的写法

小工程 layers 的每条命令在 PyTorch 里的写法
小工程 PyTorch v2.10.0 的写法 所在文件
add_library(base base/device.cpp) add_library(c10 ${C10_SRCS} ${C10_HEADERS}) c10/CMakeLists.txt
add_library(core ops/add.cpp front/engine.cpp) add_library(torch_cpu ${Caffe2_CPU_SRCS}) caffe2/CMakeLists.txt
target_link_libraries(core PUBLIC base) target_link_libraries(torch_cpu PUBLIC c10) caffe2/CMakeLists.txt
  • add_library(shell empty.cpp)
  • target_link_libraries(shell PUBLIC core)
  • add_library(torch ${DUMMY_EMPTY_FILE})
  • target_link_libraries(torch PUBLIC torch_cpu_library)
  • CUDA 构建再加 torch_cuda_library
caffe2/CMakeLists.txt
add_library(binding front/bind.cpp) add_library(torch_python SHARED ${TORCH_PYTHON_SRCS}) torch/CMakeLists.txt
target_link_libraries(binding PRIVATE shell)
  • target_link_libraries(torch_python PRIVATE ${TORCH_LIB} ${TORCH_PYTHON_LINK_LIBRARIES})
  • ${TORCH_LIB} 就是 torch
torch/CMakeLists.txt
target_include_directories(base PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}) target_include_directories(c10 PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../> ...) c10/CMakeLists.txt

caffe2/CMakeLists.txt 这个文件名是 PyTorch 合并 Caffe2 时留下的,今天它是 libtorch_cpu.so 的主构建脚本。PyTorch 比小工程多出来的是四样:

  1. 源文件清单不是手写的。 c10 用 file(GLOB C10_SRCS *.cpp core/*.cpp util/*.cpp …) 按通配符收集,c10/cuda/ 不在通配符里,所以它是另一个库。torch_cpu 与 torch_python 的清单来自 build_variables.bzl 里的 libtorch_cmake_sources 和 libtorch_python_core_sources,再加上 ATen 的源文件和 torchgen 生成的代码。
  2. 头文件路径是源码树根。 表里最后一行的 /../ 指向 c10/ 的父目录,所以 PyTorch 所有 #include 都从仓库根写起:#include <c10/core/Device.h>。
  3. 只导出标了宏的符号。 每个库编译自己的源文件时加 -fvisibility=hidden 和一个 PRIVATE 的宏定义(c10 是 -DC10_BUILD_MAIN_LIB,torch_cpu 是 CAFFE2_BUILD_MAIN_LIB,torch_python 是 THP_BUILD_MAIN_LIB),让 C10_API / TORCH_API / TORCH_PYTHON_API 在库内展开成导出(上篇「符号可见性」一节)。
  4. 语言标准写死 C++17。 c10/CMakeLists.txt 与顶层 CMakeLists.txt 都是 set(CMAKE_CXX_STANDARD 17 ...),torch/utils/cpp_extension.py 给扩展传的也是 -std=c++17,vLLM v0.15.0 同样。编译扩展时的 -std= 要跟 PyTorch 保持一致。

把三个文件里的 target_link_libraries 画在一张图上(CUDA build;箭头从依赖者指向被依赖者):

%% 图:PyTorch 各 CMake target 之间的 PUBLIC 与 PRIVATE 依赖
flowchart TB
    CEXT["<b>torch._C</b><br/>setuptools Extension,不是 CMake target"]
    TPY["<b>torch_python</b><br/>SHARED"]
    PYDEPS["Python::Module、pybind::pybind11、shm 等"]
    TORCH["<b>torch</b><br/>空壳"]
    TCUDA["torch_cuda"]
    TCPU["torch_cpu"]
    C10CUDA["c10_cuda"]
    C10["c10"]
    HO["<b>headeronly</b><br/>INTERFACE 库,只有头文件"]
    C10PRIV["fmt、nlohmann、moodycamel、dl"]
    CEXT -.->|"libraries=#91;torch_python#93;"| TPY
    TPY -.->|PRIVATE| TORCH
    TPY -.->|PRIVATE| PYDEPS
    TORCH ==>|PUBLIC| TCUDA
    TORCH ==>|PUBLIC| TCPU
    TCUDA ==>|PUBLIC| TCPU
    TCUDA ==>|PUBLIC| C10CUDA
    TCPU ==>|PUBLIC| C10
    C10CUDA ==>|PUBLIC| C10
    C10 ==>|PUBLIC| HO
    C10 -.->|PRIVATE| C10PRIV

粗实线是 PUBLIC,虚线是 PRIVATE,读法和小工程一样:从任何一个 target 出发,沿粗实线能走到的都会自动进入下游的链接命令和头文件搜索路径,到虚线为止。链接 torch 的扩展不用再写 torch_cpu、c10;fmt 不会出现在 torch_cpu 的使用者那里;torch._C 的链接命令里只有 -ltorch_python。(torch → torch_cpu、torch_cuda 等三条边在源码里经过 torch_cpu_library、torch_cuda_library 两个接口目标,图里合并到了真实的库上。)

2. stub.c 与 setup.py:_C 是怎么编出来的

_C 是 PyTorch 里唯一不由 CMake 编译的二进制。它写在 setup.py 的 configure_extension_build() 里,是一个 setuptools 的 Extension:

    main_libraries: list[str] = ["torch_python"]
    main_sources: list[str] = ["torch/csrc/stub.c"]
    # ...
    C = Extension(
        "torch._C",
        libraries=main_libraries,
        sources=main_sources,
        language="c",
        # ...
        library_dirs=library_dirs,
        extra_link_args=[
            *extra_link_args,
            *main_link_args,
            *make_relative_rpath_args("lib"),
        ],
    )

翻译成编译命令就是:用 C 编译器编 stub.c,-L torch/lib -ltorch_python,再加 -Wl,-rpath,$ORIGIN/lib,产物自动带上 .cpython-312-x86_64-linux-gnu 这样的后缀。相当于小工程里的 add_executable(app main.cpp) 加 target_link_libraries(app PRIVATE binding)。

现在回到开头的 stub.c,每一行都能解释了:

#include <Python.h>                         // PyObject、PyMODINIT_FUNC 的声明

extern PyObject* initModule(void);          // 声明:定义在 libtorch_python.so 的 Module.cpp 里,
                                            // 那边用 extern "C" 保证符号名就是 initModule

#ifndef _WIN32                              // 预处理:非 Windows 才需要显式 visibility
#ifdef __cplusplus                          // 预处理:如果被当 C++ 编译(实际是 .c,不会)
extern "C"
#endif
__attribute__((visibility("default"))) PyObject* PyInit__C(void);   // 声明并标记导出
#endif

PyMODINIT_FUNC PyInit__C(void)              // 定义:Python 解释器 dlsym 的入口
{
  return initModule();                      // 转发。链接期解析到 libtorch_python.so 的 initModule
}

为什么要一个 stub,而不是把 libtorch_python.so 直接当成 _C?两个文件名的要求冲突:

_C 与 libtorch_python.so 对文件名的不同要求
文件 文件名的要求 放在哪
Python 扩展模块 必须带 ABI tag:_C.cpython-312-x86_64-linux-gnu.so 包目录 torch/
供其他 C++ 扩展链接的库 要一个稳定的名字:libtorch_python.so,才能写 -ltorch_python torch/lib/

一个 15 行的 stub 把两个要求分开:它叫 _C.cpython-*.so,里面只有一条到 libtorch_python.so 的转发。

3. 从 setup.py 到 wheel 再到下游扩展

setup.py 分两步:先调 build_deps() 运行 CMake,把所有库编好并安装到 torch/ 下;再交给 setuptools 编上一节的 _C,并按 package_data 把文件打进 wheel。

%% 图:从 setup.py 到 wheel 再到下游扩展的构建流水线
flowchart TB
    CM["<b>setup.py 第一步:build_deps()</b><br/>运行 CMake,构建并安装到 torch/ 下"]
    WINC["<b>torch/include/</b><br/>c10/、ATen/、torch/ 的头文件"]
    WLIB["<b>torch/lib/</b><br/>• libc10.so、libtorch_cpu.so、libtorch.so<br/>• libtorch_python.so"]
    WCM["<b>torch/share/cmake/</b><br/>• Torch/TorchConfig.cmake<br/>• Caffe2/Caffe2Config.cmake<br/>• Caffe2/Caffe2Targets.cmake"]
    EXT["<b>setup.py 第二步:setuptools build_ext</b><br/>cc stub.c -L torch/lib -ltorch_python<br/>加上 -Wl,-rpath,$ORIGIN/lib"]
    WC["<b>torch/_C.cpython-*.so</b><br/>和上面三个目录一起打进 wheel"]
    CPPEXT["<b>torch.utils.cpp_extension</b><br/>-I include、-L lib、-lc10 -ltorch ..."]
    VLLM["<b>下游 CMake(vLLM)</b><br/>find_package(Torch) 得到导入目标 torch"]
    CM -->|"install(DIRECTORY ...)"| WINC
    CM -->|"install(TARGETS ...)"| WLIB
    CM -->|"install(EXPORT Caffe2Targets)"| WCM
    WLIB -.->|"先装好,第二步才能链接"| EXT
    EXT --> WC
    WINC --> CPPEXT
    WLIB --> CPPEXT
    WLIB --> VLLM
    WCM --> VLLM
    classDef wheel fill:#fff7e0,stroke:#c9a227
    class WINC,WLIB,WCM,WC wheel

黄色的四个框是最终进 wheel 的内容,图里有三件事:

  1. 两步有先后。 CMake 先把库装进 torch/lib/,setuptools 才能拿 -ltorch_python 去链接 _C(虚线)。
  2. CMake 的 install 命令决定三个目录里有什么。 以 c10 为例:install(TARGETS c10 EXPORT Caffe2Targets DESTINATION lib) 把库装进 lib/,同时把 c10 这个 target 登记进导出集合 Caffe2Targets;install(DIRECTORY ... FILES_MATCHING PATTERN "*.h") 把头文件拷进 include/c10/。
  3. 下游有两个入口。 cpp_extension 直接用 include/ 和 lib/ 拼编译命令;CMake 项目读 share/cmake/,TorchConfig.cmake 经 Caffe2Targets.cmake 把 c10、torch_cpu、torch 这些 target 原样交给 vLLM 的 find_package(Torch)。

所以 site-packages/torch/ 是一份自带 include/、lib/、share/cmake/ 的完整 C++ SDK。任何扩展——不管用 torch.utils.cpp_extension、vLLM 那样的 CMake,还是上篇第七章手写的 g++——找的都是这三个目录。

两点补充:

  • setup.py 还支持把一个 wheel 拆成两个(环境变量 BUILD_LIBTORCH_WHL 与 BUILD_PYTHON_ONLY):libtorch.so 及其依赖打成不带 _C 的 torch_no_python,Python 部分打成另一个。
  • vLLM 的 setup.py 是这条流水线的下游:它调 CMake 构建自己的 _C.abi3.so,对 PyTorch 的依赖全部经 find_package(Torch) 解析,所以 vLLM 的 wheel 必须和特定的 PyTorch 版本配对(《与 Python 之间》)。

五、实践二:mini-c10 的目录结构与第一个可链接的库

mini-c10 是贯穿全系列的练手项目,模仿 c10/ 和 ATen Dispatcher 的核心结构。本篇只做三件事:建目录、写 CMake 骨架、编出第一个能被链接的 libminic10.so。后面每一篇往里加文件。

1. 目录结构

mini-c10/
├── CMakeLists.txt                # 本篇:骨架;《构建、调试与测试工具链》补 gtest、ASan
├── minic10/                      # 库:libminic10.so,namespace minic10
│   ├── core/
│   │   ├── Version.h             # 本篇:第一个符号
│   │   ├── Version.cpp
│   │   ├── Allocator.h           # 《值、引用与所有权》
│   │   ├── StorageImpl.h         # 《值、引用与所有权》
│   │   ├── TensorImpl.h          # 《值、引用与所有权》
│   │   ├── Tensor.h              # 《值、引用与所有权》
│   │   ├── ScalarType.h          # 《模板与泛型编程》
│   │   ├── Dispatch.h            # 《模板与泛型编程》
│   │   ├── DispatchKey.h         # 《多态与类型擦除》
│   │   └── GradMode.h            # 《并发、内存模型、TLS 与守卫》
│   ├── util/
│   │   ├── intrusive_ptr.h       # 《值、引用与所有权》
│   │   └── ArrayRef.h            # 《模板与泛型编程》
│   ├── macros/Macros.h           # 《宏、静态注册与代码生成》:MINI_API、MINI_CHECK、...
│   ├── dispatch/                 # 《多态与类型擦除》:KernelFunction.h、OperatorEntry.h、Dispatcher.h
│   ├── library.h                 # 《宏、静态注册与代码生成》:MINI_LIBRARY 宏
│   ├── Parallel.h                # 《并发、内存模型、TLS 与守卫》
│   └── ops/                      # 《模板与泛型编程》起:add.cpp、mul.cpp
├── examples/
│   └── hello.cpp                 # 本篇:链接 libminic10 的最小可执行文件
├── python/minic10_python.cpp     # 《与 Python 之间》
└── test/                         # 《构建、调试与测试工具链》

和 PyTorch 的三个维度逐项对照:

mini-c10 与 PyTorch 在目录、命名空间、库三个维度上的对应
维度 mini-c10 PyTorch
目录:核心抽象 minic10/ c10/ + aten/src/ATen/core/
目录:算子实现 minic10/ops/ aten/src/ATen/native/
目录:Python 绑定 python/ torch/csrc/ 中含 Python.h 的部分
命名空间 统一 minic10 c10 / at
库 一个 libminic10.so libc10.so + libtorch_cpu.so

mini-c10 把 PyTorch 的两层目录、两个命名空间、两个库压成了一层,只保留”头文件从根写起、Python 绑定单独放”这两条约定。头文件路径从项目根开始写(#include <minic10/core/Version.h>),和 PyTorch 的 #include <c10/core/Device.h> 同一个约定。

2. 第一个符号:Version.h / Version.cpp

内容在 上篇 2.1 节已经给出,这里解释设计上的四个选择,每个都对应本文的一个概念:

// minic10/core/Version.h
#pragma once                                  // 上篇 3.3 节:防止重复包含

#include <cstdint>
#include <string>

namespace minic10 {                           // 第二章:所有东西在 minic10:: 下

constexpr int kVersionMajor = 0;              // 上篇 4.3 节:constexpr 变量隐含 inline,
constexpr int kVersionMinor = 1;              //         放头文件不违反 ODR

std::string version_string();                 // 上篇 3.2 节:声明;定义在 Version.cpp,编进 .so

inline int version_number() {                 // 上篇 4.3 节:头文件里的函数定义必须 inline
  return kVersionMajor * 1000 + kVersionMinor;
}

} // namespace minic10
// minic10/core/Version.cpp
#include <minic10/core/Version.h>             // 先包含自己的头文件,保证声明与定义一致

namespace minic10 {

namespace {                                   // 上篇 4.4 节:内部链接,不导出,不与别的 .cpp 冲突
const char* build_flavor() {
#ifdef NDEBUG                                 // 上篇 2.2 节:预处理条件编译;CMake Release 构建定义 NDEBUG
  return "release";
#else
  return "debug";
#endif
}
} // namespace

std::string version_string() {                // 上篇 3.2 节:定义
  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';
  return 0;
}

”.cpp 第一行先包含自己的头文件”是 PyTorch 的惯例(c10/core/Device.cpp 第一行 #include <c10/core/Device.h>),目的是让编译器在编译 .cpp 时就能对照头文件里的声明检查签名——如果头文件里写 std::string version_string(); 而 .cpp 里写 const char* version_string(),编译期就报错,而不是等到链接期出现莫名的 undefined reference。

3. 手工走一遍四个阶段

在 mini-c10/ 目录下:

# 编译(预处理 + 编译 + 汇编):-fPIC 是动态库的要求,-I. 让 <minic10/...> 能找到
clang++ -std=c++17 -Wall -Wextra -fPIC -I. -c minic10/core/Version.cpp -o Version.o

# 链接成动态库
clang++ -std=c++17 -shared -o libminic10.so Version.o          # macOS 用 .dylib

# 编译并链接可执行文件
clang++ -std=c++17 -Wall -Wextra -I. examples/hello.cpp -L. -lminic10 -Wl,-rpath,'$ORIGIN' -o hello

./hello

以上命令用 Apple clang 21 在 macOS 上实际运行(把 .so 换成 .dylib、-Wl,-rpath,'$ORIGIN' 换成 DYLD_LIBRARY_PATH=.),-Wall -Wextra 无警告,输出:

mini-c10 0.1 (debug), number=1

再看符号(上篇 5.1 节给的是 Linux 的输出,这里是 macOS 的,去掉了 libc++ 的内部符号):

$ nm -C Version.o | grep minic10
0000000000000218 t minic10::(anonymous namespace)::build_flavor()
0000000000000000 T minic10::version_string()

$ nm -gC libminic10.dylib | grep minic10
0000000000000498 T minic10::version_string()

$ nm -C hello.o | grep minic10
0000000000000190 T minic10::version_number()
                 U minic10::version_string()

$ otool -L hello        # Linux: ldd hello
hello:
	libminic10.dylib (compatibility version 0.0.0, current version 0.0.0)
	/usr/lib/libc++.1.dylib (...)
	/usr/lib/libSystem.B.dylib (...)

把三段 nm 输出按符号对齐(— 表示该文件里没有这个符号):

mini-c10 三个函数在各文件符号表里的状态
符号 Version.o libminic10.dylib 的导出表(nm -g) hello.o 原因
build_flavor() t(内部链接) — — 定义在匿名命名空间,不导出
version_string() T(定义) T(导出) U(未定义,等链接) 头文件只有声明,定义在 Version.cpp
version_number() — — T(定义;Linux 上是 W) inline 函数,谁调用谁的目标文件里有一份

hello.o 里唯一的 U 由 libminic10 的导出表满足,所以 hello 的依赖表(otool -L)里有 libminic10;Version.o 没有调用 version_number,因此不含它的定义。这和 libc10.so/libtorch_cpu.so/_C.so 之间的关系是同一个模型,只是规模差了五个数量级。

4. CMake 骨架

# mini-c10/CMakeLists.txt
cmake_minimum_required(VERSION 3.18)
project(minic10 CXX)

# 与 PyTorch 2.10 / vLLM 0.15 一致(两者的 CMakeLists.txt 都是 CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

# 《构建、调试与测试工具链》会用到 compile_commands.json(clangd)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

# 默认构建动态库,与 PyTorch 的 BUILD_SHARED_LIBS 默认值一致
option(BUILD_SHARED_LIBS "Build minic10 as a shared library" ON)

# ---- 库:libminic10 ----------------------------------------------------------
# 后续各篇往这个列表里加 .cpp;头文件不需要列出(只要能被 include 到即可),
# 列出是为了让 IDE 显示它们,与 c10/CMakeLists.txt 的做法一致
set(MINIC10_SRCS
    minic10/core/Version.cpp
)
set(MINIC10_HEADERS
    minic10/core/Version.h
)

add_library(minic10 ${MINIC10_SRCS} ${MINIC10_HEADERS})

# 头文件从项目根开始写:#include <minic10/core/Version.h>
# PUBLIC:链接 minic10 的目标自动获得这个 include 路径(对应 c10 的 $<BUILD_INTERFACE:.../..>)
target_include_directories(minic10 PUBLIC
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
    $<INSTALL_INTERFACE:include>)

# 与 c10 相同的警告级别起点;《构建、调试与测试工具链》再加 -Werror、sanitizer
target_compile_options(minic10 PRIVATE -Wall -Wextra)

# 《宏、静态注册与代码生成》会在这里加 -fvisibility=hidden 和 -DMINIC10_BUILD_MAIN_LIB,
# 并给需要导出的符号加 MINI_API。本篇先用默认可见性(全部导出)。

# ---- 示例可执行文件 ---------------------------------------------------------
add_executable(hello examples/hello.cpp)
target_link_libraries(hello PRIVATE minic10)

# 让 build 目录里的 hello 能直接跑(RPATH 指向 libminic10.so 所在目录)
set_target_properties(hello PROPERTIES
    BUILD_RPATH "${CMAKE_CURRENT_BINARY_DIR}")

# ---- 安装 -------------------------------------------------------------------
install(TARGETS minic10 DESTINATION lib)
install(DIRECTORY minic10/ DESTINATION include/minic10 FILES_MATCHING PATTERN "*.h")

使用:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -G Ninja
cmake --build build
./build/hello
# mini-c10 0.1 (release), number=1      (Release 构建定义了 NDEBUG,所以 build_flavor 是 release)

这份 CMakeLists.txt 只用了 CMake 最基础的命令,每一条都与 c10/CMakeLists.txt 中的对应项一一对照:

mini-c10 与 c10/CMakeLists.txt 的逐条对照
mini-c10 c10/CMakeLists.txt
add_library(minic10 ${MINIC10_SRCS} ${MINIC10_HEADERS}) add_library(c10 ${C10_SRCS} ${C10_HEADERS})
target_include_directories(minic10 PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}> ...) target_include_directories(c10 PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../> ...)(c10 的根在上一级)
target_compile_options(minic10 PRIVATE -Wall -Wextra) torch_compile_options(c10)
(《宏、静态注册与代码生成》加)-fvisibility=hidden、-DMINIC10_BUILD_MAIN_LIB -fvisibility=hidden、-DC10_BUILD_MAIN_LIB
install(TARGETS minic10 DESTINATION lib) install(TARGETS c10 EXPORT Caffe2Targets DESTINATION lib)
install(DIRECTORY minic10/ DESTINATION include/minic10 ...) install(DIRECTORY ${CMAKE_CURRENT_LIST_DIR} DESTINATION include FILES_MATCHING PATTERN "*.h")

《构建、调试与测试工具链》会把 EXPORT、find_package 支持、gtest、sanitizer 补齐。

5. 本篇留下的问题

mini-c10 现在只有一个函数,但它已经是一个”库”:有头文件和实现的分离,有导出和不导出的符号,有一个链接它的可执行文件。接下来的问题是往里放东西——《值、引用与所有权》要放的是 intrusive_ptr、TensorImpl、StorageImpl 和 Tensor 句柄,那时候”对象放在哪里、活多久、谁负责释放”就成了主题。

六、工程实践建议与常见错误

1. 按阶段定位错误

按编译阶段定位错误
错误信息(节选) 阶段 常见原因
fatal error: torch/torch.h: No such file or directory 预处理 少 -I;torch/torch.h 需要 include/torch/csrc/api/include 这个额外路径
error: 'Tensor' was not declared in this scope / 'at' has not been declared 编译 少 #include,或者只有前向声明却用了完整定义
error: invalid use of incomplete type 'class at::Tensor' 编译 前向声明了但没包含完整定义(上篇 3.4 节)
undefined reference to 'at::xxx' 链接
  • 少 -ltorch_cpu/-lc10
  • 或函数声明了没定义
  • 或声明上没有 TORCH_API(符号没导出)
multiple definition of 'xxx' 链接 头文件里的函数定义忘了 inline;或同一个 .cpp 被加进两个目标
error while loading shared libraries: libtorch.so: cannot open shared object file 加载 没有 RPATH 也没设 LD_LIBRARY_PATH
undefined symbol: _ZN2at... (import 时) 加载
  • 编译扩展用的 PyTorch 头文件和运行时加载的 .so 版本不一致
  • 或 ABI 不匹配([abi:cxx11])
  • 或 -std= 不一致导致某些 inline 函数签名不同
dynamic module does not define module export function (PyInit_xxx) 加载 扩展用了 -fvisibility=hidden 却没给 PyInit_xxx 加默认可见性;或模块名和 PYBIND11_MODULE/TORCH_EXTENSION_NAME 不一致
运行时算子”不存在”,但 nm 里能看到注册代码 链接/加载 静态库没用 --whole-archive,注册所在的 .o 被丢弃(上篇 5.3 节,《宏、静态注册与代码生成》)

2. 头文件卫生

  • 每个头文件 #pragma once;每个头文件自包含(单独 #include 它就能编译,不依赖包含顺序)。PyTorch 的 lint 会检查这一点。
  • 能前向声明就不要 #include;头文件里不要 using namespace(torch/types.h 那种是在自己的命名空间里做接口设计,是例外,不是范例)。
  • 头文件里定义的函数必须 inline(或是模板/constexpr/类内成员);头文件里的变量必须 extern、inline(C++17)或 constexpr。
  • .cpp 第一行包含自己的头文件。
  • 只在 .cpp 里用的辅助函数放匿名命名空间。

3. 链接与部署

  • 扩展的编译选项(-std=、-D_GLIBCXX_USE_CXX11_ABI、编译器大版本)要和 PyTorch 一致。torch.utils.cpp_extension 会替你做;手写 CMake 时用 find_package(Torch) 的 TORCH_CXX_FLAGS。
  • 用 RPATH($ORIGIN)而不是 LD_LIBRARY_PATH 部署。
  • 不要把 libtorch_*.so 拷到系统目录或另一个 Python 环境里”共享”——它们和特定的 wheel 版本、CUDA 版本、Python 版本(libtorch_python.so)绑定。
  • 出链接问题时,ninja -v 或 make VERBOSE=1 拿到完整命令,用 nm -DC lib.so | grep symbol 确认符号到底在不在、是不是导出的、修饰名是否一致。
  • 出加载问题时,LD_DEBUG=libs python -c 'import torch' 让 ld.so 打印每一个库的查找过程。

4. 阅读 PyTorch 源码时的定位技巧

  • 看到一个类型,先看它的命名空间猜它在哪个目录、哪个库:c10:: → c10/ → libc10.so;at:: → aten/ → libtorch_cpu.so;torch:: → torch/csrc/ → 看是否碰 Python 决定 libtorch_cpu.so 还是 libtorch_python.so。
  • 看到 C10_API/TORCH_API/TORCH_PYTHON_API,它就是这个库的”公开 API”标记。
  • build_variables.bzl 是”哪个 .cpp 进哪个库”的权威清单,比读 CMake 快。
  • aten/src/ATen/templates/ 是 torchgen 的模板,ATen/core/TensorBody.h、ATen/Functions.h、ATen/ops/*.h 这些在源码树里找不到的头文件由它们生成到 build 目录(《宏、静态注册与代码生成》)。
  • 找一个函数的定义:先在同名 .h 的同目录找同名 .cpp;找不到,看 native_functions.yaml 的 dispatch: 字段(at::empty_like → aten/src/ATen/native/TensorFactories.cpp 的 empty_like)。

七、本文小结

回到开头的问题。

import torch 时加载了哪些 .so? 先是 libtorch_global_deps.so(RTLD_GLOBAL,只为把 MKL/OpenMP/CUDA runtime 带进全局符号空间),然后是 torch/_C.cpython-*.so(RTLD_LOCAL),后者通过 $ORIGIN/lib 的 RPATH 递归拉起 libtorch_python.so → libtorch.so → libtorch_cpu.so(+ libtorch_cuda.so)→ libc10.so(+ libc10_cuda.so)和 libshm.so。

它们之间是什么依赖关系? 单向的四层:c10 不依赖任何 PyTorch 代码;torch_cpu 依赖 c10;torch_cuda 依赖 torch_cpu 和 c10_cuda;torch 是把 CPU 和 CUDA 打包的空壳;torch_python 依赖 torch 和 Python;_C 是 15 行 stub 到 torch_python 的转接头。命名空间 c10::/at::/torch:: 大致对应前三层,但 torch:: 横跨 libtorch_cpu.so 和 libtorch_python.so。

自定义扩展链接到哪一个? 用了 c10:: 的类型链 -lc10;用了 at::Tensor、算子、TORCH_LIBRARY 链 -ltorch_cpu(或 -ltorch);用了 CUDA 链 -lc10_cuda -ltorch_cuda;用了 pybind11 的 Tensor 转换链 -ltorch_python。torch.utils.cpp_extension 默认全加;vLLM 为了 Python 稳定 ABI 只链 torch,不链 torch_python。

上篇的机制表里还差一行,本篇补上:

本篇补上的机制:命名空间
机制 一句话 在 PyTorch 里的体现
命名空间 组织名字、决定修饰名,与目录和库无对应关系 c10::/at::/torch::;namespace torch { using namespace at; }
目录 → 库 哪些目录编进哪个库由 CMake 决定,不由目录层级决定 c10/ → libc10.so;aten/ + torch/csrc/ 的大部分 → libtorch_cpu.so
库的分层 每层只依赖更低的层,只导出标了 *_API 的符号 c10 ← torch_cpu ← torch ← torch_python ← _C
setup.py 与 wheel .so 与 RPATH 一起进 wheel,$ORIGIN/lib 让它们在任何安装位置都能互相找到 -Wl,-rpath,$ORIGIN/lib

Java 工程师需要放弃的第三个直觉:“一个包就是一个 jar”——命名空间、目录、库是三个独立的维度,PyTorch 只是让它们大致对齐。

下一篇《值、引用与所有权》进入对象模型:at::Tensor y = x; 之后 y 和 x 是什么关系,数据什么时候被释放。

八、自测

  1. torch:: 命名空间里的东西都在 libtorch.so 里吗?c10/ 目录下的代码都编进 libc10.so 吗?

    答案

    都不是。torch:: 横跨 libtorch_cpu.so(torch::jit、torch::autograd 的大部分)与 libtorch_python.so(torch:: 下的 Python 绑定),libtorch.so 本身几乎是空壳;c10/ 下的 c10/cuda/ 单独编成 libc10_cuda.so。命名空间、目录、库是三个独立的维度,对应关系由 CMake 决定。

  2. 一个只用了 at::Tensor 与 TORCH_LIBRARY 注册算子的 CPU 扩展,最少要链接哪些库?加了 pybind11 的 Tensor 转换之后呢?

    答案

    -lc10 -ltorch_cpu(或 -ltorch,它会拉起 torch_cpu);pybind11 的 at::Tensor ↔ torch.Tensor 转换在 libtorch_python.so 里,要再加 -ltorch_python,同时扩展就绑死了 Python 版本——vLLM 为了 Python 稳定 ABI 只链 torch、不链 torch_python。

  3. import torch 为什么先以 RTLD_GLOBAL 加载 libtorch_global_deps.so,再以默认的 RTLD_LOCAL 加载 torch/_C.*.so?

    答案

    前者只为把 MKL / OpenMP / CUDA runtime 这类第三方库的符号放进全局符号空间,让之后加载的任何 .so(包括用户扩展)都能解析到同一份;_C 及其 DT_NEEDED 链上的 PyTorch 自己的库则保持 RTLD_LOCAL,符号只在依赖链内可见,避免与别的扩展模块冲突。

  4. torch/CMakeLists.txt 里写的是 target_link_libraries(torch_python PRIVATE ${TORCH_LIB} ...)。setup.py 链接 torch._C 时只写了 libraries=["torch_python"],为什么 import torch 时 libtorch_cpu.so、libc10.so 仍然会被加载?如果这里把 PRIVATE 改成 PUBLIC,torch._C 的链接命令会变吗?

    答案

    PRIVATE / PUBLIC 只决定 CMake 是否把依赖传给构建期的下游 target;加载期看的是 .so 里的 DT_NEEDED,ld.so 会递归加载:_C → libtorch_python.so → libtorch.so → libtorch_cpu.so → libc10.so。改成 PUBLIC 也不会影响 torch._C:它由 setuptools 而不是 CMake 链接,不读 CMake target 的传播属性,链接命令仍然只有 -ltorch_python。

  5. 小工程 layers 里,把 target_link_libraries(binding PRIVATE shell) 的 PRIVATE 改成 PUBLIC,app 的链接命令和依赖表各有什么变化?app 运行时加载的库会变吗?

    答案

    链接命令从只有 libbinding 变成 libbinding、libshell、libcore、libbase 四个,app 的依赖表也从一行变成四行:PUBLIC 依赖会传给下游,shell PUBLIC core、core PUBLIC base 一路传到 app。运行时加载的库不变,两种写法下都是四个,因为加载器会沿每个库自己的依赖表递归加载。

  1. import torch 先由 _load_global_deps() 以 RTLD_GLOBAL dlopen libtorch_global_deps.so(把 CUDA runtime、cuDNN、NCCL 的符号放进全局命名空间),再导入扩展模块 torch/_C.*.so,它的 DT_NEEDED 链上是 libtorch_python.so → libtorch.so → libtorch_cpu.so / libtorch_cuda.so → libc10.so / libc10_cuda.so。详见第三章、第四章。 ↩

  2. c10 是最底层(Tensor 元数据、Device、Allocator、Dispatcher 核心),torch_cpu / torch_cuda 是算子与 kernel,torch 是把两者拼起来的空壳,torch_python 是 Python 绑定;每一层只导出标了 C10_API / TORCH_API 的符号,其余在 -fvisibility=hidden 下不可见。详见第二章、第三章。 ↩

  3. 用 torch.utils.cpp_extension 构建的扩展链接 libc10.so、libtorch.so、libtorch_cpu.so(CUDA 扩展再加 libc10_cuda.so、libtorch_cuda.so),用了 pybind11 / Python API 时再加 libtorch_python.so,并用 -Wl,-rpath 把搜索路径烧进去。符号在加载期由动态链接器解析,所以扩展的 ABI(_GLIBCXX_USE_CXX11_ABI、编译器版本)必须与这些库一致。详见第四章、上篇第七章。 ↩

这篇对你有用?

本文由 arganzheng 创作,采用 CC BY 4.0 许可协议。在保留原文作者、署名以及完整原文链接(https://arganzheng.life/cpp-project-layout-namespaces-libraries-and-cmake.html)的前提下,欢迎各种形式的转载、翻译或商业引用。


COMMENTS

评论存放在 GitHub Discussions, 用 GitHub 账号登录即可发表,支持 Markdown。 想针对正文某句话说?选中那段文字,点浮出的「评论」即可划线评论;觉得哪里写错了,发表时勾上「同时提交 Issue」。 有人回复你时 GitHub 会按你的通知设置发邮件,不用守在这里。

×