Skip to content

自定义编译器插件 ​

Kotlin 编译器插件 API 尚不稳定,且在每个版本中都会引入破坏性变更。

编译器插件通过挂钩(hook)编译过程,在代码编译期间对其进行分析或修改,而无需修改编译器本身。例如,它们可以为代码添加注解,或者生成新代码以使其与其他框架或 API 兼容。

在创建自定义编译器插件之前,请查看可用编译器插件列表,了解是否已有适合您用例的插件。

您还可以检查是否可以使用 Kotlin Symbol Processing (KSP) API 或外部 Lint 分析工具(例如 Android lint)来实现目标。

如果您_仍然_找不到满足需求的方法,可以创建自定义编译器插件。请注意,Kotlin 编译器插件 API 不稳定。由于每个新的编译器版本都会引入破坏性变更,您需要持续投入大量精力进行维护。

Kotlin 编译器与编译器插件 ​


  • Kotlin compiler stages
  • Kotlin 编译器会:

    1. 解析源代码并将其转换为结构化的语法树。
    2. 通过确定代码含义、解析名称、检查类型以及强制执行可见性规则来分析和解析代码。
    3. 生成中间表示 (Intermediate Representation, IR),这是一种充当源代码与机器码之间桥梁的数据结构。
    4. 逐步将 IR 降级转换(Lower)为更简单的形式。
    5. 将 Lower 后的 IR 转换为特定于目标的输出,例如 JVM 字节码、JavaScript 或原生机器码。

插件可以通过前端 API 影响编译器的初始阶段,改变编译器解析代码的方式。例如,插件可以添加注解、引入没有函数体的新方法,或者更改可见性修饰符。这些更改在 IDE 中是可见的。

插件还可以通过后端 API 影响后续阶段,修改声明的行为。这些更改会出现在编译完成后生成的二进制文件中。

在实践中,编译器插件会影响从分析和解析到代码生成的各个阶段,涵盖前端和后端。例如,前端部分生成声明,而后端部分为这些声明添加主体。

Kotlin compiler stages with plugins

Kotlin serialization 插件就是一个很好的例子。该插件的前端部分添加了一个伴生对象和一个序列化器函数,并添加了防止名称冲突的检查。后端部分则通过 KSerializer 对象实现所需的序列化行为。

Kotlin 编译器插件模板 ​

要开始编写自定义编译器插件,可以使用 Kotlin 编译器插件模板。然后注册前端和后端插件 API 的扩展点。

目前,只能使用 Gradle 开发自定义编译器插件。

前端插件 API ​

前端插件 API 也称为前端中间表示 (FIR),具有以下专门用于自定义解析的扩展点:

扩展名称描述
FirAdditionalCheckersExtension添加自定义编译器检查器。
FirDeclarationGenerationExtension生成新声明。
FirExtensionSessionComponent在 FirSession 中注册自定义组件,供插件的其他部分使用。
FirFunctionTypeKindExtension定义新的函数类型族。
FirMetadataSerializerPlugin读取声明元数据并向其中写入信息。
FirStatusTransformerExtension修改声明状态属性,例如可见性或模态(modality)。
FirSupertypeGenerationExtension为现有类添加新的超类型。
FirTypeAttributeExtension根据类型注解为某些类型添加特殊属性。

IDE 集成 ​

解析的更改会影响代码高亮显示和建议等 IDE 行为,因此让插件与 IDE 保持兼容至关重要。每个版本的 IntelliJ IDEA 和 Android Studio 都包含一个 Kotlin 编译器的开发版本。该版本特定于 IDE,且与已发布的 Kotlin 编译器并不二进制兼容。因此,当更新 IDE 时,还需要更新编译器插件以使其保持正常工作。出于此原因,社区插件默认不会被加载。

为了确保自定义编译器插件可以在不同的 IDE 版本中正常工作,请针对各个 IDE 版本进行测试并修复发现的任何问题。

如果能提供针对 Kotlin 编译器插件的 devkit,支持多个 IDE 版本可能会变得更加容易。如果您对该功能感兴趣,欢迎在我们的问题跟踪器中分享反馈。

后端插件 API ​

后端插件开发难度较大,若要不降低 IDE 或调试器的性能更是如此,因此请谨慎且保守地进行更改。

后端插件 API 也称为 IR,具有单个扩展点:IrGenerationExtension。使用此扩展点并重写 generate() 函数,可以为前端已生成的声明添加主体,或者更改现有的声明主体。

通过此扩展点所做的更改未经编译器检查。您必须确保所做的更改不会破坏编译器在此阶段的预期。例如,您可能会意外引入无效类型、不正确的函数引用,或者引入超出正确作用域的引用。

探索后端插件代码 ​

您可以研究 Kotlin serialization 插件的代码,了解后端插件编译器代码在实践中的样貌。例如,SerializableCompanionIrGenerator.kt 会为关键序列化器成员填充缺失的主体。一个示例是 generateChildSerializersGetter() 函数,它会收集 KSerializer 表达式的列表并在数组中返回它们。

检查后端插件代码是否存在问题 ​

可以通过三种方式检查后端插件代码中的问题:

  1. 验证 IR

    构建 IR 树并启用 Xverify-ir 编译器选项。此选项对编译速度有性能影响,因此建议仅在测试期间使用。

  2. 转储并比较 IR 输出

    使用 -Xphases-to-dump-before=ExternalPackageParentPatcherLowering 编译器选项在 IR lowering 编译阶段之后创建转储文件。对于 JVM 后端,请使用 -Xdump-directory=<your-file-directory> 编译器选项配置转储目录。手动编写预期代码,生成另一个转储文件,然后比较两者以查看是否存在差异。

  3. 调试编译器代码

    在 convertToIr.kt 文件中,于 convertToIrAndActualize() 函数中添加断点,并在调试模式下运行编译器,以在编译期间获取更详细的信息。

测试您的插件 ​

实现插件后,请对其进行充分测试。Kotlin 编译器插件模板已配置为使用 Kotlin 编译器测试框架。您可以在以下目录中添加测试:

  • compiler-plugin/testData
  • compiler-plugin/testData/box 用于代码生成测试
  • compiler-plugin/testData/diagnostics 用于诊断测试

当测试运行时,该框架会:

  1. 解析测试源文件。例如,anotherBoxTest.kt
  2. 为每个文件构建 FIR 和 IR。
  3. 将这些内容写入文本转储文件。例如,anotherBoxTest.fir.txt 和 anotherBoxTest.fir.ir.txt。
  4. 将这些文件与之前创建的文件(如果存在)进行比较。

您可以使用这些文件来检查生成的差异中是否存在非预期的更改。如果没有问题,新的转储文件将成为您最新的_基准(golden)_文件:作为经过批准且可信的基准,用于与未来的更改进行比对。

获取帮助 ​

如果在开发自定义编译器插件时遇到问题,可以在 Kotlin Slack 的 #compiler 频道中寻求帮助。我们无法保证一定能提供解决方案,但会尽力提供协助。