LLVM Pass开发入门：从环境搭建到Hello World实现

原创于 2026-11-02 12:21:30 发布 · 272 阅读

本内容遵循CC 4.0 BY-SA版权协议

本文系统介绍LLVM Pass开发全流程：从Ubuntu环境下LLVM工具链安装与CMake环境配置，到编写FunctionPass实现Hello World功能；涵盖opt工具加载、Clang集成、GDB调试技巧、常见崩溃与IR验证问题排查；并延伸至代码优化、统计信息收集和插桩等实用扩展方向，聚焦LLVM IR分析与转换核心能力。

1. LLVM Pass开发环境准备

在开始编写第一个LLVM Pass之前，我们需要先搭建好开发环境。LLVM作为一个模块化的编译器框架，其Pass系统是进行代码分析和转换的核心机制。这里我推荐使用Ubuntu 20.04 LTS作为开发平台，因为它的软件包管理对LLVM支持较好。

1.1 安装LLVM工具链

首先通过apt安装LLVM的最新稳定版本（当前为LLVM 13）：

sudo apt-get install llvm-13 llvm-13-dev clang-13 libclang-13-dev

安装完成后，验证安装是否成功：

llvm-config-13 --version

注意：不同版本的LLVM API可能有细微差异，建议始终使用同一版本进行开发和测试。我在实际项目中曾因混用LLVM-11和LLVM-13导致难以排查的兼容性问题。

1.2 配置开发环境

创建一个专门的工作目录，并设置环境变量方便后续操作：

mkdir llvm-pass-tutorial && cd llvm-pass-tutorial
export LLVM_DIR=/usr/lib/llvm-13

建议使用CMake来管理项目，创建如下目录结构：

.
├── CMakeLists.txt
└── src
    └── HelloPass.cpp

2. 第一个Hello World Pass实现

2.1 Pass基础结构

LLVM Pass有多种类型，我们从一个最简单的FunctionPass开始。创建src/HelloPass.cpp文件：

#include "llvm/Pass.h"
#include "llvm/IR/Function.h"
#include "llvm/Support/raw_ostream.h"

using namespace llvm;

namespace {
struct Hello : public FunctionPass {
    static char ID;
    Hello() : FunctionPass(ID) {}
    
    bool runOnFunction(Function &F) override {
        errs() << "Hello: ";
        errs().write_escaped(F.getName()) << '\n';
        return false;
    }
};
}

char Hello::ID = 0;
static RegisterPass<Hello> X("hello", "Hello World Pass");

这个Pass会遍历程序中的所有函数，并打印出函数名称。关键点说明：

继承自FunctionPass表示这是一个函数级别的Pass
runOnFunction是主要的处理逻辑入口
返回false表示没有修改IR代码

2.2 CMake构建配置

编写CMakeLists.txt确保正确链接LLVM库：

cmake_minimum_required(VERSION 3.13)
project(LLVMPassDemo)

find_package(LLVM REQUIRED CONFIG)
message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
include_directories(${LLVM_INCLUDE_DIRS})
add_definitions(${LLVM_DEFINITIONS})

add_library(HelloPass MODULE
    src/HelloPass.cpp
)

set_target_properties(HelloPass PROPERTIES
    COMPILE_FLAGS "-fno-rtti -fPIC"
    PREFIX ""
)

构建项目：

mkdir build && cd build
cmake .. && make

成功编译后会生成HelloPass.so动态库文件。

3. 运行和测试Pass

3.1 使用opt工具加载Pass

LLVM提供了opt工具来运行Pass。首先我们需要一个测试用的LLVM IR文件：

clang-13 -S -emit-llvm -o test.ll test.c

然后运行我们的Pass：

opt-13 -load ./HelloPass.so -hello < test.ll > /dev/null

你应该能看到程序中所有函数的名称输出。

3.2 集成到Clang编译流程

要让Pass在常规编译过程中运行，可以修改编译命令：

clang-13 -Xclang -load -Xclang ./HelloPass.so test.c

实操技巧：在开发阶段，建议先用opt工具测试Pass，确认基本功能正常后再集成到完整编译流程中。这样可以节省大量编译等待时间。

4. Pass开发进阶技巧

4.1 调试Pass的有效方法

LLVM Pass开发中常见的调试手段：

使用LLVM_DEBUG宏：

#define DEBUG_TYPE "hello"
LLVM_DEBUG(dbgs() << "Debugging info: " << F.getName() << "\n");

运行时需要指定调试类型：

opt-13 -debug-only=hello -load ./HelloPass.so -hello < test.ll

打印IR内容：

F.print(errs());  // 打印整个函数的IR

使用GDB调试：

gdb --args opt-13 -load ./HelloPass.so -hello < test.ll

4.2 常见问题排查

Pass没有被执行 ：

检查是否注册了Pass（RegisterPass）
确认opt命令的-load参数路径正确
查看Pass是否被包含在指定的PassManager中

Segmentation fault ：

检查IR遍历时是否正确处理了nullptr
确认没有修改正在遍历的IR结构

不正确的IR修改 ：

使用verifyFunction检查IR有效性
逐步测试小的IR变换

5. Pass的实用扩展方向

掌握了基础Pass开发后，可以考虑以下几个实用方向：

5.1 实现简单的代码优化

例如，一个消除冗余加载的Pass：

bool runOnFunction(Function &F) override {
    bool Changed = false;
    for (auto &BB : F) {
        for (auto &I : BB) {
            if (auto *LI = dyn_cast<LoadInst>(&I)) {
                if (LI->getPointerOperand()->hasOneUse()) {
                    LI->eraseFromParent();
                    Changed = true;
                }
            }
        }
    }
    return Changed;
}

5.2 收集程序统计信息

统计函数的基本块数量和指令数：

errs() << "Function " << F.getName() << ":\n";
errs() << "  Basic Blocks: " << F.size() << "\n";
errs() << "  Instructions: " << F.getInstructionCount() << "\n";

5.3 插桩实现动态分析

在函数入口插入跟踪调用：

LLVMContext &Ctx = F.getContext();
IRBuilder<> Builder(Ctx);
Builder.SetInsertPoint(&F.getEntryBlock().front());

FunctionCallee TraceFn = F.getParent()->getOrInsertFunction(
    "trace_func", Type::getVoidTy(Ctx), Type::getInt8PtrTy(Ctx));
Builder.CreateCall(TraceFn, Builder.CreateGlobalStringPtr(F.getName()));

在实际项目中，Pass开发最难的部分往往不是编写代码本身，而是理解LLVM IR的复杂结构和各种边界情况。我建议新手从小的、具体的优化目标开始，逐步积累对IR的认知。每次实现新功能时，先用小测试用例验证，再扩展到更复杂的场景。

标签