如何将自定义LLVM Pass接入Rustc编译流程？

核心前提：LLVM版本严格匹配 #

自定义Pass的编译必须使用与当前rustc绑定的LLVM版本——LLVM API无稳定性保证，版本不匹配会直接导致加载失败：

• 查看rustc绑定的LLVM版本：执行rustc -vV，输出中会包含LLVM version字段。
• 编译自定义Pass时，必须使用该版本的LLVM头文件和库进行编译。

正确的加载命令 #

rustc不支持Clang的-fpass-plugin参数，需使用LLVM原生的-load-pass-plugin参数，通过-C llvm-args传递给LLVM，同时结合-C passes指定要运行的Pass：

RUSTFLAGS="-C llvm-args=-load-pass-plugin=/opt/new-pass/mypass.so -C passes=my-pass" cargo build

进阶：指定Pass运行阶段 #

如果Pass需要插入到特定优化流水线阶段，需明确指定执行顺序，比如在O3优化完成后运行：

RUSTFLAGS="-C llvm-args=-load-pass-plugin=/opt/new-pass/mypass.so -C passes=default<O3>,my-pass" cargo build

常见问题排查 #

• "unknown pass name"错误：

  • 检查Pass注册名称是否与-C passes中的my-pass完全一致，该名称对应你在Pass代码中通过llvm::PassRegistry注册的标识。
  • 增加LLVM调试日志验证插件是否加载：添加-C llvm-args=-debug-pass=Structure参数，查看输出中是否包含你的Pass名称。

• 插件加载无报错但Pass未运行：

  • 确认LLVM小版本完全匹配（如LLVM 16.0.6而非16.0.0）。
  • 检查插件与当前系统架构兼容（如x86_64插件不能在aarch64环境运行）。
  • 确保使用rustup安装的官方rustc版本（部分发行版定制rustc可能默认禁用LLVM插件支持）。

内容的提问来源于stack exchange，提问作者Jerry