1. 一个老牌编译器项目为什么值得在今天重新翻开它的源码树我先坦白一下自己的经历。用LLVM写工具、调Clang报错、在Mesa里看llvmpipe的日志这些事我都干过好几年但很长时间里我对llvm-project的认识始终停留在编译器基础设施这六个字上。真正让我下定决心把整个源码树翻一遍的导火索是有一次调试一个自定义Pass时发现优化顺序怎么调都不对翻文档翻到头痛最后去源码里搜pass的注册名才找到了线索。那一刻我意识到用了这么多年的东西我对它的内部结构其实一无所知。llvm-project是LLVM官方维护的monorepo聚集了编译器工具链、运行时库、调试器、代码生成后端等一大堆子项目。它解决的核心问题非常明确提供一套模块化、可复用的编译器组件让别人不用从零写一个编译器而是基于LLVM的中间表示IR和优化管道快速构建出属于自己的语言前端、静态分析工具或者代码生成后端。项目正文虽然只给了llvm-project这几个字但结合网络热词里出现的llvm 15.0.7和llvmpipe可以判断这是一篇围绕LLVM整体生态展开的项目梳理型文章重点面向三类读者想系统了解编译器内部结构的初学者、需要基于LLVM做二次开发或定制Pass的工程师、以及在使用Mesa/llvmpipe软渲染时想搞明白底层原理的图形开发者。这篇东西不打算写成官方文档的复读机。我会按照自己实际翻阅源码树的顺序把llvm-project里的每个子项目讲清楚然后从零构建一次LLVM 15.0.7把过程中最折腾人的坑都摆出来接着单独聊聊llvmpipe 256 bits这个热搜词背后的软渲染与JIT编译链路最后带大家写一个真正能跑通的自定义Pass。整个过程都是我在实际环境中验证过的不是纸上谈兵。2. llvm-project源码树每个子项目是干什么的依赖关系如何2.1 monorepo的顶层布局与设计思路先说一个最基础但很多人搞混的概念LLVM和llvm-project不是一回事。单独说LLVM通常指的是llvm-project里的llvm目录也就是核心的编译器基础设施——IR、优化器、目标无关代码生成器、以及各架构的后端。而llvm-project这个更大的仓库把所有周边组件打包在了一起目的是解决多个项目协同开发的版本匹配问题。在早期LLVM、Clang各是各的仓库升级一个要手动保证另一个的兼容性痛苦得很。现在monorepo模式把版本对齐这个事彻底简化了clone一次所有子项目都在同一个快照里切分支、回滚、交叉编译都省心得多。克隆下来的顶层目录结构是固定的你会在根目录看到llvm、clang、clang-tools-extra、lld、lldb、polly、compiler-rt、libcxx、libcxxabi、libunwind、flang、mlir、openmp、bolt这一串子目录。每个目录都是一个相对独立的组件但依赖关系并不对称。比如clang依赖llvm核心lld也依赖llvm核心但llvm核心不依赖clangcompiler-rt是运行时库它可以独立构建也可以在构建Clang时一起启用mlir基于LLVM的核心基础设施构建了自己的多级IR框架但它的代码生成后端最终仍要落到LLVM IR上。理解这种依赖关系对后面配置CMake构建选项很有帮助——不是你随便勾选所有项目就能顺畅编过的项目之间还有版本匹配和依赖顺序的问题。2.2 核心子项目逐个拆解llvm目录是整个仓库的心脏。它分成include、lib、tools、utils等几个子目录。include里定义了大量头文件包括IR的类型系统、Pass接口、代码生成器的接口lib里是真正的实现比如opt这个优化器、llc这个静态编译器、llvm-as/llvm-dis这类IR汇编/反汇编工具都在llvm/tools下面。如果你只是想用LLVM做静态分析其实不会直接碰这块代码但一旦要写Pass、要理解优化管道这里就是你的主战场。clang是C/C/Objective-C的前端。它负责把源代码解析成AST再做语义分析最终emit出LLVM IR交给后端。clang-tools-extra里塞了一堆基于Clang的辅助工具比如clang-tidy做代码检查、clangd做语言服务、include-what-you-use做头文件清理。lld是一个链接器它和传统GNU ld相比最大的优势是速度快、内存占用低尤其适合大型C项目的链接场景。lldb是基于LLVM的调试器虽然规模和GDB比还有差距但它的架构更现代支持表达式求值、JIT和IDE集成比GDB顺畅得多。2.3 运行时与辅助组件的角色再往下是compiler-rt、libcxx、libcxxabi、libunwind这几个运行时组件。compiler-rt提供了编译器内置函数比如整数除法溢出检查、SanitizerASan、UBSan、TSan的运行时支持。libcxx是C标准库实现也属于LLVM生态的一部分libcxxabi是C ABI的实现负责异常处理、运行时类型信息这些libunwind提供栈回溯能力异常机制的底层就用到它。这几样东西不是所有场景都要编但如果你要构建一个完整的、自洽的C工具链它们就是CLANG_LIBCXX、CLANG_LIBUNWIND这些CMake选项背后的实际组件。mlir近几年风头很劲它提供了一套可扩展的多级IR框架特别适合做深度学习编译器。flang则是Fortran前端被整合进monorepo之后现在也走的是解析到语义落到LLVM IR这条路。openmp是并行运行时bolt是链接后二进制优化器polly是面向循环嵌套的多面体优化框架。这些项目的存在让llvm-project变成了一个几乎覆盖编译全流程的全家桶从前端语言解析、中间优化、后端代码生成、链接、调试、运行时支持、二进制优化全部被你掌握。这也是为什么很多工业级工具链包括一些国产编译器都选择基于它来做二次开发因为它早就不是一个单纯优化器的定位了。提示第一次看源码目录别纠结每个子项目都看懂先建立一个谁负责哪一层的认知地图然后按需深入。我个人的顺序是先llvm目录下的include和lib等真正需要写Pass时再由点带面。3. 从零构建LLVM 15.0.7完整流程与最容易翻车的环节3.1 构建前的环境评估与工具链要求如果你用的是较新的发行版构建LLVM之前先确认几件事GCC版本、CMake版本、Python版本、磁盘空间和内存大小。LLVM对工具链版本有硬性的最低要求因为源码本身采用C17以及部分C20特性编写太老的GCC或Clang会直接编译失败。推荐用GCC 11以上或者Clang 14以上的版本CMake要求3.20以上Python要求3.6以上——LLVM的配置阶段和后期的测试脚本依赖Python。磁盘方面一个完整构建的源码树加构建目录至少要50GB空余空间如果你还要开Debug模式构建体积会再翻一番。内存上配置阶段对内存需求不大但编译阶段会开大量并行任务建议内存不低于16GB否则建议用-j参数控制并行度。整个过程我以版本15.0.7为例这也是网络热词里出现过的版本号。15.0.7属于15系列的一个补丁版本修复了一些安全问题功能上和15.0.0基本一致。如果你用的系统自带Clang或GCC版本偏老建议先升级工具链不然会在编译过程中碰到各种莫名其妙的语法错误排查起来特别费时间。曾经有朋友用Ubuntu 20.04自带的GCC 9编LLVM 15一开始顺利编译到中间某个模块报了C标准库的诡异错误——就是工具链版本不够升级到GCC 11之后同样的配置一次通过。3.2 CMake配置的关键参数与我的推荐组合拿到源码后先建一个build目录然后跑cmake。我常用的配置组合是这样的cmake -G Ninja \ -DCMAKE_BUILD_TYPERelease \ -DLLVM_ENABLE_PROJECTSclang;lld;compiler-rt;libcxx;libcxxabi;libunwind \ -DLLVM_TARGETS_TO_BUILDX86;AArch64 \ -DLLVM_ENABLE_ASSERTIONSON \ -DCMAKE_INSTALL_PREFIX/opt/llvm-15 \ -DLLVM_OPTIMIZED_TABLEGENON \ ../llvm-project/llvm逐项解释一下为什么要这么配。CMAKE_BUILD_TYPERelease是开优化不带的线编出来的工具链是没优化的跑起来慢得让人怀疑人生。LLVM_ENABLE_PROJECTS决定除了LLVM本身之外还要编哪些子项目如果你暂时不需要Clang只想编LLVM核心那就只留llvm但我强烈建议大家至少把clang和lld加进来因为后面写Pass、跑测试都需要它们。LLVM_TARGETS_TO_BUILD这块非常关键默认会编所有目标架构的后端耗时极久如果你是x86开发就直接写X86;AArch64能省下大量构建时间后面需要其他架构再重新configure一次也不迟。LLVM_ENABLE_ASSERTIONSON的意思是在LLVM自身的代码里启用断言检查开发Pass时开着它能提前暴露很多内存或类型系统层面的问题。LLVM_OPTIMIZED_TABLEGENON这个选项值得单独说。TableGen是LLVM里代码生成器基础设施的一个重要工具它负责从描述文件生成大量C代码。这个选项会先用一个Release版的TableGen去编最终版本虽然会增加一小段前期编译时间但整体是划算的因为TableGen在编译过程中的调用频率极高。3.3 实际构建中的性能优化与卡点排查配置完成后就是编译用Ninja作为构建系统是因为它在增量编译和并行度控制上比Makefile好太多。构建命令很简单cmake --build . -j$(nproc)但别直接-j$(nproc)如果你内存不够比如只有8GB32核全并行会让OOM杀手毫不留情地把编译进程杀掉。这时候要手动限制并行度比如-j4或者-j6。我自己测试过16GB内存配8核用-j8是稳定的32GB可以开到16。编译整个Release版加clang和lld耗时大概在30分钟到1小时左右具体取决于你的CPU。如果时间紧张可以加ccache来缓存编译产物下次重新构建或者切分支时提速非常明显。构建过程中最常遇到的几个坑我逐个说下。第一个是缺zlibLLVM在压缩Binary时依赖zlib少了它会报Could NOT find ZLIB装一下系统包就行。第二个是缺ncursesLLDB需要用到终端UI库如果你不编LLDB可以不管但编了LLDB就绕不开。第三个是Python路径问题某些系统上CMake会找到Python 2而不是Python 3导致配置阶段直接报错这时候需要在CMake命令里显式指定-DPython3_EXECUTABLE/usr/bin/python3。第四个是GLIBCXX版本问题编译过程中如果报找不到GLIBCXX_3.4.29这类符号就是系统libstdc版本太老升级GCC解决别想着绕过绕不过的。3.4 安装与验证拿到一份可用的工具链编译结束后验证成果的方式很简单cmake --install .安装到/usr/local或者你指定的前缀目录。装完之后跑一下clang --version确认版本号是15.0.7再用一个hello world试试clang -O2 -S -emit-llvm hello.c -o hello.ll这条命令会把C源码编译成LLVM IR文件打开hello.ll能看到一大堆开头的全局符号和define开头的函数定义这就是你亲手构建出来的编译器在前端阶段产出的结果。如果这一步顺了说明整个工具链基本没问题。整个构建过程虽然漫长但回报很大——你手上现在有一份完全可以自己掌控的编译器后续想加Pass、改优化策略、做链接优化都是在这个基座上展开的。4. llvmpipe与256 bits软件渲染器背后的JIT编译链路4.1 llvmpipe到底是个什么东西上网搜LLVM相关热词时经常会看到一条串着版本号的横幅比如Mesa 23.2.0 llvmpipe (LLVM 15.0.7, 256 bits)。这里的llvmpipe并不是llvm-project仓库里的项目它是Mesa图形驱动栈中的一个软件光栅化器。Mesa是Linux上的一套OpenGL/Vulkan实现当你的机器没有独立显卡、或者显卡驱动有问题、或者你处于无头服务器环境时Mesa会用软件方式模拟GPU的渲染管线llvmpipe就是其中负责把图形管线跑在CPU上的那一层。理解了这一点256 bits也顺理成章了。它指的是llvmpipe在JIT编译时生成的SIMD指令宽度。现代x86 CPU的AVX2指令集是256位宽一次能处理8个32位浮点数或者4个64位浮点数。llvmpipe的策略是把图形渲染中大量逐像素、逐顶点的计算向量化每次用SIMD指令处理8个像素所以你在Mesa的启动日志里看到256 bits就说明它在用AVX2指令集路径。如果CPU只支持SSE2日志里就会显示128 bits。这也是为什么llvmpipe的性能表现和CPU的SIMD能力强相关——AVX2的CPU跑llvmpipe比只支持SSE2的旧CPU快接近一倍。4.2 llvmpipe和LLVM的关系IR到机器码的桥梁llvmpipe和LLVM的关系是整个软渲染架构里最值得琢磨的地方。传统软渲染器通常是手写大量汇编或者SSE intrinsics来实现光栅化维护成本极高而且每种新指令集都要重新适配。llvmpipe换了一种思路它把渲染的管线编译过程拆成前端和后端。前端描述渲染状态、顶点处理、像素着色逻辑——这些描述会被翻译成LLVM IR然后LLVM作为JIT编译器在运行时把这些IR编译成当前CPU架构的机器码。因为LLVM天然支持多目标架构和不同SIMD级别llvmpipe就省掉了维护多套汇编实现的功夫只需要面向LLVM IR编程剩下的代码生成全部交给LLVM。这个过程的具体链路是Mesa的着色器编译器把GLSL/Vulkan着色器翻译成中间表示NIRllvmpipe拿到NIR后用LLVM后端生成主机代码。当程序运行时调用了某个绘制指令llvmpipe会先去查有没有已编译好的着色器没有就现场JIT编译一份并缓存下来。这就是为什么你第一次跑一个OpenGL程序时会有点顿挫感后面就流畅了——那次顿挫就是JIT编译花的时间。这种设计跟Java的JVM有点像同一份字节码在不同CPU上运行时JIT编译出不同指令集层面的机器码换到支持AVX-512的CPU上llvmpipe会自然生成宽度更高的SIMD指令软件层代码基本不用改。4.3 具体场景什么时候你其实在用llvmpipe很多开发者没有意识到自己天天在用llvmpipe。最常见的是云服务器和CI环境这类机器没有GPU跑测试时如果渲染相关Mesa会自动落到llvmpipe。我遇到过的最典型的情况是跑一套E2E浏览器测试浏览器调WebGL测试环境是Docker容器没有显卡设备映射。这时候如果Mesa没装好WebGL直接报错装好llvmpipe后一切正常只是帧率很低。这也解释了为什么llvmpipe对CI稳定性很重要它让你在无GPU环境下也能完整跑通图形相关测试。另一个高频场景是虚拟机。VirtualBox这类虚拟机软件对OpenGL支持做的并不好默认会用llvmpipe做软件渲染。一旦你启动虚拟机里的某3D程序CPU占用率瞬间拉满就是llvmpipe在加班。对这个场景知道llvmpipe的存在反而能帮上忙——根据日志里的llvmpipe (LLVM x.y.z, 256 bits)判断你装的Mesa版本换个新版本可能SIMD优化更好性能会有提升。这部分经验很实际不用动显卡只升级Mesa虚拟机中的图形性能就可能明显变好。5. 在llvm-project里动手自定义Pass的完整走查5.1 New Pass Manager的基本框架与踩坑认知到了这一步你已经有了一个能跑通的LLVM 15.0.7工具链也理解了llvmpipe跟LLVM的JIT关系。现在该上手做点正事了写一个自定义Pass。这是把看源码变成用源码最关键的一个动作也是很多人卡住的地方。LLVM 15在Pass机制上有个重大变化老Pass Manager已经被移除默认全部用New Pass Manager。所以网上很多教程里写的legacy::FunctionPass、registerPass这些老API在LLVM 15上根本编译不过。写Pass之前先搞清楚New Pass Manager的几个核心概念PassInfoMixin、PreservedAnalyses、AnalysisManager。所有新风格的Pass都从一个Mixin继承声明自己分析或修改的是函数、模块还是循环PreservedAnalyses用来告诉优化管道你的Pass保留了哪些分析结果如果不声明管道会保守地清空所有缓存性能会下降。理解这几个概念再回头看官方文档会觉得轻松很多。5.2 一个能编译的简单Pass统计函数调用次数下面我用一个实例演示写Pass的标准动作。目标统计当前模块里所有函数被其他地方调用的总次数并把结果打印出来。这个Pass做不了太多事但非常适合作为第一个跑通的Pass因为它的逻辑足够简单你只需要关注Pass的骨架和接线方式。// CallCounter.cpp #include llvm/IR/Function.h #include llvm/IR/Module.h #include llvm/IR/Instructions.h #include llvm/Pass.h #include llvm/Passes/PassBuilder.h #include llvm/Passes/PassPlugin.h #include llvm/Support/raw_ostream.h using namespace llvm; namespace { struct CallCounter : public PassInfoMixinCallCounter { PreservedAnalyses run(Module M, ModuleAnalysisManager MAM) { unsigned callCount 0; for (auto F : M) { for (auto BB : F) { for (auto I : BB) { if (auto *CI dyn_castCallInst(I)) { (void)CI; callCount; } } } } errs() [CallCounter] Total call instructions: callCount \n; return PreservedAnalyses::all(); } }; } // namespace extern C ::llvm::PassPluginLibraryInfo LLVM_ATTRIBUTE_WEAK llvmGetPassPluginInfo() { return { LLVM_PLUGIN_API_VERSION, CallCounter, LLVM_VERSION_STRING, [](PassBuilder PB) { PB.registerPipelineParsingCallback( [](StringRef Name, ModulePassManager MPM, ArrayRefPassBuilder::PipelineElement) { if (Name call-counter) { MPM.addPass(CallCounter()); return true; } return false; }); }}; }代码逻辑不复杂遍历Module下所有的Function每个Function里遍历BasicBlock每个BasicBlock里遍历指令用dyn_castCallInst判断这条指令是不是调用指令是的话计数加一。最终把统计结果打到stderr上。注意函数名llvmGetPassPluginInfo是插件机制的入口必须用extern C导出并且带上LLVM_ATTRIBUTE_WEAK这是LLVM插件加载方式要求的我早期在这里栽过跟头符号名写错一个opt工具怎么加载都找不到插件。5.3 编译和运行Pass踩过哪些坑编译这个Pass不能直接甩给gcc或者clang要像下面这样用LLVM提供的编译参数clang -stdc17 -fno-rtti -fno-exceptions \ $(llvm-config --cxxflags) \ -shared -fPIC CallCounter.cpp -o libCallCounter.so-fno-rtti和-fno-exceptions特别重要因为LLVM自身编译时就关闭了RTTI和异常你的插件也必须保持一致否则链接阶段会报一堆undefined symbol。llvm-config --cxxflags返回LLVM的头文件路径和编译选项这把头文件对应关系一次性搞定。如果编译时报找不到PassPlugin.h说明你的llvm-config指向的是系统自带的旧版LLVM而不是你刚构建的15.0.7。这时候需要把/opt/llvm-15/bin放到PATH前面然后用这个目录下的llvm-config重新获取环境变量。编译完之后在测试代码上运行echo int add(int a, int b) { return a b; } test.c clang -emit-llvm -c test.c -o test.bc opt -load-pass-plugin./libCallCounter.so \ -passescall-counter \ --disable-output test.bc这里有个技术点需要说明-passes参数里写的call-counter正是我们在registerPipelineParsingCallback代码里注册的Pass名称两边必须严格一致否则opt会报Unknown pass name。运行后终端会打印出[CallCounter] Total call instructions: 0因为test.c里并没有发生函数调用只有定义。你可以多写几个函数互相调用再试一次这个Pass就能统计到数字了。这也是为什么LLVM官方把它叫做Hello World级别的Pass它验证的是你从编译插件到加载执行全链路是否打通。5.4 Pass开发的进阶注意事项上面这个例子虽然简单但已经涵盖了Pass开发里最容易出错的三件事插件入口导出、New Pass Manager的类型匹配、编译参数对齐。等你掌握了这个流程继续往里加东西就容易多了。我记得有次做一个更复杂的分析Pass需要遍历每个函数的参数并判断是否是指针类型这时候要处理整数类型、指针类型、聚合类型之间的差异还得考虑dyn_cast用错case会导致崩溃。这些经验只能靠多跑多调试积累没有捷径。另一个建议是写Pass之前先搜索一下llvm/lib/Transforms目录下的现有实现很多你想实现的功能大概率已经有现成模板改造比从零写稳得多。提示调试Pass的时候搭配-print-after-all或-print-before-all看优化管道每一步的IR变化能快速定位问题出在哪一步。这条经验帮我省了无数时间。6. 版本演进观察从15.0.7到新版本的生态变化与升级注意事项6.1 15.0.7属于哪个时代的产品版本号15.0.7属于LLVM 15系列。这个版本处于一个分水岭位置它默认启用了New Pass Manager移除了legacy pass同时宣告了Opaque Pointer的过渡。Opaque Pointer的意思是不再区分i32*、i8*这类带类型指针统一用ptr表示这大大简化了IR的类型系统但对现有代码的影响很大——任何依赖指针类型做判断的Pass和工具在15之后都要修改。很多第三方着色器编译器、静态分析工具在这个版本上都要适配这也是为什么很多WebGPU和Vulkan实现当时在升级LLVM版本的时候都带着封发布。从实际使用角度LLVM 15对CPU后端和优化器的改进虽然稳定但相比后续的16、17、18、19版本它在编译速度、sanitizer能力、mlir的成熟度上还是明显落后的。所以如果你的目标是学习LLVM开发选15没问题如果是要上生产环境做代码优化建议跳级到更晚版本。但无论选哪个版本目录结构、CMake配置方式、Pass编写范式都是基本相同的15学通换新版本只需要关注官方release note上的breaking changes。6.2 从15到更新的版本升级迁移要小心什么升级LLVM版本最怕的不是API不兼容而是看起来能用但行为变了。API不兼容编译器会直接报错行为变化则会悄悄坑你。举两个最常见的例子优化管道默认的pass顺序在16之后有过几次调整同一个IR文件用15和17分别做-O2产物可能相差百分之几的性能这不算bug是优化策略的演进。另外一个是Clang对C标准的支持变化15默认C1717默认C20如果代码依赖旧的隐式转换规则升级后可能莫名其妙多了warning甚至error。我的建议是如果已经有基于LLVM 15的业务代码先别急着升级。先跑一遍全量测试把编译期告警清完再观察运行期行为差异。调包Pass的名字、头文件路径、CMake变量名这种事官方release note都有写老老实实对照着改就行。真正需要谨慎的是那些没有写在release note里的细微变化比如某个attribute的语义调整、某个优化对未定义行为的假设更严苛了。这类问题只能靠测试覆盖来兜底没有侥幸空间。6.3 生态里那些容易被忽略的邻居项目最后提一下llvm-project生态里容易被忽略的几个组件它们在特定场景下作用很大。bolt做链接后二进制优化对大型服务端程序的启动时间和体积都有可观提升适合对性能抠得极细的团队。mlir在AI编译领域越来越重要如果你做深度学习模型编译器llvm-project里的mlir就是必选项。polly做多面体优化对循环嵌套密集的数值计算代码效果显著但配置复杂度也高。compiler-rt里的sanitizer已经是C/C内存安全检查的事实标准CI里跑ASan几乎是标配。7. 一些基于实操的收尾心得与建议把llvm-project完整构建一遍、写一个能跑的Pass、再用它去理解llvmpipe的JIT编译流程这一圈走下来我的一个很深的体会是编译器领域没有太多玄学绝大多数疑惑都能通过翻源码和跑实验得到答案。拿我开头提到的那个pass顺序问题来说最后就是靠打印IR、逐个开关优化项定位到是某个早期pass把一个分支结构改掉了才导致后面的分析失效。这种问题如果只知道用LLVM而不知道去llvm-project源码里找原因可能永远也解决不了。如果只能给一条建议我会说别怕构建时间长把llvm-project完整从源码编译一次比看十篇源码分析文章都有用。构建过程中遇到的每一个报错、每一次查阅CMake变量、每一条include路径都是对这套工具链工作原理的深度接触。而且有了这个本地工具链你可以随时改代码、重新生成、测试自己的Pass这个动手能力是看文档永远拿不到的。至于后续扩展你可以从两个方向深入一是研究llvm的tablegen机制理解代码生成器的描述语言如何驱动后端生成指令选择代码这是编译器后端开发的核心二是看看mlir的多级IR设计它把编译器变成了一块块可插拔的积木从中能学到很多通用的中间表示设计思路。无论选哪条路之前从头构建和写Pass的经验都会成为你继续深入的底气。