很多人第一次拿到 llvm-project 这个仓库时脑子里只有一个笼统的想法把 LLVM 克隆下来、编译一把能跑 clang 就行。但真正动手以后发现事情远没有这么简单——光是 CMake 参数就能把人绕晕更别提编到一半内存不够、磁盘爆掉、不小心选了个要等一整晚的构建配置。这篇文章就围绕 llvm-project 这一个项目把我自己从零开始折腾构建、调试、二次开发的完整过程记录下来包括每一步为什么这么做、哪些参数别乱动、踩了哪些坑、最终怎么落地一条稳定可复现的构建流水线。无论你是为了做编译器课程作业、跑 Clang 静态分析、给自定义后端写 LLVM Pass还是单纯想在本地用一份带符号的 debug 版 clang这篇都能给你一套可以直接抄作业的方案。1. 先搞清楚 llvm-project 里装的到底是什么1.1 一个仓库多个子项目别再只盯着 LLVM 核心llvm-project 是 LLVM 官方把 LLVM 编译器基础设施相关的所有子项目统一到一个仓库后的名字。早期 LLVM 是分散在多个仓库里的开发者和下游用户要手动拼版本非常痛苦。后来官方把 llvm、clang、lld、libcxx、compiler-rt、libunwind、polly、flang、mlir、openmp、clang-tools-extra 这些全部塞进同一个仓库按 tag 一起发版这样版本之间天然对齐。实际使用中你未必需要全部构建——比如你只写普通 C/C 编译器工具链flangFortran 前端和 mlir多级 IR 框架就基本用不上但如果你在做 AI 编译器或芯片后端mlir 和 lld 又会变成核心依赖。所以第一步不是急着 cmake而是先确认自己到底需要哪些子项目这决定了后面 CMake 参数怎么写。一个常见的误区是以为 llvm-project 只是“LLVM 源码的容器”实际上它每个子目录都能独立成为工程。拿 clang 举例它既是 C/C/Objective-C 的前端也是基于 LibTooling 做静态分析、代码重构、自动修补的底座。clang-tools-extra 里还带着 clang-tidy、clang-format、clangd 这些日常开发高频工具。如果你做的项目只依赖 clang 的语法树分析能力那完全可以在构建时只开 clang、clang-tools-extra把 mlir 和 flang 关掉节省一大截编译时间。1.2 为什么本地手动编译 llvm-project 仍然值得做看到这里你可能会问我直接 apt install clang 或者从 GitHub Release 下载二进制包不好吗为什么还要花几个小时本地编译我自己的体会是预编译包的定位是“稳定、通用、尽量不折腾”但它满足不了三类场景。第一类是调试和开发场景。你写了一个 Clang 插件或者 LLVM Pass一旦断言失败、段错误你需要带 debug 符号的 clang 和库才能定位到具体源码行。发行版自带的二进制通常剥离了符号不从头编一个 debug 版排查问题就像闭着眼找针。第二类是定制和裁剪场景。预编译包为了兼容老机器指令集、优化选项都偏保守而你在自己机器上可以做 LTO、PGO或者只保留少数 target编译出来的工具链更小、更快。第三类是实验和新特性场景。官方 Release 版本落后于主线你要试最新的 C 标准特性、新 Pass 管理器行为或者某个刚合入的优化就必须自己拉 llvm-project 主线来编。从投入产出比看第一次完整构建 debugassert 全开确实要四十到九十分钟但这份劳动是“一次付出、持续受益”之后你每改一个小改动增量编译可能只要几十秒。这也是我在这篇里强调“构建配置要一次配好、别反复整库重编”的原因。2. 构建前必须做的三个决策2.1 选分支还是选 Tag稳定复现是第一原则llvm-project 的 main 分支每天都有几十个 commit今天编能用、明天拉新代码可能就编不过。如果你是在做课程项目或公司交付强烈建议锁一个 release tag比如 llvmorg-17.0.6。Tag 是经过发布流程验证的配套子项目版本一致网上搜到的解决方案也基本对得上。如果你确实要用 main 分支新特性建议记录下当时 commit 的 hash并把 hash 写进 README 或构建脚本。有人以为 commit hash 是代码库内部的事和构建者无关但实际排查问题时不同 commit 之间的行为差异可能是天壤之别。尤其是 LLVM 每年会有一次大规模 API 迁移前一周还能编译的插件代码后一周可能就需要改 include 和接口名。所以无论选哪个分支最终都要落到“可重复构建”这个原则上——只要把 commit hash 和 cmake 命令记录下来任何一台机器都能复现同样的产物。2.2 盘点自己的机器内存、磁盘、CPU 核数llvm-project 的构建压力主要不在 CPU而在内存和磁盘。我见过太多人信心满满地 ./build 然后被 OOM 杀掉。这里给一个我自己验证过的参考Debug Assertions 开启的构建每个并行编译任务大约需要 1.5GB 到 2GB 的物理内存如果你有 16GB 内存并行度设为 8 比较安全16 / 2 8设成 16 甚至 32 就是等着被系统按在地上摩擦。磁盘空间也是个大坑。一个包含 clang、lld、compiler-rt 的全量 Debug 构建源码加构建产物很容易超过 50GB。就算你只编 llvm 和 clang也要留出 30GB 以上的余量。这里建议在项目根目录下建一个 .gitignore 或者干脆把 build 目录放到独立磁盘分区避免 build 产物把系统盘撑爆。另外编译过程中临时文件也占用空间磁盘剩余低于 10GB 时链接 clang 这种巨型二进制非常容易失败。CPU 核数直接影响并行编译时间。查看可用核心数用 nprocLinux/macOS 都有。我一般会留一个核心给系统响应比如 16 核机器上就用 -j15。更精细的做法是用 Ninja 的 Ninja Status 工具实时观察编译进度和内存占用一旦内存快满就降并行度而不是等 OOM。2.3 用 CMake Ninja 还是传统 Makefilellvm-project 官方构建说明里CMake 几乎是唯一入口。生成器我强烈推荐 Ninja而不是 Unix Makefiles。Ninja 的增量构建比 Make 快一个数量级而且默认就会充分利用多核。你只需要装好 ninja-build 和 cmake版本上clang 17 及以后建议 cmake 3.20ninja 1.10太老的版本可能不识别新参数。另外一个决策是编译器用 GCC 还是 Clang。第一次构建建议用系统自带的 GCC因为 GCC 的兼容性包袱最少发行版怎么装都能编。编完第一版 clang 后如果你想用“自举”方式——也就是用自己编出来的 clang 再编一遍 llvm-project——那属于后续优化不建议第一次就这么干因为自举如果出问题你很难区分是 clang 的问题还是 CMake 配置的问题。我通常的做法是先用 GCC 编一个 release 版本再用这个 release clang 去编 debug 版本这样两边编译器和目标版本都足够新编译器 bug 概率也降到最低。3. 完整构建流程从 clone 到第一个 clang3.1 拉取代码注意 submodule 和深层 clonellvm-project 仓库本身没有第三方 submodule 依赖直接克隆即可不需要 --recursive。不过仓库体积较大如果只想看最新代码建议用 --depth1 做浅克隆。但要注意浅克隆会丢掉历史 tag如果你之后需要切到某个 release tag 验证问题就得先 fetch 完整历史。最稳妥的做法是完整克隆然后在本地打一个 tag 标记当前 commit。克隆命令很简单git clone https://github.com/llvm/llvm-project.git cd llvm-project git tag -l llvmorg-* | tail -20如果你在 release tag 上构建建议直接 checkout 分支而不是 tag避免后续 fetch 和 rebase 的麻烦。比如git checkout llvmorg-17.0.6 -b build-17.0.6这样你在这个分支上做任何本地修改都有清晰的追踪记录后面更新也好管理。顺便说一句记得把 git lfs 装上llvm-project 里有少量大文件缺失会导致个别测试数据不完整。3.2 CMake 参数逐个拆解哪些必开哪些别乱开进入 llvm-project 根目录后我会建一个独立的 build 目录避免源码目录里混入构建产物mkdir build cd build然后执行 cmake。下面是我最常用的一套 debug 配置适合开发调试和 LLVM Pass 学习cmake -G Ninja ../llvm \ -DLLVM_ENABLE_PROJECTSclang;lld;clang-tools-extra \ -DLLVM_TARGETS_TO_BUILDX86 \ -DCMAKE_BUILD_TYPEDebug \ -DLLVM_ENABLE_ASSERTIONSON \ -DCMAKE_C_COMPILERgcc \ -DCMAKE_CXX_COMPILERg \ -DBUILD_SHARED_LIBSON一行行解释。-DLLVM_ENABLE_PROJECTSclang;lld;clang-tools-extra是启用哪些子项目。分号隔开不要带空格。这里不需要写 llvm 本身因为 llvm 是默认被构建的框架。-DLLVM_TARGETS_TO_BUILDX86是目标架构。如果你只需要 x86就只编 X86。默认是构建所有 target比如 ARM、AArch64、RISC-V、WebAssembly 等编译时间至少翻倍。做实验时尽量裁剪。-DCMAKE_BUILD_TYPEDebug决定优化等级和调试信息。Debug 生成未优化的代码带着完整 DWARF 调试信息是查看源码断点和变量值的前提。但 Debug 版本的 clang 自身运行很慢跑大型源码分析会明显卡顿这是正常现象。-DLLVM_ENABLE_ASSERTIONSON是打开内部断言。LLVM 源码里大量 assert()在 debug 阶段能拦截很多无效输入和错误逻辑。强烈建议开发期打开但 release 版建议关闭因为断言检查会拖慢运行速度。-DCMAKE_C_COMPILERgcc和-DCMAKE_CXX_COMPILERg指定第一遍编译器。-DBUILD_SHARED_LIBSON把 LLVM 编译成动态库而非静态库。这个选项在 Debug 下尤其重要因为 Debug 静态库体积巨大每次链接都特别慢共享库既省磁盘又能显著加快链接速度。缺点是产物的分发部署会复杂一些需要带着 so/dylib 一起走。如果你更看重最终安装体积和运行性能比如想给自己做一套日常使用的 clang 工具链那可以用 Release 静态库cmake -G Ninja ../llvm \ -DLLVM_ENABLE_PROJECTSclang;lld \ -DLLVM_TARGETS_TO_BUILDX86 \ -DCMAKE_BUILD_TYPERelease \ -DLLVM_ENABLE_ASSERTIONSOFF \ -DLLVM_OPTIMIZED_TABLEGENON注意-DLLVM_OPTIMIZED_TABLEGENON它会用 release 版 tablegen 生成文件能明显加速整个构建同时不影响最终 debug 产物。这个选项在 Release 配置里收益很小但在 Debug 配置里收益巨大如果你采用 debug共享库tablegen 优化组合能省下不少时间。3.3 开始构建并行度怎么选中途挂了怎么办配置完成后构建命令极简ninja -j8这里 -j8 是我 16GB 内存能承受的并行度。如果你机器是 32GB 内存可以放到 -j14 到 -j1664GB 内存就大胆一些。判断并行度是否合适有个简单办法打开 top 或 htop观察内存占用是否超过了总内存的 80%。如果超过马上 Ctrl-C然后用更小的 -j 重跑。Ninja 支持断点续编之前编好的不会重来这是它比 Makefile 强太多的地方。构建过程中偶尔会遇到某个 .cpp 编译报错。常见的一种是内存不足导致的内部编译器错误报错信息类似 “clang: error: unable to execute command: Killed”。这种问题通常不是源码问题而是并行度太高触发了 OOM。解决办法就是降低并行度重新触发Ninja 会跳过已经完成的文件不会浪费时间。另一种是系统自带 CMake 版本太老报 CMake Error at CMakeLists.txt。如果你不想升级系统 cmake可以装一个高版本的 cmake 到用户目录pip install cmake # 会装一个新版 cmake 到 python 环境或者在 llvm-project 根目录下用 cmake-format 之类的脚本检查版本。总之如果卡在 cmake 阶段大概率是版本问题及时升级比闷头查快得多。3.4 验证产物和使用方式构建结束后clang 的可执行文件在 build/bin 下。你可以直接运行build/bin/clang --version看到版本号、目标架构信息后就可以写个小程序测试。我习惯建一个 hello.c#include stdio.h int main(void) { printf(hello llvm\n); return 0; }然后编译build/bin/clang -O0 -g hello.c -o hello ./hello如果想确认用的确实是本地刚编出来的 clang可以加上 -### 参数打印真实调用的工具链路径build/bin/clang -### hello.c -o hello这样能看到它调用的 cc1、ld 等路径确保没有意外走系统的旧版本。4. 从构建到开发Clang 插件与 LLVM Pass 的调试环境4.1 为什么你一定要留一份 DebugAssertions 版本的构建我见过不少同学直接用发行版 clang 写 LLVM Pass等出了段错误只能 printf 大法到处插桩。这不是不行但效率很低。LLVM Pass 是跑在 LLVM 内部的优化组件它出问题的时候往往连堆栈都看不到因为整个程序被优化得面目全非。如果你用的是 DebugAssertions 构建LLVM 的断言能帮你精确指出是哪个 Pass 的哪个逻辑出了问题根本不给你时间去瞎猜。举个例子我在给自定义 IR 指令写下降 Pass 时曾经把一个 Instruction 的父 BasicBlock 拿错了直接在 Release 版上跑表现出来是编译产物随机崩溃非常难查。后来换到 Debug 构建LLVM 的assert(Inst-getParent() BB)直接告诉我是哪个基本块不匹配问题五分钟就定位了。这就是为什么“开发环境一定用 Debug、部署环境才用 Release”是 LLVM 社区的一条铁律。还有一点Debug 构建里能开启 AddressSanitizer 和 UndefinedBehaviorSanitizer 这类运行时检测工具。你可以在 CMake 里加-DLLVM_USE_SANITIZERAddress这样编出来的 clang 自身带内存错误检测你写的插件如果踩了野指针或越界数组clang 会立刻报出详细堆栈。缺点是构建时间和运行性能都会下降所以我一般只在插件调试阶段开 Address正式 do testing 时关掉。4.2 用 LLVM Pass 做第一个二次开发实验假设你想写一个最简单的 Function Pass遍历每个函数的名字并打印。在 llvm-project 里有完整的 Pass 文档和示例。我这里简化一下思路你需要创建一个 .cpp 文件然后在 CMakeLists.txt 里通过 add_llvm_pass_plugin 把它编译成动态加载的插件。#include llvm/IR/Function.h #include llvm/Pass.h #include llvm/IR/LegacyPassManager.h #include llvm/Transforms/IPO/PassManagerBuilder.h using namespace llvm; namespace { struct HelloFunctionPass : public FunctionPass { static char ID; HelloFunctionPass() : FunctionPass(ID) {} bool runOnFunction(Function F) override { errs() Hello from function: F.getName() \n; return false; } }; } char HelloFunctionPass::ID 0; static RegisterPassHelloFunctionPass X(hello-function, Hello Function Pass);然后在 CMake 中add_llvm_pass_plugin(HelloPass hello.cpp)编好后用法是build/bin/clang -fpass-pluginbuild/lib/HelloPass.so hello.c -o hello这时你会看到每个函数名被打印出来。这个实验的意义不仅是“做一个 pass”更重要的是让你熟悉 LLVM 的 Pass 注册机制、IR 遍历方式以及 clang 加载 pass 插件的完整链路。这套流程在写业务里的定制优化、代码插桩或者模糊测试工具时全部都能复用。4.3 用 lldb/gdb 直接调试 clang 自身Debug 构建最大的红利是你能用调试器直接打断点。比如你怀疑 clang 在生成代码时某个环节崩溃可以这样gdb --args build/bin/clang -c test.c -o test.o然后在 gdb 里 run崩溃后 bt 查看堆栈。因为 clang 自己是 Debug 构建所有符号都在看到的调用栈直接对应到源码文件行。这也是我平常定位编译崩溃的首要手段比反复加打印高效太多。不过 Debug 版 clang 的启动速度确实慢某些超大规模翻译单元上可能要跑很久。如果你只需要复现崩溃建议先构造一个最小测试用例再在 gdb 里跑。最小化用例的过程本身也是对 LLVM 内部错误机理的逆向分析收获往往比修复 bug 本身更大。5. 高频问题排查与构建提速技巧5.1 内存不够先别急着加硬件很多人一遇到编译 OOM 就想着加内存条实际上多数情况下是配置的问题。最立竿见影的方案是关掉 Debug改用 RelWithDebInfo。它仍然带调试符号但优化等级为 -O2编译时间和内存消耗都会大幅下降。调试体验上函数参数经常被优化掉查看变量值确实没有 Debug 方便但应付大多数定位场景已经足够。第二个方案是减少并行度。有人觉得 -j 开得越大编得越快但在 Debug 全开时每个任务的内存天花板极高并行度上去了反而会因为 swap 拖慢整体。我测过16GB 内存机器上 -j8 与 -j16 的时间差距约在 5% 到 10%完全没必要冒 OOM 风险。第三个方案是关掉 asserts。这个是在迫不得已时才推荐因为断言本身就是帮你抓 bug 的。如果只是为了出产物那可以将LLVM_ENABLE_ASSERTIONS设为 OFF配 RelWithDebInfo 一起用构建时间能降到 Debug 版的三分之一左右。5.2 构建太慢可能是你一直没做增量构建很多人在 llvm-project 上犯的错是每次改一个 cmake 变量就重新建一个新 build 目录然后从头编译。实际上 Ninja 的增量构建非常智能只要你的改动不影响大多数源文件的依赖它只编译受影响的文件。所以正确的做法是一个 build 目录对应一组配置文件不要频繁重建。如果一定要切换配置比如从 Debug 切 Release也不建议覆盖原目录新建一个 build-release 目录更稳妥两者可以并存。还有一个加速技巧是 ccache。llvm-project 的编译单元非常多新建 build 目录时反复编译相同的源文件是纯浪费。配好 ccache 后第二次构建大部分文件都命中缓存时间能缩短一半以上。安装 ccache 后在 CMake 里指定-DCMAKE_C_COMPILER_LAUNCHERccache \ -DCMAKE_CXX_COMPILER_LAUNCHERccache然后记住在 ~/.ccache/ccache.conf 里把 max_size 调大比如 32G否则默认 5G 不够支撑这种大型项目。5.3 clang 编出来的程序运行报错先看三个经典方向第一库路径问题。本地 clang 默认去找系统 libstdc/libc如果你编译器版本较新可能链接到不兼容的 C 标准库。通常需要配合-stdliblibstdc或-stdliblibc做显式指定或设置LD_LIBRARY_PATH指向新构建的 libc 目录。第二动态链接器路径问题。你如果用BUILD_SHARED_LIBSON编出来的 clang 依赖 build/lib 下大量的 .so。直接把 build/bin/clang 拷贝到别的机器上肯定跑不起来。部署时要么记得带库要么改用 static 库构建要么仔细设置 rpath。这个坑在写文档时很容易被忽略但真的遇到时能卡一下午。第三target 不匹配。拿 X86 编译出的 clang 去跑 ARM 交叉编译如果没有额外配置 sysroot 和 linker基本不会成功。如果你要做多目标开发构建时把LLVM_TARGETS_TO_BUILD改为ALL或者在命令行用--target指定。5.4 排查细节怎么判断是上游 bug 还是自己配置问题当你跑 clang 测试出现 assertion 失败时先别急着去 GitHub 提 issue先做三个自检。一是确认你和主流 release 分支的差距比如你是用 main 分支某个 commit那么行为可能和 release 差异很大issue 前先搜 commit log。二是最小化用例把触发问题的源码裁剪到尽量短这一步基本能区分是 clang 前端错误还是优化器错误。三是对照一遍 CMake 参数特别是你是否打开了某些非默认选项比如-DLLVM_ENABLE_EXPERIMENTAL_TARGETS里加了新架构。如果确实怀疑是 llvm-project 的 bug建议在该版本的 release tag 上复现一次如果 release 不复现那大概率是 main 分支的新回归处理方式就是回退 commit、等待修复或者在 llvm-project 的 issue 区提供最小复现文件。这个过程我走了无数次每次都能学到新东西。6. 版本升级与分支切换如何平滑迁移自己的代码6.1 为什么 llvm 每年都会“破坏性”更新LLVM 社区以 API 变动频繁著称每年大版本都会调整 Pass 接口、删除旧模块、改名 header。如果你是基于 llvm-project 做二次开发的工作一定要意识到这一点。不是“代码写完了就一劳永逸”而是“每次升级都要预留出适配窗口”。最常见的破坏来自两个方向。第一个是 header 目录调整比如llvm/IR/Function.h可能会移动到llvm/IR/Function.h不变但llvm/IR/LegacyPassManager.h可能被拆成多个子模块。第二个是 Pass API 演进旧版FunctionPass可能需要改成新 Pass Manager 的AnalysisKey注册方式改动量不小。我个人的迁移策略是先升级到相邻大版本比如从 LLVM 17 到 LLVM 18不要直接跳两个以上版本否则错误堆积太多根本不知道是谁引起的。每升一级就编一遍、跑一遍自己的测试集确认无回归后再去下一个版本。虽然多花几次编译时间但整体定位成本大大降低。6.2 本地如何同时保留多版本构建日常工作经常需要同时对比不同 LLVM 版本的行为比如一个 Pass 在 16 上正常、在 18 上崩溃。这时多 build 目录就派上用场了。我会建 llvm-project 下三个目录build-17-release build-17-debug build-18-debug每个目录独立 configure、独立 ninja彼此不影响。使用哪个版本就把对应 build/bin 放到 PATH 前面。这样不仅切换方便还能用 diff 命令比较两个 clang 对同一源码生成的汇编差异定位到是哪个版本的哪种优化策略变了。注意在切换时把CMAKE_INSTALL_PREFIX也区分开避免 install 时互相覆盖。6.3 升级后必做的测试清单不管从哪个版本升到哪个版本我升级完必做这样几件事第一跑一遍 clang 自带的快速测试ninja check-clang会有一部分测试不通过重点看是不是新增失败。如果大量失败往往是配置或者底层环境问题而不是代码兼容。第二用以前的典型项目重新编译一次最好是你自己维护的一个中型 C 工程这样能覆盖模板、异常、RTTI 等常见特性。第三做一次简单的性能对比用同一个 benchmark 跑新旧 clang 的可执行文件避免升级后优化意外变差。第四检查所有自定义插件的编译是否正常因为 Pass API 变动基本都会在插件编译时报错提前暴露就是好事。7. 一处容易被忽视的细节LLVM_ENABLE_PROJECTS 和 LLVM_ENABLE_RUNTIMES 到底怎么分新手最容易混淆的是 LLVM_ENABLE_PROJECTS 和 LLVM_ENABLE_RUNTIMES。前者在 llvm 主构建里直接编译模块之间耦合紧密适合 clang、lld、clang-tools-extra 这类“本身就是 LLVM 开发者子项目”的模块。后者处于更外圈像 libcxx、libcxxabi、compiler-rt、libunwind它们需要先有一个可用的 clang 或 gcc 才能编译也不适合和 LLVM 核心放在同一个构建里搅和。拿 libcxx 举例你想构建一套新的 C 标准库如果在 PROJECTS 里指定 libcxx意味着 clang 在构建时会去寻找尚未生成的 libcxx 头文件和库很容易死锁。正确做法是在 RUNTIMES 里启用这样 CMake 会先构建 clang 本身再进入 runtime 阶段用刚构建好的 clang 去编 C 运行库。我配过一次 libcxx 的 debug 环境用-DLLVM_ENABLE_RUNTIMESlibcxx;libcxxabi;libunwind一次就成功了换成 PROJECTS 反而卡在循环依赖上。如果你只想要默认 libstdc 组件其实没必要碰 RUNTIMES。默认 clang 会用系统 libstdc 工作得很好除非你确实在改 libc 自身源码或需要精确控制 C ABI 版本。选错了只会增加构建复杂度和额外时间。8. 从构建到落地一份可持续维护的构建脚本模板到了这个阶段你已经有能力编出一个可用的 clang也有了调试和开发的基本环境。我在实际工作中会把构建参数固化到一个 shell 脚本里避免每次面向 CMake 大海捞针。下面是一份我常用的模板按需改注释里的开关即可#!/usr/bin/env bash set -euo pipefail LLVM_SRC_DIR$(cd $(dirname ${BASH_SOURCE[0]})/../llvm pwd) BUILD_DIR${BUILD_DIR:-${LLVM_SRC_DIR}/../build-debug} INSTALL_DIR${INSTALL_DIR:-${LLVM_SRC_DIR}/../install-debug} cmake -G Ninja -S ${LLVM_SRC_DIR} -B ${BUILD_DIR} \ -DLLVM_ENABLE_PROJECTSclang;lld;clang-tools-extra \ -DLLVM_ENABLE_RUNTIMES \ -DLLVM_TARGETS_TO_BUILDX86 \ -DCMAKE_BUILD_TYPEDebug \ -DLLVM_ENABLE_ASSERTIONSON \ -DLLVM_OPTIMIZED_TABLEGENON \ -DBUILD_SHARED_LIBSON \ -DCMAKE_INSTALL_PREFIX${INSTALL_DIR} \ -DCMAKE_C_COMPILERgcc \ -DCMAKE_CXX_COMPILERg \ -DCMAKE_C_COMPILER_LAUNCHERccache \ -DCMAKE_CXX_COMPILER_LAUNCHERccache cmake --build ${BUILD_DIR} -- -j$(nproc)脚本里把源码目录、构建目录、安装目录都拆开好处是 cmake 重新配置时不会污染源码树也不会因为路径写死导致换机器后失效。set -euo pipefail确保任何一步失败都立刻停止不会带病继续。构建完成后我再单独跑cmake --install ${BUILD_DIR}把产物整理到干净的 install 目录方便后续部署或打压缩包。我最喜欢这套脚本的一点是它完全可复现。换一台新机器只要装上 cmake、ninja、gcc/g、ccache执行一次脚本就自动生成一个可用的 llvm-project 开发环境不用再担心某个参数漏配或写错。9. 最后的实操建议llvm-project 是一个足够大、足够深的项目初次接触很容易被它的体量吓到。但实际用下来的感觉它更像一套积木你可以只取 llvmclang 做工具链也可以挂在 mlir 上做编译器和 AI 加速还能用 libcxx 构建完全可控的 C 运行环境。关键是从小处开始先确定目标再选分支和 tag再配置 CMake再动手编译。每走通一步你对这个庞大工程的理解就会深一层。我自己在折腾 llvm-project 的过程中最大的体会是不要试图一次掌握所有内容也不要一开始就纠结所有参数的含义。把构建跑通、把调试环境配好然后去写一个简单的 Pass 或插件遇到问题再回头查文档和源码。这种“从实践中学习再回到实践中去”的路径远比从头到尾背诵 CMake 选项和 API 列表要有效得多。如果你正在做一个自定义编译器、静态分析工具、或编译器后端相关的工作建议把这份构建脚本和 debug 环境作为第一里程碑。真正跨过“能编、能跑、能调”这道坎之后后续研究 IR 设计和优化算法的学习曲线会平缓很多。 llvm-project 从零构建到二次开发：CMake配置、Debug调试与LLVM Pass实践
很多人第一次拿到 llvm-project 这个仓库时脑子里只有一个笼统的想法把 LLVM 克隆下来、编译一把能跑 clang 就行。但真正动手以后发现事情远没有这么简单——光是 CMake 参数就能把人绕晕更别提编到一半内存不够、磁盘爆掉、不小心选了个要等一整晚的构建配置。这篇文章就围绕 llvm-project 这一个项目把我自己从零开始折腾构建、调试、二次开发的完整过程记录下来包括每一步为什么这么做、哪些参数别乱动、踩了哪些坑、最终怎么落地一条稳定可复现的构建流水线。无论你是为了做编译器课程作业、跑 Clang 静态分析、给自定义后端写 LLVM Pass还是单纯想在本地用一份带符号的 debug 版 clang这篇都能给你一套可以直接抄作业的方案。1. 先搞清楚 llvm-project 里装的到底是什么1.1 一个仓库多个子项目别再只盯着 LLVM 核心llvm-project 是 LLVM 官方把 LLVM 编译器基础设施相关的所有子项目统一到一个仓库后的名字。早期 LLVM 是分散在多个仓库里的开发者和下游用户要手动拼版本非常痛苦。后来官方把 llvm、clang、lld、libcxx、compiler-rt、libunwind、polly、flang、mlir、openmp、clang-tools-extra 这些全部塞进同一个仓库按 tag 一起发版这样版本之间天然对齐。实际使用中你未必需要全部构建——比如你只写普通 C/C 编译器工具链flangFortran 前端和 mlir多级 IR 框架就基本用不上但如果你在做 AI 编译器或芯片后端mlir 和 lld 又会变成核心依赖。所以第一步不是急着 cmake而是先确认自己到底需要哪些子项目这决定了后面 CMake 参数怎么写。一个常见的误区是以为 llvm-project 只是“LLVM 源码的容器”实际上它每个子目录都能独立成为工程。拿 clang 举例它既是 C/C/Objective-C 的前端也是基于 LibTooling 做静态分析、代码重构、自动修补的底座。clang-tools-extra 里还带着 clang-tidy、clang-format、clangd 这些日常开发高频工具。如果你做的项目只依赖 clang 的语法树分析能力那完全可以在构建时只开 clang、clang-tools-extra把 mlir 和 flang 关掉节省一大截编译时间。1.2 为什么本地手动编译 llvm-project 仍然值得做看到这里你可能会问我直接 apt install clang 或者从 GitHub Release 下载二进制包不好吗为什么还要花几个小时本地编译我自己的体会是预编译包的定位是“稳定、通用、尽量不折腾”但它满足不了三类场景。第一类是调试和开发场景。你写了一个 Clang 插件或者 LLVM Pass一旦断言失败、段错误你需要带 debug 符号的 clang 和库才能定位到具体源码行。发行版自带的二进制通常剥离了符号不从头编一个 debug 版排查问题就像闭着眼找针。第二类是定制和裁剪场景。预编译包为了兼容老机器指令集、优化选项都偏保守而你在自己机器上可以做 LTO、PGO或者只保留少数 target编译出来的工具链更小、更快。第三类是实验和新特性场景。官方 Release 版本落后于主线你要试最新的 C 标准特性、新 Pass 管理器行为或者某个刚合入的优化就必须自己拉 llvm-project 主线来编。从投入产出比看第一次完整构建 debugassert 全开确实要四十到九十分钟但这份劳动是“一次付出、持续受益”之后你每改一个小改动增量编译可能只要几十秒。这也是我在这篇里强调“构建配置要一次配好、别反复整库重编”的原因。2. 构建前必须做的三个决策2.1 选分支还是选 Tag稳定复现是第一原则llvm-project 的 main 分支每天都有几十个 commit今天编能用、明天拉新代码可能就编不过。如果你是在做课程项目或公司交付强烈建议锁一个 release tag比如 llvmorg-17.0.6。Tag 是经过发布流程验证的配套子项目版本一致网上搜到的解决方案也基本对得上。如果你确实要用 main 分支新特性建议记录下当时 commit 的 hash并把 hash 写进 README 或构建脚本。有人以为 commit hash 是代码库内部的事和构建者无关但实际排查问题时不同 commit 之间的行为差异可能是天壤之别。尤其是 LLVM 每年会有一次大规模 API 迁移前一周还能编译的插件代码后一周可能就需要改 include 和接口名。所以无论选哪个分支最终都要落到“可重复构建”这个原则上——只要把 commit hash 和 cmake 命令记录下来任何一台机器都能复现同样的产物。2.2 盘点自己的机器内存、磁盘、CPU 核数llvm-project 的构建压力主要不在 CPU而在内存和磁盘。我见过太多人信心满满地 ./build 然后被 OOM 杀掉。这里给一个我自己验证过的参考Debug Assertions 开启的构建每个并行编译任务大约需要 1.5GB 到 2GB 的物理内存如果你有 16GB 内存并行度设为 8 比较安全16 / 2 8设成 16 甚至 32 就是等着被系统按在地上摩擦。磁盘空间也是个大坑。一个包含 clang、lld、compiler-rt 的全量 Debug 构建源码加构建产物很容易超过 50GB。就算你只编 llvm 和 clang也要留出 30GB 以上的余量。这里建议在项目根目录下建一个 .gitignore 或者干脆把 build 目录放到独立磁盘分区避免 build 产物把系统盘撑爆。另外编译过程中临时文件也占用空间磁盘剩余低于 10GB 时链接 clang 这种巨型二进制非常容易失败。CPU 核数直接影响并行编译时间。查看可用核心数用 nprocLinux/macOS 都有。我一般会留一个核心给系统响应比如 16 核机器上就用 -j15。更精细的做法是用 Ninja 的 Ninja Status 工具实时观察编译进度和内存占用一旦内存快满就降并行度而不是等 OOM。2.3 用 CMake Ninja 还是传统 Makefilellvm-project 官方构建说明里CMake 几乎是唯一入口。生成器我强烈推荐 Ninja而不是 Unix Makefiles。Ninja 的增量构建比 Make 快一个数量级而且默认就会充分利用多核。你只需要装好 ninja-build 和 cmake版本上clang 17 及以后建议 cmake 3.20ninja 1.10太老的版本可能不识别新参数。另外一个决策是编译器用 GCC 还是 Clang。第一次构建建议用系统自带的 GCC因为 GCC 的兼容性包袱最少发行版怎么装都能编。编完第一版 clang 后如果你想用“自举”方式——也就是用自己编出来的 clang 再编一遍 llvm-project——那属于后续优化不建议第一次就这么干因为自举如果出问题你很难区分是 clang 的问题还是 CMake 配置的问题。我通常的做法是先用 GCC 编一个 release 版本再用这个 release clang 去编 debug 版本这样两边编译器和目标版本都足够新编译器 bug 概率也降到最低。3. 完整构建流程从 clone 到第一个 clang3.1 拉取代码注意 submodule 和深层 clonellvm-project 仓库本身没有第三方 submodule 依赖直接克隆即可不需要 --recursive。不过仓库体积较大如果只想看最新代码建议用 --depth1 做浅克隆。但要注意浅克隆会丢掉历史 tag如果你之后需要切到某个 release tag 验证问题就得先 fetch 完整历史。最稳妥的做法是完整克隆然后在本地打一个 tag 标记当前 commit。克隆命令很简单git clone https://github.com/llvm/llvm-project.git cd llvm-project git tag -l llvmorg-* | tail -20如果你在 release tag 上构建建议直接 checkout 分支而不是 tag避免后续 fetch 和 rebase 的麻烦。比如git checkout llvmorg-17.0.6 -b build-17.0.6这样你在这个分支上做任何本地修改都有清晰的追踪记录后面更新也好管理。顺便说一句记得把 git lfs 装上llvm-project 里有少量大文件缺失会导致个别测试数据不完整。3.2 CMake 参数逐个拆解哪些必开哪些别乱开进入 llvm-project 根目录后我会建一个独立的 build 目录避免源码目录里混入构建产物mkdir build cd build然后执行 cmake。下面是我最常用的一套 debug 配置适合开发调试和 LLVM Pass 学习cmake -G Ninja ../llvm \ -DLLVM_ENABLE_PROJECTSclang;lld;clang-tools-extra \ -DLLVM_TARGETS_TO_BUILDX86 \ -DCMAKE_BUILD_TYPEDebug \ -DLLVM_ENABLE_ASSERTIONSON \ -DCMAKE_C_COMPILERgcc \ -DCMAKE_CXX_COMPILERg \ -DBUILD_SHARED_LIBSON一行行解释。-DLLVM_ENABLE_PROJECTSclang;lld;clang-tools-extra是启用哪些子项目。分号隔开不要带空格。这里不需要写 llvm 本身因为 llvm 是默认被构建的框架。-DLLVM_TARGETS_TO_BUILDX86是目标架构。如果你只需要 x86就只编 X86。默认是构建所有 target比如 ARM、AArch64、RISC-V、WebAssembly 等编译时间至少翻倍。做实验时尽量裁剪。-DCMAKE_BUILD_TYPEDebug决定优化等级和调试信息。Debug 生成未优化的代码带着完整 DWARF 调试信息是查看源码断点和变量值的前提。但 Debug 版本的 clang 自身运行很慢跑大型源码分析会明显卡顿这是正常现象。-DLLVM_ENABLE_ASSERTIONSON是打开内部断言。LLVM 源码里大量 assert()在 debug 阶段能拦截很多无效输入和错误逻辑。强烈建议开发期打开但 release 版建议关闭因为断言检查会拖慢运行速度。-DCMAKE_C_COMPILERgcc和-DCMAKE_CXX_COMPILERg指定第一遍编译器。-DBUILD_SHARED_LIBSON把 LLVM 编译成动态库而非静态库。这个选项在 Debug 下尤其重要因为 Debug 静态库体积巨大每次链接都特别慢共享库既省磁盘又能显著加快链接速度。缺点是产物的分发部署会复杂一些需要带着 so/dylib 一起走。如果你更看重最终安装体积和运行性能比如想给自己做一套日常使用的 clang 工具链那可以用 Release 静态库cmake -G Ninja ../llvm \ -DLLVM_ENABLE_PROJECTSclang;lld \ -DLLVM_TARGETS_TO_BUILDX86 \ -DCMAKE_BUILD_TYPERelease \ -DLLVM_ENABLE_ASSERTIONSOFF \ -DLLVM_OPTIMIZED_TABLEGENON注意-DLLVM_OPTIMIZED_TABLEGENON它会用 release 版 tablegen 生成文件能明显加速整个构建同时不影响最终 debug 产物。这个选项在 Release 配置里收益很小但在 Debug 配置里收益巨大如果你采用 debug共享库tablegen 优化组合能省下不少时间。3.3 开始构建并行度怎么选中途挂了怎么办配置完成后构建命令极简ninja -j8这里 -j8 是我 16GB 内存能承受的并行度。如果你机器是 32GB 内存可以放到 -j14 到 -j1664GB 内存就大胆一些。判断并行度是否合适有个简单办法打开 top 或 htop观察内存占用是否超过了总内存的 80%。如果超过马上 Ctrl-C然后用更小的 -j 重跑。Ninja 支持断点续编之前编好的不会重来这是它比 Makefile 强太多的地方。构建过程中偶尔会遇到某个 .cpp 编译报错。常见的一种是内存不足导致的内部编译器错误报错信息类似 “clang: error: unable to execute command: Killed”。这种问题通常不是源码问题而是并行度太高触发了 OOM。解决办法就是降低并行度重新触发Ninja 会跳过已经完成的文件不会浪费时间。另一种是系统自带 CMake 版本太老报 CMake Error at CMakeLists.txt。如果你不想升级系统 cmake可以装一个高版本的 cmake 到用户目录pip install cmake # 会装一个新版 cmake 到 python 环境或者在 llvm-project 根目录下用 cmake-format 之类的脚本检查版本。总之如果卡在 cmake 阶段大概率是版本问题及时升级比闷头查快得多。3.4 验证产物和使用方式构建结束后clang 的可执行文件在 build/bin 下。你可以直接运行build/bin/clang --version看到版本号、目标架构信息后就可以写个小程序测试。我习惯建一个 hello.c#include stdio.h int main(void) { printf(hello llvm\n); return 0; }然后编译build/bin/clang -O0 -g hello.c -o hello ./hello如果想确认用的确实是本地刚编出来的 clang可以加上 -### 参数打印真实调用的工具链路径build/bin/clang -### hello.c -o hello这样能看到它调用的 cc1、ld 等路径确保没有意外走系统的旧版本。4. 从构建到开发Clang 插件与 LLVM Pass 的调试环境4.1 为什么你一定要留一份 DebugAssertions 版本的构建我见过不少同学直接用发行版 clang 写 LLVM Pass等出了段错误只能 printf 大法到处插桩。这不是不行但效率很低。LLVM Pass 是跑在 LLVM 内部的优化组件它出问题的时候往往连堆栈都看不到因为整个程序被优化得面目全非。如果你用的是 DebugAssertions 构建LLVM 的断言能帮你精确指出是哪个 Pass 的哪个逻辑出了问题根本不给你时间去瞎猜。举个例子我在给自定义 IR 指令写下降 Pass 时曾经把一个 Instruction 的父 BasicBlock 拿错了直接在 Release 版上跑表现出来是编译产物随机崩溃非常难查。后来换到 Debug 构建LLVM 的assert(Inst-getParent() BB)直接告诉我是哪个基本块不匹配问题五分钟就定位了。这就是为什么“开发环境一定用 Debug、部署环境才用 Release”是 LLVM 社区的一条铁律。还有一点Debug 构建里能开启 AddressSanitizer 和 UndefinedBehaviorSanitizer 这类运行时检测工具。你可以在 CMake 里加-DLLVM_USE_SANITIZERAddress这样编出来的 clang 自身带内存错误检测你写的插件如果踩了野指针或越界数组clang 会立刻报出详细堆栈。缺点是构建时间和运行性能都会下降所以我一般只在插件调试阶段开 Address正式 do testing 时关掉。4.2 用 LLVM Pass 做第一个二次开发实验假设你想写一个最简单的 Function Pass遍历每个函数的名字并打印。在 llvm-project 里有完整的 Pass 文档和示例。我这里简化一下思路你需要创建一个 .cpp 文件然后在 CMakeLists.txt 里通过 add_llvm_pass_plugin 把它编译成动态加载的插件。#include llvm/IR/Function.h #include llvm/Pass.h #include llvm/IR/LegacyPassManager.h #include llvm/Transforms/IPO/PassManagerBuilder.h using namespace llvm; namespace { struct HelloFunctionPass : public FunctionPass { static char ID; HelloFunctionPass() : FunctionPass(ID) {} bool runOnFunction(Function F) override { errs() Hello from function: F.getName() \n; return false; } }; } char HelloFunctionPass::ID 0; static RegisterPassHelloFunctionPass X(hello-function, Hello Function Pass);然后在 CMake 中add_llvm_pass_plugin(HelloPass hello.cpp)编好后用法是build/bin/clang -fpass-pluginbuild/lib/HelloPass.so hello.c -o hello这时你会看到每个函数名被打印出来。这个实验的意义不仅是“做一个 pass”更重要的是让你熟悉 LLVM 的 Pass 注册机制、IR 遍历方式以及 clang 加载 pass 插件的完整链路。这套流程在写业务里的定制优化、代码插桩或者模糊测试工具时全部都能复用。4.3 用 lldb/gdb 直接调试 clang 自身Debug 构建最大的红利是你能用调试器直接打断点。比如你怀疑 clang 在生成代码时某个环节崩溃可以这样gdb --args build/bin/clang -c test.c -o test.o然后在 gdb 里 run崩溃后 bt 查看堆栈。因为 clang 自己是 Debug 构建所有符号都在看到的调用栈直接对应到源码文件行。这也是我平常定位编译崩溃的首要手段比反复加打印高效太多。不过 Debug 版 clang 的启动速度确实慢某些超大规模翻译单元上可能要跑很久。如果你只需要复现崩溃建议先构造一个最小测试用例再在 gdb 里跑。最小化用例的过程本身也是对 LLVM 内部错误机理的逆向分析收获往往比修复 bug 本身更大。5. 高频问题排查与构建提速技巧5.1 内存不够先别急着加硬件很多人一遇到编译 OOM 就想着加内存条实际上多数情况下是配置的问题。最立竿见影的方案是关掉 Debug改用 RelWithDebInfo。它仍然带调试符号但优化等级为 -O2编译时间和内存消耗都会大幅下降。调试体验上函数参数经常被优化掉查看变量值确实没有 Debug 方便但应付大多数定位场景已经足够。第二个方案是减少并行度。有人觉得 -j 开得越大编得越快但在 Debug 全开时每个任务的内存天花板极高并行度上去了反而会因为 swap 拖慢整体。我测过16GB 内存机器上 -j8 与 -j16 的时间差距约在 5% 到 10%完全没必要冒 OOM 风险。第三个方案是关掉 asserts。这个是在迫不得已时才推荐因为断言本身就是帮你抓 bug 的。如果只是为了出产物那可以将LLVM_ENABLE_ASSERTIONS设为 OFF配 RelWithDebInfo 一起用构建时间能降到 Debug 版的三分之一左右。5.2 构建太慢可能是你一直没做增量构建很多人在 llvm-project 上犯的错是每次改一个 cmake 变量就重新建一个新 build 目录然后从头编译。实际上 Ninja 的增量构建非常智能只要你的改动不影响大多数源文件的依赖它只编译受影响的文件。所以正确的做法是一个 build 目录对应一组配置文件不要频繁重建。如果一定要切换配置比如从 Debug 切 Release也不建议覆盖原目录新建一个 build-release 目录更稳妥两者可以并存。还有一个加速技巧是 ccache。llvm-project 的编译单元非常多新建 build 目录时反复编译相同的源文件是纯浪费。配好 ccache 后第二次构建大部分文件都命中缓存时间能缩短一半以上。安装 ccache 后在 CMake 里指定-DCMAKE_C_COMPILER_LAUNCHERccache \ -DCMAKE_CXX_COMPILER_LAUNCHERccache然后记住在 ~/.ccache/ccache.conf 里把 max_size 调大比如 32G否则默认 5G 不够支撑这种大型项目。5.3 clang 编出来的程序运行报错先看三个经典方向第一库路径问题。本地 clang 默认去找系统 libstdc/libc如果你编译器版本较新可能链接到不兼容的 C 标准库。通常需要配合-stdliblibstdc或-stdliblibc做显式指定或设置LD_LIBRARY_PATH指向新构建的 libc 目录。第二动态链接器路径问题。你如果用BUILD_SHARED_LIBSON编出来的 clang 依赖 build/lib 下大量的 .so。直接把 build/bin/clang 拷贝到别的机器上肯定跑不起来。部署时要么记得带库要么改用 static 库构建要么仔细设置 rpath。这个坑在写文档时很容易被忽略但真的遇到时能卡一下午。第三target 不匹配。拿 X86 编译出的 clang 去跑 ARM 交叉编译如果没有额外配置 sysroot 和 linker基本不会成功。如果你要做多目标开发构建时把LLVM_TARGETS_TO_BUILD改为ALL或者在命令行用--target指定。5.4 排查细节怎么判断是上游 bug 还是自己配置问题当你跑 clang 测试出现 assertion 失败时先别急着去 GitHub 提 issue先做三个自检。一是确认你和主流 release 分支的差距比如你是用 main 分支某个 commit那么行为可能和 release 差异很大issue 前先搜 commit log。二是最小化用例把触发问题的源码裁剪到尽量短这一步基本能区分是 clang 前端错误还是优化器错误。三是对照一遍 CMake 参数特别是你是否打开了某些非默认选项比如-DLLVM_ENABLE_EXPERIMENTAL_TARGETS里加了新架构。如果确实怀疑是 llvm-project 的 bug建议在该版本的 release tag 上复现一次如果 release 不复现那大概率是 main 分支的新回归处理方式就是回退 commit、等待修复或者在 llvm-project 的 issue 区提供最小复现文件。这个过程我走了无数次每次都能学到新东西。6. 版本升级与分支切换如何平滑迁移自己的代码6.1 为什么 llvm 每年都会“破坏性”更新LLVM 社区以 API 变动频繁著称每年大版本都会调整 Pass 接口、删除旧模块、改名 header。如果你是基于 llvm-project 做二次开发的工作一定要意识到这一点。不是“代码写完了就一劳永逸”而是“每次升级都要预留出适配窗口”。最常见的破坏来自两个方向。第一个是 header 目录调整比如llvm/IR/Function.h可能会移动到llvm/IR/Function.h不变但llvm/IR/LegacyPassManager.h可能被拆成多个子模块。第二个是 Pass API 演进旧版FunctionPass可能需要改成新 Pass Manager 的AnalysisKey注册方式改动量不小。我个人的迁移策略是先升级到相邻大版本比如从 LLVM 17 到 LLVM 18不要直接跳两个以上版本否则错误堆积太多根本不知道是谁引起的。每升一级就编一遍、跑一遍自己的测试集确认无回归后再去下一个版本。虽然多花几次编译时间但整体定位成本大大降低。6.2 本地如何同时保留多版本构建日常工作经常需要同时对比不同 LLVM 版本的行为比如一个 Pass 在 16 上正常、在 18 上崩溃。这时多 build 目录就派上用场了。我会建 llvm-project 下三个目录build-17-release build-17-debug build-18-debug每个目录独立 configure、独立 ninja彼此不影响。使用哪个版本就把对应 build/bin 放到 PATH 前面。这样不仅切换方便还能用 diff 命令比较两个 clang 对同一源码生成的汇编差异定位到是哪个版本的哪种优化策略变了。注意在切换时把CMAKE_INSTALL_PREFIX也区分开避免 install 时互相覆盖。6.3 升级后必做的测试清单不管从哪个版本升到哪个版本我升级完必做这样几件事第一跑一遍 clang 自带的快速测试ninja check-clang会有一部分测试不通过重点看是不是新增失败。如果大量失败往往是配置或者底层环境问题而不是代码兼容。第二用以前的典型项目重新编译一次最好是你自己维护的一个中型 C 工程这样能覆盖模板、异常、RTTI 等常见特性。第三做一次简单的性能对比用同一个 benchmark 跑新旧 clang 的可执行文件避免升级后优化意外变差。第四检查所有自定义插件的编译是否正常因为 Pass API 变动基本都会在插件编译时报错提前暴露就是好事。7. 一处容易被忽视的细节LLVM_ENABLE_PROJECTS 和 LLVM_ENABLE_RUNTIMES 到底怎么分新手最容易混淆的是 LLVM_ENABLE_PROJECTS 和 LLVM_ENABLE_RUNTIMES。前者在 llvm 主构建里直接编译模块之间耦合紧密适合 clang、lld、clang-tools-extra 这类“本身就是 LLVM 开发者子项目”的模块。后者处于更外圈像 libcxx、libcxxabi、compiler-rt、libunwind它们需要先有一个可用的 clang 或 gcc 才能编译也不适合和 LLVM 核心放在同一个构建里搅和。拿 libcxx 举例你想构建一套新的 C 标准库如果在 PROJECTS 里指定 libcxx意味着 clang 在构建时会去寻找尚未生成的 libcxx 头文件和库很容易死锁。正确做法是在 RUNTIMES 里启用这样 CMake 会先构建 clang 本身再进入 runtime 阶段用刚构建好的 clang 去编 C 运行库。我配过一次 libcxx 的 debug 环境用-DLLVM_ENABLE_RUNTIMESlibcxx;libcxxabi;libunwind一次就成功了换成 PROJECTS 反而卡在循环依赖上。如果你只想要默认 libstdc 组件其实没必要碰 RUNTIMES。默认 clang 会用系统 libstdc 工作得很好除非你确实在改 libc 自身源码或需要精确控制 C ABI 版本。选错了只会增加构建复杂度和额外时间。8. 从构建到落地一份可持续维护的构建脚本模板到了这个阶段你已经有能力编出一个可用的 clang也有了调试和开发的基本环境。我在实际工作中会把构建参数固化到一个 shell 脚本里避免每次面向 CMake 大海捞针。下面是一份我常用的模板按需改注释里的开关即可#!/usr/bin/env bash set -euo pipefail LLVM_SRC_DIR$(cd $(dirname ${BASH_SOURCE[0]})/../llvm pwd) BUILD_DIR${BUILD_DIR:-${LLVM_SRC_DIR}/../build-debug} INSTALL_DIR${INSTALL_DIR:-${LLVM_SRC_DIR}/../install-debug} cmake -G Ninja -S ${LLVM_SRC_DIR} -B ${BUILD_DIR} \ -DLLVM_ENABLE_PROJECTSclang;lld;clang-tools-extra \ -DLLVM_ENABLE_RUNTIMES \ -DLLVM_TARGETS_TO_BUILDX86 \ -DCMAKE_BUILD_TYPEDebug \ -DLLVM_ENABLE_ASSERTIONSON \ -DLLVM_OPTIMIZED_TABLEGENON \ -DBUILD_SHARED_LIBSON \ -DCMAKE_INSTALL_PREFIX${INSTALL_DIR} \ -DCMAKE_C_COMPILERgcc \ -DCMAKE_CXX_COMPILERg \ -DCMAKE_C_COMPILER_LAUNCHERccache \ -DCMAKE_CXX_COMPILER_LAUNCHERccache cmake --build ${BUILD_DIR} -- -j$(nproc)脚本里把源码目录、构建目录、安装目录都拆开好处是 cmake 重新配置时不会污染源码树也不会因为路径写死导致换机器后失效。set -euo pipefail确保任何一步失败都立刻停止不会带病继续。构建完成后我再单独跑cmake --install ${BUILD_DIR}把产物整理到干净的 install 目录方便后续部署或打压缩包。我最喜欢这套脚本的一点是它完全可复现。换一台新机器只要装上 cmake、ninja、gcc/g、ccache执行一次脚本就自动生成一个可用的 llvm-project 开发环境不用再担心某个参数漏配或写错。9. 最后的实操建议llvm-project 是一个足够大、足够深的项目初次接触很容易被它的体量吓到。但实际用下来的感觉它更像一套积木你可以只取 llvmclang 做工具链也可以挂在 mlir 上做编译器和 AI 加速还能用 libcxx 构建完全可控的 C 运行环境。关键是从小处开始先确定目标再选分支和 tag再配置 CMake再动手编译。每走通一步你对这个庞大工程的理解就会深一层。我自己在折腾 llvm-project 的过程中最大的体会是不要试图一次掌握所有内容也不要一开始就纠结所有参数的含义。把构建跑通、把调试环境配好然后去写一个简单的 Pass 或插件遇到问题再回头查文档和源码。这种“从实践中学习再回到实践中去”的路径远比从头到尾背诵 CMake 选项和 API 列表要有效得多。如果你正在做一个自定义编译器、静态分析工具、或编译器后端相关的工作建议把这份构建脚本和 debug 环境作为第一里程碑。真正跨过“能编、能跑、能调”这道坎之后后续研究 IR 设计和优化算法的学习曲线会平缓很多。