LLVM Pass加载报undefined symbol，根本原因是插件与opt运行时符号不匹配：版本不一致、ABI/PassManager不兼容、符号未导出、初始化函数无extern "C"修饰或动态库依赖缺失。
LLVM Pass 插件加载时报 undefined symbol，基本可以断定是插件二进制与当前 opt 或 clang 运行时符号不匹配——不是代码写错了，而是链接环境没对齐。
检查插件是否用对了 LLVM 版本构建
LLVM 的 C++ ABI、Pass 接口、甚至 RTTI/异常处理策略在不同版本间可能不兼容。LLVM15+ 已彻底弃用 LegacyPassManager，若你仍用旧式 RegisterPass<T> + legacy::PassManagerBase 方式编译插件，但运行时用的是 LLVM15 的 opt（默认启用新 PassManager），就会触发 undefined symbol: _ZN4llvm12PassRegistry11getPassRegistryEv 这类典型错误。
- 运行
opt --version确认实际使用的 LLVM 版本（注意：不是你$PATH里看着像的版本，而是opt二进制真正链接的库） - 用
ldd $(which opt) | grep llvm查看它依赖的libLLVM.so路径，再用readelf -V /path/to/libLLVM.so | head -20看 SONAME 版本号 - 你的插件必须用同一构建树（
$LLVM_HOME/build）下的头文件和库来编译，不能混用系统包、conda 包或不同源码分支
确认插件导出符号是否被隐藏
LLVM 默认启用 -fvisibility=hidden，如果你的插件 CMake 没显式放开符号可见性，opt -load 就找不到 RegisterPass 注册点，报 undefined symbol: _ZTVN4llvm10FuncEncryptE（虚表未导出）或类似。
- 在插件的
CMakeLists.txt中加：set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fvisibility=default") - 避免使用
add_library(... MODULE)—— 它在某些 CMake 版本下会强制hidden；改用SHARED并手动设置SOVERSION - 用
nm -D your_pass.so | grep Register检查是否导出了RegisterPass<...>实例（应为T类型，不是U）
排查 extern "C" 和名称修饰干扰
LLVM 插件加载器通过 dlsym 查找 C 风格符号，比如 LLVMInitializeMyPass。如果你在插件里写了 C++ 全局函数但没加 extern "C"，链接器生成的是修饰名（如 _Z20LLVMInitializeMyPassv），opt 就找不到入口。
- 所有供
opt -load调用的初始化函数（如LLVMInitializeMyPass）必须用extern "C"包裹 - 确保函数签名完全匹配：LLVM15 要求是
void LLVMInitializeMyPass(llvm::PassRegistry &)，不能少引用符或错类型 - 用
objdump -t your_pass.so | grep Initialize确认符号存在且是全局（g标记）、非弱（!标记）
运行时动态库路径和依赖缺失
插件 .so 文件本身可能依赖其他 LLVM 库（如 libLLVMCore.so），但 opt 加载时只负责插件主模块，不自动解析其依赖链。常见报错如 undefined symbol: _ZN4llvm12DebugLocImplC1ERKS0_，其实是插件链接了 libLLVMDebugInfoCore.so，但该库不在 LD_LIBRARY_PATH 中。
- 用
ldd your_pass.so检查所有依赖是否=> found；若有not found，补全路径 - 不要依赖
LD_LIBRARY_PATH临时设置——它不传递给opt子进程；改用patchelf --set-rpath '$ORIGIN/../lib' your_pass.so把路径硬编码进去 - 若插件依赖
libc++，确保opt和插件都链接同一份libc++.so（尤其在 macOS 或自建 LLVM 时易出问题）
最常被忽略的一点：LLVM 插件不是“编译完就能用”，它本质是运行时反射加载的共享对象，符号一致性比普通可执行文件更敏感。哪怕只差一个 patch 版本（如 15.0.6 vs 15.0.7），也可能因内部类布局变更导致虚函数调用崩溃——此时 undefined symbol 只是表象，背后是 ABI 断裂。务必让插件构建环境与目标 opt 二进制 100% 同源。
