很多刚接触编译技术的朋友第一次看到llvm-project这个仓库名都会有点懵看起来是一个项目但git clone下来之后动辄 20GB编译一次少则三四个小时多则一夜仓库里塞满了llvm、clang、lld、libc、compiler-rt这种一眼看不出用途的目录。这篇文章我想从一个多年使用 LLVM 的从业者视角把llvm-project当作一个具体项目来拆解它究竟是什么、怎么把它构建起来、代码从哪里开始读、怎么真正尝试去修改它以及哪些配套子项目值得关注。内容偏实操适合编译器爱好者、嵌入式工程师、语言开发者也适合那些做性能调优或想做静态分析的开发者。1. 从20GB源码里找门路llvm-project的仓库解剖1.1 它不是一个项目而是一整套编译工具链很多人以为llvm-project就是“LLVM 编译器”其实不够准确。LLVM 项目最初是伊利诺伊大学的一个研究型编译器框架后来慢慢变成了一个庞大的工具链生态而llvm-project是这些子项目的统一 monorepo。简单说你 clone 下来的不是一个单一代码库而是一整个“编译器全家桶”。monorepo 的优点是所有组件的版本天然同步改一个接口可以同步跑全量测试不用担心clang和llvm版本错配。这一点对日常开发和 CI 非常友好也是现在 LLVM 基金会选择把所有项目打包在一个仓库里的原因。典型结构长这样llvm-project/ ├── clang/ # C/C/Objective-C 前端 ├── clang-tools-extra/ # clang-tidy、clangd 等辅助工具 ├── cmake/ # 公共 CMake 配置 ├── compiler-rt/ # sanitizer、profile、builtin 等运行时库 ├── flang/ # Fortran 前端 ├── libc/ # LLVM 的 C 标准库实现 ├── libc/ # LLVM 的 C 标准库实现 ├── libcabi/ # C ABI 支持层 ├── libunwind/ # 栈回溯库 ├── lld/ # 链接器 ├── llvm/ # 核心中间表示、优化器、后端 ├── lldb/ # 调试器 ├── mlir/ # 可扩展的编译器中间表示框架 ├── polly/ # 基于多面体模型的循环优化 ├── pstl/ # 并行标准库 └── third-party/其中llvm/是整个项目的核心里面是独立的llvm代码树包括 IR 定义、Pass 优化框架、各后端目标实现。clang/则是使用 LLVM 作为后端的最著名前端很多嵌入式开发者其实只用 clang 编译交叉编译根本没碰过llvm/内部的源码。1.2 一个容易误会的点“LLVM”到底指什么这里必须岔开说一个初学者经常混淆的点当你看到“LLVM”时它可能是三个层次的东西广义上指整个 LLVM 生态包括 clang、lld、libc 等狭义上特指llvm/目录下的核心库和工具有时它又特指 LLVM IR即中间表示。在llvm-project语境下一般说的是广义生态。所以当你读 README 或者搜索资料时先搞清楚对方说的是哪一层否则会绕很多弯路。比如有人问“LLVM 能优化我的 Rust 代码吗”严格说 Rust 默认后端确实是 LLVM但他想问的其实是rustc这中间的层次关系完全不同。1.3 为什么仓库这么大llvm-project体积大的原因不只是“代码多”还因为里面包含了大量测试文件、lit 测试用例、跨平台的后端描述、自动生成的 TableGen 源码以及各种支持和验证代码。很多子项目都是“代码 测试”对半开甚至测试占大头。我见过有人为了省体积用--depth 1浅克隆但仍然会拉下来不少东西因为没有--filter的话所有子项目的文件都会被拉取。如果只是用 clang 做日常编译其实没必要 clone 整个仓库。但如果你要研究或修改某一块比如想看看libc的实现或者想自己写一个 LLVM Pass那这个 monorepo 反而是最优选择因为你改完llvm/里的代码可以直接在同一套构建里测试 clang 和 opt 工具。2. 首次构建不再翻车下载、CMake与链接内存一个都不能少2.1 环境准备与依赖构建llvm-project的门槛不高但如果你用的环境太老很容易在配置阶段就去世。我在 Ubuntu 上用的一直是 GCC 12配合 CMake 3.28 以上Ninja 1.11Python 3.10 以上。LLVM 官方对编译器版本要求越来越苛刻比如新版本可能要 GCC 7.4 以上但建议别压着最低线走否则编译clang时偶尔会遇到标准库头文件缺失这种莫名其妙的错误。依赖上需要ninja-build、cmake、gcc/g、python3以及zlib、libxml2之类的开发包。如果是 macOS需要 Xcode Command Line ToolsWindows 上我建议直接装 Visual Studio 2022然后用Ninja clang-cl或者Visual Studio Generator两种路线前者速度更快后者配置省心。磁盘空间方面源码加构建产物至少准备 80GB。可能很多人觉得夸张但Release Assert模式下光是llvm和clang这两个目标加起来就常常超过 40GB。不想占太多空间的话后面会说怎么裁剪目标架构和组件。2.2 clone 的正确姿势很多教程会告诉你直接跑git clone https://github.com/llvm/llvm-project.git这没问题但如果你想节省时间我会建议浅克隆加分支过滤。想实际开发就用--depth 1先省一半体积等你要看历史时再git fetch --unshallow。我一般用git clone --filterblob:none --depth 1 https://github.com/llvm/llvm-project.git--filterblob:none可以延迟下载文件内容先只拿提交树和文件元信息需要 checkout 时才真正拉 blob。这个技巧在网速一般的时候能明显降低首次下载的等待时间。2.3 CMake 配置别把所有组件都编译一遍你会发现官方文档里最常出现的构建命令是这样的cmake -S llvm-project/llvm -B build \ -DCMAKE_BUILD_TYPERelease \ -DLLVM_ENABLE_PROJECTSclang;lld \ -DLLVM_TARGETS_TO_BUILDX86 \ -G Ninja cmake --build build -- -j$(nproc)第一次构建的人很容易踩两个坑一个是漏了-DLLVM_ENABLE_PROJECTS结果只构建出llvm核心库和opt、llc工具没有 clang另一个是没指定LLVM_TARGETS_TO_BUILD默认把 X86、ARM、AArch64、RISCV、WebAssembly 等几十个后端全编一遍时间直接翻倍。LLVM_ENABLE_PROJECTS控制的是clang、lld、compiler-rt这些独立子项目它们默认不参与构建。LLVM_TARGETS_TO_BUILD则控制后端目标架构。我们日常在 x86 机器上做开发写X86就够了做交叉编译时再加ARM或AArch64非常灵活。2.4 构建加速ccache、lld与链接并发第一次全量构建是最煎熬的。clang和llvm加起来通常要编译几万个源文件CPU 强的话半小时到一小时能完成弱一点的机器三小时起步。我的建议是三条第一开 ccache。LLVM 这种大项目非常适合缓存编译结果改动一个头文件导致大量重编译时ccache 的命中率能让你少等很久。CMake 阶段加一行-DCMAKE_C_COMPILER_LAUNCHERccache -DCMAKE_CXX_COMPILER_LAUNCHERccache第二用 ninja。Ninja 的并行调度比 make 强太多大项目里能让 CPU 跑得更满交互也更快。第三给链接器设并发上限。纯 C 项目编译要不了多少内存真正爆内存的是链接阶段。多个大型二进制同时链接每个ld可能吃掉 4~8GB很容易 OOM。Ninja 可以通过环境变量限制链接任务数export NINJA_STATUS[%f/%t %es] cmake --build build -- -j16 ninja -j2 # 如果链接内存不够更优雅的做法是在 CMake 配置里设置LLVM_PARALLEL_LINK_JOBS2只限制链接并发编译并发还是可以拉到满。2.5 构建常见错误三个我在不同平台反复遇到过的坑ld 内存不足提示clang: error: unable to execute command: Killed或者ld.lld: error: link failed。应对方式是配置上提到的LLVM_PARALLEL_LINK_JOBS或换用lld作为项目链接器内存占用更低速度更快。构建 LLVM 的推荐做法就是让 clang 用 lld 链接自己-DLLVM_ENABLE_LLDON即可。头文件 with modifications在 macOS 上经常遇到系统自带的 libc 和项目内 libc 冲突导致编译自己的 Pass 时提示各种诡异的std::符号错误。解决办法是统一工具链在项目里用同一个 clang并显式指定 include 路径。Debug 版本体积爆炸默认Debug构建的 LLVM 极为膨胀单个工具几百 MB 很常见而且运行奇慢。不是调试 LLVM 本身的话用Release加 CI 标志LLVM_ENABLE_ASSERTIONSON就能兼顾安全和性能。断言打开后很多算法内部检查也会启用对开发 LLVM Pass 的人来说发现问题更快。3. 源码阅读路线从一行C代码到机器码的旅程3.1 三段式架构前端、中端、后端想读懂llvm-project的源码必须先建立一张地图。经典编译器分三段前端把高级语言变成中间表示优化器对中间表示做变换后端把优化后的 IR 变成目标汇编和二进制。这三段在llvm-project里对应不同的目录前段clang/、flang/中段llvm/lib/IR、llvm/lib/Transforms、llvm/lib/Passes后端llvm/lib/Target下面按架构分目录比如X86、ARM、RISCV、WebAssembly理解这个结构后你就知道阅读路径应该顺着“前端 - IR - 优化 - 后端”这条线走而不是东看一块西看一块。3.2 前端如何生成 IR以clang为例最常用的观察方法是把 C 代码转成可读的.ll文件cat hello.c int add(int a, int b) { return a b; } clang -S -emit-llvm hello.c -o hello.ll生成的hello.ll长这样简化define i32 add(i32 noundef %a, i32 noundef %b) { %add add nsw i32 %a, %b ret i32 %add }clang/目录下负责生成 IR 的核心代码在clang/lib/CodeGen/其中CGStmt.cpp负责语句的生成CGExpr.cpp负责表达式的生成。如果你想知道一个for循环在 IR 层面怎么表示直接翻CGStmt.cpp里的EmitForStmt函数。可读性比想象中好很多起码注释和函数名很直白。3.3 IR 上的优化到底在做什么中间表示是 LLVM 的灵魂。IR 是一种静态单赋值形式SSA每个变量只能被赋值一次这极大方便了数据流分析。llvm/lib/IR/定义了Instruction、BasicBlock、Function、Module等核心类llvm/lib/Transforms/下是按优化类型分的目录Scalar/各种标量优化比如死代码消除、循环不变量外提Vectorize/循环向量化和 SLPVectorizerIPO/跨函数优化比如内联Utils/工具性质的重写比如PromoteMemToReg读这些代码时不需要一上来就啃算法细节建议先在你自己的.ll文件上跑几个 pass 看效果再回源码对照理解。比如opt -passesadce hello.ll -S -o hello.adce.ll-passesadce是积极死代码消除执行后你会看到不再使用的指令被删掉。再去看llvm/lib/Transforms/Scalar/ADCE.cpp你就知道它对每条指令做了一个“是否仍有外部可观察副作用”的判断比普通 DCE 留存的边界更宽。3.4 后端从 IR 到汇编IR 被优化完接下来是llc的工作。llc负责把 LLVM IR 转成目标机器代码核心流程包括指令选择、寄存器分配、指令调度、代码布局等。比如llc hello.ll -o hello.s -mtriplex86_64llvm/lib/Target/X86/下你会看到大量.td文件这是 TableGen 语言描述的指令集信息比如X86InstrInfo.td描述了 x86 指令的编码格式、操作数类型和指令选择规则。TableGen 是 LLVM 项目里很有特色的一块相当于用领域特定语言描述目标机器的指令再用脚本生成 C 代码。刚开始读会觉得像外语看几遍就能理解它其实是在描述“这条指令怎么匹配、怎么编码、带什么约束”。3.5 用工具建立直觉读源码的最大误区是抱着几万行文件硬啃。我的习惯是先用工具把 IR 和汇编打出来建立直觉再回到源码里找对应实现。llvm-project自带的分析工具非常全这里列几个我常用的工具作用clang -emit-llvm把前端输入转成 IRopt -passes...在 IR 上跑指定的优化llc把 IR 生成汇编llvm-dis把 bitcode 转回可读的.llllvm-mca机器码性能分析能看到吞吐量、延迟llvm-objdump反编译目标文件llvm-cxxfilt符号还原看 C 符号表时很实用这些工具在build/bin/下面构建完就有了。读源码之前先在终端里反复摆弄它们你会省下很多看文档的时间。4. 动手写LLVM Pass最小示例与运行时踩坑4.1 为什么要自己写 Pass如果你的目标只是“看懂 LLVM”那不一定需要写代码但如果你想做自定义静态分析、面向特定场景的优化、或者把 LLVM 集成到自己的工具链里写一个 Pass 是绕不开的第一步。Pass 的本质是一段可以在 IR 上进行的变换或分析逻辑。LLVM 提供了统一的 Pass 管理框架你可以把 Pass 编译成动态库用opt来加载。4.2 最小示例打印函数名我练手时写过的最小的一个 Pass 是“打印模块里所有函数的名字”。用新 Pass Manager 的写法如下#include llvm/IR/Function.h #include llvm/IR/Module.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 FunctionNamePrinter : public PassInfoMixinFunctionNamePrinter { PreservedAnalyses run(Module M, ModuleAnalysisManager AM) { for (auto F : M) outs() function: F.getName() \n; return PreservedAnalyses::all(); } }; } // namespace extern C LLVM_ATTRIBUTE_WEAK ::llvm::PassPluginLibraryInfo llvmGetPassPluginInfo() { return {LLVM_PLUGIN_API_VERSION, FunctionNamePrinter, 0.1, [](PassBuilder PB) { PB.registerPipelineParsingCallback( [](StringRef Name, ModulePassManager MPM, ArrayRefPassBuilder::PipelineElement) { if (Name function-name-printer) { MPM.addPass(FunctionNamePrinter()); return true; } return false; }); }}; }这里需要简单解释一下代码结构run方法是对 Module 的主入口里头遍历每个 Function用outs()打印函数名。PassPluginLibraryInfo是插件导出接口registerPipelineParsingCallback让opt -passesfunction-name-printer能识别这个自定义 pass。4.3 编译成动态库编译这个 Pass 时最省事的方式是借用 LLVM 的 CMake 工具链。如果你已经有构建好的 LLVM 目录可以建一个独立小工程CMakeLists.txt里通过find_package(LLVM REQUIRED CONFIG)引入 LLVM 的目标路径然后:mkdir pass-build cd pass-build cmake -DLT_LLVM_INSTALL_DIR$HOME/llvm-project/build /path/to/your/pass-src make如果没有走安装流程find_package就需要指定LLVM_DIR为build/lib/cmake/llvm。这一步是新手最容易卡住的地方因为文档里通常假设“你已经在系统里安装好了 LLVM”而实际开发是在源码目录里直接用。我踩过一次之后就把LLVM_DIR和Clang_DIR写进了环境变量长期省心。4.4 用 opt 运行自定义 Pass编译成功后你会得到一个.so文件然后用之前生成的hello.ll来测试opt -load-pass-plugin./build/libFunctionNamePrinter.so \ -passesfunction-name-printer \ hello.ll -S -o /dev/null如果输出里出现了function: add之类的结果说明 Pass 能正常工作。整个流程跑通后你就算真正踏进了 LLVM 开发和扩展的大门。之后再学runOnFunction、Analysis、PreservedAnalyses等概念会顺很多。4.5 新 Pass Manager 和旧 Pass Manager 的区别网上很多老教程还在写旧的FunctionPass接口每次都要实现runOnFunction并返回false。新 Pass Manager 则更强调显式的 Analysis 依赖和更清晰的生命周期。现在 LLVM 官方正面建议用新 Pass ManagerOpt 命令行默认也已经切到新 PM。如果你在编译时遇到“PB.registerPipelineParsingCallback找不到”之类的错误多半是代码里混用了旧的legacy::FunctionPass接口。建议尽量跟着官方llvm/examples/Bye/里的示例走它是作为示例保留的新 PM 插件代码历久弥新。4.6 动手前先学会调试写 Pass 一定会遇到崩溃。我在最初上手时就经常调到一个错误的指令指针就挂掉。Debug 的经验是这样的先确认 IR 是合法的再确认 pass 注册名正确然后用-debug-pass-manager开关看 pass 是否被正确调度最后在代码里加dbgs()打印关键信息。遇到段错误先开AddressSanitizer构建 LLVM定位信息和速度都会好很多。5. 那些容易被忽略的宝藏子项目5.1 lld链接速度上的最大提升用过ld.gold或系统默认ld的人初次用lld通常会惊讶于它的速度。LLVM 项目里lld/就是官方链接器它把传统ld的十几秒缩短到一两秒特别是带调试信息的大项目优势更明显。自从把公司的 C 工程切到-fuse-ldlld之后增量构建节省的时间非常可观几乎成了团队标配。5.2 compiler-rtsanitizer 全家桶compiler-rt/下有AddressSanitizerASan、UndefinedBehaviorSanitizerUBSan、ThreadSanitizerTSan等运行时库。很多人天天-fsanitizeaddress跑测试却不清楚实现就在这个目录里。ASan 的基本原理是插桩内存访问把每次读写映射到影子内存并检查合法性能精确抓到越界数组、use-after-free 这类内存问题。如果你想深入底层内存检测compiler-rt/lib/asan/是个非常不错的实战样本。5.3 MLIR编译器基础设施在 AI 领域的变体mlir/是相对年轻但热度很高的子项目它提供了一个可扩展的中间表示框架让开发者可以使用多级抽象比如从高层算子图一路 lower 到底层循环或特定硬件指令。如今很多 AI 编译框架如 TensorFlow、PyTorch 的部分编译器路径都基于 MLIR 思路。如果你做机器学习编译或异构计算mlir/比传统 LLVM Pass 更贴近你的场景但学习曲线也更陡理解 ODS、Dialect、Type 体系需要额外花不少时间。5.4 libc 和 libunwind标准库的另一面libc是 LLVM 项目的 C 标准库实现和 libstdc 相比可读性更好模块化也更强。在 macOS 上系统大量使用 libcLinux 上如果你用 clang 编译指定-stdliblibc也能切过去。libc的源码是学习 STL 实现细节的好材料比如想看std::string的 SSO 优化可以直接在libcxx/include/string里找到相关代码。5.5 flang 与 clang-tools-extraflang是 Fortran 前端如果你做科学计算这块很有价值clang-tools-extra则包含了clang-tidy、clangd、clang-format等日常频繁使用的工具。这些工具同样属于llvm-project构建clang后只要在LLVM_ENABLE_PROJECTS里加上clang-tools-extra就能一起编出来。很多人单独下载 clangd 来用却不知道它其实也是这个仓库的一部分。6. 构建和使用中的通用建议我从实战里总结的几条6.1 版本与发行版的关系LLVM 项目每半年发布一个大版本GitHub 主分支通常是最新开发版。如果你是为了稳定使用我建议直接切到llvmorg-18.1.8这类发布 tag而不是追 main。新版往往意味着新特性和新优化但也意味着潜在的回归和接口变化。真实项目里最怕的就是半路升级导致现有 Pass 接口失效所以尽量用长期稳定版本或者固定 commit 构建。6.2 不要盲目打开全部组件前面提到LLVM_ENABLE_PROJECTS默认是空但有些人会写-DLLVM_ENABLE_PROJECTSall这在配置新版本时可能编译出惨烈的耗时。建议按需选择。如果你只是用 clang 编译 C 代码那么clang加lld就够了做静态分析再加clang-tools-extra跑测试要compiler-rt用 MLIR 再把mlir加进去。全部打开不仅编译时间爆炸测试也容易互相报错干扰我第一次全量构建就翻车在 runtime 测试阶段。6.3 关于测试的建议LLVM 自带测试系统是lit。构建完以后运行大型测试经常会因为机器资源不足而挂掉但不代表代码有问题。经验是先跑小范围测试比如ninja check-llvm-unit再针对特定目录运行 litllvm-lit test/Transforms/ADCE当你修改了某个 Pass至少要把与该 Pass 相关的测试跑通。很多我见过的新手一上来就ninja check-all机器一卡就误以为是自己代码改动引起的问题白白浪费时间。7. 写在最后把这个仓库真正用起来如果前面这么多内容你只想记住三件事那我认为是第一llvm-project是一个 monorepo使用之前先看它的LLVM_ENABLE_PROJECTS和LLVM_TARGETS_TO_BUILD别盲目构建第二从“clang -S -emit-llvm-opt-llc”这条工具链上建立对编译过程的直觉再回到llvm/lib/里追具体实现第三自己写一个最小的 Pass 跑通之后你会发现这个看似庞大的仓库突然变得亲切了因为你知道它最有价值的那条扩展路径在哪里。我最初开始接触 LLVM 时也犯过很多错误比如在 16GB 内存的机器上不加限制地并行链接直接 OOM比如默认 Target 全开导致一次构建跑了一晚上再比如把新 Pass Manager 和旧接口混在一起编译错误一屏又一屏。现在回头看这些坑基本都是信息差不是能力问题。所以这篇文章没有堆一大堆理论术语而是尽可能把当时我希望别人能告诉我的经验写出来。只要你愿意花一个下午把构建流程跑通再用一个晚上写一个自己的 Pass之后再面对任何编译工具链问题你都会比大多数人更有底气。因为你知道这个庞大的项目内部是怎么组织、怎么构建、怎么扩展的剩下的一切都只是顺着这条路径继续往前走而已。