编写LLVM Pass引入llvm/IR/Module.h提示文件未找到问题排查

算力阿峰

2026-8-26

问题描述

编写LLVM Pass时遇到头文件找不到的编译错误，代码中引入的头文件如下：

#include <llvm/IR/Module.h>
#include <llvm/IR/Function.h>
#include <llvm/IR/Instructions.h>
#include <llvm/IR/Constants.h>
#include <llvm/IR/CallSite.h>
#include <llvm/Analysis/LoopInfo.h>
#include <llvm/Support/raw_ostream.h>
#include <glog/logging.h>

本地存放头文件的include目录结构：

── include
│   ├── glog
│   │   ├── logging.h
│   │   ├── log_severity.h
│   │   ├── platform.h
│   │   └── vlog_is_on.h
│   ├── llvm
│   │   └── IR
│   │       └── Module.h
│   └── llvm-c
│       ├── DataTypes.h
│       ├── ExternC.h
│       └── Types.h

编译报错信息：

1:10: fatal error: 'llvm/IR/Module.h' file not found
#include <llvm/IR/Module.h>
^~~~~~~~~~~~~~~~~~ 1 error generated.

根因排查

报错的直接原因是编译器无法在预设的搜索路径中找到对应头文件，结合给出的目录结构，按影响优先级排序有三个核心问题：

未将自定义include目录加入编译器搜索路径：使用尖括号<>引用头文件时，编译器默认仅搜索系统标准头文件目录、编译参数-I显式指定的目录。你存放头文件的这个include目录不属于系统默认搜索路径，如果编译时没有传入对应-I参数指定该目录位置，编译器根本不会进入这个目录查找头文件，直接抛出找不到文件的错误。
LLVM头文件集合严重残缺：你当前include目录下的llvm子目录结构不完整，仅存在llvm/IR/Module.h单个文件，代码中引用的Function.h、Instructions.h等同目录头文件，以及Analysis、Support目录下的头文件完全缺失。就算正确添加了搜索路径解决当前Module.h的报错，后续也会连续触发其他LLVM头文件找不到的错误，零散拷贝单个LLVM头文件的方式完全无法满足编译需求。
存在LLVM版本兼容问题：llvm/IR/CallSite.h在LLVM 11及之后的版本中已被移除，相关实现迁移到了llvm/IR/AbstractCallSite.h，如果你使用的是高版本LLVM，路径配置正确后也会因为这个头文件不存在触发编译错误。

修复步骤

替换残缺的LLVM头文件：不要手动零散拷贝LLVM头文件，直接安装对应版本的LLVM开发包，或者指向你编译LLVM时生成的完整build目录下的头文件集合，保证所有引用的LLVM头文件目录结构完整。
自动获取正确编译参数：不要手动硬编码头文件路径，通过llvm-config --cxxflags命令可以自动输出对应版本LLVM所需的头文件搜索路径、编译宏、C++标准版本等参数，避免手动配置漏项。常规的LLVM Pass编译命令参考：
```
clang++ -fPIC -shared YourPass.cpp -o YourPass.so `llvm-config --cxxflags --ldflags --libs core analysis`
```
适配LLVM版本：如果使用LLVM 11及以上版本，移除#include <llvm/IR/CallSite.h>引用，替换为对应版本的头文件，并调整相关API调用逻辑适配版本变更。
glog头文件如果安装在非系统默认路径，同样需要将glog的根include目录加入编译搜索路径，当前报错还未执行到glog头文件查找步骤，优先解决LLVM头文件配置问题即可。

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