1. 先搞清楚llvm-project 到底是个什么东西我第一次接触 llvm-project是很多年前在一个嵌入式 C 编译器的项目里。当时我的任务是把一套私有编译器前端接到一个新的后端上参考资料全是 LLVM 的文档。我花了一整周才真正理解它的架构在解决什么问题——那种感觉不是“哦我看懂了”而是“原来编译器还能这样设计”。先说一个最容易被误解的点LLVM 不是“编译器的编译器”。准确说llvm-project 是一个模块化的编译器工具链生态核心是 LLVM 中间表示IR和它的 Pass 优化框架。很多人听到“编译器基础设施”这个说法觉得抽象换个方式理解它把传统编译器那条“源码 - 目标机器码”的粗管道拆成了三层清晰独立的管道每一层都能被单独使用和替换。这是 llvm-project 源码树的核心模块拆解你 clone 下来之后会看到这些目录各有分工llvm/— LLVM Core包含 IR 定义、优化器、目标后端X86、ARM、RISC-V 等、汇编器、链接器等基础库clang/— C/C/Objective-C 的前端负责把源码解析并生成 LLVM IRlld/— 高性能链接器现代构建里替代系统 ld 的黄金选择libc / libcabi— C 标准库实现及其 ABI 层macOS 和部分 Linux 发行版在用compiler-rt/— 运行时库包含 sanitizerAddressSanitizer、UndefinedBehaviorSanitizer 等、profile 运行时、builtinsflang/— Fortran 前端对LLVM 早就不是 C/C 专属mlir/— 多层级 IR 框架是编译器中间表示的下一代抽象专门服务异构计算和 AI 编译器如果你做的是编译器开发、性能工程、语言设计甚至只是想知道 GCC 和 clang 路线图的底层逻辑llvm-project 都值得你会读、会查、会编译。这篇文章不是 LLVM 官方教程的复读是我从“会用 clang 编译 C 文件”到“能在 LLVM 上写 Pass 和分析优化”这一路踩过来的实操记录。注意下文出现的“LLVM”均指 llvm-project 这个整体项目严格来说它包含但不限于 LLVM Core 子项目。2. 三个端的设计逻辑为什么 LLVM 能同时服务编译器和无数新领域2.1 传统编译器为什么改起来要命老式编译器比如早期 GCC 的架构最痛苦的地方在于前端和后端耦合太紧。你加一种新的语言支持就得为每个目标架构重新处理一遍语义你加一个新的目标架构前端那套中间数据结构和优化也绕不开。每一层之间的“接口”都是隐式的、松散的约定改起来牵一发动全身。LLVM 的破局点在于它把编译过程强行规范成了三段并且每一段的边界由一套显式的、可序列化的中间表示来沟通源码 - 前端Clang 等 - LLVM IR - 优化器Pass - LLVM IR - 后端Instruction Selection / Register Allocation - 目标机器码这个设计的关键不是“分了三段”而是中间的 IR 是公有的第一公民。任何语言只要你能生成合法的 LLVM IR就能自动获得所有优化和后端支持任何新 CPU 架构只需要实现一个从 LLVM IR 到目标指令集的翻译后端就能跑通所有支持 LLVM 的语言。这也是“LLVM 是编译器的编译器”这句话的真正含义它通过一次性实现通用的中端和后端让所有愿意接轨的语言和架构都能复用这套基础设施而不是直接吃掉你的编译器再吐一个出来。2.2 LLVM IR 的三个设计细节最值得反复品味LLVM IR 是一种静态单赋值SSA形式的强类型中间语言。三个细节我建议初学者优先搞懂后面做 Pass 全靠它们吃饭其一SSA 意味着每个变量只被赋值一次。这天然消除了很多数据流分析里“这个变量多个版本”的混乱每个值都有明确的定义点和活跃范围。比如一个简单的加法表达式在 IR 里长这样%add add i32 %a, %b%add这个名字在函数体内唯一它指向的 SSA 值只有一条定义路径。你在分析数据流时不需要追踪一个变量在分支里被反复改写的情况这大幅简化了定值-使用链的构建成本。其二内存访问和计算是显式分离的。源码里的int x a[i] 1会被拆成 load、add、store 三条指令。很多第一次接触 IR 的人会觉得它啰嗦但正是这种“把内存副作用显式保留”的方式让优化器能精细判断什么时候可以做常量传播、什么时候可以把 load 提到循环外而不破坏程序语义。其三IR 携带完整的类型信息和转换语义。getelementptr常被缩写为 GEP是 LLVM IR 里头新手最容易懵的指令它专门用来计算地址偏移而不是直接访问内存。它遵循指针的“结构体扁平化”语义索引语义和 C 的数组/结构体下标规则保持一致。很多内存误用 bug 其实就是对 GEP 的位移计算理解有偏差。2.3 Pass 机制LLVM 的优化魔法全部发生在这里Pass趟是 LLVM 优化器执行单元的名字。每一趟 Pass 负责对 IR 做一种特定的分析或变换比如常量传播Constant Propagation死代码消除Dead Code Elimination循环不变量外提Loop Invariant Code Motion内联Inlining向量化Loop Vectorize寄存器分配这是后端的 Pass整条-O2优化流水线就是几十个 Pass 按固定顺序排队执行。这种模块化的好处是你可以像搭积木一样为自定义优化场景自由组合 Pass而不需要改编译器前端。比如 AI 编译栈里很多团队就是拿 LLVM 自己写几个专用 Pass 插到默认流水线里。到目前为止LLVM 的 Pass 基础设施正在全面过渡到New Pass ManagerNPM。NPM 相比旧 Pass Manager 的改进主要体现在两个地方一是 Pass 间的依赖关系显式化避免了旧架构里跨 Pass 共享数据的隐式缓存难题二是能对 CGSCCCall Graph SCC调用图强连通分量级的分析和变换做更好的增量复用。实操提示在 llvm-project 源码树里看优化流程最快的方式是跑opt -passesdefaultO2 -debug-pass-manager加一个简单 IR 文件它会打印出优化执行的所有 Pass 顺序。这个命令能救无数个“为什么优化没生效”的困惑。3. 从零构建 llvm-project我的实测完整过程和避坑记录3.1 构建前必须想清楚的三个前提如果你只是用 clang 编译 C通常不需要自己构建整个 llvm-project发行版自带的 clang 已经够用。但如果你想做以下事情就必须源码构建改 IR 或写自定义 Pass 并调试为第三方语言实现前端研究 lld 的链接算法给 LLVM 提交代码构建前你得确认三件事这三件我全踩过不同的坑第一磁盘空间。完整构建 llvm-project 的 Debug 版本只算对象的存放就需要 60GB 以上空间。我自己最惨的一次是忘记清旧构建目录SSD 直接见红。建议至少预留 100GB且尽量放在 SSD 上——机械硬盘的随机读写会让链接阶段慢到怀疑人生。第二内存和并发数。链接 LLVM 库是内存杀手尤其是LLVM_ENABLE_PROJECTSclang;lld时。经验值8GB 内存的机器只能用-j216GB 可以-j4我日常用 32GB 内存开-j8比较稳。内存不足时你会看到ld进程直接被内核 OOM Killer 杀掉没有任何报错提示非常诡异。第三CMake 和编译器的版本。llvm-project 对基础编译器的版本下限要求逐年提升。旧 GCC 可能因为缺 C17 特性编译到一半才报错那是最浪费时间的。建议先用新一点的 GCC 或 clang 作为 bootstrap 编译器然后用构建出的新 clang 再重建一次也就是自举循环。3.2 完整构建命令与关键 CMake 参数解读以下是我在 Ubuntu 22.04 上验证过的构建命令序列用的源码版本是 LLVM 18.x release 分支git clone --depth1 -b llvmorg-18.1.8 https://github.com/llvm/llvm-project.git cd llvm-project mkdir build cd build cmake -G Ninja \ -DCMAKE_BUILD_TYPERelease \ -DLLVM_ENABLE_PROJECTSclang;lld \ -DLLVM_TARGETS_TO_BUILDX86 \ -DLLVM_ENABLE_ASSERTIONSON \ -DCMAKE_C_COMPILERgcc \ -DCMAKE_CXX_COMPILERg \ ../llvm ninja -j8我来逐条解释这些参数因为网上抄来的一大堆参数有很多是旧的、误导的-DLLVM_ENABLE_PROJECTSclang;lld这是定义你要额外构建哪些子项目的开关。注意格式是分号分隔不是空格。如果这里没有写clang你构建出来的只有 LLVM Core 那一套工具opt、llc、llvm-dis 等没有 clang 编译器。-DLLVM_TARGETS_TO_BUILDX86只构建 X86 后端。这能显著缩短编译时间。如果你做交叉编译或调试多架构代码可以加ARM;AArch64;RISCV但每个后端都是数万行 TableGen 生成的代码时间成本直线上升。-DLLVM_ENABLE_ASSERTIONSON对 LLVM 开发而言几乎必须开着。它让内部的不变量检查在运行时生效能挡下很多因逻辑错误导致的潜在内存非法访问。代价是性能比 Release-无断言模式慢但调试体验完全不同。-DCMAKE_C_COMPILER/-DCMAKE_CXX_COMPILER指定 bootstrap 编译器。注意如果你在这台机器上装过多个 clang 版本CMake 可能会自动选一个版本过高的 clang 作为编译器和当前源码不兼容导致编译期间产生“unexpected AST type”之类随机崩溃。显式指定一个保守的 gcc 通常最稳。关于构建时间和速度用 Ninja 而不是 make 是标配。上面这个配置在 16 核 CPU 32GB 内存的机器上首次全新构建大约需要 3045 分钟如果不开assertions能快一些但我不建议为省时间关掉它。3.3 加速二次构建的实用策略我强烈建议配置ccache来加速 clang 自身在开发过程中的反复编译。这个工具能缓存预处理的编译结果让我在做实验时把增量编译时间从十几分钟压到几分钟。我常加的 CMake 选项是-DLLVM_CCACHE_BUILDON它要求系统里已经有 ccache并且 CMake 能找到它。对个人开发者来说这是性价比最高的一个加速措施。另外如果你有充裕的内存可以加大链接并行度用lld替代系统默认的ldgold来链接 LLVM 自身能大大缩短最后的 link 时间。LLVM 官方就是拿 lld 自链接的这也是我建议在上面项目列表里带上lld的原因之一——先构建一个 lld再用它来链接后续的构建产物。4. 亲手看一次优化用 llvm-project 自带工具理解 O2 流水线4.1 从 C 源码到 IR 再到优化的全流程演示没有比动手看更能理解 LLVM 的了。我先用一个极简例子演示从 C 代码到优化后汇编的完整链路。先准备一个测试文件// test.c int sum(int n) { int s 0; for (int i 0; i n; i) s i * 2; return s; }第一步用 clang 生成可读的 IR不加优化clang -S -emit-llvm test.c -o test.ll打开test.ll你会看到一堆%s、%i的 SSA 变量和br、icmp指令还有load、store对局部变量的内存操作。这就是 clang 前端刚从 AST 生成的原始 IR——内容还不够优美大量访存和跳转指令可以优化掉。第二步用opt跑 O2 优化opt -S -passesdefaultO2 test.ll -o test.opt.ll对比优化前后的 IR你会发现原始 IR 里的store和load基本消失了循环不变计算被外提i*2被改写成i 1整数乘法被编译成移位指令循环体内的指令变成“s 每轮累加 2*i”优化器还生成了一个归纳变量indvar把每次加法拆成初始值和步长更关键的是循环展开没有发生这取决于后端在指令选择和向量化阶段是否判断为有利第三步生成最终汇编llc test.opt.ll -o test.sllc是负责把优化后的 IR 降到目标机器码的工具。这里面还有一层指令选择SelectionDAG 或 GlobalISel和寄存器分配Register Allocation要做它才是“后端”工作的主战场。4.2 OptimizationRemark让编译器告诉你它做了什么很多人在做性能优化时面对“优化器为什么没把我的循环向量化”很困惑。LLVM 提供了诊断输出机制让编译器直接解释它的决策。在编译时加-Rpass系列参数即可clang -O2 -Rpassloop-vectorize -Rpass-missedloop-vectorize test.c -o /dev/null输出可能是test.c:4:9: remark: vectorized loop (vectorization width: 4, interleaved count: 2) [-Rpassloop-vectorize]如果它没有向量化大部分时候会打印-Rpass-missed里的原因比如“loop not vectorized: the lack of a safe stride”或者“couldnt prove it is safe to reorder memory operations”。这类信息在分析gcc -O2和clang -O2性能差异时特别有用——很多时候不是 clang 优化不行而是它的合法性检查比 GCC 更保守拒绝了一些 GCC 敢做的假设。这些 Remark 可以直接被opt等文本工具消费也可以生成为 YAML/JSON 格式喂给可视化工具。Clang 的-fsave-optimization-record选项支持把 remark 导出成 JSON 文件后续可以用opt-viewer脚本渲染成 HTML 报告看每个源代码行被优化了多少次。这是做性能回归分析的利器。4.3 为什么 clang 的速度优势对日常使用感知不强但对 CI 影响巨大你经常会看到 clang 比 GCC 快的对比数据。确实clang 的单线程编译速度通常比 GCC 快尤其在语法分析和 AST 生成阶段。但日常开发中瓶颈往往在模板实例化和链接阶段clang 在这两个环节的速度优势没那么明显。不过在 CI 流水线上每次编译都是几十分钟的事clang 的编译速度优势能直接折算成机器成本和等待时间。更关键的是clang 的诊断信息更友好——错误信息通常带颜色、段落、修复提示甚至能直接给你建议怎么写正确的调用方式。这一点在大型 C 工程里是真正的生产力因为它让开发者平均定位 bug 的时间显著缩短。5. 实战写第一个自定义 LLVM Pass 并跑通看完优化流水线什么样之后最值得自己动手做的一件事就是写一个 Pass 插入到优化流程里。我自己当时是从一个函数内打印每个 loop trip count 的 Analysis Pass 入门的受益匪浅。5.1 环境准备新建一个 LLVM 外部 Pass 工程在 LLVM 新版本里推荐使用 New Pass Manager 写 Pass。我以写一个最简单的 FunctionPass 为例它尝试统计每个函数里基本块的数量。先看工程结构MyPass/ ├── CMakeLists.txt └── MyPass.cppCMakeLists.txt 内容这里假设你用了上面构建好的 llvm-project 源码树cmake_minimum_required(VERSION 3.20) project(MyPass) find_package(LLVM REQUIRED CONFIG) message(STATUS Found LLVM ${LLVM_PACKAGE_VERSION}) include_directories(${LLVM_INCLUDE_DIRS}) separate_arguments(LLVM_DEFINITIONS_LIST NATIVE_COMMAND ${LLVM_DEFINITIONS}) add_definitions(${LLVM_DEFINITIONS_LIST}) add_library(MyPass MODULE MyPass.cpp) target_link_libraries(MyPass PRIVATE LLVMCore LLVMSupport LLVMPasses)这里的关键点find_package(LLVM REQUIRED CONFIG)会找你的llvm-project/build/lib/cmake/llvm/LLVMConfig.cmake必须用MODULE而不是SHARED因为插件动态库要被opt动态加载链接的库不是随意挑的LLVMCore提供 IR 的定义LLVMPasses提供 Pass 基础设施LLVMSupport提供错误处理、命令行等MyPass.cpp 的内容#include llvm/IR/Function.h #include llvm/IR/LegacyPassManager.h #include llvm/Passes/PassBuilder.h #include llvm/Passes/PassPlugin.h #include llvm/Support/raw_ostream.h using namespace llvm; namespace { struct CountBasicBlocksPass : public PassInfoMixinCountBasicBlocksPass { PreservedAnalyses run(Function F, FunctionAnalysisManager AM) { size_t count 0; for (auto BB : F) count; errs() Function F.getName() has count basic blocks\n; return PreservedAnalyses::all(); } }; } // namespace llvm::PassPluginLibraryInfo getMyPassPluginInfo() { return {LLVM_PLUGIN_API_VERSION, CountBasicBlocksPass, LLVM_VERSION_STRING, [](PassBuilder PB) { PB.registerPipelineParsingCallback( [](StringRef Name, FunctionPassManager FPM, ArrayRefPassBuilder::PipelineElement) { if (Name count-bb) { FPM.addPass(CountBasicBlocksPass()); return true; } return false; }); }}; } extern C LLVM_ATTRIBUTE_WEAK ::llvm::PassPluginLibraryInfo llvmGetPassPluginInfo() { return getMyPassPluginInfo(); }这段代码的核心逻辑分成三块CountBasicBlocksPass继承PassInfoMixin这是 New Pass Manager 的风格——Pass 不再是继承某个基类并重写runOnFunction()而是实现一个模板化的run()方法返回PreservedAnalyses告诉优化器哪些分析结果没被改动registerPipelineParsingCallback把命令行字符串count-bb映射到这个 Pass这样opt才能通过名字识别llvmGetPassPluginInfo是插件入口点opt通过它拿到插件的信息并完成运行时注册5.2 编译并运行自定义 Pass假设我的构建目录是build源码树在llvm-project则编译命令mkdir -p MyPass/build cd MyPass/build cmake .. make然后找一个 IR 文件测试opt -load-pass-plugin./libMyPass.so -passescount-bb test.opt.ll输出会逐行打印Function sum has 4 basic blocks如果第一次没能正常加载先确认你的opt和插件是否用同一套 LLVM 源码构建且版本一致。这是插件开发最常见的启动问题。5.3 从“能跑”到“能改优化”一些关键认知写完这个 Hello World 级别的 Pass 之后我建议你紧接着做这几件事它们比插件本身更能提升你对架构的理解给 Pass 加实际的 IR 变换逻辑比如把某个特定模式的add指令替换成另一个函数调用观察新 IR 的变化在 Pass 里使用AnalysisManager请求上游分析的结果比如LoopAnalysis、DominatorTreeAnalysis体会“Pass 是依赖关系明确的单元”这个设计哲学用-print-after-all观察你注册的 Pass 在流水线里的真实执行位置理解 NPM 对 Pass 顺序的控制方式我实际中发现很多写 Pass 的新手最大的误区是试图在 Pass 内部直接操作MachineFunction机器指令层的函数表示但 New Pass Manager 的 Function 层 Pass 只能在 IR 上工作机器指令层的 Pass 需要挂在MachineFunctionPass体系下而且它们运行的时机完全不一样。不要在百万行级 IR Pass 框架里纠结“我想改汇编”——那是 CodeGen 层的活。6. 构建和开发中最容易踩的坑我的完整排查链路记录6.1 诡异的内存溢出为什么链接阶段会 OOM在构建 llvm-project 时最让我崩溃的坑是链接内存不足。现象是编译到 90% 之后ninja突然报错ld进程被Killed。一开始我以为是自己加了太多 debug 符号反复调优化等级都没解决。后来我用top盯着观察发现是同时链接多个库导致峰值内存叠加。完整的排查链路是这样的先用ninja -j1串行链接确认单个链接进程的内存峰值是多少——发现光链接libLLVMCore.a的最终可执行文件就要吃掉约 6GB 内存然后检查是不是启用了LLVM_LINK_LLVM_DYLIB—— 当这个选项开启时所有工具都会链接到一个巨大的动态库libLLVM-18.so链接时内存开销最大。这其实是官方推荐的减小磁盘占用方式但对内存小的机器不友好最终解决方法是关掉LLVM_LINK_LLVM_DYLIB改用静态链接每个工具同时限制ninja并行度到 2另外如果系统ld是 GNU BFD它的内存占用比 lld 高不少。用-fuse-ldlld能让链接时间缩短 30%峰值内存也下降。这也是我建议一开始就构建lld的原因。6.2 TableGen 魔咒改了个 td 文件构建却用了旧逻辑LLVM 的指令选择、寄存器信息、调用约定都通过 TableGen.td文件描述再由 TableGen 生成 C 源码。很多 LLVM 开发的新手会踩这样的坑改完一个.td文件后重新ninja发现生成的汇编完全没变化。这背后的原因是TableGen 生成的.inc文件是构建系统追踪的依赖但如果你修改的.td只影响某个后续 Pass 的 TableGen 后端而那个 Pass 本身又是以OBJECT库形式存在构建系统可能没有正确重建依赖图。我的排查经验是先用ninja -t targets查目标名再用touch手动触发相关.inc文件重建ninja -t targets | grep -i mybackend ninja -t commands | grep -i tablegenLLVM 官方构建系统对 TableGen 依赖的处理已经很完善但当你做实验性改动、加自己的 TableGen 后端时这种问题非常常见。不要盲目全量重建太慢用ninja -t工具链精确找到该重建的目标才是效率王道。6.3 调试符号加载失败Debug 版本与 Release 版本混用的陷阱很多人在CMAKE_BUILD_TYPEDebug下写 Pass然后用 Release 版的opt去加载插件插件所以跑不了。具体表现是opt报failed to load plugin或者加载了但运行到某个 Pass 直接段错误。真正的原因不只是 ABI 兼容而是 LLVM 默认启用了 RTTI 和异常但不同构建类型下_GLIBCXX_DEBUG宏状态不同导致标准库容器布局不一致跨版本加载插件时迭代器就会爆掉。所以有个铁律同一个 llvm-project 源码树用什么构建配置编出了opt你的插件也必须用同样的配置编译。如果必须使用系统自带 clang 的插件系统 clang 的构建配置不是你能控制的最稳妥的做法是自带一份源码树专门为“插件开发”构建反正我把这个坑踩明白了之后就固定用一个独立的build-debug目录来写 Pass再也不用系统 clang 做实验了。7. 给新手的自学历路线图从会用到能贡献如果你看完上面这些打算认真开始学 llvm-project我根据自己的经历给一条自认为比较顺畅的路线第一周熟悉工具链。不写任何代码把clang、opt、llc、llvm-dis、lli解释器这五个工具的常用命令全过一遍。可以拿自己的小程序生成 IR用opt -O2对比前后的 IR 差异。这阶段的目的不是理解每个细节而是建立“IR 是我的工作素材”的感觉。第二到三周读文档和源码。重点阅读llvm/docs/下的LangRef.rst、Passes.rst、WritingAnLLVMPass.rst。前两个是必须精读的后者虽然描述的是 legacy Pass Manager但理解基本概念仍有帮助。源码层面优先读llvm/lib/Transforms/里的简单 Pass比如ADCE、SCCP。第四到六周动手写。从分析型 Pass 开始统计信息、打印 IR再转到变换型 Pass替换指令、优化循环。目标不是写规整的代码而是通过迭代让opt跑通、让FileCheck测试通过。之后深入一个领域。对代码生成感兴趣就研究 SelectionDAG 和 GlobalISel对编译优化感兴趣就深入 LoopPass 和 SCEV标量演进分析对新语言前端感兴趣就研究 Clang 的AST/Sema和CodeGen模块。LLVM 是个大得可怕的体系没有人能全部掌握选定一个方向深挖才是可持续路线。在实际操作中我最受益的一种学习方式是故意写坏一个 Pass——让某个变换 pass 故意生成不正确的 IR然后看opt的 verifier 如何报错。LLVM IR 自带一套验证器-verify能在每个 Pass 之后检查 IR 的合法性。可能是错误操作但这个“验证器帮我报错”的互动过程让我很快理解了 IR 的约束条件和 Pass 的责任边界。另一个特别好的入口是修 Clang 的诊断信息。LLVM 社区里有很多good first issue标签的问题其中不少是“为某个表达式补一条更友好的错误提示”。这个过程不需要深刻理解后端但对阅读前端代码、理解 AST 结构、熟悉提交流程非常有帮助。我认识的几位 LLVM 活跃贡献者都是从这类小任务开始的。最后再分享一个我个人的体会llvm-project 是我见过的把“工程实践”和“学术思想”结合得最好的大型开源项目之一。它的 IR 设计有当年教科书里数据流分析的影子它的 Pass 架构是编译器理论教材的最佳实践案例而它的代码生成框架又能一路通到处理器的指令调度细节。不要指望三个月内把它读透但哪怕只是每天花点时间看一个 Pass 的实现坚持下来你对编译原理和程序执行的理解都会上一个台阶。
