Kotlin IR编译器插件开发指南

在 Kotlin 中开发基于 IR（Intermediate Representation）的编译器插件，可以深度定制语言功能或实现高级代码转换。以下是分步骤指南：

一、IR 编译器插件基础

IR 是什么？
- Kotlin 编译器将源码转换为 IR 中间表示（1.4+ 默认后端）
- 相比旧的 PSI-based 插件，IR 插件更稳定且能直接操作语义层
插件能力范围
- 修改现有代码（如插入日志、性能监控）
- 生成新代码（注解处理、DSL 增强）
- 自定义语法糖（需配合解析器修改）

二、开发环境搭建

Gradle 配置

// build.gradle.kts
plugins {kotlin("jvm") version "1.9.0" // 使用最新稳定版
}dependencies {implementation(kotlin("compiler-embeddable")) // 必须的编译器依赖
}

插件入口类

import org.jetbrains.kotlin.compiler.plugin.ComponentRegistrar
import org.jetbrains.kotlin.config.CompilerConfigurationclass MyIrPluginRegistrar : ComponentRegistrar {override fun registerProjectComponents(project: MockProject,configuration: CompilerConfiguration) {IrGenerationExtension.registerExtension(project, MyIrGenerationExtension())}
}

三、核心开发流程（以代码生成为例）

示例目标：实现 `@MeasureTime` 注解统计方法执行时间

定义注解

@Retention(AnnotationRetention.SOURCE)
@Target(AnnotationTarget.FUNCTION)
annotation class MeasureTime

实现 IR 转换扩展

class MeasureTimeIrExtension : IrGenerationExtension {override fun generate(moduleFragment: IrModuleFragment,pluginContext: IrPluginContext) {val irFactory = pluginContext.irFactorymoduleFragment.transformChildrenVoid(object : IrElementTransformerVoid() {override fun visitFunction(declaration: IrFunction): IrStatement {if (declaration.hasAnnotation(MeasureTime::class)) {return injectTimingCode(declaration, pluginContext)}return super.visitFunction(declaration)}})}
}

注入测量代码

private fun injectTimingCode(func: IrFunction,context: IrPluginContext
): IrFunction {val startVar = context.irFactory.createVariable(name = Name.identifier("_start"),type = context.irBuiltIns.longType,isVar = true)val startExpr = IrCallImpl(startVar.symbol,context.irBuiltIns.setLong.owner.symbol,type = context.irBuiltIns.longType).apply {putValueArgument(0, IrConstImpl.long(0, context.irBuiltIns.longType, System.nanoTime()))}val originalBody = func.body?.deepCopyWithSymbols()val newBody = context.irFactory.createBlockBody(start = SYNTHETIC_OFFSET,end = SYNTHETIC_OFFSET).apply {statements += startExproriginalBody?.statements?.let { statements.addAll(it) }statements += createPrintlnCall(context, "Method ${func.name} took ${System.nanoTime() - _start}ns")}return func.apply {body = newBody}
}

四、调试与测试技巧

IR 树输出

// 在插件中插入调试代码
println(irFunction.dump())

单元测试方案

class MeasureTimeTest : AbstractIrTextTest() {@Testfun testMethodInstrumentation() {val code = """@MeasureTimefun test() { println("Hello") }"""assertGeneratedCode(code) {contains("System.nanoTime()")hasNoErrors()}}
}

五、高级主题

符号解析 (Symbol Resolution)
- 通过 IrPluginContext.referenceFunctions() 查找系统函数
- 使用 irBuiltIns 访问基础类型（如 irBuiltIns.unitType）

元编程

// 动态创建新函数
val newFunction = irFactory.createFunction(name = Name.identifier("generated_${func.name}"),visibility = DescriptorVisibilities.PUBLIC,returnType = context.irBuiltIns.unitType
)

兼容性处理
- 通过 @OptIn(CompilerPluginApiPreview::class) 处理实验性 API
- 针对不同 Kotlin 版本使用条件编译

六、部署与集成

创建 SPI 配置
- 在 resources/META-INF/services 中添加 ComponentRegistrar 入口
```
com.example.MyIrPluginRegistrar
```

作为独立插件使用

./gradlew jar
kotlinc -Xplugin=build/libs/my-plugin.jar -Xallow-result-return-type

常见问题解决

Q: 如何处理泛型类型？
- 使用 IrTypeParameters 和 IrTypeArguments 构建泛型签名
Q: 如何避免符号解析失败？
- 优先使用 IrPluginContext 提供的符号查找方法
- 对跨模块引用使用 IrExternalDeclarationsGenerator