如何在Kotlin K2编译器插件中使用HtmlFirDump？

1. 核心Dump代码 #

在K2编译器插件中，你可以通过HtmlFirDump直接导出FIR元素的结构化HTML文件，以下是最简实现：

import org.jetbrains.kotlin.fir.dump.HtmlFirDump
import org.jetbrains.kotlin.fir.dump.HtmlFirDumpConfiguration
import java.io.File

/**
 * 导出单个FIR文件的结构到HTML
 * @param firFile 要分析的FIR文件节点
 * @param outputDir 输出目录路径
 */
fun dumpFirStructure(firFile: org.jetbrains.kotlin.fir.declarations.FirFile, outputDir: String) {
    // 配置Dump内容：可按需开启/关闭源码、描述符、属性显示
    val dumpConfig = HtmlFirDumpConfiguration(
        showSourceCode = true,
        showDescriptors = true,
        showAttributes = true
    )
    val htmlDump = HtmlFirDump(dumpConfig)
    val outputFile = File(outputDir, "${firFile.name}.fir.html")
    
    // 创建输出目录（如果不存在）
    outputFile.parentFile.mkdirs()
    
    // 执行Dump并写入文件
    htmlDump.dumpElement(firFile, outputFile.outputStream())
}

2. 在插件中触发Dump #

通过FirAnalysisHandlerExtension在编译分析阶段注入Dump逻辑，遍历所有处理的FIR文件：

import org.jetbrains.kotlin.fir.analysis.extensions.FirAnalysisHandlerExtension
import org.jetbrains.kotlin.fir.declarations.FirFile

class FirDumpAnalysisExtension : FirAnalysisHandlerExtension() {
    override fun runAnalysis(files: List<FirFile>) {
        super.runAnalysis(files)
        val outputDir = "./fir-structure-dumps" // 自定义输出路径
        
        files.forEach { firFile ->
            // 可添加过滤逻辑，比如只Dump特定包/类
            if (firFile.packageName.asString().startsWith("com.your.package")) {
                dumpFirStructure(firFile, outputDir)
            }
        }
    }
}

3. 注册插件扩展 #

将上述分析扩展注册到编译器插件中：

import org.jetbrains.kotlin.compiler.plugin.CompilerPluginRegistrar
import org.jetbrains.kotlin.config.CompilerConfiguration

class FirDumpPluginRegistrar : CompilerPluginRegistrar() {
    override fun ExtensionStorage.registerExtensions(configuration: CompilerConfiguration) {
        FirAnalysisHandlerExtension.registerExtension(FirDumpAnalysisExtension())
    }
}

注意事项 #

• HtmlFirDump属于Kotlin编译器内部API，版本兼容性需与插件依赖的Kotlin版本保持一致；
• 调试完成后建议移除Dump代码，避免额外的编译性能开销；
• 生成的HTML文件可直接在浏览器中打开，查看FIR节点的层级结构、关联源码及属性详情。

内容的提问来源于stack exchange，提问作者Todd O'Bryan