CTO 当时拍板要把手里那一大坨编译器工具链整体迁移到 LLVM 架构上。当时我们几个核心开发坐在会议室里听完整个计划的第一反应不是“这个技术选型对不对”而是“我们到底要从哪里开始看这份代码”。llvm-project 这个仓库说大是真的大说乱也真的乱但一旦你摸清了它的骨架后面学到的每一层设计都会让你觉得以前写的那些编译器相关代码只是冰山一角。这篇文章不是给 LLVM 写使用手册而是我从零开始啃 llvm-project 的实际路线。我会从“它到底解决了什么问题”讲起把仓库里那些天天被人挂在嘴边的子项目逐个拆开再把构建、调试、贡献的实操细节也一并交代清楚。如果你正准备入坑编译器、优化器、代码生成这些方向这篇文章应该能帮你少走不少弯路。1. LLVM 到底是什么它解决了什么问题1.1 从 Low Level Virtual Machine 到编译器基础设施LLVM 这个名字最早确实来源于 Low Level Virtual Machine但今天它已经和“虚拟机”没什么关系了。当你打开 llvm-project 仓库你看到的是一个完整的编译器基础设施它提供了中间表示IR、优化管线、代码生成、链接器、标准库、调试器甚至还有用于构建 AI 编译器的 MLIR 框架。与其说它是一个编译器不如说它是一整套“造编译器”的积木。为什么业界会对这个东西如此狂热关键原因在于它的三段式架构。传统编译器比如 GCC的架构比较“整体式”前端负责把源代码变成中间表示优化器对中间表示做处理后端生成目标机器码。这三个阶段耦合很深你要想给一门新语言做一个编译器就需要把整个编译器栈全都重写一遍你要想支持一个新的 CPU 架构同样也要从语言的前端一路改到后端的寄存器分配器。这种模型不是不能工作而是太“重”了。LLVM 的思路是把编译过程彻底拆开Clang 负责把 C/C 等语言变成 LLVM IR优化器专门针对 LLVM IR 做各种 pass后端CodeGen则把 LLVM IR 变成目标平台的汇编或机器码。前端、优化器、后端各自独立接口就是 LLVM IR 本身你可以只替换其中一个环节其他部分完全复用。这种松耦合的设计在今天的行业里几乎是“标准答案”你想给 Rust 做一套新的编译目标直接把 Rust 的前端接到 LLVM 的后端上你想给公司自研芯片做工具链直接用 LLVM 的优化器和代码生成只需要换一个后端描述。1.2 LLVM 架构的核心设计哲学LLVM 之所以能这么灵活架构上有一个非常核心的抽象就是 LLVM IR。它是一门“中间语言”但它不是像 C 那样的高级语言也不是像 x86 汇编那样的低级语言。它的风格我一般跟别人解释时会说它是一套“放在编译器中间的 RISC 指令集”每条指令都做了显式的类型标注内存访问和计算被清楚地区分开所有值都以静态单赋值SSA形式存在也就是说每个变量只赋值一次。这种设计的直接好处是优化器可以非常方便地分析程序的数据流。你不用靠别名分析来解决“一个变量被改了之后另一个变量还能不能用”的问题因为 SSA 形式天然保证了每个值只被定义一次。与此同时LLVM IR 又被设计成“可读的人类文本”也就是说你运行clang -S -emit-llvm之后能直接看到优化前的 IR很容易调试和验证 pass 是否存在问题。仓库里另一个随处可见的设计哲学是“库化”。LLVM 核心代码几乎全部以静态库的形式组织你可以按需链接到自己的工具中而不是像传统编译器那样把整套程序捆绑在一起。正是这种“库化”设计才支撑起了后来 Clang 静态分析器、LLD 链接器、甚至各种商业化工具链的快速发展。对学习源码的人而言这也是个好消息你可以只编译特定组件单独看某一段代码逻辑而不必每次都全量构建整个项目。1.3 我们为什么要关注 llvm-project关注度这件事完全不需要我替它吹。现在几乎所有主流移动端、桌面端、游戏主机、嵌入式芯片的编译器工具链都或多或少地在使用 LLVM 技术。苹果的 Xcode 默认编译器就是 Clang/LLVMAndroid NDK 从 r13 版本开始不再默认使用 GCCRust 的官方编译器 rustc 使用 LLVM 做后端Swift 的编译器也是基于 LLVM各家 GPU 厂商的驱动编译器里同样能见到它的身影。除了编译器本身MLIR 还被大模型编译器、HPC 编译器、芯片设计工具广泛使用你可以说 llvm-project 已经不只是编译器爱好者的专属领域而是整个基础软件生态里绕不开的底层设施。如果你所在的公司或团队未来有自研语言、自研芯片工具链、性能调优工具这类计划早一天把 llvm-project 看懂就多一分对底层技术栈的掌控力。这个项目的学习曲线确实陡但投入产出比非常高。2. 从零构建把 llvm-project 跑起来的完整流程2.1 需要准备的环境与依赖想要理解 llvm-project最好还是先动手把它编译一遍。直接看代码和真正跑完一次构建对仓库的体量感是完全不一样的。我先给你一个环境最低配置操作系统Ubuntu 22.04 这类 Linux 发行版体验最佳macOS 也能跑Windows 上用 Visual Studio 或 MinGW 也可以但坑会多一些。内存建议不低于 16GB尤其是要同时构建 Clang 和多个后端目标时。8GB 内存也能勉强跑但很容易在链接阶段把内存吃满。磁盘源码加构建产物预留至少 60GB 比较稳妥。Release 类型构建后所有库和二进制加起来体积很大。工具CMake 3.20 以上、Ninja、GCC 或 Clang、Python 3。构建过程中要用到 Python 去运行各种测试和脚本。这里多提一句如果你本机已经装了比较高版本的 Clang建议用 Clang 来编译 LLVM。因为 LLVM 自身是 Clang 的“主战场”很多测试和编译选项都需要用 Clang 才能触发完整功能。只装 GCC 也不是不行很多发行版默认就能过但某些分析和测试用例的表现会不一样。2.2 CMake 配置参数逐个拆解llvm-project 的构建官方推荐直接用 CMake Ninja。以下是我经常使用的一组配置我会把每个关键参数都拆开讲清楚cmake -S llvm-project/llvm -B build -G Ninja \ -DCMAKE_BUILD_TYPERelease \ -DLLVM_ENABLE_PROJECTSclang;lld;clang-tools-extra \ -DLLVM_TARGETS_TO_BUILDX86;AArch64;RISCV \ -DLLVM_USE_LINKERlld \ -DLLVM_CCACHE_BUILDON-S llvm-project/llvm源码根目录不是llvm-project本身而是它里面的llvm子目录这一点很多人第一次会搞错。-G NinjaNinja 比 Make 在并行构建上的调度更智能增量构建速度明显更快。-DCMAKE_BUILD_TYPERelease构建类型。默认情况下 LLVM 会开启大量断言编译和运行都会变慢。Release 会关闭断言、开启优化产物比 Debug 小得多。平日调试源码时我会选RelWithDebInfo也就是开启优化但保留调试符号。-DLLVM_ENABLE_PROJECTSclang;lld;clang-tools-extra这里指定要构建哪些上层子项目。注意只要不是和 LLVM 核心绑定的项目基本都要通过这个变量显式打开。-DLLVM_TARGETS_TO_BUILDX86;AArch64;RISCV指定后端目标。全部目标都编译非常耗时日常只编自己需要的几个就好。-DLLVM_USE_LINKERlld用 lld 做链接器。链接 LLVM 这种大项目时链接速度能快很多倍强烈推荐。-DLLVM_CCACHE_BUILDON开启 ccache 缓存后续反复修改头文件或切换配置时能省下大量重建时间。配置完成后直接运行ninja即可开始构建。不加参数时默认会构建全部目标如果你只想构建 clang可以运行ninja clang只想测试某个组件也可以先构建对应的 check 目标。2.3 构建过程的避坑与实测心得首次全量构建 Clang 加 LLVM 核心库在我的机器上16 核 CPU32GB 内存大概要 15 到 20 分钟。如果不小心把全部后端目标都编了三四十分钟也是常事。这里有几个实战中容易踩的坑先放出来提醒你并行数不是越大越好。我建议用ninja -j后面跟的核心数不要超过物理核数超线程对某些编译步骤帮助有限反而会让内存占用爆掉。别在构建中途看到“某个测试失败”就慌。构建阶段失败通常是环境问题可以先用ninja -k 0让 Ninja 尽量多执行几个任务方便一次性看到所有报错。如果是从老版本 LLVM 升级构建目录尽量清掉 build 目录重新配置 CMake。LLVM 的 CMake 配置经常会引入新的选项或改变旧的默认值旧缓存容易导致一些“莫名其妙”的编译错误。链接阶段进程被 OOM 杀掉最常见的就是c: fatal error: Killed signal terminated program cc1plus。这时需要减少并行任务数或者换用 lld 做链接器。我第一次使用这个仓库时就是因为没有用 lld导致在链接libLLVM.so时卡了非常久还时不时被 OOM 杀掉。换成-DLLVM_USE_LINKERlld之后问题直接消失。如果你是在老一点的发行版上担心系统 lld 版本太低也可以手动指定路径比如-DLLVM_USE_LINKER/usr/bin/ld.lld-14。3. llvm-project 子项目漫游谁在解决什么问题3.1 核心子项目作用对照表llvm-project 这个仓库从名字看好像是一个项目打开里面的目录才发现是一堆项目拼在一起。下面这张表是我觉得最值得先了解的子项目你后续看代码时心里先有个地图。子项目目录作用典型使用场景llvm/LLVM 核心库与工具包含 IR 定义、优化 pass、代码生成、后端学习编译器后端、写优化 passclang/C/C/Objective-C 前端大部分开发者最先接触的部分clang-tools-extra/clang-tidy、clangd、clang-format 等工具代码静态检查、IDE、代码格式化lld/链接器链接速度优先时的首选链接器compiler-rt/运行时库包含 ASan、UBSan、TSan 等工具内存检测、未定义行为检测平时做性能分析时也会用到libcxx/与libcxxabi/C 标准库实现与 ABI 层使用 Clang 构建 C 项目时的运行时支持libunwind/C 异常与栈回溯支持配合 libc 使用lldb/调试器断点调试、内存分析非常适合看 Flutter/LLVM 自身代码时使用mlir/多层次 IR 基础设施AI 编译器、张量编译器、自定义 DSL 编译器flang/Fortran 前端HPC 和科学计算相关项目polly/基于多面体模型的循环优化高性能计算领域我刚开始接触这个仓库时最容易犯的错误就是混淆llvm和clang的关系。clang只是 llvm-project 里的一个前端它负责把 C/C 源码转换成 LLVM IR后续优化和代码生成都在llvm目录下的系统里完成。你写一个.c文件然后敲clang -O2实际上是 clang 加 LLVM 优化器加后端代码生成三者的联合工作而不是 clang 一个程序从头做到了尾。3.2 最容易被忽视的工具Compiler-RT 与 LLD很多人接触 LLVM 都是从 Clang 开始的但我想特别说一下compiler-rt和lld这俩在 llvm-project 里名气不如 Clang实际价值却一点不低。compiler-rt是编译器运行时库ASanAddressSanitizer、UBSanUndefinedBehaviorSanitizer、TSanThreadSanitizer都在这边实现。我刚工作时线上 C 服务出现内存越界排查手段几乎就是反复看代码和用 GDB。后来在公司内部推广-fsanitizeaddress很多隐藏问题跑一遍单测就能暴露出来。它的实现原理是编译时插入对内存访问的检查代码运行时维护一个影子内存区域来追踪每块内存的状态一旦发现有越界访问就立刻报错并打印堆栈。对技术人员来说这个子项目可以说是性价比最高的内功心法之一。lld则是高性能链接器。早些年链接一个大型 C 项目动辄几十秒甚至几分钟换成 lld 之后经常几秒就结束。它对 ELF、Mach-O、COFF 都支持而且很多构建系统现在默认就会优先使用 lld比如 Chromium、Android 等大型项目。你要看代码重点可以放在它的 lld/ELF 目录那是一个非常适合研究链接流程的入口代码量不大但逻辑非常完整。3.3 MLIRLLVM 项目的“第二曲线”如果只看 2025 年这个时间点mlir/目录可以说是 llvm-project 里最热的新增长点。MLIR 的全称是 Multi-Level Intermediate Representation它想解决的问题是传统编译器只有一层 LLVM IR但现代编译任务往往需要很多不同抽象级别的中间表示比如 AI 框架里既有张量级别的计算图也有循环级别的变换最终还要落到底层硬件指令。如果从高层语义直接降到 LLVM IR信息丢失太严重很多优化根本做不了。MLIR 引入了“dialect”这个概念你可以把每种中间表示定义为一个 dialect在同一个编译流程中容纳多个层次的 IR。比如说 TensorFlow 或 PyTorch 的模型可以先转换到tensordialect经过一系列张量优化后再逐步 lower 到linalg、affine最后到达 LLVM dialect再交给 LLVM 后端生成机器码。这套思路让 MLIR 成了 AI 编译器、芯片编译器、HPC 编译器等领域的新宠。我在一个做自研芯片工具链的项目里用过 MLIR最大的体会是它把“如何设计多层 IR”从一门经验活变成了一个标准化的框架。你不需要自己从头搭一套编译器基础设施只需要定义好自己需要的 dialect然后写 lowering pass 就行。现在主流的大模型部署工具链底层几乎都能看到 MLIR 的身影这也是为什么我建议编译器新手把 MLIR 列入必读清单。4. 深入 LLVM IR 与表驱动开发这门手艺的精髓4.1 LLVM IR优化器的通用语言如果你想真正理解 llvm-project绕不开的一个核心概念就是 LLVM IR。它可以被看作是所有前端和后端之间的“契约”Clang 生成 IR优化器处理 IR后端消费 IR。我建议每个入坑的人先学会用肉眼读 IR再看优化 pass 的代码。举一个非常简单的例子。我们写一个 C 函数int add(int a, int b) { return a b; }用clang -S -emit-llvm -O2 add.c生成后可以看到类似这样的 IRdefine i32 add(i32 %a, i32 %b) local_unnamed_addr { %add add nsw i32 %a, %b ret i32 %add }注意每一行都带类型信息i32就是 32 位整数%a和%b是函数参数名。add nsw里的nsw是no signed wrap表示这个加法不会发生有符号溢出编译器可以依此做一些更激进的优化。这种显式类型、显式 SSA 形式的设计让优化器可以非常容易地做各种变换。如果你之前接触过编译原理但没写过 IR pass我建议你从llvm/lib/Transforms/Scalar/下面的简单 pass 开始看。比如EarlyCSE、GVN这类 pass代码量适中逻辑容易理解能帮你把 IR 和优化算法对上号。4.2 TableGenLLVM 的元编程艺术LLVM 这套代码里几乎没有哪份后端指令集描述文件是一行一行手写固有指令的。它有一个非常重要的组件叫 TableGen通常简写为 td它本质上是一个领域特定语言用来描述目标架构的各种属性然后通过 tablegen 工具生成 C 代码。比如说你想为一个新的 CPU 后端定义一个加法指令通常会在.td文件里描述指令的助记符、编码、操作数类型、约束等信息。TableGen 会把这些信息展开成一系列 C 类和方法供指令选择器、汇编器、反汇编器、机器码输出器共同使用。这样做的好处非常明显你只需要维护一份描述就能保证后端各个模块之间的数据始终一致不会出现“汇编器支持的指令在反汇编器里却是另一套定义”这种问题。我刚开始看llvm/lib/Target/X86/X86InstrInfo.td时感觉像是在读一门新语言完全看不懂。后来试着给一个开源 RISC-V 后端加了两条自定义指令才真正理解它的价值一条指令的代价往往是不到十行的.td描述然后就能自动出现在汇编器、反汇编器和指令选择器中。这种“改数据不改逻辑”的开发体验比手撸几份 C 代码要优雅太多。4.3 源码阅读实践建议读 LLVM 源码最忌讳从头到尾线性阅读因为代码量极大你很快就会迷失。我的方法是按“需求驱动”来读先明确一个问题然后顺着问题的线索跳着看。一个常见路径是想知道某个 C 语言写法最终变成什么汇编指令就先用 Clang 编译生成 IR再看 IR 优化结果最后用llc生成目标汇编反查它是通过哪段后端代码做的指令选择。这套流程跑通之后你对 LLVM 的抽象层次会形成非常立体的认知。另一个路径是从 pass 入手。比如某个编译器优化让你觉得很有意思你可以在llvm/lib/Transforms/里找到对应源码逐步打断点或加打印观察一个 IR 样例在 pass 前后的变化。实践下来这种“用问题牵引源码阅读”的方式比从命令行帮助信息开始啃要有效得多。5. 上手贡献如何从看代码变成改代码5.1 代码风格与 Review 文化如果你在 llvm-project 里提交代码第一件事就是要学会它的代码风格。LLVM 有自己专门的.clang-format文件通常要求使用clang-format格式化后再提交并且遵循它的命名规范类型名用大驼峰函数名用小驼峰变量名也是小驼峰类成员变量以_结尾等等。一开始会觉得约束很多但好处是整个项目代码风格高度统一。提交信息方面LLVM 有个不成文的惯例标题通常写成[模块] 简短描述比如[CodeGen] Fix crash on empty return statements。正文要解释“为什么”而不是简单描述“改了什么”。这个习惯在开源社区很受重视我自己的经验是把所有相关背景都写进 commit message过几个月回看时你会感激自己当时写得很详细。Code review 通常是走 GitHub 的 Pull Request。项目维护者非常看重每个 commit 是否有足够多的测试覆盖。你修一个 bug最好同时带上一个能够复现该 bug 的测试用例而不是只贴修复代码。这一点在 LLVM 社区几乎是硬性要求。5.2 跑测试lit 与 FileCheckLLVM 的测试体系主要基于lit和FileCheck两个工具。lit负责发现测试用例、执行命令、汇总结果FileCheck通过匹配输出文本中的模式来判断测试是否通过。一个简单的 IR 测试可能长这样; RUN: opt -passesinstcombine -S %s | FileCheck %s ; CHECK: %add add i32 %a, %b define i32 test(i32 %a, i32 %b) { %x add i32 %a, %b %y add i32 %x, 0 ret i32 %y }RUN告诉 lit 要执行什么命令CHECK指明期望看到的结果。很多人在第一次提交 LLVM 补丁时都会低估写测试的重要性但维护者们往往非常严格没有测试的补丁基本不太可能被合入。另外LLVM 社区一直比较强调“先发测试用例证明 bug 存在再发修复代码”的做法。你在 PR 中放一个能复现问题的测试维护者看起来会轻松很多也更容易信任这个改动。5.3 新手任务选择很多人问第一次给 llvm-project 贡献代码应该从什么地方开始我的建议是先去找一个真实存在但改动小的 bug 修而不是一上来就写一个新的优化 pass。你可以在 GitHub 的 issue 区里找good first issue相关标签也可以看一下clang-tools-extra或lld这类相对独立的子项目它们不像核心 CodeGen 那样对全局影响大非常适合入门。我自己的第一个 LLVM commit就是给一个诊断信息补全了[[nodiscard]]属性。改动非常小但流程走完后我对“如何跑测试、如何提交、如何回复 review 意见”熟悉起来了。后面再去改 CodeGen 相关的代码心里就有底了。建议你也用这种“小步快跑”的方式切入创业公司的说法叫“先把闭环跑通”。6. 常见问题与排查技巧实录6.1 构建环境问题速查表下面这张表是我不止一次在实际环境里遇到的坑。这些问题看着小但每一个都能让你白白浪费半天。现象可能原因解决办法链接阶段提示ld.lld: error: undefined symbol某些子项目没有启用或 LLVM 版本不匹配检查LLVM_ENABLE_PROJECTS确认相关组件都已打开CMake 配置后Ninja 生成时提示找不到clangCMake 缓存过期或CMAKE_C_COMPILER指向被删除的工具链清空 build 目录重新配置显式指定编译器路径编译 Clang 时内存不足 OOM并行任务太多降低-j并发数或启用 lld 链接考虑使用 ccache运行 clang 时提示error while loading shared libraries: libLLVM.so动态库路径没有配置设置LD_LIBRARY_PATH指向 build/lib或改用静态链接方式FileCheck测试报错但看不出问题生成文件中存在平台差异比如路径分隔符、汇编注释符号使用llvm/utils/update_test_checks.py自动更新 CHECK 行Debug 构建运行巨慢Debug 模式下 LLVM 有大量断言且优化等级为 -O0需要调试时使用RelWithDebInfo日常编译用 Release这里有一个我特别想强调的细节LLVM 的 Debug 构建和 Release 构建性能差异可以达到 10 倍以上。如果你只是想把项目跑起来做实验建议用 Release如果你要改源码、设断点、观察 pass 过程选择RelWithDebInfo更合理。它会在保留大多数优化的情况下给出调试符号体验好了不止一点。6.2 修改源码后的调试技巧给 LLVM 提交代码或者做二次开发真正的难点往往不在于“改代码”而在于“验证修改是否生效”。有一种比较通用的调试手段是对某个 pass 或某个 API 打日志用opt -passes... -debug-only...这类选项输出调试信息。LLVM 内部有大量LLVM_DEBUG(dbgs() ...)的打印语句平时默认不显示开启对应 debug 类型后就能看到 pass 内部的处理过程。另一种非常高效的定位方式是使用精简后的 IR 测试用例。当你怀疑某个优化 pass 或多个 pass 交互导致生成结果不对时把一个大的源码文件用clang -S -emit-llvm转成 IR然后手动精简到一行函数就能复现的程度。这样可以大大缩小排查范围尤其适用于 CodeGen 相关的疑难 bug。我自己在定位一个寄存器分配器崩溃时就是靠这种方式把几万行的测试用例一点点减到 20 行以内最后才发现是一个非常冷门的指令模式没有处理。另外提醒一点修改头文件之后增量构建可能不会像预期那样完美。LLVM 的头文件依赖非常稠密改一个核心头文件可能会触发大规模重编。建议在开发时把编译单元拆小尽量让改动局部化如果大规模重编实在避免不了那就把 ccache 用起来能省大量时间。6.3 从构建到 debug 的一体化工作流最后分享一个我个人比较喜欢的工作流。我会把 llvm-project 的源码、build 目录和一个小测试目录放在同一个工作空间下。平常写完代码先在你的测试目录里创建一个.ll文件然后用build/bin/opt或build/bin/llc单独跑通核心流程确认 IR 处理结果符合预期之后再用build/bin/clang做一次全流程验证最后再跑 lit 测试和完整回归。这套流程的妙处在于大多数时候你不需要构建整棵 LLVM 树只跑那一个二进制文件即可。尤其是当你只修改了一个 pass 时ninja opt和ninja llc通常只要几十秒或几分钟比全量重复构建快得多。等所有逻辑验证完了再干净利落地提交 commit然后跑一次ninja check-all做全量回归这时候即使有零星失败也容易定位。结尾我在实际使用 llvm-project 的这些日子里最深的一个体会是这个项目看起来庞大但它从来不是靠“魔改乱堆”的方式长成的每一个子项目、每一层抽象背后都有非常清晰的设计动机。你要做的不是一次性把它全部吞下去而是找到一个切入点比如 Clang 前端、某个优化 pass、某个后端 target或者 MLIR 里的某个 dialect然后顺着这个点向外延伸。如果你正准备开始我的建议是先花一个下午把 LLVM 构建起来再用 clang 生成 IR亲手跑几个优化 pass打通这套“编译实验”的感觉。这个项目后续还能给你带来多少东西取决于你愿意深入多少但至少第一步永远不会白走。
CTO 当时拍板要把手里那一大坨编译器工具链整体迁移到 LLVM 架构上。当时我们几个核心开发坐在会议室里听完整个计划的第一反应不是“这个技术选型对不对”而是“我们到底要从哪里开始看这份代码”。llvm-project 这个仓库说大是真的大说乱也真的乱但一旦你摸清了它的骨架后面学到的每一层设计都会让你觉得以前写的那些编译器相关代码只是冰山一角。这篇文章不是给 LLVM 写使用手册而是我从零开始啃 llvm-project 的实际路线。我会从“它到底解决了什么问题”讲起把仓库里那些天天被人挂在嘴边的子项目逐个拆开再把构建、调试、贡献的实操细节也一并交代清楚。如果你正准备入坑编译器、优化器、代码生成这些方向这篇文章应该能帮你少走不少弯路。1. LLVM 到底是什么它解决了什么问题1.1 从 Low Level Virtual Machine 到编译器基础设施LLVM 这个名字最早确实来源于 Low Level Virtual Machine但今天它已经和“虚拟机”没什么关系了。当你打开 llvm-project 仓库你看到的是一个完整的编译器基础设施它提供了中间表示IR、优化管线、代码生成、链接器、标准库、调试器甚至还有用于构建 AI 编译器的 MLIR 框架。与其说它是一个编译器不如说它是一整套“造编译器”的积木。为什么业界会对这个东西如此狂热关键原因在于它的三段式架构。传统编译器比如 GCC的架构比较“整体式”前端负责把源代码变成中间表示优化器对中间表示做处理后端生成目标机器码。这三个阶段耦合很深你要想给一门新语言做一个编译器就需要把整个编译器栈全都重写一遍你要想支持一个新的 CPU 架构同样也要从语言的前端一路改到后端的寄存器分配器。这种模型不是不能工作而是太“重”了。LLVM 的思路是把编译过程彻底拆开Clang 负责把 C/C 等语言变成 LLVM IR优化器专门针对 LLVM IR 做各种 pass后端CodeGen则把 LLVM IR 变成目标平台的汇编或机器码。前端、优化器、后端各自独立接口就是 LLVM IR 本身你可以只替换其中一个环节其他部分完全复用。这种松耦合的设计在今天的行业里几乎是“标准答案”你想给 Rust 做一套新的编译目标直接把 Rust 的前端接到 LLVM 的后端上你想给公司自研芯片做工具链直接用 LLVM 的优化器和代码生成只需要换一个后端描述。1.2 LLVM 架构的核心设计哲学LLVM 之所以能这么灵活架构上有一个非常核心的抽象就是 LLVM IR。它是一门“中间语言”但它不是像 C 那样的高级语言也不是像 x86 汇编那样的低级语言。它的风格我一般跟别人解释时会说它是一套“放在编译器中间的 RISC 指令集”每条指令都做了显式的类型标注内存访问和计算被清楚地区分开所有值都以静态单赋值SSA形式存在也就是说每个变量只赋值一次。这种设计的直接好处是优化器可以非常方便地分析程序的数据流。你不用靠别名分析来解决“一个变量被改了之后另一个变量还能不能用”的问题因为 SSA 形式天然保证了每个值只被定义一次。与此同时LLVM IR 又被设计成“可读的人类文本”也就是说你运行clang -S -emit-llvm之后能直接看到优化前的 IR很容易调试和验证 pass 是否存在问题。仓库里另一个随处可见的设计哲学是“库化”。LLVM 核心代码几乎全部以静态库的形式组织你可以按需链接到自己的工具中而不是像传统编译器那样把整套程序捆绑在一起。正是这种“库化”设计才支撑起了后来 Clang 静态分析器、LLD 链接器、甚至各种商业化工具链的快速发展。对学习源码的人而言这也是个好消息你可以只编译特定组件单独看某一段代码逻辑而不必每次都全量构建整个项目。1.3 我们为什么要关注 llvm-project关注度这件事完全不需要我替它吹。现在几乎所有主流移动端、桌面端、游戏主机、嵌入式芯片的编译器工具链都或多或少地在使用 LLVM 技术。苹果的 Xcode 默认编译器就是 Clang/LLVMAndroid NDK 从 r13 版本开始不再默认使用 GCCRust 的官方编译器 rustc 使用 LLVM 做后端Swift 的编译器也是基于 LLVM各家 GPU 厂商的驱动编译器里同样能见到它的身影。除了编译器本身MLIR 还被大模型编译器、HPC 编译器、芯片设计工具广泛使用你可以说 llvm-project 已经不只是编译器爱好者的专属领域而是整个基础软件生态里绕不开的底层设施。如果你所在的公司或团队未来有自研语言、自研芯片工具链、性能调优工具这类计划早一天把 llvm-project 看懂就多一分对底层技术栈的掌控力。这个项目的学习曲线确实陡但投入产出比非常高。2. 从零构建把 llvm-project 跑起来的完整流程2.1 需要准备的环境与依赖想要理解 llvm-project最好还是先动手把它编译一遍。直接看代码和真正跑完一次构建对仓库的体量感是完全不一样的。我先给你一个环境最低配置操作系统Ubuntu 22.04 这类 Linux 发行版体验最佳macOS 也能跑Windows 上用 Visual Studio 或 MinGW 也可以但坑会多一些。内存建议不低于 16GB尤其是要同时构建 Clang 和多个后端目标时。8GB 内存也能勉强跑但很容易在链接阶段把内存吃满。磁盘源码加构建产物预留至少 60GB 比较稳妥。Release 类型构建后所有库和二进制加起来体积很大。工具CMake 3.20 以上、Ninja、GCC 或 Clang、Python 3。构建过程中要用到 Python 去运行各种测试和脚本。这里多提一句如果你本机已经装了比较高版本的 Clang建议用 Clang 来编译 LLVM。因为 LLVM 自身是 Clang 的“主战场”很多测试和编译选项都需要用 Clang 才能触发完整功能。只装 GCC 也不是不行很多发行版默认就能过但某些分析和测试用例的表现会不一样。2.2 CMake 配置参数逐个拆解llvm-project 的构建官方推荐直接用 CMake Ninja。以下是我经常使用的一组配置我会把每个关键参数都拆开讲清楚cmake -S llvm-project/llvm -B build -G Ninja \ -DCMAKE_BUILD_TYPERelease \ -DLLVM_ENABLE_PROJECTSclang;lld;clang-tools-extra \ -DLLVM_TARGETS_TO_BUILDX86;AArch64;RISCV \ -DLLVM_USE_LINKERlld \ -DLLVM_CCACHE_BUILDON-S llvm-project/llvm源码根目录不是llvm-project本身而是它里面的llvm子目录这一点很多人第一次会搞错。-G NinjaNinja 比 Make 在并行构建上的调度更智能增量构建速度明显更快。-DCMAKE_BUILD_TYPERelease构建类型。默认情况下 LLVM 会开启大量断言编译和运行都会变慢。Release 会关闭断言、开启优化产物比 Debug 小得多。平日调试源码时我会选RelWithDebInfo也就是开启优化但保留调试符号。-DLLVM_ENABLE_PROJECTSclang;lld;clang-tools-extra这里指定要构建哪些上层子项目。注意只要不是和 LLVM 核心绑定的项目基本都要通过这个变量显式打开。-DLLVM_TARGETS_TO_BUILDX86;AArch64;RISCV指定后端目标。全部目标都编译非常耗时日常只编自己需要的几个就好。-DLLVM_USE_LINKERlld用 lld 做链接器。链接 LLVM 这种大项目时链接速度能快很多倍强烈推荐。-DLLVM_CCACHE_BUILDON开启 ccache 缓存后续反复修改头文件或切换配置时能省下大量重建时间。配置完成后直接运行ninja即可开始构建。不加参数时默认会构建全部目标如果你只想构建 clang可以运行ninja clang只想测试某个组件也可以先构建对应的 check 目标。2.3 构建过程的避坑与实测心得首次全量构建 Clang 加 LLVM 核心库在我的机器上16 核 CPU32GB 内存大概要 15 到 20 分钟。如果不小心把全部后端目标都编了三四十分钟也是常事。这里有几个实战中容易踩的坑先放出来提醒你并行数不是越大越好。我建议用ninja -j后面跟的核心数不要超过物理核数超线程对某些编译步骤帮助有限反而会让内存占用爆掉。别在构建中途看到“某个测试失败”就慌。构建阶段失败通常是环境问题可以先用ninja -k 0让 Ninja 尽量多执行几个任务方便一次性看到所有报错。如果是从老版本 LLVM 升级构建目录尽量清掉 build 目录重新配置 CMake。LLVM 的 CMake 配置经常会引入新的选项或改变旧的默认值旧缓存容易导致一些“莫名其妙”的编译错误。链接阶段进程被 OOM 杀掉最常见的就是c: fatal error: Killed signal terminated program cc1plus。这时需要减少并行任务数或者换用 lld 做链接器。我第一次使用这个仓库时就是因为没有用 lld导致在链接libLLVM.so时卡了非常久还时不时被 OOM 杀掉。换成-DLLVM_USE_LINKERlld之后问题直接消失。如果你是在老一点的发行版上担心系统 lld 版本太低也可以手动指定路径比如-DLLVM_USE_LINKER/usr/bin/ld.lld-14。3. llvm-project 子项目漫游谁在解决什么问题3.1 核心子项目作用对照表llvm-project 这个仓库从名字看好像是一个项目打开里面的目录才发现是一堆项目拼在一起。下面这张表是我觉得最值得先了解的子项目你后续看代码时心里先有个地图。子项目目录作用典型使用场景llvm/LLVM 核心库与工具包含 IR 定义、优化 pass、代码生成、后端学习编译器后端、写优化 passclang/C/C/Objective-C 前端大部分开发者最先接触的部分clang-tools-extra/clang-tidy、clangd、clang-format 等工具代码静态检查、IDE、代码格式化lld/链接器链接速度优先时的首选链接器compiler-rt/运行时库包含 ASan、UBSan、TSan 等工具内存检测、未定义行为检测平时做性能分析时也会用到libcxx/与libcxxabi/C 标准库实现与 ABI 层使用 Clang 构建 C 项目时的运行时支持libunwind/C 异常与栈回溯支持配合 libc 使用lldb/调试器断点调试、内存分析非常适合看 Flutter/LLVM 自身代码时使用mlir/多层次 IR 基础设施AI 编译器、张量编译器、自定义 DSL 编译器flang/Fortran 前端HPC 和科学计算相关项目polly/基于多面体模型的循环优化高性能计算领域我刚开始接触这个仓库时最容易犯的错误就是混淆llvm和clang的关系。clang只是 llvm-project 里的一个前端它负责把 C/C 源码转换成 LLVM IR后续优化和代码生成都在llvm目录下的系统里完成。你写一个.c文件然后敲clang -O2实际上是 clang 加 LLVM 优化器加后端代码生成三者的联合工作而不是 clang 一个程序从头做到了尾。3.2 最容易被忽视的工具Compiler-RT 与 LLD很多人接触 LLVM 都是从 Clang 开始的但我想特别说一下compiler-rt和lld这俩在 llvm-project 里名气不如 Clang实际价值却一点不低。compiler-rt是编译器运行时库ASanAddressSanitizer、UBSanUndefinedBehaviorSanitizer、TSanThreadSanitizer都在这边实现。我刚工作时线上 C 服务出现内存越界排查手段几乎就是反复看代码和用 GDB。后来在公司内部推广-fsanitizeaddress很多隐藏问题跑一遍单测就能暴露出来。它的实现原理是编译时插入对内存访问的检查代码运行时维护一个影子内存区域来追踪每块内存的状态一旦发现有越界访问就立刻报错并打印堆栈。对技术人员来说这个子项目可以说是性价比最高的内功心法之一。lld则是高性能链接器。早些年链接一个大型 C 项目动辄几十秒甚至几分钟换成 lld 之后经常几秒就结束。它对 ELF、Mach-O、COFF 都支持而且很多构建系统现在默认就会优先使用 lld比如 Chromium、Android 等大型项目。你要看代码重点可以放在它的 lld/ELF 目录那是一个非常适合研究链接流程的入口代码量不大但逻辑非常完整。3.3 MLIRLLVM 项目的“第二曲线”如果只看 2025 年这个时间点mlir/目录可以说是 llvm-project 里最热的新增长点。MLIR 的全称是 Multi-Level Intermediate Representation它想解决的问题是传统编译器只有一层 LLVM IR但现代编译任务往往需要很多不同抽象级别的中间表示比如 AI 框架里既有张量级别的计算图也有循环级别的变换最终还要落到底层硬件指令。如果从高层语义直接降到 LLVM IR信息丢失太严重很多优化根本做不了。MLIR 引入了“dialect”这个概念你可以把每种中间表示定义为一个 dialect在同一个编译流程中容纳多个层次的 IR。比如说 TensorFlow 或 PyTorch 的模型可以先转换到tensordialect经过一系列张量优化后再逐步 lower 到linalg、affine最后到达 LLVM dialect再交给 LLVM 后端生成机器码。这套思路让 MLIR 成了 AI 编译器、芯片编译器、HPC 编译器等领域的新宠。我在一个做自研芯片工具链的项目里用过 MLIR最大的体会是它把“如何设计多层 IR”从一门经验活变成了一个标准化的框架。你不需要自己从头搭一套编译器基础设施只需要定义好自己需要的 dialect然后写 lowering pass 就行。现在主流的大模型部署工具链底层几乎都能看到 MLIR 的身影这也是为什么我建议编译器新手把 MLIR 列入必读清单。4. 深入 LLVM IR 与表驱动开发这门手艺的精髓4.1 LLVM IR优化器的通用语言如果你想真正理解 llvm-project绕不开的一个核心概念就是 LLVM IR。它可以被看作是所有前端和后端之间的“契约”Clang 生成 IR优化器处理 IR后端消费 IR。我建议每个入坑的人先学会用肉眼读 IR再看优化 pass 的代码。举一个非常简单的例子。我们写一个 C 函数int add(int a, int b) { return a b; }用clang -S -emit-llvm -O2 add.c生成后可以看到类似这样的 IRdefine i32 add(i32 %a, i32 %b) local_unnamed_addr { %add add nsw i32 %a, %b ret i32 %add }注意每一行都带类型信息i32就是 32 位整数%a和%b是函数参数名。add nsw里的nsw是no signed wrap表示这个加法不会发生有符号溢出编译器可以依此做一些更激进的优化。这种显式类型、显式 SSA 形式的设计让优化器可以非常容易地做各种变换。如果你之前接触过编译原理但没写过 IR pass我建议你从llvm/lib/Transforms/Scalar/下面的简单 pass 开始看。比如EarlyCSE、GVN这类 pass代码量适中逻辑容易理解能帮你把 IR 和优化算法对上号。4.2 TableGenLLVM 的元编程艺术LLVM 这套代码里几乎没有哪份后端指令集描述文件是一行一行手写固有指令的。它有一个非常重要的组件叫 TableGen通常简写为 td它本质上是一个领域特定语言用来描述目标架构的各种属性然后通过 tablegen 工具生成 C 代码。比如说你想为一个新的 CPU 后端定义一个加法指令通常会在.td文件里描述指令的助记符、编码、操作数类型、约束等信息。TableGen 会把这些信息展开成一系列 C 类和方法供指令选择器、汇编器、反汇编器、机器码输出器共同使用。这样做的好处非常明显你只需要维护一份描述就能保证后端各个模块之间的数据始终一致不会出现“汇编器支持的指令在反汇编器里却是另一套定义”这种问题。我刚开始看llvm/lib/Target/X86/X86InstrInfo.td时感觉像是在读一门新语言完全看不懂。后来试着给一个开源 RISC-V 后端加了两条自定义指令才真正理解它的价值一条指令的代价往往是不到十行的.td描述然后就能自动出现在汇编器、反汇编器和指令选择器中。这种“改数据不改逻辑”的开发体验比手撸几份 C 代码要优雅太多。4.3 源码阅读实践建议读 LLVM 源码最忌讳从头到尾线性阅读因为代码量极大你很快就会迷失。我的方法是按“需求驱动”来读先明确一个问题然后顺着问题的线索跳着看。一个常见路径是想知道某个 C 语言写法最终变成什么汇编指令就先用 Clang 编译生成 IR再看 IR 优化结果最后用llc生成目标汇编反查它是通过哪段后端代码做的指令选择。这套流程跑通之后你对 LLVM 的抽象层次会形成非常立体的认知。另一个路径是从 pass 入手。比如某个编译器优化让你觉得很有意思你可以在llvm/lib/Transforms/里找到对应源码逐步打断点或加打印观察一个 IR 样例在 pass 前后的变化。实践下来这种“用问题牵引源码阅读”的方式比从命令行帮助信息开始啃要有效得多。5. 上手贡献如何从看代码变成改代码5.1 代码风格与 Review 文化如果你在 llvm-project 里提交代码第一件事就是要学会它的代码风格。LLVM 有自己专门的.clang-format文件通常要求使用clang-format格式化后再提交并且遵循它的命名规范类型名用大驼峰函数名用小驼峰变量名也是小驼峰类成员变量以_结尾等等。一开始会觉得约束很多但好处是整个项目代码风格高度统一。提交信息方面LLVM 有个不成文的惯例标题通常写成[模块] 简短描述比如[CodeGen] Fix crash on empty return statements。正文要解释“为什么”而不是简单描述“改了什么”。这个习惯在开源社区很受重视我自己的经验是把所有相关背景都写进 commit message过几个月回看时你会感激自己当时写得很详细。Code review 通常是走 GitHub 的 Pull Request。项目维护者非常看重每个 commit 是否有足够多的测试覆盖。你修一个 bug最好同时带上一个能够复现该 bug 的测试用例而不是只贴修复代码。这一点在 LLVM 社区几乎是硬性要求。5.2 跑测试lit 与 FileCheckLLVM 的测试体系主要基于lit和FileCheck两个工具。lit负责发现测试用例、执行命令、汇总结果FileCheck通过匹配输出文本中的模式来判断测试是否通过。一个简单的 IR 测试可能长这样; RUN: opt -passesinstcombine -S %s | FileCheck %s ; CHECK: %add add i32 %a, %b define i32 test(i32 %a, i32 %b) { %x add i32 %a, %b %y add i32 %x, 0 ret i32 %y }RUN告诉 lit 要执行什么命令CHECK指明期望看到的结果。很多人在第一次提交 LLVM 补丁时都会低估写测试的重要性但维护者们往往非常严格没有测试的补丁基本不太可能被合入。另外LLVM 社区一直比较强调“先发测试用例证明 bug 存在再发修复代码”的做法。你在 PR 中放一个能复现问题的测试维护者看起来会轻松很多也更容易信任这个改动。5.3 新手任务选择很多人问第一次给 llvm-project 贡献代码应该从什么地方开始我的建议是先去找一个真实存在但改动小的 bug 修而不是一上来就写一个新的优化 pass。你可以在 GitHub 的 issue 区里找good first issue相关标签也可以看一下clang-tools-extra或lld这类相对独立的子项目它们不像核心 CodeGen 那样对全局影响大非常适合入门。我自己的第一个 LLVM commit就是给一个诊断信息补全了[[nodiscard]]属性。改动非常小但流程走完后我对“如何跑测试、如何提交、如何回复 review 意见”熟悉起来了。后面再去改 CodeGen 相关的代码心里就有底了。建议你也用这种“小步快跑”的方式切入创业公司的说法叫“先把闭环跑通”。6. 常见问题与排查技巧实录6.1 构建环境问题速查表下面这张表是我不止一次在实际环境里遇到的坑。这些问题看着小但每一个都能让你白白浪费半天。现象可能原因解决办法链接阶段提示ld.lld: error: undefined symbol某些子项目没有启用或 LLVM 版本不匹配检查LLVM_ENABLE_PROJECTS确认相关组件都已打开CMake 配置后Ninja 生成时提示找不到clangCMake 缓存过期或CMAKE_C_COMPILER指向被删除的工具链清空 build 目录重新配置显式指定编译器路径编译 Clang 时内存不足 OOM并行任务太多降低-j并发数或启用 lld 链接考虑使用 ccache运行 clang 时提示error while loading shared libraries: libLLVM.so动态库路径没有配置设置LD_LIBRARY_PATH指向 build/lib或改用静态链接方式FileCheck测试报错但看不出问题生成文件中存在平台差异比如路径分隔符、汇编注释符号使用llvm/utils/update_test_checks.py自动更新 CHECK 行Debug 构建运行巨慢Debug 模式下 LLVM 有大量断言且优化等级为 -O0需要调试时使用RelWithDebInfo日常编译用 Release这里有一个我特别想强调的细节LLVM 的 Debug 构建和 Release 构建性能差异可以达到 10 倍以上。如果你只是想把项目跑起来做实验建议用 Release如果你要改源码、设断点、观察 pass 过程选择RelWithDebInfo更合理。它会在保留大多数优化的情况下给出调试符号体验好了不止一点。6.2 修改源码后的调试技巧给 LLVM 提交代码或者做二次开发真正的难点往往不在于“改代码”而在于“验证修改是否生效”。有一种比较通用的调试手段是对某个 pass 或某个 API 打日志用opt -passes... -debug-only...这类选项输出调试信息。LLVM 内部有大量LLVM_DEBUG(dbgs() ...)的打印语句平时默认不显示开启对应 debug 类型后就能看到 pass 内部的处理过程。另一种非常高效的定位方式是使用精简后的 IR 测试用例。当你怀疑某个优化 pass 或多个 pass 交互导致生成结果不对时把一个大的源码文件用clang -S -emit-llvm转成 IR然后手动精简到一行函数就能复现的程度。这样可以大大缩小排查范围尤其适用于 CodeGen 相关的疑难 bug。我自己在定位一个寄存器分配器崩溃时就是靠这种方式把几万行的测试用例一点点减到 20 行以内最后才发现是一个非常冷门的指令模式没有处理。另外提醒一点修改头文件之后增量构建可能不会像预期那样完美。LLVM 的头文件依赖非常稠密改一个核心头文件可能会触发大规模重编。建议在开发时把编译单元拆小尽量让改动局部化如果大规模重编实在避免不了那就把 ccache 用起来能省大量时间。6.3 从构建到 debug 的一体化工作流最后分享一个我个人比较喜欢的工作流。我会把 llvm-project 的源码、build 目录和一个小测试目录放在同一个工作空间下。平常写完代码先在你的测试目录里创建一个.ll文件然后用build/bin/opt或build/bin/llc单独跑通核心流程确认 IR 处理结果符合预期之后再用build/bin/clang做一次全流程验证最后再跑 lit 测试和完整回归。这套流程的妙处在于大多数时候你不需要构建整棵 LLVM 树只跑那一个二进制文件即可。尤其是当你只修改了一个 pass 时ninja opt和ninja llc通常只要几十秒或几分钟比全量重复构建快得多。等所有逻辑验证完了再干净利落地提交 commit然后跑一次ninja check-all做全量回归这时候即使有零星失败也容易定位。结尾我在实际使用 llvm-project 的这些日子里最深的一个体会是这个项目看起来庞大但它从来不是靠“魔改乱堆”的方式长成的每一个子项目、每一层抽象背后都有非常清晰的设计动机。你要做的不是一次性把它全部吞下去而是找到一个切入点比如 Clang 前端、某个优化 pass、某个后端 target或者 MLIR 里的某个 dialect然后顺着这个点向外延伸。如果你正准备开始我的建议是先花一个下午把 LLVM 构建起来再用 clang 生成 IR亲手跑几个优化 pass打通这套“编译实验”的感觉。这个项目后续还能给你带来多少东西取决于你愿意深入多少但至少第一步永远不会白走。
