如果你是一名编译器后端工程师或者正在折腾编程语言、高性能计算、图像渲染相关的项目那么有一个名字你早晚躲不开LLVM。围绕它展开的 llvm-project 是当前开源世界里规模最大、影响最深的编译器基础设施之一从苹果的 Swift 到 Rust 的默认后端再到各种 GPU 编译栈、数据库执行引擎几乎处处都有它的影子。我最早接触 LLVM 是在做一门解释型语言的原生编译优化后来又在 llvmpipe 软件渲染器上排查过性能瓶颈前后啃了不少源码和构建脚本。这篇内容我想从一个实践者的角度把 llvm-project 的架构逻辑、构建方法、核心子项目的关系以及真正在工程里用得上的落地经验一次性讲清楚帮刚入门的朋友省掉几个月的踩坑时间也帮已经在用 LLVM 但只停留在 Clang 层面的同学打开视野。llvm-project 是一个 monorepo单仓库多项目形态的开源项目由 LLVM 基金会维护。早期 LLVM 是单独一个仓库后来为了版本一致性和构建便利性把 Clang、LLD、libc、compiler-rt、lldb、MLIR、polly、flang、libclc、llvmpipe 等一大票子项目全部收拢在一起。也就是说你从 GitHub 上拉下来的 llvm-project 实际上是整个 LLVM 生态的完整源代码集合。那么问题来了为什么一个编译器的项目会让这么多人关注而且它能应用的范围远远超出了“写一个编译器”本身这就是我在这一篇里要重点展开的内容。1. 内容整体设计与思路拆解1.1 从“编译器”到“编译器基础设施”很多人第一次接触 LLVM 时会困惑它到底是一个编译器还是一个库这个困惑很自然因为 llvm-project 跟传统的 GCC 那种“一个可执行程序干完整件事”的设计完全不同。LLVM 从一开始就按照库的思维来组织它把编译过程的各个环节拆成独立组件以库的形式提供给上层使用。你甚至可以完全不用 Clang只拿 LLVM 的库写自己的编译器后端、写静态分析工具、写代码生成器。这种设计直接决定了 llvm-project 的目录划分。顶层的 llvm/ 目录是核心里面包含支持编写编译器所需的全部基础设施IR中间表示的定义与处理、优化 pass 框架、目标描述文件TableGen、代码生成器CodeGen、MC 层机器码相关、JIT 执行引擎MCJIT、ORC、以及各种后端X86、ARM、RISCV、NVPTX 等。Clang 则是基于 LLVM 库做的一个具体的 C/C/Objective-C 编译器前端。1.2 为什么 LLVM 是三段式架构LLVM 最核心的设计是经典的三段式架构前端Frontend、优化器Optimizer、后端Backend。前端负责把源代码解析成 AST再降级成 LLVM IR优化器在 IR 层面上做与目标机器无关的优化后端把优化后的 IR 翻译成目标机器的汇编或者机器码。这套架构的价值在于如果你想发明一种新语言你只需要写一个新的前端把语法转成 LLVM IR就可以立即享受到现有全部后端架构的生成能力和长期积累的优化 pass。反过来说如果你想支持一款新的 CPU 架构你不需要关心任何具体语言只要写一个把 LLVM IR 映射到目标指令集的后端即可。这种解耦带来的生态效应非常恐怖越是分布广泛的通用基础设施越多人贡献能力越强反过来又吸引更多人使用。llvmpipe 则是这套架构在图形渲染领域的应用典型。它是一个纯 CPU 的 OpenGL 软件光栅化器利用 LLVM IR 作为着色器编译的中间表示运行时借用 LLVM 的 JIT 能力把着色器代码动态翻译成当前 CPU 的原生指令。llvmpipe 位于 llvm-project 中 mesa 相关生态的协作位置在实际工程里经常被用来驱动虚拟 GPU、无 GPU 服务器环境下的图形加速或者用来调试图形管线问题。1.3 模块化带来的选择成本成也模块化败也模块化。llvm-project 的默认配置是构建所有项目但在真实项目里我们几乎不需要全部构建。如果你的目标是做语言前端只需要 LLVM 核心 Clang 就够了如果你做的是链接器相关研究只需要 LLVM 核心 LLD如果你只需要软件渲染那可能是 Mesa 那边带着 LLVM 核心构建而不需要 Clang 和 LLD。因此理解 llvm-project 的工程结构学会选择性地构建组件是从入门到进阶必须迈过的坎。2. 源码构建与工程实践2.1 先说结论一定要用 Ninja 配合 CCache我见过太多人在 llvm-project 上编译到一半机器卡死或者一次增量编译等十分钟。LLVM 的代码量摆在那里全量构建需要相当可观的 CPU 资源和磁盘空间。如果你不是刻意要研究构建系统本身请优先选择 Ninja 而不是 Makefile。Ninja 的增量构建判断更加精确而且能够利用机器上全部核心并行编译在我实测的机器上Ninja 的构建速度比 Make 快 30% 左右在大规模增量场景下差距更明显。同时务必安装 ccache。LLVM 的 C 代码编译起来极其耗时很多头文件会被重复展开数千次。CCache 可以有效缓存编译产物特别是当你需要频繁在 Debug 和 Release 之间切换、或者微调某个 pass 源码重新编译时CCache 能把重新编译时间从十几分钟压到一两分钟。具体启用方式是在 cmake 配置时加上-DCMAKE_CXX_COMPILER_LAUNCHERccache。2.2 CMake 配置的关键参数LLVM 使用 CMake 管理构建。以下是一个我个人比较推荐的构建配置适合做编译器开发或日常实验git clone https://github.com/llvm/llvm-project.git cd llvm-project mkdir build cd build cmake -G Ninja ../llvm \ -DCMAKE_BUILD_TYPERelease \ -DLLVM_ENABLE_PROJECTSclang;lld;libcxx;libcxxabi \ -DLLVM_TARGETS_TO_BUILDX86;RISCV;NVPTX \ -DLLVM_ENABLE_ASSERTIONSON \ -DCMAKE_C_COMPILERclang \ -DCMAKE_CXX_COMPILERclang \ -DLLVM_CCACHE_BUILDON解释一下关键参数LLVM_ENABLE_PROJECTS需要额外构建的子项目列表。这里我选了 clangC/C 前端、lld链接器、libcxx/libcxxabiC 标准库。如果你不需要这些可以留空只构建 LLVM 核心。LLVM_TARGETS_TO_BUILD要生成哪些后端。默认是构建所有后端但全量构建很浪费时间按需指定会让整体构建快很多。这里我选了 X86本机架构、RISCV近期在做 RISC-V 相关实验、NVPTXGPU 相关LLVM 在 GPU 编译器栈中扮演核心角色覆盖了从 CUDA 到 OpenCL 的编译路径。LLVM_ENABLE_ASSERTIONS开启断言。开发调试时强烈建议打开很多 IR 一致性问题会在断言阶段暴露出来而不是等生成错误代码后再排查。LLVM_CCACHE_BUILDLLVM 官方 CMake 提供的 ccache 集成开关在较新版本中更简洁替代手动设置CMAKE_CXX_COMPILER_LAUNCHER。注意LLVM_ENABLE_PROJECTS和LLVM_ENABLE_RUNTIMES是两个不同的概念。像 libcxx、compiler-rt 这类运行时组件在较新的 LLVM 版本中推荐放到LLVM_ENABLE_RUNTIMES里构建因为它们本质上是要跟目标系统工具链打交道的需要独立于 LLVM 本身的构建环境。如果混用位置可能遇到标准库头文件路径冲突的问题。2.3 构建 Release 版还是 Debug 版如果你的目标是自己开发 LLVM 的 pass 或者修改 IR 处理逻辑建议选择 Release Assertions 的组合。纯 Debug 版本的 LLVM 在优化掉很多检查之后会插入大量调试符号和未优化代码运行速度慢上好几倍编译编译器的编译器会让人痛不欲生。而 Release Assertions 既保证了运行速度又保留了内部一致性检查是兼顾调试信息与性能的最优解。如果确实需要深入调试 LLVM 本身的执行流程例如跟踪某个 pass 对 IR 的修改过程可以单独把某个子目录切换为 Debug 编译或者在 CMake 中指定-DLLVM_OPTIMIZED_TABLEGENON避免 TableGen 生成器成为构建瓶颈。2.4 构建时常见的资源瓶颈LLVM 构建时的内存消耗不容小觑。链接阶段特别容易把内存吃满尤其是clang或者lld这类大型 C 程序使用 lld 作为链接器构建整个项目时常见峰值内存会到 8GB 以上。如果你的机器内存吃紧可以设置-DLLVM_USE_LINKERlld -DCMAKE_EXE_LINKER_FLAGS-Wl,--no-keep-memory另外-DCMAKE_BUILD_TYPERelWithDebInfo可以在调试符号与性能之间取得平衡适合在性能基本可用的情况下用 gdb/lldb 定位问题。还有一个小提示不要把构建目录放在网络磁盘或加密文件系统上。LLVM 构建会产生海量小文件读写文件系统元数据性能严重影响构建速度。本地 SSD 是最稳妥的选择我在 NFS 挂载目录上构建过一次耗时是本地磁盘的三倍以上。3. 核心原理与子项目串讲3.1 LLVM IR整个生态的中枢神经LLVM IR 采用静态单赋值SSA形式这意味每个变量只能被赋值一次。SSA 形式让数据流分析变得非常简单你不需要考虑变量遮蔽的问题每个值都有一个唯一的定义点数据依赖关系直接用 use-def 链就能完整表达。正因如此IR 上的优化 pass 写起来才那么干净。IR 在 llvm-project 中包含三种形式内存中的表示、文本可读形式.ll 文件、二进制位码形式.bc 文件。三种形式可以互相转换这在调试和测试中特别常用。实际工程中我经常干的一件事是从目标文件反解出 IR对一个 .o 文件执行llvm-dis看编译器到底把源码优化成了什么样子。这种能力是 GCC 系列工具链无法直接提供的也是 LLVM 做编译器教学和研究的最佳切入点。用一个简单示例体验一下。假设有如下 C 代码int add(int a, int b) { return a b; }使用 Clang 编译生成文本 IRclang -S -emit-llvm add.c -o add.ll得到的 IR 大致长这样define i32 add(i32 %a, i32 %b) { entry: %add add nsw i32 %a, %b ret i32 %add }注意nsw标志位它表示“no signed wrap”即这个加法不会发生有符号溢出。这个信息是 Clang 前端基于 C 语言标准中关于有符号整数溢出的未定义行为规则生成的LLVM 优化器拿到这个标志之后就可以在后续做更激进的变换而不用担心语义改变。类似的标志位还有nuwno unsigned wrap、inboundsGEP 指针运算不越界等。理解这些标志对解读 IR 和编写 pass 至关重要。3.2 ClangC/C 生态的事实标准前端Clang 在 llvm-project 里的地位比较特殊它虽然只是前端但实际使用人数最多。Clang 的优势不仅在于生成代码质量更在于其高度模块化的架构这使它非常适合做静态分析、代码重构、索引等工具。如果你用过 clang-tidy、clangd应该已经体验到这些工具快速、准确、内存可控的良好表现而这都源于 Clang 提供的前端 API。从工程角度讲Clang 的命令行参数设计比 GCC 更清晰错误信息通常更加精确。它还能无缝配合 LLVM 的工具链进行 LTO链接时优化、PGO配置文件引导优化和 BOLT二进制布局优化等深度调优这是老牌编译器难以比拟的整合度。3.3 LLD给你一个足够快的链接器链接器听起来不如编译器炫酷但 LLD 设计上强调并行化与简单架构链接速度远胜过传统 GNU ld。我自己参与过一个大型 C 项目的构建优化链接时间从 GNU ld 的 2 分半压到 LLD 的 15 秒左右整个增量开发循环都舒畅了不少。更关键的是LLD 对 ELF、Mach-O、COFF、Wasm 格式的支持都很成熟跨平台特性让它成为许多工具链默认的链接器选择。3.4 MLIR编译器界的乐高积木MLIRMulti-Level Intermediate Representation是 llvm-project 新加入的子项目专为异构计算和编译流水线设计。如果说 LLVM IR 是锁死在低层目标相关的级别上MLIR 则允许你构建自定义的多层 IR 表示并且可以在不同抽象级别之间做渐进降低progressive lowering。这在机器学习编译器领域尤其有用把深度学习框架的算子图先下降到 MLIR 的 Tensor 级别表示再逐步降到 Linalg、Affine、LLVM Dialect最终生成高效的底层代码。这种多级表示不再像传统编译器一样从高级语言一步跳到 LLVM IR而是让你能够在不同阶段保留对问题领域的语义信息从而做更精准的优化。如果你正在研究 AI 编译器MLIR 是绕不开的核心组件。3.5 llvmpipeLLVM 在图形渲染中的重要布局搜索热词里出现了 llvmpipe这里展开多说一点。llvmpipe 是 Mesa 3D 项目中的软件光栅化器它借用 LLVM 的 JIT 编译能力在运行时把 OpenGL / Vulkan 的着色器编译为当前 CPU 的原生指令。这样即使在没有独立显卡的机器上也能以可以接受的速度完成图形渲染任务。llvmpipe 的实践中LLVM 扮演了一个“即时编译器”的角色需要将着色器 IR 映射到目标 ISA并对性能敏感的循环做自动向量化处理。这里涉及到的 LLVM 后端能力和优化能力远超一般“编译 C 代码”的应用场景。实际调试 llvmpipe 时会因为 256 位向量、SIMD 指令选择、寄存器分配等问题频繁深入到 LLVM 的后端内部逻辑因此 llvmpipe 也是一个极好的学习 LLVM JIT 与代码生成内部机制的入口。3.6 其他值得关注的子项目compiler-rt提供编译器生成代码时的运行时支持库例如__sanitizer家族AddressSanitizer、UndefinedBehaviorSanitizer 等、__builtin实现、profile 运行时等是工程级代码质量保障利器。libc / libcabiLLVM 官方的 C 标准库实现配合 Clang 使用时能避免 GCC 头文件对非标准特性的依赖调试体验清晰。lldbLLVM 生态的调试器与 LLVM/Clang 共享代码解析基础设施对现代语言调试支持更好。polly基于多面体模型的循环优化框架能以高层次的视角改写嵌套循环是程序自动并行化和数据局部性优化的重要研究方向。flangLLVM 官方的 Fortran 前端让经典科学计算语言也进入 LLVM 生态。4. 核心实操环节4.1 基于 LLVM 写一个自定义 pass理解 LLVM 最快的方式就是写一个优化 pass。LLVM 的 pass 框架经历了多次演变从最早的 legacy PM到现在的 new pass manager。以现在主流的 new pass manager 为例一个简单的函数级 pass 长这样#include llvm/IR/Function.h #include llvm/IR/Instructions.h #include llvm/IR/LegacyPassManager.h #include llvm/Pass.h #include llvm/Passes/PassBuilder.h #include llvm/Passes/PassPlugin.h using namespace llvm; namespace { struct MyPass : public PassInfoMixinMyPass { PreservedAnalyses run(Function F, FunctionAnalysisManager AM) { for (BasicBlock BB : F) { for (Instruction I : BB) { if (auto *Op dyn_castBinaryOperator(I)) { if (Op-getOpcode() Instruction::Add) { errs() Found add in function: F.getName() \n; } } } } return PreservedAnalyses::all(); } }; } // namespace extern C ::llvm::PassPluginLibraryInfo LLVM_ATTRIBUTE_WEAK llvmGetPassPluginInfo() { return {LLVM_PLUGIN_API_VERSION, MyPass, LLVM_VERSION_STRING, [](PassBuilder PB) { PB.registerPipelineParsingCallback( [](StringRef Name, FunctionPassManager FPM, ArrayRefPassBuilder::PipelineElement) { if (Name my-pass) { FPM.addPass(MyPass()); return true; } return false; }); }}; }将代码编译成动态库后可以通过 Clang 的-fpass-plugin选项加载观察它对每个加法指令的识别。这个示例同时展示了 LLVM pass 的调试方式和插件化扩展能力你不需要重新编译整个 LLVM只要编译这个独立的 pass 插件就能完成对编译流程的定制。对于企业级开发这种机制让编译器基础设施能够像中间件一样被团队按需集成。4.2 使用 llvmpipe 做无显卡环境渲染调试假设你在一个没有 GPU 的服务器上跑图形相关的测试可以强制 Mesa 使用 llvmpipe 作为渲染设备export LIBGL_ALWAYS_SOFTWAREtrue export GALLIUM_DRIVERllvmpipe然后运行glxinfo | grep OpenGL renderer正常情况下你应该看到类似输出OpenGL renderer string: llvmpipe (LLVM 15.0.7, 256 bits)这里的 “256 bits” 指的是 llvmpipe 在当前 CPU 上使用的 SIMD 向量位宽。现代 x86 处理器通过 AVX2 寄存器实现 256 位向量运算llvmpipe 就是借助 LLVM 的自动向量化能力把像素着色器中的标量计算转换成 SIMD 指令从而在无 GPU 条件下尽量榨干 CPU 的并行算力。如果你看到的是 “128 bits”说明当前环境没有启用 AVX2或者 llvmpipe 检测到 CPU 不支持 256 位操作。可以尝试确认 CPU 特性、检查编译时的目标选项、以及 Mesa 的构建配置。这种细节排查对于在容器化环境里做图形基准测试的人非常实用。4.3 编写自定义后端的第一步TableGen 目标描述如果你想为一种全新的 CPU 架构编写 LLVM 后端第一步是写 TableGen 文件描述指令集。LLVM 的后端并非把指令信息硬编码在 C 里而是用 TableGen 这种领域专用语言描述指令格式、寄存器、调用约定等信息再由 TableGen 工具自动生成庞大的 C 代码包括指令选择器、汇编器、反汇编器等。这套描述方法虽然上手曲线陡峭但一旦你理解了 TableGen 的声明式写法维护后端的工作量比手写所有代码要小一个数量级。一个非常简单的寄存器描述示例如下def GPR : RegisterClassMyTarget, [i32], 0, (add R0, R1, R2, R3); def ADDrr : MyTargetInst(outs GPR:$dst), (ins GPR:$src1, GPR:$src2), add $dst, $src1, $src2, [];这行描述告诉 LLVM有一条加法指令将两个寄存器操作数相加结果写回目标寄存器指令的汇编形式是 “add”。TableGen 工具会为这个描述生成匹配器Matcher和发射器Emitter相关的 C 代码文件帮助编译器自动完成从 SelectionDAG / GlobalISel 节点到机器指令的映射。4.4 工程中怎么选 LLVM 版本版本选择直接影响你的开发体验。LLVM 每六个月发布一个主版本通常 3 月和 9 月各一次。对于生产项目我建议至少使用上一稳定版避开 .0 这种首发版因为首发版往往伴随着构建脚本的小问题和部分 API 的不稳定。比如 llvmpipe 在某个较新版本中的渲染行为回归就曾经给我们的软渲染方案带来过困扰。如果你依赖 LLVM 的 C API请留意 API 在版本间的破坏性变更。new pass manager 在 LLVM 14 左右基本稳定如果想在这个领域做长期开发选 LLVM 16 比较稳妥。另外Ubuntu 等发行版提供的 LLVM 包通常不是最新版但足够稳定适合想避免源码编译开销的人。从工程维护角度另一个建议是把 LLVM 构建集成到 CI 中而不是只靠本地构建。因为 LLVM 庞大的代码量导致构建失败往往是在编译器、链接器或某个 obscure 依赖库的版本不匹配上提前在 CI 里发现问题可以节省大量团队协作成本。5. 常见问题与排查技巧实录5.1 构建时 OOM 怎么办LLVM 在链接 clang 或者 lld 时经常爆内存。我的解决方案是不要限制并行度但限制大目标文件的链接并发-DLLVM_PARALLEL_LINK_JOBS2这个参数控制同时运行的链接任务数量能有效压低内存峰值。如果机器内存只有 16GB建议设置成 1 或 2如果是 32GB 以上可以适当放宽。更多的时候瓶颈会出现在链接单个超级大目标文件时比如LLVMCore或Clang这时候可以利用 lld 的--threads1选项降低内存消耗虽然链接时间变长但至少不会 OOM。另外如果是在容器里构建注意容器本身的内存限制不是宿主机内存有多少容器 CGroup 只分配了一部分。5.2 运行 clang 时报 “Could not find compiler-rt” 或者 “unable to find viable overloaded operator” 之类诡异错误前者大多是路径配置问题检查clang -print-resource-dir输出是否正确看看lib/linux/libclang_rt.*是否确实在那个目录下。后者则可能是你的 Libc 和 libstdc 头文件混用导致的标准库冲突。如果使用-stdliblibc编译确保所有翻译单元都用了同一个标准库不要和默认的 libstdc 混着来。5.3 增量构建不生效这类问题常发生在 ccache 和 CMake 的缓存之间。如果改了某个头文件但增量构建没有重新编译相关目标可以先清掉 ccache 再重新构建确认是否是缓存误判。也可以重新生成 CMake 缓存有时 CMake 对依赖图的追踪不够精细会错过一些直接赋值的源码改动。还有一点不要使用ninja -j$(nproc)之外的通配并行度如果机器超卖CPU 核数不是越多越好反而因为调度开销拖慢整体时间。我通常用ninja -j$(($(nproc) - 2))留出核心给系统其他进程。5.4 调试 pass 时看不到打印输出新 pass manager 的 pass 打印输出与旧版行为不同因为 pass 的执行顺序由 PassBuilder 统一管理再加上 optimization level 的过滤很多自定义 pass 根本没被跑起来就会觉得“怎么没输出”。这时候建议先用opt -passesmy-pass -disable-output example.ll手动跑一下看能不能输出。如果手动能跑但在 clang 里加载不了再查 plugin 的注册逻辑是否被正确链接。5.5 为什么 llvmpipe 在 ARM 机器上慢得离谱llvmpipe 的性能高度依赖于 SIMD 指令集。ARM 架构上的 NEON 通常是 128 位对应位宽就显示为 128 bits性能相比 x86 的 AVX2 会有数倍差距。此外如果 llvmpipe 构建时没有启用正确的 CPU 特性例如缺少-mcpunativeJIT 生成的代码就不会利用 NEON 指令性能会进一步退化。可以用MESA_DEBUG1环境变量打开 Mesa 的调试输出确认 JIT 相关的编译信息。5.6 链接时 LTO 报错LTO 是 LLVM 的优势功能但引入它也意味着要处理“跨编译单元的优化需要全部 IR 一起处理”的问题。常见错误有module flags冲突、mismatched debug info等。多数情况是不同编译单元使用了不同编译选项尤其是-g与不带-g混编。还有一种情况是某些库使用了非 LLVM 编译器编译比如 GCC GFortran 编译的对象文件和开启 LTO 的 Clang 代码链接时会因为 LLVM bitcode 和普通对象文件混在一起而报错。解决方案是给相关库加上-Wno-errorlto-type-mismatch或者统一全部用 Clang 编译。6. 给新手的几条实操建议如果你是刚接触 llvm-project我建议按以下路径循序进入先从 Swift 或 Rust 的 Toolchain 里认识 LLVM 的存在感试着用rustc --print sysroot找找其中的 LLVM 动态库。用现成的发行版 LLVM 包写一个小 pass搭出 pass 脚手架跑opt手动验证 IR 变换效果。不要上来就源码编译整个 LLVM先跑通工具链流程。然后按照需求构建一份源码版本做到能针对某个模块单独调试。最终才深入 TableGen 和 CodeGen那是 LLVM 最深的地方。另外强烈建议把llvm-project的 GitHub release 页面加入关注列表。每当主版本发布release notes 必看尤其关注 API 变更和构建系统变动这些细节决定了你升级 LLVM 版本时的成本和风险。调试层面的小工具也建议提前熟悉opt -print-after-all可以打印 pass 执行前后的 IRllvm-mca可以做静态性能分析llvm-mc可以单独对汇编片段做解析输出llvm-objdump配合反汇编指令解读复杂问题的现象。这些东西在写后端的路上几乎天天都要用到。在 llvmpipe 的调试里还有一个隐藏技巧是设置LP_DEBUG1它能输出 llvmpipe 内部关于渲染管线状态的信息包括是否走了慢速失败路径。做软渲染开发和诊断图形驱动问题时这个调试开关比 gdb 打断点还要高效因为它直接暴露了 llvmpipe 引擎在哪个阶段选择放弃快速路径。回看这一路的折腾我认为 llvm-project 最可贵的地方在于它把“编译器”这个概念从一个封闭的黑盒开放成了一整套理解编程语言和硬件的框架。无论你想做的是一门新语言的前端、一个为特定芯片设计的指令选择器、一套用于程序分析的静态工具还是一个不依赖 GPU 的渲染后端llvm-project 都提供了坚实而高效的底座。如果你打算长期深耕底层系统软件尽早深入 LLVM把它的构建、IR、pass、后端这套链路摸熟会是一笔回报率极高的投资。
如果你是一名编译器后端工程师或者正在折腾编程语言、高性能计算、图像渲染相关的项目那么有一个名字你早晚躲不开LLVM。围绕它展开的 llvm-project 是当前开源世界里规模最大、影响最深的编译器基础设施之一从苹果的 Swift 到 Rust 的默认后端再到各种 GPU 编译栈、数据库执行引擎几乎处处都有它的影子。我最早接触 LLVM 是在做一门解释型语言的原生编译优化后来又在 llvmpipe 软件渲染器上排查过性能瓶颈前后啃了不少源码和构建脚本。这篇内容我想从一个实践者的角度把 llvm-project 的架构逻辑、构建方法、核心子项目的关系以及真正在工程里用得上的落地经验一次性讲清楚帮刚入门的朋友省掉几个月的踩坑时间也帮已经在用 LLVM 但只停留在 Clang 层面的同学打开视野。llvm-project 是一个 monorepo单仓库多项目形态的开源项目由 LLVM 基金会维护。早期 LLVM 是单独一个仓库后来为了版本一致性和构建便利性把 Clang、LLD、libc、compiler-rt、lldb、MLIR、polly、flang、libclc、llvmpipe 等一大票子项目全部收拢在一起。也就是说你从 GitHub 上拉下来的 llvm-project 实际上是整个 LLVM 生态的完整源代码集合。那么问题来了为什么一个编译器的项目会让这么多人关注而且它能应用的范围远远超出了“写一个编译器”本身这就是我在这一篇里要重点展开的内容。1. 内容整体设计与思路拆解1.1 从“编译器”到“编译器基础设施”很多人第一次接触 LLVM 时会困惑它到底是一个编译器还是一个库这个困惑很自然因为 llvm-project 跟传统的 GCC 那种“一个可执行程序干完整件事”的设计完全不同。LLVM 从一开始就按照库的思维来组织它把编译过程的各个环节拆成独立组件以库的形式提供给上层使用。你甚至可以完全不用 Clang只拿 LLVM 的库写自己的编译器后端、写静态分析工具、写代码生成器。这种设计直接决定了 llvm-project 的目录划分。顶层的 llvm/ 目录是核心里面包含支持编写编译器所需的全部基础设施IR中间表示的定义与处理、优化 pass 框架、目标描述文件TableGen、代码生成器CodeGen、MC 层机器码相关、JIT 执行引擎MCJIT、ORC、以及各种后端X86、ARM、RISCV、NVPTX 等。Clang 则是基于 LLVM 库做的一个具体的 C/C/Objective-C 编译器前端。1.2 为什么 LLVM 是三段式架构LLVM 最核心的设计是经典的三段式架构前端Frontend、优化器Optimizer、后端Backend。前端负责把源代码解析成 AST再降级成 LLVM IR优化器在 IR 层面上做与目标机器无关的优化后端把优化后的 IR 翻译成目标机器的汇编或者机器码。这套架构的价值在于如果你想发明一种新语言你只需要写一个新的前端把语法转成 LLVM IR就可以立即享受到现有全部后端架构的生成能力和长期积累的优化 pass。反过来说如果你想支持一款新的 CPU 架构你不需要关心任何具体语言只要写一个把 LLVM IR 映射到目标指令集的后端即可。这种解耦带来的生态效应非常恐怖越是分布广泛的通用基础设施越多人贡献能力越强反过来又吸引更多人使用。llvmpipe 则是这套架构在图形渲染领域的应用典型。它是一个纯 CPU 的 OpenGL 软件光栅化器利用 LLVM IR 作为着色器编译的中间表示运行时借用 LLVM 的 JIT 能力把着色器代码动态翻译成当前 CPU 的原生指令。llvmpipe 位于 llvm-project 中 mesa 相关生态的协作位置在实际工程里经常被用来驱动虚拟 GPU、无 GPU 服务器环境下的图形加速或者用来调试图形管线问题。1.3 模块化带来的选择成本成也模块化败也模块化。llvm-project 的默认配置是构建所有项目但在真实项目里我们几乎不需要全部构建。如果你的目标是做语言前端只需要 LLVM 核心 Clang 就够了如果你做的是链接器相关研究只需要 LLVM 核心 LLD如果你只需要软件渲染那可能是 Mesa 那边带着 LLVM 核心构建而不需要 Clang 和 LLD。因此理解 llvm-project 的工程结构学会选择性地构建组件是从入门到进阶必须迈过的坎。2. 源码构建与工程实践2.1 先说结论一定要用 Ninja 配合 CCache我见过太多人在 llvm-project 上编译到一半机器卡死或者一次增量编译等十分钟。LLVM 的代码量摆在那里全量构建需要相当可观的 CPU 资源和磁盘空间。如果你不是刻意要研究构建系统本身请优先选择 Ninja 而不是 Makefile。Ninja 的增量构建判断更加精确而且能够利用机器上全部核心并行编译在我实测的机器上Ninja 的构建速度比 Make 快 30% 左右在大规模增量场景下差距更明显。同时务必安装 ccache。LLVM 的 C 代码编译起来极其耗时很多头文件会被重复展开数千次。CCache 可以有效缓存编译产物特别是当你需要频繁在 Debug 和 Release 之间切换、或者微调某个 pass 源码重新编译时CCache 能把重新编译时间从十几分钟压到一两分钟。具体启用方式是在 cmake 配置时加上-DCMAKE_CXX_COMPILER_LAUNCHERccache。2.2 CMake 配置的关键参数LLVM 使用 CMake 管理构建。以下是一个我个人比较推荐的构建配置适合做编译器开发或日常实验git clone https://github.com/llvm/llvm-project.git cd llvm-project mkdir build cd build cmake -G Ninja ../llvm \ -DCMAKE_BUILD_TYPERelease \ -DLLVM_ENABLE_PROJECTSclang;lld;libcxx;libcxxabi \ -DLLVM_TARGETS_TO_BUILDX86;RISCV;NVPTX \ -DLLVM_ENABLE_ASSERTIONSON \ -DCMAKE_C_COMPILERclang \ -DCMAKE_CXX_COMPILERclang \ -DLLVM_CCACHE_BUILDON解释一下关键参数LLVM_ENABLE_PROJECTS需要额外构建的子项目列表。这里我选了 clangC/C 前端、lld链接器、libcxx/libcxxabiC 标准库。如果你不需要这些可以留空只构建 LLVM 核心。LLVM_TARGETS_TO_BUILD要生成哪些后端。默认是构建所有后端但全量构建很浪费时间按需指定会让整体构建快很多。这里我选了 X86本机架构、RISCV近期在做 RISC-V 相关实验、NVPTXGPU 相关LLVM 在 GPU 编译器栈中扮演核心角色覆盖了从 CUDA 到 OpenCL 的编译路径。LLVM_ENABLE_ASSERTIONS开启断言。开发调试时强烈建议打开很多 IR 一致性问题会在断言阶段暴露出来而不是等生成错误代码后再排查。LLVM_CCACHE_BUILDLLVM 官方 CMake 提供的 ccache 集成开关在较新版本中更简洁替代手动设置CMAKE_CXX_COMPILER_LAUNCHER。注意LLVM_ENABLE_PROJECTS和LLVM_ENABLE_RUNTIMES是两个不同的概念。像 libcxx、compiler-rt 这类运行时组件在较新的 LLVM 版本中推荐放到LLVM_ENABLE_RUNTIMES里构建因为它们本质上是要跟目标系统工具链打交道的需要独立于 LLVM 本身的构建环境。如果混用位置可能遇到标准库头文件路径冲突的问题。2.3 构建 Release 版还是 Debug 版如果你的目标是自己开发 LLVM 的 pass 或者修改 IR 处理逻辑建议选择 Release Assertions 的组合。纯 Debug 版本的 LLVM 在优化掉很多检查之后会插入大量调试符号和未优化代码运行速度慢上好几倍编译编译器的编译器会让人痛不欲生。而 Release Assertions 既保证了运行速度又保留了内部一致性检查是兼顾调试信息与性能的最优解。如果确实需要深入调试 LLVM 本身的执行流程例如跟踪某个 pass 对 IR 的修改过程可以单独把某个子目录切换为 Debug 编译或者在 CMake 中指定-DLLVM_OPTIMIZED_TABLEGENON避免 TableGen 生成器成为构建瓶颈。2.4 构建时常见的资源瓶颈LLVM 构建时的内存消耗不容小觑。链接阶段特别容易把内存吃满尤其是clang或者lld这类大型 C 程序使用 lld 作为链接器构建整个项目时常见峰值内存会到 8GB 以上。如果你的机器内存吃紧可以设置-DLLVM_USE_LINKERlld -DCMAKE_EXE_LINKER_FLAGS-Wl,--no-keep-memory另外-DCMAKE_BUILD_TYPERelWithDebInfo可以在调试符号与性能之间取得平衡适合在性能基本可用的情况下用 gdb/lldb 定位问题。还有一个小提示不要把构建目录放在网络磁盘或加密文件系统上。LLVM 构建会产生海量小文件读写文件系统元数据性能严重影响构建速度。本地 SSD 是最稳妥的选择我在 NFS 挂载目录上构建过一次耗时是本地磁盘的三倍以上。3. 核心原理与子项目串讲3.1 LLVM IR整个生态的中枢神经LLVM IR 采用静态单赋值SSA形式这意味每个变量只能被赋值一次。SSA 形式让数据流分析变得非常简单你不需要考虑变量遮蔽的问题每个值都有一个唯一的定义点数据依赖关系直接用 use-def 链就能完整表达。正因如此IR 上的优化 pass 写起来才那么干净。IR 在 llvm-project 中包含三种形式内存中的表示、文本可读形式.ll 文件、二进制位码形式.bc 文件。三种形式可以互相转换这在调试和测试中特别常用。实际工程中我经常干的一件事是从目标文件反解出 IR对一个 .o 文件执行llvm-dis看编译器到底把源码优化成了什么样子。这种能力是 GCC 系列工具链无法直接提供的也是 LLVM 做编译器教学和研究的最佳切入点。用一个简单示例体验一下。假设有如下 C 代码int add(int a, int b) { return a b; }使用 Clang 编译生成文本 IRclang -S -emit-llvm add.c -o add.ll得到的 IR 大致长这样define i32 add(i32 %a, i32 %b) { entry: %add add nsw i32 %a, %b ret i32 %add }注意nsw标志位它表示“no signed wrap”即这个加法不会发生有符号溢出。这个信息是 Clang 前端基于 C 语言标准中关于有符号整数溢出的未定义行为规则生成的LLVM 优化器拿到这个标志之后就可以在后续做更激进的变换而不用担心语义改变。类似的标志位还有nuwno unsigned wrap、inboundsGEP 指针运算不越界等。理解这些标志对解读 IR 和编写 pass 至关重要。3.2 ClangC/C 生态的事实标准前端Clang 在 llvm-project 里的地位比较特殊它虽然只是前端但实际使用人数最多。Clang 的优势不仅在于生成代码质量更在于其高度模块化的架构这使它非常适合做静态分析、代码重构、索引等工具。如果你用过 clang-tidy、clangd应该已经体验到这些工具快速、准确、内存可控的良好表现而这都源于 Clang 提供的前端 API。从工程角度讲Clang 的命令行参数设计比 GCC 更清晰错误信息通常更加精确。它还能无缝配合 LLVM 的工具链进行 LTO链接时优化、PGO配置文件引导优化和 BOLT二进制布局优化等深度调优这是老牌编译器难以比拟的整合度。3.3 LLD给你一个足够快的链接器链接器听起来不如编译器炫酷但 LLD 设计上强调并行化与简单架构链接速度远胜过传统 GNU ld。我自己参与过一个大型 C 项目的构建优化链接时间从 GNU ld 的 2 分半压到 LLD 的 15 秒左右整个增量开发循环都舒畅了不少。更关键的是LLD 对 ELF、Mach-O、COFF、Wasm 格式的支持都很成熟跨平台特性让它成为许多工具链默认的链接器选择。3.4 MLIR编译器界的乐高积木MLIRMulti-Level Intermediate Representation是 llvm-project 新加入的子项目专为异构计算和编译流水线设计。如果说 LLVM IR 是锁死在低层目标相关的级别上MLIR 则允许你构建自定义的多层 IR 表示并且可以在不同抽象级别之间做渐进降低progressive lowering。这在机器学习编译器领域尤其有用把深度学习框架的算子图先下降到 MLIR 的 Tensor 级别表示再逐步降到 Linalg、Affine、LLVM Dialect最终生成高效的底层代码。这种多级表示不再像传统编译器一样从高级语言一步跳到 LLVM IR而是让你能够在不同阶段保留对问题领域的语义信息从而做更精准的优化。如果你正在研究 AI 编译器MLIR 是绕不开的核心组件。3.5 llvmpipeLLVM 在图形渲染中的重要布局搜索热词里出现了 llvmpipe这里展开多说一点。llvmpipe 是 Mesa 3D 项目中的软件光栅化器它借用 LLVM 的 JIT 编译能力在运行时把 OpenGL / Vulkan 的着色器编译为当前 CPU 的原生指令。这样即使在没有独立显卡的机器上也能以可以接受的速度完成图形渲染任务。llvmpipe 的实践中LLVM 扮演了一个“即时编译器”的角色需要将着色器 IR 映射到目标 ISA并对性能敏感的循环做自动向量化处理。这里涉及到的 LLVM 后端能力和优化能力远超一般“编译 C 代码”的应用场景。实际调试 llvmpipe 时会因为 256 位向量、SIMD 指令选择、寄存器分配等问题频繁深入到 LLVM 的后端内部逻辑因此 llvmpipe 也是一个极好的学习 LLVM JIT 与代码生成内部机制的入口。3.6 其他值得关注的子项目compiler-rt提供编译器生成代码时的运行时支持库例如__sanitizer家族AddressSanitizer、UndefinedBehaviorSanitizer 等、__builtin实现、profile 运行时等是工程级代码质量保障利器。libc / libcabiLLVM 官方的 C 标准库实现配合 Clang 使用时能避免 GCC 头文件对非标准特性的依赖调试体验清晰。lldbLLVM 生态的调试器与 LLVM/Clang 共享代码解析基础设施对现代语言调试支持更好。polly基于多面体模型的循环优化框架能以高层次的视角改写嵌套循环是程序自动并行化和数据局部性优化的重要研究方向。flangLLVM 官方的 Fortran 前端让经典科学计算语言也进入 LLVM 生态。4. 核心实操环节4.1 基于 LLVM 写一个自定义 pass理解 LLVM 最快的方式就是写一个优化 pass。LLVM 的 pass 框架经历了多次演变从最早的 legacy PM到现在的 new pass manager。以现在主流的 new pass manager 为例一个简单的函数级 pass 长这样#include llvm/IR/Function.h #include llvm/IR/Instructions.h #include llvm/IR/LegacyPassManager.h #include llvm/Pass.h #include llvm/Passes/PassBuilder.h #include llvm/Passes/PassPlugin.h using namespace llvm; namespace { struct MyPass : public PassInfoMixinMyPass { PreservedAnalyses run(Function F, FunctionAnalysisManager AM) { for (BasicBlock BB : F) { for (Instruction I : BB) { if (auto *Op dyn_castBinaryOperator(I)) { if (Op-getOpcode() Instruction::Add) { errs() Found add in function: F.getName() \n; } } } } return PreservedAnalyses::all(); } }; } // namespace extern C ::llvm::PassPluginLibraryInfo LLVM_ATTRIBUTE_WEAK llvmGetPassPluginInfo() { return {LLVM_PLUGIN_API_VERSION, MyPass, LLVM_VERSION_STRING, [](PassBuilder PB) { PB.registerPipelineParsingCallback( [](StringRef Name, FunctionPassManager FPM, ArrayRefPassBuilder::PipelineElement) { if (Name my-pass) { FPM.addPass(MyPass()); return true; } return false; }); }}; }将代码编译成动态库后可以通过 Clang 的-fpass-plugin选项加载观察它对每个加法指令的识别。这个示例同时展示了 LLVM pass 的调试方式和插件化扩展能力你不需要重新编译整个 LLVM只要编译这个独立的 pass 插件就能完成对编译流程的定制。对于企业级开发这种机制让编译器基础设施能够像中间件一样被团队按需集成。4.2 使用 llvmpipe 做无显卡环境渲染调试假设你在一个没有 GPU 的服务器上跑图形相关的测试可以强制 Mesa 使用 llvmpipe 作为渲染设备export LIBGL_ALWAYS_SOFTWAREtrue export GALLIUM_DRIVERllvmpipe然后运行glxinfo | grep OpenGL renderer正常情况下你应该看到类似输出OpenGL renderer string: llvmpipe (LLVM 15.0.7, 256 bits)这里的 “256 bits” 指的是 llvmpipe 在当前 CPU 上使用的 SIMD 向量位宽。现代 x86 处理器通过 AVX2 寄存器实现 256 位向量运算llvmpipe 就是借助 LLVM 的自动向量化能力把像素着色器中的标量计算转换成 SIMD 指令从而在无 GPU 条件下尽量榨干 CPU 的并行算力。如果你看到的是 “128 bits”说明当前环境没有启用 AVX2或者 llvmpipe 检测到 CPU 不支持 256 位操作。可以尝试确认 CPU 特性、检查编译时的目标选项、以及 Mesa 的构建配置。这种细节排查对于在容器化环境里做图形基准测试的人非常实用。4.3 编写自定义后端的第一步TableGen 目标描述如果你想为一种全新的 CPU 架构编写 LLVM 后端第一步是写 TableGen 文件描述指令集。LLVM 的后端并非把指令信息硬编码在 C 里而是用 TableGen 这种领域专用语言描述指令格式、寄存器、调用约定等信息再由 TableGen 工具自动生成庞大的 C 代码包括指令选择器、汇编器、反汇编器等。这套描述方法虽然上手曲线陡峭但一旦你理解了 TableGen 的声明式写法维护后端的工作量比手写所有代码要小一个数量级。一个非常简单的寄存器描述示例如下def GPR : RegisterClassMyTarget, [i32], 0, (add R0, R1, R2, R3); def ADDrr : MyTargetInst(outs GPR:$dst), (ins GPR:$src1, GPR:$src2), add $dst, $src1, $src2, [];这行描述告诉 LLVM有一条加法指令将两个寄存器操作数相加结果写回目标寄存器指令的汇编形式是 “add”。TableGen 工具会为这个描述生成匹配器Matcher和发射器Emitter相关的 C 代码文件帮助编译器自动完成从 SelectionDAG / GlobalISel 节点到机器指令的映射。4.4 工程中怎么选 LLVM 版本版本选择直接影响你的开发体验。LLVM 每六个月发布一个主版本通常 3 月和 9 月各一次。对于生产项目我建议至少使用上一稳定版避开 .0 这种首发版因为首发版往往伴随着构建脚本的小问题和部分 API 的不稳定。比如 llvmpipe 在某个较新版本中的渲染行为回归就曾经给我们的软渲染方案带来过困扰。如果你依赖 LLVM 的 C API请留意 API 在版本间的破坏性变更。new pass manager 在 LLVM 14 左右基本稳定如果想在这个领域做长期开发选 LLVM 16 比较稳妥。另外Ubuntu 等发行版提供的 LLVM 包通常不是最新版但足够稳定适合想避免源码编译开销的人。从工程维护角度另一个建议是把 LLVM 构建集成到 CI 中而不是只靠本地构建。因为 LLVM 庞大的代码量导致构建失败往往是在编译器、链接器或某个 obscure 依赖库的版本不匹配上提前在 CI 里发现问题可以节省大量团队协作成本。5. 常见问题与排查技巧实录5.1 构建时 OOM 怎么办LLVM 在链接 clang 或者 lld 时经常爆内存。我的解决方案是不要限制并行度但限制大目标文件的链接并发-DLLVM_PARALLEL_LINK_JOBS2这个参数控制同时运行的链接任务数量能有效压低内存峰值。如果机器内存只有 16GB建议设置成 1 或 2如果是 32GB 以上可以适当放宽。更多的时候瓶颈会出现在链接单个超级大目标文件时比如LLVMCore或Clang这时候可以利用 lld 的--threads1选项降低内存消耗虽然链接时间变长但至少不会 OOM。另外如果是在容器里构建注意容器本身的内存限制不是宿主机内存有多少容器 CGroup 只分配了一部分。5.2 运行 clang 时报 “Could not find compiler-rt” 或者 “unable to find viable overloaded operator” 之类诡异错误前者大多是路径配置问题检查clang -print-resource-dir输出是否正确看看lib/linux/libclang_rt.*是否确实在那个目录下。后者则可能是你的 Libc 和 libstdc 头文件混用导致的标准库冲突。如果使用-stdliblibc编译确保所有翻译单元都用了同一个标准库不要和默认的 libstdc 混着来。5.3 增量构建不生效这类问题常发生在 ccache 和 CMake 的缓存之间。如果改了某个头文件但增量构建没有重新编译相关目标可以先清掉 ccache 再重新构建确认是否是缓存误判。也可以重新生成 CMake 缓存有时 CMake 对依赖图的追踪不够精细会错过一些直接赋值的源码改动。还有一点不要使用ninja -j$(nproc)之外的通配并行度如果机器超卖CPU 核数不是越多越好反而因为调度开销拖慢整体时间。我通常用ninja -j$(($(nproc) - 2))留出核心给系统其他进程。5.4 调试 pass 时看不到打印输出新 pass manager 的 pass 打印输出与旧版行为不同因为 pass 的执行顺序由 PassBuilder 统一管理再加上 optimization level 的过滤很多自定义 pass 根本没被跑起来就会觉得“怎么没输出”。这时候建议先用opt -passesmy-pass -disable-output example.ll手动跑一下看能不能输出。如果手动能跑但在 clang 里加载不了再查 plugin 的注册逻辑是否被正确链接。5.5 为什么 llvmpipe 在 ARM 机器上慢得离谱llvmpipe 的性能高度依赖于 SIMD 指令集。ARM 架构上的 NEON 通常是 128 位对应位宽就显示为 128 bits性能相比 x86 的 AVX2 会有数倍差距。此外如果 llvmpipe 构建时没有启用正确的 CPU 特性例如缺少-mcpunativeJIT 生成的代码就不会利用 NEON 指令性能会进一步退化。可以用MESA_DEBUG1环境变量打开 Mesa 的调试输出确认 JIT 相关的编译信息。5.6 链接时 LTO 报错LTO 是 LLVM 的优势功能但引入它也意味着要处理“跨编译单元的优化需要全部 IR 一起处理”的问题。常见错误有module flags冲突、mismatched debug info等。多数情况是不同编译单元使用了不同编译选项尤其是-g与不带-g混编。还有一种情况是某些库使用了非 LLVM 编译器编译比如 GCC GFortran 编译的对象文件和开启 LTO 的 Clang 代码链接时会因为 LLVM bitcode 和普通对象文件混在一起而报错。解决方案是给相关库加上-Wno-errorlto-type-mismatch或者统一全部用 Clang 编译。6. 给新手的几条实操建议如果你是刚接触 llvm-project我建议按以下路径循序进入先从 Swift 或 Rust 的 Toolchain 里认识 LLVM 的存在感试着用rustc --print sysroot找找其中的 LLVM 动态库。用现成的发行版 LLVM 包写一个小 pass搭出 pass 脚手架跑opt手动验证 IR 变换效果。不要上来就源码编译整个 LLVM先跑通工具链流程。然后按照需求构建一份源码版本做到能针对某个模块单独调试。最终才深入 TableGen 和 CodeGen那是 LLVM 最深的地方。另外强烈建议把llvm-project的 GitHub release 页面加入关注列表。每当主版本发布release notes 必看尤其关注 API 变更和构建系统变动这些细节决定了你升级 LLVM 版本时的成本和风险。调试层面的小工具也建议提前熟悉opt -print-after-all可以打印 pass 执行前后的 IRllvm-mca可以做静态性能分析llvm-mc可以单独对汇编片段做解析输出llvm-objdump配合反汇编指令解读复杂问题的现象。这些东西在写后端的路上几乎天天都要用到。在 llvmpipe 的调试里还有一个隐藏技巧是设置LP_DEBUG1它能输出 llvmpipe 内部关于渲染管线状态的信息包括是否走了慢速失败路径。做软渲染开发和诊断图形驱动问题时这个调试开关比 gdb 打断点还要高效因为它直接暴露了 llvmpipe 引擎在哪个阶段选择放弃快速路径。回看这一路的折腾我认为 llvm-project 最可贵的地方在于它把“编译器”这个概念从一个封闭的黑盒开放成了一整套理解编程语言和硬件的框架。无论你想做的是一门新语言的前端、一个为特定芯片设计的指令选择器、一套用于程序分析的静态工具还是一个不依赖 GPU 的渲染后端llvm-project 都提供了坚实而高效的底座。如果你打算长期深耕底层系统软件尽早深入 LLVM把它的构建、IR、pass、后端这套链路摸熟会是一笔回报率极高的投资。
