企业官网建设流程全解析

“llvm-project”这个名字，对很多刚开始接触编译器、或者已经写了几年业务代码但没深入过编译原理的同学来说，是个既熟悉又模糊的存在。你大概率见过它，知道它是 LLVM 的代码仓库，甚至可能在 GitHub 上 star 过，但真当你需要进入这个仓库做点什么的时候——不管是想研究优化 pass、给 Clang 提一个 warning，还是出于好奇想把这个超大项目从源码构建一遍——你才会意识到，这不是一个“下载下来看看”就能搞定的项目。

它可能是目前人类开源社区里最复杂的 C++ 工程之一。我不夸张地说，llvm-project 里面包含的不仅是编译器前端、中端、后端，还包括调试器、链接器、标准库、运行时、向量化库、还有一整套用于构建编译器基础设施的框架。读完这篇文章，不说让你成为 LLVM 专家，但至少你会对整个仓库的布局、从哪里下手、怎么构建、怎么调试、怎么提交 patch，有一个清晰且能直接落地的认识。

1. 项目整体认知与领域定位

1.1 它不只是一个编译器

很多人以为“LLVM 就是编译器”，这句话准确但不完整。llvm-project 是一个“编译器基础设施”集合。什么叫做基础设施？就是说，它不仅提供了一个能干活的产品（比如 Clang 编译器），更重要的是提供了一套被无数其他项目所依赖的底层能力。你可以把 LLVM 理解成一块“编译器乐高底板”，Clang、Flang、lld、libc++ 这些具体工具，都是在这块底板上拼出来的成品，而其他像 Rust、Swift、Julia、GPU 编译、FPGA 综合工具、人工智能推理引擎，也都在这块底板上面各取所需。

这个仓库的边界在近几年越来越大。现在它的顶层目录里，除了传统的llvm/和clang/，还要加上lld/、lldb/、compiler-rt/、mlir/、flang/、polly/、libc/、libcxx/、libcxxabi/、libunwind/等十几个子项目。跟早年“一个 monorepo 装全家桶”的思路不同，现在 LLVM 的开发模式已经默认把所有组件放到同一个仓库、同一个 commit 下做协同演进。这样的好处很明显：跨组件的 API 变更不再需要繁琐的“先改 A 再改 B 再改 C”的独立 PR 流程，而是可以像改一个工程内的一个模块那样直接完成原子修改。

也正是因为这个原因，如果你要参与 LLVM 开发，或者你只是想在内部工具链里基于 LLVM 做一些二次开发，你几乎必然要面对“整个仓库”而不是某个独立小项目。过去那种“我只想弄个 Clang 前端，不想编译其他部分”的操作变得越来越困难，因为架构已经高度耦合。所以我的建议是，别抗拒 monorepo，与其纠结“为什么这么大”，不如先把它当成一个整体来理解。

1.2 为什么值得读源码/参与贡献

参与 LLVM 不等于“给世界上最难的编译器贡献代码”，它有非常多种进入方式。我之前在社区里见过不少贡献者，有的就是从修一个测试用例格式开始的，有的是从改进llvm-mca的文档注释开始的，真正一上来就改 Instruction Selection 的人反而是少数。这个项目最大的魅力在于，它的代码质量和模块化程度在开源界属于顶级水平，阅读它的源码就像读一本活的编译器设计教科书。你在大学里学过的词法分析、语法分析、中间表示、数据流分析、寄存器分配，这里都有最完整、最“生产级”的工程实现。

加上现在 LLVM 不只是传统编译器的代名词，它背后的 MLIR 生态已经成了机器学习和芯片设计领域的“事实标准”。很多做 AI 编译器、做异构计算、做自动化芯片验证的团队，每天都在跟 MLIR 里的linalg、tensor、async这些方言打交道。你如果能把 llvm-project 的源代码读明白，收益不只是“我会写编译器”，而是你等于掌握了现代计算系统里非常底层也非常值钱的那一类工程能力。

2. 源码目录结构与仓库布局

2.1 顶层目录到底是怎么分工的

很多新手刚打开 llvm-project 仓库，第一反应是：这么多目录，先看哪个？我列几个最核心的，并告诉你它们各自解决什么问题：

• llvm/：核心，包含整个中间表示（IR）、优化器、目标描述、代码生成、向量化等底层实现。无论你以后用哪个组件，都得依赖这部分。
• clang/：C/C++/Objective-C 的编译器前端。它的任务是把源码变成 LLVM IR，并负责产生警告、错误诊断和语法树相关的所有工作。
• lld/：一个新的、内置的链接器。现在很多 Linux 发行版、Android、iOS 工具链都把 lld 作为默认链接器之一，速度比传统 GNU ld 快不少。
• lldb/：调试器实现，类似 GDB，但是基于 LLVM 的库设计，天然能读取很多 LLVM 格式的调试信息。
• compiler-rt/：编译器运行时库，提供各种底层支持，比如sanitizer，也就是 ASan、UBSan、TSan 这些东西。你要做内存安全检测，离不开这个目录。
• mlir/：MLIR，一套构建“编译器编译器”的框架。你可能用到 MLIR 的地方包括：深度学习编译、HLS（高层次综合）、算法优化等。
• flang/：Fortran 前端。别小看它，科学计算领域还有很多 Fortran 代码，它正逐渐成为“LLVM 全家桶”里的重要成员。
• libcxx/、libcxxabi/、libunwind/：C++ 标准库的实现，以及 C++ ABI 支持。默认 Clang 在 Linux 上会用系统的 libstdc++，但你可以把这些库编译出来作为自定义工具链的配套。
• polly/：一个基于多面体模型的循环优化器，功能很强，但没有成为默认优化流程的一部分，更多是作为一个研究平台存在。

这些目录之间不是孤立的，比如 Clang 会大量使用llvm/下面的 ADT（比如SmallVector、StringRef）、llvm/IR、llvm/CodeGen等模块。你读代码时，经常会看到一个文件里既包含 clang 独有的逻辑，又频繁调用 llvm 的通用基础设施。

2.2 llvm/include 与 llvm/lib 的目录约定

拿llvm/子项目来说，它的核心代码分成include和lib两个大块。include/llvm下面放的是所有对外暴露的头文件，lib下面放的是实现。有一个细节值得记住：这两个目录的结构是严格对应的。你在include/llvm/IR/IRBuilder.h里看到的IRBuilder，实现一定在lib/IR/IRBuilder.cpp。掌握了这个约定，你在阅读任何一个自己没见过的新模块时会非常轻松：只要有头文件路径，你就能推断出实现文件的路径，甚至可以推断出一个新功能应该放在哪里。

llvm/下面还有tools/、test/、unittests/、examples/等目录。tools/是一系列可执行文件，opt、llc、llvm-dis、llvm-as、llvm-nm这些命令行工具都在这。很多人学习 LLVM 就是从在tools/opt里跑一个 pass 开始的。test/则是整个项目的核心测试文件，它用的是lit+FileCheck这套测试框架。你在改动代码后，需要保证ninja check-llvm、ninja check-clang这些测试能通过。

这种目录组织方式也直接影响了社区对代码变更的审查文化。你在 code review 里经常能看到 “Please add test” 这样的要求。只要涉及行为变化，教程文档不重要、注释可以补，但测试是必须有的，而且测试必须放在test/中对应的子目录下。这个习惯对新人来说是最需要适应的。

3. 构建系统与实操配置

3.1 构建前的环境准备

LLVM 的构建对机器配置有一定要求，尤其是当你第一次尝试完整构建的时候，请务必做好心理准备：这是一个比较耗时且吃内存的过程。官方推荐的内存底线是 8GB，实际上你如果要同时构建 Clang 和 lld，16GB 只是起步，32GB 会更舒服一点。磁盘空间上，一个普通的 Release 构建占 20GB 左右很常见，Debug 构建因为包含大量调试符号甚至会奔着 40GB、50GB 去。

系统层面，我推荐先准备好这些依赖：

• 编译器的编译器：LLVM 自身是用 C++17 写的，你需要一个比较新的编译器来编译它。Linux 上推荐 GCC 7 以上或者 Clang 12 以上，macOS 上直接用 Xcode 自带的 Clang 就行。
• CMake：建议 3.20 以上版本。各 LLVM 版本对 CMake 的最低版本要求不同，但尽量新一点总没错。
• Ninja：强烈建议用 Ninja 作为构建后端，比 make 快出好几个量级。命令行敲-G Ninja就好。
• Python 3：lit测试框架要用到它。

在某些 Linux 版本上可能还需要安装zlib、libxml2这些开发包。如果构建过程中报找不到某个头文件，优先检查对应依赖有没有装全。

3.2 第一次完整构建的命令

我以一个相对保守但实用的配置为例，展示一下我平时构建 LLVM 时最常用的一份 CMake 参数：

git clone https://github.com/llvm/llvm-project.git cd llvm-project mkdir build && cd build cmake -G Ninja ../llvm \ -DCMAKE_BUILD_TYPE=Release \ -DLLVM_ENABLE_PROJECTS="clang;lld;clang-tools-extra" \ -DLLVM_TARGETS_TO_BUILD="X86;AArch64" \ -DLLVM_ENABLE_ASSERTIONS=ON \ -DCMAKE_C_COMPILER=clang \ -DCMAKE_CXX_COMPILER=clang++ \ -DCMAKE_CXX_FLAGS="-march=native" \ -DLLVM_PARALLEL_LINK_JOBS=2 ninja -j$(nproc)

我解释一下这里面几个关键参数，因为很多人就是馋 CC 没领会埋伏。

LLVM_ENABLE_PROJECTS决定你需要构建哪些“上层项目”。clang、lld、clang-tools-extra是比较常规的选择。注意一个坑：在比较新的版本里，像libcxx这类库的构建已经转成了LLVM_ENABLE_RUNTIMES，如果你把libcxx放进LLVM_ENABLE_PROJECTS，构建系统可能会给你一个警告甚至直接报错。这个变化让不少人踩过坑，现在如果你需要编译 C++ 标准库，应该用类似-DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind"的配置。

LLVM_TARGETS_TO_BUILD指定目标架构后端。默认会开启 X86、AArch64、ARM、PowerPC、RISCV 等等一大堆，会明显拉长编译时间。如果你只是学习或者做 x86 上的开发，只留X86足够；我顺手加上了 AArch64，因为现在做交叉工具链场景更多。

LLVM_ENABLE_ASSERTIONS是个很微妙的选择。把它设成 ON，你会得到一个更便于调试、能在运行时检查很多不变量的构建，但编译器本身会变慢；设成 OFF，你会得到一个“干净”的发布版，但调试 bug 时容易失去很多线索。开发 LLVM 的人几乎都会开 ON，普通使用场景则一般关掉以获得性能。

最后一个LLVM_PARALLEL_LINK_JOBS=2非常实用。LLVM 的链接阶段特别吃内存，尤其是 Debug 模式，一次性链接几百个目标文件，任何一个 linker 进程吃了 5GB、10GB 内存都不奇怪。限制并行链接任务数可以防止机器在链接阶段被永久卡死。

3.3 常用构建参数与组合打法

我见过不少同学在选构建类型时很随意，结果后来不断返工。这里补充一个“组合拳”视角：你其实不一定需要每次都用同一个构建目录，可以准备多个 build 目录，分别对应不同的目的。

• build-release：CMAKE_BUILD_TYPE=Release，LLVM_ENABLE_ASSERTIONS=OFF，用途是得到一个可发布版本的二进制，比如你要拿来替代系统默认的 Clang，或者跑 benchmark。
• build-debug：CMAKE_BUILD_TYPE=Debug，LLVM_ENABLE_ASSERTIONS=ON，用途是排查问题、单步调试编译器本身。
• build-reldeb：CMAKE_BUILD_TYPE=RelWithDebInfo，LLVM_ENABLE_ASSERTIONS=ON，这个是我个人最常用的开发配置。它比 Debug 快不少，又保留了调试符号和断言，配合 gdb/lldb 用起来非常香。

从性能角度再提一句，如果你只是写个 pass 实验一下，不需要默认开启所有目标架构。我们平时做实验的机器如果不涉及其他架构，一般都会加-DLLVM_TARGETS_TO_BUILD=X86，编译速度会有质的提升。ninja本身也会做增量构建，所以日常开发时其实只要第一次“熬”过去，后面改一小块代码再编译就很快了。

4. 核心组件拆解与工作场景

4.1 LLVM Core：IR、Pass 和 CodeGen

llvm/核心的数据库是全套的中间表示（IR）和优化器。所有前端（Clang、Flang、Rust 等）最终都会产出 IR，所有后端也会从 IR 开始做指令选择、寄存器分配、指令调度。理解 IR 是你深入任何 LLVM 相关工作的第一步。

IR 有三种表示形式：文本格式（.ll）、二进制位码格式（.bc）和在内存中的 C++ 类结构。很多初学同学会直接看.ll文本文件，我建议你一定要学会使用llvm-as、llvm-dis和opt这几个命令行工具。比如你把一个 C 文件编译成 IR，可以这样：

clang -emit-llvm -S foo.c -o foo.ll opt -passes=mem2reg foo.ll -S -o foo.mem2reg.ll

opt -passes是跑优化 pass 的入口。在 LLVM 17 之后，新 Pass Manager 已经全面接管，opt命令的-passes参数是主线，旧的-foo形式已经移除。如果你想看 IR 优化前后的差异，用-print-after-all或者-print-before-all配合llvm-diff都很方便。

从代码结构上来讲，llvm/lib/Passes/PassBuilder.cpp是优化流水线的核心文件之一。你现在看到的 O2、O3 优化级别，并不是硬编码在某个 super pass 里，而是各个 module、function、loop 级别的 pass 按照顺序组合而成。如果你想自己写一个 function pass，最简单的方式是在PassBuilder.cpp中注册一个 pipeline 扩展点，然后在opt里就能用-passes=my-pass来测试。我个人觉得这个流程对新手非常友好，能让一个 pass 在一两个小时内跑起来。

4.2 Clang：前端和诊断信息

Clang 可能是你平时最熟悉的 LLVM 产品。它提供了非常优秀的语法树（AST）、词法分析和语义分析。你日常写的代码在clang里的处理流程大概是：词法分析产生 token，语法分析产生 AST，语义分析在这个阶段解决类型检查和重载决议，然后通过 AST 到 IR 的降级（codegen）生成 LLVM IR。别被这些名词吓到，工程实现远比教科书的描述要细，但大方向就是如此。

如果你想要亲手感受 Clang 的前端处理，可以试试clang -Xclang -ast-dump -fsyntax-only foo.c，它会输出一棵非常完整的语法树。有时候排查宏展开、模板匹配的问题，这个命令比单步调试还好使。

Clang 还有一个亮点，就是它的诊断信息特别友好。你写错一个类型，它不光告诉你“这里错了”，还会标出“为什么错”，甚至给出建议修改。这些诊断逻辑很多都实现了在非常深的语义分析代码里，比如SemaExpr.cpp和SemaOverload.cpp，体积非常大。但这也正是 Clang 能在市场份额上不断超过 GCC 的原因之一：用户体验优秀，工程结构清晰。

4.3 LLD：现代链接器

链接器在传统认知里是个很“无趣”的模块，但 lld 彻底改变了这种印象。它把原本基于脚本的 GNU ld 模式，变成了一个库化、编译友好的链接器。在使用体验上，大多数情况下只需要写clang -fuse-ld=lld，它就会用 lld 完成链接。

从代码层面看，lld 的 ELF 支持在lld/ELF/目录下，涉及“符号解析”、“输入文件描述”、“输出节布局”、“重定位写入”等逻辑。很多人第一次看lld源码觉得很难，一个重要原因是你对 ELF 文件格式不够熟。我建议你先补充一点 ELF 的基础知识：section、symbol、relocation、dynamic section、GOT/PLT 是怎么工作的，再回头看 lld 的代码就不会觉得是天书了。

一个比较有意思的模块是 lld 的并行化。它跟很多传统链接器不同，在设计上非常注重多线程性能，所以在现代大项目链接场景下极快。这其实也体现了 LLVM 项目一贯的哲学：不只是把一个工具做好，而是把一个关键基础设施在工程上做到“库化”和“可复用”。

4.4 MLIR 与跨领域生态

MLIR（Multi-Level Intermediate Representation）最近几年热度极高，它的定位已经超出了“编译器优化”，更偏向“领域特化的编译器构建框架”。MLIR 的核心思想是提供很多可组合的 IR 抽象层，每个抽象层被称为“dialect”。比如func这个 dialect 表示普通函数控制流，linalg表示线性代数运算，tensor表示 Tensor 操作，scf表示结构化控制流。你可以把多个 dialect 混在一个 IR 里，然后通过 pass 逐步把高层次的 dialect 下降到底层。

如果你从事 AI 编译器相关的工作，MLIR 一定会出现在你的工具链中。我之前做 GPU 算子编译时，整套优化流程就是把 Torch 模型先是下降到tosa或linalg，然后经过triton/gpu这些 dialect 再生成 PTX 码。这套流程几乎每一步都在 MLIR 的框架里完成。因此，哪怕你暂时不碰传统 C/C++ 编译，只要你在计算底层工作，MLIR 都值得你投入时间。

5. 调试工具链与测试方法

5.1 用 lit 和 FileCheck 写测试

在 llvm-project 里写测试，你几乎绕不开 lit 和 FileCheck。lit 是测试驱动器，负责执行测试命令、检查输出、汇总结果。FileCheck 是输出检查器，你在RUN:行里面会看到类似CHECK:、CHECK-NEXT:这样的标记，FileCheck 会从命令输出中查找这些标记是否按预期出现。

早期我写测试时很容易犯一个错误：把所有预期输出完整地贴到CHECK里，结果代码一改，测试就成片红。后来我才理解，主流 LLVM 测试追求的是“只验证你关心的行为”，不要抓大而全的输出。比如你测一个 pass 是否消除了某个指令，你只需要在对应位置加CHECK-NOT: add或者CHECK: ret，而不要把你中间每一步都写进去。这样既能保证测试的针对性，又能降低后续维护成本。

一个典型的 lit 测试文件长这样：

; RUN: opt -passes=instcombine -S %s | FileCheck %s define i32 @test(i32 %x) { %a = add i32 %x, 0 ret i32 %a } ; CHECK-LABEL: define i32 @test ; CHECK-NOT: add

%s表示当前文件路径，FileCheck %s表示检查脚本也是同一个文件。这个模式在测试优化 pass 时非常常用。你可以通过ninja check-llvm-unit跑单元测试，通过ninja check-clang跑 Clang 的集成测试。原则上，每个代码变更都应该配套至少一个测试，这是 LLVM 社区不可妥协的规矩。

5.2 调试 LLVM 自身的方法

调试 LLVM 自身是一门手艺，跟你调试普通应用有区别。首先，opt这类工具绝大多数情况下接收的是.ll或.bc文件，输入是可复现的，你可以用 lldb/gdb 直接放断点。其次，LLVM 自己提供了非常强大的调试日志机制。最简单的是用-debug，它会打印大量 debug 信息，但输出量很惊人。建议配合-debug-only=passname来筛选，比如：

opt -passes=loop-vectorize -debug-only=loop-vectorize foo.ll -S -o /dev/null

这个命令只会输出跟loop-vectorize相关的调试信息，调试体验非常好。

如果问题是出现在 Clang 后端生成某个特定指令时，用llc配合-print-after-isel、-print-after-regalloc可以让你在这种后端 pipeline 的不同阶段看 IR 和指令序列。这套日志粒度很细，但一旦你习惯了，会大大提升你排查问题的效率。

6. 社区协作与为项目做贡献

6.1 从找到“第一次贡献”开始

很多朋友想给 LLVM 做贡献，但总有一种“无从下手”的焦虑。我给出的建议是三步走。

第一，从你真实的痛点和日常使用 bug 入手。你在用 Clang 时遇到一个不够友好的错误诊断、一个很诡异的警告误报，或者一个可以在文档里补充的地方，这些就是最好的起点。第二，在 GitHub 的 issue 区、Phabricator 或 GitHub 的 pull request 区，搜索带 “good first issue” 或 “beginner” 标签的问题。这里有专门为新手准备的坑位。第三，先在本地把代码改出来、把测试补好、把格式调对，然后再去了解社区的交流流程。

社区协作最重要的技能其实是沟通能力。LLVM 的 code review 文化非常讲究“挑剔”，但这并不是故意为难人，而是因为编译器代码的影响面特别大。任何一个小改动都可能影响几十万行代码的编译结果，所以评审者会偏保守。你提交 patch 前一定要写好 commit message，说明问题背景、复现方式、修改思路、测试结果。这看起来像例行公事，但它恰恰是社区信任建立的基础。

6.2 实际贡献流程中的几个细节

用 git 管理 llvm-project 源码时，除非你已经是长期维护者，否则不要直接从 master 开分支再推回 master。标准做法是 fork 一份到自己的账号下，然后按 feature 分支开发，开发完提 pull request 等待 review。

代码合并到上游之前，你需要遵守 clang-format 的代码风格。git clang-format是一个非常方便的命令，它会在你上次提交的基础上对修改部分做格式化。如果你忘记跑 clang-format，CI（快速）可能直接给你挂掉。测试也必须用 lit 在本地跑过，可以只跑你涉及的那一层。如果你改了llvm/lib/Transforms下的 pass，至少跑一下相关的ninja check-llvm-transforms。

社区对 commit message 同样有要求。规范的模板大致是：第一行[folder] short description，空一行后写详细说明，再空一行写测试计划。比如[InstCombine] Simplify add with zero operands。这种命名方式能让整个 git log 按目录类别快速筛选，也有利于后续的自动化工具跟踪。

7. 常见问题与排查技巧实录

7.1 构建阶段的高频问题

我在多年的 LLVM 构建经验里，碰到过不少几乎人人都会撞上的问题，这里做一个速查记录：

最让我意外的其实是第一个 “内存爆炸” 问题。很多新手以为“我在 12 核机器上就ninja -j12”，结果链接阶段直接把机器跑死。我自己的经验是，链接任务一定要降并发，编译任务反而可以拉满。所以我都会在构建参数里把LLVM_PARALLEL_LINK_JOBS单独设小。另一个很实用的技巧是启用ccache，用-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache配置。第二次构建速度能提升好几倍，几乎所有老 LLVM 开发者都会开。

7.2 调试与测试阶段的避坑清单

调试 LLVM 时最容易踩的坑，是分不清“输入的问题”和“编译器的问题”。比如你写了一个 pass，发现输出 IR 不对，直接怀疑 pass 有 bug。但进一步排查后发现是opt工具本身读入的.ll文件有陷阱，或者是之前的 pass 把 SSA 形式搞乱了。我现在的习惯是，每次实验都先用opt -print-after-all或者-print-changed把整个优化链路的变更加载出来看，先定位在哪一步变了样，再深入那一层的实现。

测试阶段的高频问题主要集中在 FileCheck 语法上。CHECK-NOT的语义常常被误解：它检查的是从上一条CHECK行到下一个CHECK行之间没有出现某个模式，并不是“整个文件都不许出现”。所以很多人写CHECK-NOT: blabla却总失败，就是因为没搞懂它的扫描区间。同样，CHECK-DAG适合匹配顺序不确定的行，但不要滥用，因为它会显著降低测试的确定性。

还有一个细节可能影响测试结果：测试文件里那些%开头的标识符。在 lit 脚本中，%s、%t这些是 lit 的内置变量，而在.ll文件里%是寄存器名。这两个概念容易混淆。如果你写; RUN: opt -passes=... %s -o %t.ll，这是正确的，lit 会把%s替换成当前文件路径、%t替换成临时文件名。如果手滑写成%x，lit 会报错或者不替换。

结尾：一点个人经验

我在 LLVM 上折腾了几年，最大的感慨是：这个项目不像普通开源库那样 “装个包就能跑”，它的门槛确实存在，但这个门槛更多是在“信息组织方式”上，而不是在“某个具体算法有多难”上。只要你愿意花一个周末认真看一下目录结构、跑通一次构建、读一个简单 pass 的实现，你就会发现后面的路越来越顺畅。如果真的让我给新手一个最实用的建议，那就是：永远不要只跟着教程看，挑一个你真正在业务里会碰到的编译问题，带着问题去源码里撕开一条口子往里钻，这比读一百篇导论文章都管用。