大概所有第一次看到“llvmpipe (LLVM 15.0.7, 256 bits)”这行信息的人心里都会咯噔一下LLVM不是编译器吗为什么出现在图形栈的报错里我当年第一次在无GPU的服务器上跑OpenGL程序时看到这行字也花了好一阵子才弄明白这其实是Mesa里的软件渲染器llvmpipe在告诉你它正在用LLVM把图形着色器编译成CPU指令256 bits则代表当前JIT生成代码用到了256位SIMD向量宽度。说回llvm-project本身它远不止“一个编译器”这么简单。它是一个由LLVM核心库、Clang前端、LLD链接器、libc标准库、compiler-rt运行时库、LLDB调试器、MLIR、Flang等一系列子项目组成的庞大基础设施。无论你是想研究编译器优化、给语言加前端、做GPU软件栈还是排查构建系统里的诡异链接错误这套源码都值得你花时间读一读。这篇文章我会从llvmpipe这个入口讲起再带你从源码布局、构建配置、Pass开发、版本迁移到工程集成的常见坑走一遍我实际折腾llvm-project的路线。1. 一条“llvmpipe 256 bits”信息背后llvm-project到底在解决什么问题llvmpipe是Mesa 3D图形库中的一个软件光栅化器。简单说当系统没有可用GPU或显存不够时OpenGL/Vulkan命令会被Mesa接管llvmpipe负责在CPU上把这些图形管线模拟出来。问题是怎么模拟才够快如果每个着色器都用解释器慢慢跑性能会惨不忍睹。llvmpipe的答案是把着色器先翻译成LLVM IR再通过LLVM的JIT引擎在运行时生成当前CPU能直接执行的机器码。这样一来一个复杂的片段着色器在第一次执行时会被编译成高度优化的原生指令后续再跑就能直接享受AVX2甚至AVX-512带来的并行吞吐。所以那行“llvmpipe (LLVM 15.0.7, 256 bits)”其实是Mesa在构造渲染器版本字符串时拼出来的运行时信息它内部链接的LLVM是15.0.7版本生成代码时使用的最大SIMD向量位宽是256位。很多人以为这是报错其实它不是这是正常的上下文打印。不过这句话确实点出了一个很多人忽略的事实llvm-project的价值绝不在编译器前端而在“把高级语义高效翻译成目标机器指令”这一整套可复用技术栈。Clang只是站在LLVM肩膀上的一个前端产物MLIR、Flang、LLVM自身都在利用同一套中间表示和代码生成后端。理解了这一点也就理解了你为什么要啃llvm-project源码你需要的不只是“会写C的编译器”而是一套能嵌入自己项目、按需定制、可控可调的编译基础设施。它解决的问题从语言解析、语义分析到中端优化、指令选择、寄存器分配再到链接和运行时几乎覆盖了编译与执行的全部环节。对我个人来说llvm-project最大的吸引力在于它把“编译器”拆成了一堆可以独立使用的库而不是一个黑盒可执行文件。你可以只调用它的优化器也可以只复用它的指令选择器甚至可以让它在运行时动态生成一段专用计算逻辑。llvmpipe就是这种能力的典型用户。2. 拿到llvm-project源码后先看清目录再动手构建2.1 源码获取、版本选择与镜像llvm-project的源码托管在GitHub官方仓库日常开发基本都基于它的monorepo结构。拉取方式很简单git clone https://github.com/llvm/llvm-project.git cd llvm-project git checkout llvmorg-15.0.7这里有个容易犯的错不要直接clone完就在默认分支上乱build。默认分支往往是正在剧烈开发的主线API天天变今天能编过的代码明天可能就断了。如果是为了复现生产环境问题或者想跟某个具体版本比如文中反复提到的15.0.7保持一致务必checkout到对应tag。国内网络经常clone到一半失败遇到这种情况可以试试把仓库地址换成镜像或者用--depth1只拉取最新commit。如果你需要子模块再执行git submodule update --init --recursive不过llvm-project现在基本已经把依赖收进monorepo了这一步在多数场景下可以省略。拿到源码后第一件事不是跑cmake而是先浏览根目录下的子项目。你会看到llvm/是核心clang/是C/C前端lld/是链接器libcxx/、libcxxabi/是C标准库实现compiler-rt/提供Sanitizer和运行时库lldb/是调试器mlir/是通用多级IR框架flang/是Fortran前端polly/做循环优化openmp/管理OpenMP运行时。目录之间的关系不是“一个可执行文件里包含所有”而是通过CMake的组件化机制按需组合。这个设计是llvm-project能够被llvmpipe这类大型项目嵌入的关键。2.2 CMake配置里哪些开关必须关心构建llvm-project最常用的组合是Ninja Clang但第一遍构建不一定非要用Clang系统自带的GCC也能完成。一个我验证过很多次的最小配置是cmake -G Ninja -S llvm -B build \ -DCMAKE_BUILD_TYPERelease \ -DLLVM_TARGETS_TO_BUILDhost \ -DLLVM_ENABLE_PROJECTSclang;lld cmake --build build --target llc opt clang几个关键开关值得解释一下LLVM_TARGETS_TO_BUILD控制要生成哪些后端目标。默认是all意味着会把X86、ARM、AArch64、RISC-V等几十个后端的代码全部编译进去构建时间和磁盘占用直接爆炸。日常开发用host就够了只编当前机器的目标架构。LLVM_ENABLE_PROJECTS启用llvm核心之外的前端和工具链组件。注意这里会显著增加编译时间如果你只是想研究优化器或Pass可以先只编核心不加任何项目后面需要时再补。LLVM_ENABLE_RUNTIMES这是跟LLVM_ENABLE_PROJECTS容易混淆的另一套机制主要用于构建compiler-rt、libcxx、libcxxabi这些运行时库。它们往往依赖已经构建好的编译器所以放在runtime阶段单独处理而不是跟普通项目一起编。第一次构建llvm-project请不要对时间抱有任何幻想。即使只编核心加X86后端在8核机器上也可能需要20-30分钟如果选了all目标几十GB磁盘空间和数小时编译都是常态。我的建议是先小步快跑把llc和opt编出来这两个工具一个是代码生成器一个是优化器足够你验证大部分想法。等到确实需要Clang、LLD再增量补上CMake构建系统的增量能力能帮你省掉大量重复等待。3. 第一个Pass理解llvm-project最经典的扩展点3.1 用一个FunctionPass跑通opt对于刚接触llvm-project的人最值得上手的切入点不是改后端指令选择器而是写一个LLVM Pass。Pass是LLVM优化流程里的基本处理单元它遍历IR并做某种变换或分析。写一个最简单的Pass可以让你在几小时内跑通“源码-IR-优化-输出”的完整工具链。这里我用New Pass Manager的写法给你一份可直接运行的代码。假设你要给每个函数插一条调试输出#include llvm/IR/Function.h #include llvm/IR/IRBuilder.h #include llvm/IR/Instructions.h #include llvm/IR/Module.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 { class MyFunctionPass : public PassInfoMixinMyFunctionPass { public: PreservedAnalyses run(Function F, FunctionAnalysisManager AM) { errs() Function: F.getName() \n; return PreservedAnalyses::all(); } }; } // namespace llvm::PassPluginLibraryInfo getMyPluginInfo() { return {LLVM_PLUGIN_API_VERSION, MyFunctionPass, LLVM_VERSION_STRING, [](PassBuilder PB) { PB.registerPipelineParsingCallback( [](StringRef Name, FunctionPassManager FPM, ArrayRefPassBuilder::PipelineElement) { if (Name my-function-pass) { FPM.addPass(MyFunctionPass()); return true; } return false; }); }}; } extern C LLVM_ATTRIBUTE_WEAK ::llvm::PassPluginLibraryInfo llvmGetPassPluginInfo() { return getMyPluginInfo(); }把它编成动态库然后用opt加载clang -O0 -emit-llvm -c test.c -o test.bc opt -load-pass-plugin./libMyPass.so -passesmy-function-pass test.bc -o /dev/null注意这里用的是新PM写法不是老式initFunctionPass那套。如果你手头的教程还在让你继承FunctionPass、用runOnFunction那多半是基于Legacy PassManager的老文档在LLVM 15上虽然还能编译但已经不是推荐路径了。3.2 为什么说opt是调后端前必须掌握的“手术台”写Pass容易但调试Pass才是真正的分水岭。opt这个工具就是你的手术台它允许你对任意IR文件执行任意Pass组合并在每个Pass后查看IR发生了什么。我最常用的三个参数是-print-after-all在每一个Pass运行结束后打印整个模块的IR。-filter-print-funcsfuncName只打印指定函数的IR避免输出太大。-debug-onlymy-debug-tag配合LLVM_DEBUG宏输出指定调试信息而不是看所有日志。举个例子当你怀疑某个优化Pass把你的循环变量搞没了可以用opt -passesloop-mssa,licm -print-after-all test.bc逐段对照变换前后的IR。我第一次定位CSE公共子表达式消除导致的问题就是靠-print-after-all把数万行IR翻了个底朝天最后发现是某个Pass的PreservedAnalyses没写对错误地保留了分析结果导致后续Pass用了陈旧的依赖信息。这种问题看源码很难一眼看到但配合IR输出后逻辑会清楚得多。3.3 LLVM IR数据结构的“卑鄙”之处在你动手写Pass之前还需要对LLVM IR的数据结构有点概念。LLVM IR本质上是一个SSA形式的有向图Module持有若干个FunctionFunction由若干BasicBlock组成BasicBlock里是一条条Instruction指令间通过Value和Use互相引用。这个结构和普通AST最大的区别是每个操作数都直接指向它的定义指令修改起来非常容易造成悬垂引用。新手最常见的坑是遍历指令时往当前BasicBlock里插入新指令导致迭代器失效。LLVM的IRBuilder默认会在某个插入点之后插入但如果你同时还在迭代指令插入行为就可能改变你还没访问到的指令的排布。稳妥的做法是先把要处理的指令收集到一个SmallVector里遍历完后再统一插入或删除。另外修改IR后务必正确返回PreservedAnalyses。如果你动了函数体却返回PreservedAnalyses::all()LLVM会认为所有分析结果仍然有效后面拿到陈旧分析数据的Pass会给你带来难以名状的bug。这也是很多Pass编写者一上来就踩的坑。4. 版本号里的现实LLVM 15.0.7带来哪些API断裂和迁移任务4.1 NewPM全面接管Legacy PassManager退出LLVM 15是一个分水岭。从这一版开始面向新Pass管理器的优化管线成为唯一默认路径旧式Pass的许多API被标记为deprecated甚至有部分在后续版本里被直接删除。如果你是从LLVM 12或更早版本迁移过来的项目大概率会看到一堆编译器报错说找不到legacy::FunctionPass相关头文件或者createLegacyPMFunctionPass之类的函数已经不存在。我当时迁移一个自定义优化插件时流程大致是把继承的FunctionPass改成PassInfoMixinT把runOnFunction改成run(Function F, FunctionAnalysisManager AM)把INITIALIZE_PASS这种宏拿掉换成PassPluginLibraryInfo注册把createXxxPass工厂函数删掉直接在PassBuilder的PipelineParsingCallback里构造。看起来改动量不大但会让你重新理解Pass的生命周期。新PM里Pass对象可以短生命周期地多次创建分析结果通过FunctionAnalysisManager显式请求而不是靠老的getAnalysisT()全局方式。4.2 从代码和构建日志里定位破坏性变更升级LLVM版本时如果你不想一篇篇翻文档最快的方式是直接看构建日志和源码里的deprecated注释。以下是我在LLVM 15上遇到过的典型错误整理成了一张对照表旧写法LLVM 15上的表现改法llvm::legacy::PassManager头文件路径变化编译报错改用llvm::PassBuilderPointerType::getUnqual(...)报错或产生意外行为不再有typed pointer直接用PointerType::get(ctx, addrspace)GetElementPtrInst::Create带typed pointer参数编译告警或错误去掉pointee类型参数只保留元素类型TargetMachine::createDataLayout()方法签名调整使用DL TM.createDataLayout()注意const限定IRBuilder::CreateLoad传入typed pointer运行期断言使用Type *参数去掉pointer element type这些变化背后最大的推手是“Opaque Pointers”机制。LLVM早年为了在类型系统里保留指针指向的类型信息在PointerType里记录了一个ElementType也就有了typed pointer。但从LLVM 14开始这种设计成了优化器推行多态和泛型化的阻碍所以逐步转向不区分指针指向类型直接让所有指针都是不透明指针。这个改动对整个代码生成层影响非常大也让不少老的Pass在15上跑起来直接崩。4.3 TableGen、OpaquePtr等容易被忽略的变化除了Pass API和指针类型LLVM 15还有一批不那么显眼但同样致命的改动。比如llvm-tblgen生成的代码结构变了后端开发者如果自己维护指令集描述文件会发现include/llvm/Target/Target.td里的某些类名或字段定义被重命名还有MCInst相关内容调整影响汇编器实现。另一个常见的坑是C标准要求提高LLVM 15已经要求你的工具链至少支持C17如果是老旧的GCC 5或Clang 3.x编译过程中会出现一堆莫名其妙的模板错误。我的建议是升级前先读llvm/docs/ReleaseNotes.rst和llvm/docs/Deprecation.rst这两个文件把每个版本的breaking change写得最集中。不要只看网上零散教程很多教程写的其实是旧接口。如果项目里有大量自定义Pass先在独立分支上跑一遍完整构建把编译错误全部修完再合并不要在主分支上边改边看否则很容易陷入“改了一个接口又冒出三个新错误”的泥潭。5. 将llvm-project集成进自有工程时链接与ABI的深坑5.1 llvm-config与CMake中find_package(LLVM)的正确姿势自己玩LLVM时用命令行工具就够了但一旦你要把自己写的Pass或工具链集成进项目事情就变得复杂。LLVM官方提供的集成方式有两种llvm-config和CMake的find_package(LLVM)。先看llvm-config它相当于一个编译参数查询工具llvm-config --cxxflags --ldflags --libs core在构建系统里调用它可以拼出需要包含的头文件路径和库文件列表。但这里有坑--libs core只会给出核心库如果你的Pass还需要support、analysis等就得自己把它们加到参数里不然链接时一堆undefined reference。CMake推荐用find_package方式前提是你先通过make install把LLVM装到了某个前缀或者设了LLVM_DIR指向build目录find_package(LLVM REQUIRED CONFIG) message(STATUS Found LLVM ${LLVM_PACKAGE_VERSION}) include_directories(${LLVM_INCLUDE_DIRS}) add_definitions(${LLVM_DEFINITIONS}) add_executable(my_tool my_tool.cpp) target_link_libraries(my_tool PRIVATE LLVM)这种写法的潜在问题是如果系统里装了一份老版本LLVM而你又把新版本装到了/opt/llvm-15find_package很可能找到系统那份导致头文件和库版本不一致。解决办法是显式设置-DLLVM_DIR/opt/llvm-15/lib/cmake/llvm用绝对路径排除干扰。5.2 动态库、静态库和libLLVM.so的取舍LLVM库有三种分发方式大量静态库每个组件一个.a、一个合成的动态库libLLVM.so、以及按组件拆分的动态库。选择不同方式编译和运行行为差异非常大。个人经验是调试阶段用静态库最省心链接过程中任何符号缺失都会在构建期暴露交付工具给他人时用libLLVM.so更理性因为最终可执行文件体积会小很多。但如果要用libLLVM.so必须在构建LLVM时开启LLVM_BUILD_LLVM_DYLIBON然后在你的CMake里加LLVM_LINK_LLVM_DYLIBON。否则会出现一个经典问题你的可执行文件同时链接了libLLVM.so和一堆静态组件库结果运行时符号重复定义表现为段错误或直接被dynamic loader拒绝。还有一个容易忽略的点LLVM 15的C ABI对标准库版本非常敏感。如果你用GCC 9编译了LLVM再用GCC 12编译自己的插件去加载它一旦两者libstdc的std::string等布局不一致Pass加载时就会崩在构造函数里报错还很不直观。这种问题最简单的规避方式就是构建LLVM的编译器和你自己项目的编译器保持同版本至少保持同一主版本。听起来很像废话但很多人栽在上面。5.3 最容易栽的C ABI问题除了编译器版本另一个ABI深坑隐藏在宏定义和编译选项里。LLVM在头文件里大量使用LLVM_ENABLE_ABI_BREAKING_CHECKS、_DEBUG这类编译期宏。如果你的编译选项和构建LLVM时不一致比如LLVM是Release构建、定义了NDEBUG而你的工程是Debug构建、没有定义NDEBUG那么某些inline函数看到的宏状态不同数据结构的内存布局就会不一致。这会导致你在调用看似简单的接口时直接崩溃比如isaFunction、castCallInst这种动态类型检查都会访问错误的内存偏移。要定位这类问题先试试在CMake里跟上LLVM构建时一致的选项特别是CMAKE_BUILD_TYPE。如果必须混合那就尽量用动态库而不要静态库因为动态库库内部的ABI一致性由动态库自身保证你的代码只暴露在接口边界。还有一招是用llvm-config --cxxflags的输出直接作为你的CXXFLAGS让它帮你把宏定义统一起来这能避开绝大多数布局不一致问题。6. 跳进大型使用方llvmpipe之前读懂LLVM优化与调试辅助设施6.1 llvmpipe是如何借助LLVM加速图形管线的理解了Pass和集成问题之后再回头看llvmpipe你的视角会完全不同。llvmpipe并不打算一遍遍解释GLSL/Vulkan着色器它在运行时把着色器代码转化成一个LLVM模块然后调用LLVM的JIT编译管线执行。这里面的关键点是Graphic管线里一个着色器可能要处理成千上万个顶点或像素如果能自动生成一批宽度为256位或512位的SIMD指令让CPU一个指令周期同时处理8个浮点性能就会比纯标量执行快好几倍。llvmpipe中的“256 bits”就是它对这种向量化能力的总结。它通过LLVM的矢量类型和自动向量化把标量Shader代码变成针对当前CPU微架构优化的SIMD代码。MLIR甚至可以被用来做更高层的Tile调度这段在Mesa的代码里写得很清晰。当你用llvmpipe跑一个复杂3D场景时CPU温度飙升是常态因为LLVM生成的代码在“压榨”CPU每个流水线。理解这层关系后你就明白为什么llvmpipe会把自己的版本信息打印成LLVM版本号——它本质上是一个深度依赖LLVM的运行时编译器。6.2 OptBisect和llvm-reduce定位Pass问题如果你也想在类似llvmpipe的大工程里定位“到底是哪个优化Pass搞崩了”LLVM提供了一对利器opt-bisect和llvm-reduce。opt-bisect的思路是在整条优化管线里设置一个“截止序号”每运行一个Pass就检查当前编号是否超过截止值如果超过了就跳过从而用二分法快速定位是哪个Pass引入了错误。使用方式opt -O2 -opt-bisect-limit100 test.bc -o output.bc如果输出正常就增大limit不正常就缩小范围多试几次就能定位到具体Pass编号。这个工具对Mesa这类大型使用方同样有效因为你可以把优化崩溃的场景简化成一个独立的着色器IR然后逐段二分排查。llvm-reduce则是做测试用例最小化的它能把一个几万行的IR文件缩减成几十行同时仍然保留触发bug的特征。用法是准备两样东西一个初始IR文件一个判断“bug是否出现”的脚本llvm-reduce --testcheck.sh --ir-passesopt -passesloop-vectorize crash.ll脚本返回0表示bug复现成功返回非0表示未能复现。llvm-reduce会不断尝试删除IR中的函数、指令或模块直到无法再删为止。这对上报LLVM上游bug几乎是必备流程在开发自己的Pass时也能帮你快速把复杂案例简化成最小可复现样本省去大量手工剥离代码的时间。我在实际定位一个向量化导致的浮点精度问题时就是把llvmpipe的输出转成LLVM IR再用opt-bisect锁定了某个speculation pass最后用llvm-reduce拿到了一个能稳定复现的100行以内案例。整个过程比肉眼读代码高效太多。如果你打算长期跟llvm-project打交道这两样工具值得尽早熟悉。最后再分享一个个人习惯无论是提交代码还是在博客里记录经验我都会把当时的llvm-config --version、llc --version和完整的CMake命令贴在开头。很多奇怪的问题最后追根溯源都落在“LLVM版本和构建选项不一致”上。llvm-project是个包容性很强的项目但也是个对ABI和版本极度挑剔的项目。心平气和地把版本差异排查清楚很多“不可能”的错误其实都能顺藤摸瓜找到答案。 
长河君 · 2026/9/18 10:17:45 · 阅读 1.2k 从llvmpipe到llvm-project：软件渲染背后的编译基础设施解析
大概所有第一次看到“llvmpipe (LLVM 15.0.7, 256 bits)”这行信息的人心里都会咯噔一下LLVM不是编译器吗为什么出现在图形栈的报错里我当年第一次在无GPU的服务器上跑OpenGL程序时看到这行字也花了好一阵子才弄明白这其实是Mesa里的软件渲染器llvmpipe在告诉你它正在用LLVM把图形着色器编译成CPU指令256 bits则代表当前JIT生成代码用到了256位SIMD向量宽度。说回llvm-project本身它远不止“一个编译器”这么简单。它是一个由LLVM核心库、Clang前端、LLD链接器、libc标准库、compiler-rt运行时库、LLDB调试器、MLIR、Flang等一系列子项目组成的庞大基础设施。无论你是想研究编译器优化、给语言加前端、做GPU软件栈还是排查构建系统里的诡异链接错误这套源码都值得你花时间读一读。这篇文章我会从llvmpipe这个入口讲起再带你从源码布局、构建配置、Pass开发、版本迁移到工程集成的常见坑走一遍我实际折腾llvm-project的路线。1. 一条“llvmpipe 256 bits”信息背后llvm-project到底在解决什么问题llvmpipe是Mesa 3D图形库中的一个软件光栅化器。简单说当系统没有可用GPU或显存不够时OpenGL/Vulkan命令会被Mesa接管llvmpipe负责在CPU上把这些图形管线模拟出来。问题是怎么模拟才够快如果每个着色器都用解释器慢慢跑性能会惨不忍睹。llvmpipe的答案是把着色器先翻译成LLVM IR再通过LLVM的JIT引擎在运行时生成当前CPU能直接执行的机器码。这样一来一个复杂的片段着色器在第一次执行时会被编译成高度优化的原生指令后续再跑就能直接享受AVX2甚至AVX-512带来的并行吞吐。所以那行“llvmpipe (LLVM 15.0.7, 256 bits)”其实是Mesa在构造渲染器版本字符串时拼出来的运行时信息它内部链接的LLVM是15.0.7版本生成代码时使用的最大SIMD向量位宽是256位。很多人以为这是报错其实它不是这是正常的上下文打印。不过这句话确实点出了一个很多人忽略的事实llvm-project的价值绝不在编译器前端而在“把高级语义高效翻译成目标机器指令”这一整套可复用技术栈。Clang只是站在LLVM肩膀上的一个前端产物MLIR、Flang、LLVM自身都在利用同一套中间表示和代码生成后端。理解了这一点也就理解了你为什么要啃llvm-project源码你需要的不只是“会写C的编译器”而是一套能嵌入自己项目、按需定制、可控可调的编译基础设施。它解决的问题从语言解析、语义分析到中端优化、指令选择、寄存器分配再到链接和运行时几乎覆盖了编译与执行的全部环节。对我个人来说llvm-project最大的吸引力在于它把“编译器”拆成了一堆可以独立使用的库而不是一个黑盒可执行文件。你可以只调用它的优化器也可以只复用它的指令选择器甚至可以让它在运行时动态生成一段专用计算逻辑。llvmpipe就是这种能力的典型用户。2. 拿到llvm-project源码后先看清目录再动手构建2.1 源码获取、版本选择与镜像llvm-project的源码托管在GitHub官方仓库日常开发基本都基于它的monorepo结构。拉取方式很简单git clone https://github.com/llvm/llvm-project.git cd llvm-project git checkout llvmorg-15.0.7这里有个容易犯的错不要直接clone完就在默认分支上乱build。默认分支往往是正在剧烈开发的主线API天天变今天能编过的代码明天可能就断了。如果是为了复现生产环境问题或者想跟某个具体版本比如文中反复提到的15.0.7保持一致务必checkout到对应tag。国内网络经常clone到一半失败遇到这种情况可以试试把仓库地址换成镜像或者用--depth1只拉取最新commit。如果你需要子模块再执行git submodule update --init --recursive不过llvm-project现在基本已经把依赖收进monorepo了这一步在多数场景下可以省略。拿到源码后第一件事不是跑cmake而是先浏览根目录下的子项目。你会看到llvm/是核心clang/是C/C前端lld/是链接器libcxx/、libcxxabi/是C标准库实现compiler-rt/提供Sanitizer和运行时库lldb/是调试器mlir/是通用多级IR框架flang/是Fortran前端polly/做循环优化openmp/管理OpenMP运行时。目录之间的关系不是“一个可执行文件里包含所有”而是通过CMake的组件化机制按需组合。这个设计是llvm-project能够被llvmpipe这类大型项目嵌入的关键。2.2 CMake配置里哪些开关必须关心构建llvm-project最常用的组合是Ninja Clang但第一遍构建不一定非要用Clang系统自带的GCC也能完成。一个我验证过很多次的最小配置是cmake -G Ninja -S llvm -B build \ -DCMAKE_BUILD_TYPERelease \ -DLLVM_TARGETS_TO_BUILDhost \ -DLLVM_ENABLE_PROJECTSclang;lld cmake --build build --target llc opt clang几个关键开关值得解释一下LLVM_TARGETS_TO_BUILD控制要生成哪些后端目标。默认是all意味着会把X86、ARM、AArch64、RISC-V等几十个后端的代码全部编译进去构建时间和磁盘占用直接爆炸。日常开发用host就够了只编当前机器的目标架构。LLVM_ENABLE_PROJECTS启用llvm核心之外的前端和工具链组件。注意这里会显著增加编译时间如果你只是想研究优化器或Pass可以先只编核心不加任何项目后面需要时再补。LLVM_ENABLE_RUNTIMES这是跟LLVM_ENABLE_PROJECTS容易混淆的另一套机制主要用于构建compiler-rt、libcxx、libcxxabi这些运行时库。它们往往依赖已经构建好的编译器所以放在runtime阶段单独处理而不是跟普通项目一起编。第一次构建llvm-project请不要对时间抱有任何幻想。即使只编核心加X86后端在8核机器上也可能需要20-30分钟如果选了all目标几十GB磁盘空间和数小时编译都是常态。我的建议是先小步快跑把llc和opt编出来这两个工具一个是代码生成器一个是优化器足够你验证大部分想法。等到确实需要Clang、LLD再增量补上CMake构建系统的增量能力能帮你省掉大量重复等待。3. 第一个Pass理解llvm-project最经典的扩展点3.1 用一个FunctionPass跑通opt对于刚接触llvm-project的人最值得上手的切入点不是改后端指令选择器而是写一个LLVM Pass。Pass是LLVM优化流程里的基本处理单元它遍历IR并做某种变换或分析。写一个最简单的Pass可以让你在几小时内跑通“源码-IR-优化-输出”的完整工具链。这里我用New Pass Manager的写法给你一份可直接运行的代码。假设你要给每个函数插一条调试输出#include llvm/IR/Function.h #include llvm/IR/IRBuilder.h #include llvm/IR/Instructions.h #include llvm/IR/Module.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 { class MyFunctionPass : public PassInfoMixinMyFunctionPass { public: PreservedAnalyses run(Function F, FunctionAnalysisManager AM) { errs() Function: F.getName() \n; return PreservedAnalyses::all(); } }; } // namespace llvm::PassPluginLibraryInfo getMyPluginInfo() { return {LLVM_PLUGIN_API_VERSION, MyFunctionPass, LLVM_VERSION_STRING, [](PassBuilder PB) { PB.registerPipelineParsingCallback( [](StringRef Name, FunctionPassManager FPM, ArrayRefPassBuilder::PipelineElement) { if (Name my-function-pass) { FPM.addPass(MyFunctionPass()); return true; } return false; }); }}; } extern C LLVM_ATTRIBUTE_WEAK ::llvm::PassPluginLibraryInfo llvmGetPassPluginInfo() { return getMyPluginInfo(); }把它编成动态库然后用opt加载clang -O0 -emit-llvm -c test.c -o test.bc opt -load-pass-plugin./libMyPass.so -passesmy-function-pass test.bc -o /dev/null注意这里用的是新PM写法不是老式initFunctionPass那套。如果你手头的教程还在让你继承FunctionPass、用runOnFunction那多半是基于Legacy PassManager的老文档在LLVM 15上虽然还能编译但已经不是推荐路径了。3.2 为什么说opt是调后端前必须掌握的“手术台”写Pass容易但调试Pass才是真正的分水岭。opt这个工具就是你的手术台它允许你对任意IR文件执行任意Pass组合并在每个Pass后查看IR发生了什么。我最常用的三个参数是-print-after-all在每一个Pass运行结束后打印整个模块的IR。-filter-print-funcsfuncName只打印指定函数的IR避免输出太大。-debug-onlymy-debug-tag配合LLVM_DEBUG宏输出指定调试信息而不是看所有日志。举个例子当你怀疑某个优化Pass把你的循环变量搞没了可以用opt -passesloop-mssa,licm -print-after-all test.bc逐段对照变换前后的IR。我第一次定位CSE公共子表达式消除导致的问题就是靠-print-after-all把数万行IR翻了个底朝天最后发现是某个Pass的PreservedAnalyses没写对错误地保留了分析结果导致后续Pass用了陈旧的依赖信息。这种问题看源码很难一眼看到但配合IR输出后逻辑会清楚得多。3.3 LLVM IR数据结构的“卑鄙”之处在你动手写Pass之前还需要对LLVM IR的数据结构有点概念。LLVM IR本质上是一个SSA形式的有向图Module持有若干个FunctionFunction由若干BasicBlock组成BasicBlock里是一条条Instruction指令间通过Value和Use互相引用。这个结构和普通AST最大的区别是每个操作数都直接指向它的定义指令修改起来非常容易造成悬垂引用。新手最常见的坑是遍历指令时往当前BasicBlock里插入新指令导致迭代器失效。LLVM的IRBuilder默认会在某个插入点之后插入但如果你同时还在迭代指令插入行为就可能改变你还没访问到的指令的排布。稳妥的做法是先把要处理的指令收集到一个SmallVector里遍历完后再统一插入或删除。另外修改IR后务必正确返回PreservedAnalyses。如果你动了函数体却返回PreservedAnalyses::all()LLVM会认为所有分析结果仍然有效后面拿到陈旧分析数据的Pass会给你带来难以名状的bug。这也是很多Pass编写者一上来就踩的坑。4. 版本号里的现实LLVM 15.0.7带来哪些API断裂和迁移任务4.1 NewPM全面接管Legacy PassManager退出LLVM 15是一个分水岭。从这一版开始面向新Pass管理器的优化管线成为唯一默认路径旧式Pass的许多API被标记为deprecated甚至有部分在后续版本里被直接删除。如果你是从LLVM 12或更早版本迁移过来的项目大概率会看到一堆编译器报错说找不到legacy::FunctionPass相关头文件或者createLegacyPMFunctionPass之类的函数已经不存在。我当时迁移一个自定义优化插件时流程大致是把继承的FunctionPass改成PassInfoMixinT把runOnFunction改成run(Function F, FunctionAnalysisManager AM)把INITIALIZE_PASS这种宏拿掉换成PassPluginLibraryInfo注册把createXxxPass工厂函数删掉直接在PassBuilder的PipelineParsingCallback里构造。看起来改动量不大但会让你重新理解Pass的生命周期。新PM里Pass对象可以短生命周期地多次创建分析结果通过FunctionAnalysisManager显式请求而不是靠老的getAnalysisT()全局方式。4.2 从代码和构建日志里定位破坏性变更升级LLVM版本时如果你不想一篇篇翻文档最快的方式是直接看构建日志和源码里的deprecated注释。以下是我在LLVM 15上遇到过的典型错误整理成了一张对照表旧写法LLVM 15上的表现改法llvm::legacy::PassManager头文件路径变化编译报错改用llvm::PassBuilderPointerType::getUnqual(...)报错或产生意外行为不再有typed pointer直接用PointerType::get(ctx, addrspace)GetElementPtrInst::Create带typed pointer参数编译告警或错误去掉pointee类型参数只保留元素类型TargetMachine::createDataLayout()方法签名调整使用DL TM.createDataLayout()注意const限定IRBuilder::CreateLoad传入typed pointer运行期断言使用Type *参数去掉pointer element type这些变化背后最大的推手是“Opaque Pointers”机制。LLVM早年为了在类型系统里保留指针指向的类型信息在PointerType里记录了一个ElementType也就有了typed pointer。但从LLVM 14开始这种设计成了优化器推行多态和泛型化的阻碍所以逐步转向不区分指针指向类型直接让所有指针都是不透明指针。这个改动对整个代码生成层影响非常大也让不少老的Pass在15上跑起来直接崩。4.3 TableGen、OpaquePtr等容易被忽略的变化除了Pass API和指针类型LLVM 15还有一批不那么显眼但同样致命的改动。比如llvm-tblgen生成的代码结构变了后端开发者如果自己维护指令集描述文件会发现include/llvm/Target/Target.td里的某些类名或字段定义被重命名还有MCInst相关内容调整影响汇编器实现。另一个常见的坑是C标准要求提高LLVM 15已经要求你的工具链至少支持C17如果是老旧的GCC 5或Clang 3.x编译过程中会出现一堆莫名其妙的模板错误。我的建议是升级前先读llvm/docs/ReleaseNotes.rst和llvm/docs/Deprecation.rst这两个文件把每个版本的breaking change写得最集中。不要只看网上零散教程很多教程写的其实是旧接口。如果项目里有大量自定义Pass先在独立分支上跑一遍完整构建把编译错误全部修完再合并不要在主分支上边改边看否则很容易陷入“改了一个接口又冒出三个新错误”的泥潭。5. 将llvm-project集成进自有工程时链接与ABI的深坑5.1 llvm-config与CMake中find_package(LLVM)的正确姿势自己玩LLVM时用命令行工具就够了但一旦你要把自己写的Pass或工具链集成进项目事情就变得复杂。LLVM官方提供的集成方式有两种llvm-config和CMake的find_package(LLVM)。先看llvm-config它相当于一个编译参数查询工具llvm-config --cxxflags --ldflags --libs core在构建系统里调用它可以拼出需要包含的头文件路径和库文件列表。但这里有坑--libs core只会给出核心库如果你的Pass还需要support、analysis等就得自己把它们加到参数里不然链接时一堆undefined reference。CMake推荐用find_package方式前提是你先通过make install把LLVM装到了某个前缀或者设了LLVM_DIR指向build目录find_package(LLVM REQUIRED CONFIG) message(STATUS Found LLVM ${LLVM_PACKAGE_VERSION}) include_directories(${LLVM_INCLUDE_DIRS}) add_definitions(${LLVM_DEFINITIONS}) add_executable(my_tool my_tool.cpp) target_link_libraries(my_tool PRIVATE LLVM)这种写法的潜在问题是如果系统里装了一份老版本LLVM而你又把新版本装到了/opt/llvm-15find_package很可能找到系统那份导致头文件和库版本不一致。解决办法是显式设置-DLLVM_DIR/opt/llvm-15/lib/cmake/llvm用绝对路径排除干扰。5.2 动态库、静态库和libLLVM.so的取舍LLVM库有三种分发方式大量静态库每个组件一个.a、一个合成的动态库libLLVM.so、以及按组件拆分的动态库。选择不同方式编译和运行行为差异非常大。个人经验是调试阶段用静态库最省心链接过程中任何符号缺失都会在构建期暴露交付工具给他人时用libLLVM.so更理性因为最终可执行文件体积会小很多。但如果要用libLLVM.so必须在构建LLVM时开启LLVM_BUILD_LLVM_DYLIBON然后在你的CMake里加LLVM_LINK_LLVM_DYLIBON。否则会出现一个经典问题你的可执行文件同时链接了libLLVM.so和一堆静态组件库结果运行时符号重复定义表现为段错误或直接被dynamic loader拒绝。还有一个容易忽略的点LLVM 15的C ABI对标准库版本非常敏感。如果你用GCC 9编译了LLVM再用GCC 12编译自己的插件去加载它一旦两者libstdc的std::string等布局不一致Pass加载时就会崩在构造函数里报错还很不直观。这种问题最简单的规避方式就是构建LLVM的编译器和你自己项目的编译器保持同版本至少保持同一主版本。听起来很像废话但很多人栽在上面。5.3 最容易栽的C ABI问题除了编译器版本另一个ABI深坑隐藏在宏定义和编译选项里。LLVM在头文件里大量使用LLVM_ENABLE_ABI_BREAKING_CHECKS、_DEBUG这类编译期宏。如果你的编译选项和构建LLVM时不一致比如LLVM是Release构建、定义了NDEBUG而你的工程是Debug构建、没有定义NDEBUG那么某些inline函数看到的宏状态不同数据结构的内存布局就会不一致。这会导致你在调用看似简单的接口时直接崩溃比如isaFunction、castCallInst这种动态类型检查都会访问错误的内存偏移。要定位这类问题先试试在CMake里跟上LLVM构建时一致的选项特别是CMAKE_BUILD_TYPE。如果必须混合那就尽量用动态库而不要静态库因为动态库库内部的ABI一致性由动态库自身保证你的代码只暴露在接口边界。还有一招是用llvm-config --cxxflags的输出直接作为你的CXXFLAGS让它帮你把宏定义统一起来这能避开绝大多数布局不一致问题。6. 跳进大型使用方llvmpipe之前读懂LLVM优化与调试辅助设施6.1 llvmpipe是如何借助LLVM加速图形管线的理解了Pass和集成问题之后再回头看llvmpipe你的视角会完全不同。llvmpipe并不打算一遍遍解释GLSL/Vulkan着色器它在运行时把着色器代码转化成一个LLVM模块然后调用LLVM的JIT编译管线执行。这里面的关键点是Graphic管线里一个着色器可能要处理成千上万个顶点或像素如果能自动生成一批宽度为256位或512位的SIMD指令让CPU一个指令周期同时处理8个浮点性能就会比纯标量执行快好几倍。llvmpipe中的“256 bits”就是它对这种向量化能力的总结。它通过LLVM的矢量类型和自动向量化把标量Shader代码变成针对当前CPU微架构优化的SIMD代码。MLIR甚至可以被用来做更高层的Tile调度这段在Mesa的代码里写得很清晰。当你用llvmpipe跑一个复杂3D场景时CPU温度飙升是常态因为LLVM生成的代码在“压榨”CPU每个流水线。理解这层关系后你就明白为什么llvmpipe会把自己的版本信息打印成LLVM版本号——它本质上是一个深度依赖LLVM的运行时编译器。6.2 OptBisect和llvm-reduce定位Pass问题如果你也想在类似llvmpipe的大工程里定位“到底是哪个优化Pass搞崩了”LLVM提供了一对利器opt-bisect和llvm-reduce。opt-bisect的思路是在整条优化管线里设置一个“截止序号”每运行一个Pass就检查当前编号是否超过截止值如果超过了就跳过从而用二分法快速定位是哪个Pass引入了错误。使用方式opt -O2 -opt-bisect-limit100 test.bc -o output.bc如果输出正常就增大limit不正常就缩小范围多试几次就能定位到具体Pass编号。这个工具对Mesa这类大型使用方同样有效因为你可以把优化崩溃的场景简化成一个独立的着色器IR然后逐段二分排查。llvm-reduce则是做测试用例最小化的它能把一个几万行的IR文件缩减成几十行同时仍然保留触发bug的特征。用法是准备两样东西一个初始IR文件一个判断“bug是否出现”的脚本llvm-reduce --testcheck.sh --ir-passesopt -passesloop-vectorize crash.ll脚本返回0表示bug复现成功返回非0表示未能复现。llvm-reduce会不断尝试删除IR中的函数、指令或模块直到无法再删为止。这对上报LLVM上游bug几乎是必备流程在开发自己的Pass时也能帮你快速把复杂案例简化成最小可复现样本省去大量手工剥离代码的时间。我在实际定位一个向量化导致的浮点精度问题时就是把llvmpipe的输出转成LLVM IR再用opt-bisect锁定了某个speculation pass最后用llvm-reduce拿到了一个能稳定复现的100行以内案例。整个过程比肉眼读代码高效太多。如果你打算长期跟llvm-project打交道这两样工具值得尽早熟悉。最后再分享一个个人习惯无论是提交代码还是在博客里记录经验我都会把当时的llvm-config --version、llc --version和完整的CMake命令贴在开头。很多奇怪的问题最后追根溯源都落在“LLVM版本和构建选项不一致”上。llvm-project是个包容性很强的项目但也是个对ABI和版本极度挑剔的项目。心平气和地把版本差异排查清楚很多“不可能”的错误其实都能顺藤摸瓜找到答案。