Skip to content

Debugging

One major downside to generating IR directly is that developers cannot step into generated source code with the debugger. This is an accepted trade-off with Metro (or any other compiler plugin).

Metro does offer a debug option in its plugin options/Gradle extension that will print verbose Kotlin pseudocode for all generated IR classes. This can be further tuned to print just certain classes.

metro {
  debug.set(true)
}

In the future, we could possibly explore including information in IR to synthesize call stack information similar to coroutines, but will save that for if/when it’s asked for.

Reports

Similar to Compose, Metro supports a reportsDestination property in its Gradle DSL and can output various graph reports to this destination if specified. This is very much a WIP, feedback is welcome!

Warning

You should not leave this enabled by default as it can be quite verbose and potentially expensive. The Kotlin Gradle Plugin does not include file inputs like reportsDestination as task inputs, so you may need to recompile with --rerun to force recompilation after adding this flag.

metro {
  reportsDestination.set(layout.buildDirectory.dir("metro/reports"))
}

Unmatched Exclusions and Replacements

When reportsDestination is configured, Metro will report any unmatched exclusions or replacements during contribution merging. This can help identify cases where a graph excludes or replaces a class that isn’t actually present in the merged contributions.

Reports are written to files like:

  • merging-unmatched-exclusions-fir/<graph>.txt
  • merging-unmatched-replacements-fir/<graph>.txt
  • merging-unmatched-exclusions-ir/<scope>.txt
  • merging-unmatched-replacements-ir/<scope>.txt

<graph> and <scope> here may be a path like <graph1>/<graph2>/<graph3>.txt when graph extensions or embedded classes are used.

Graph Analysis & Visualization

The interactive graph viewer lets you browse bindings, follow dependencies from roots, and inspect compiler decisions. It shows graph extensions and included graphs in the same map. See Graph Analysis for setup and viewer controls.

Decompiled Bytecode

Compiled java class files of Metro-generated types are fairly friendly to the IntelliJ “decompile to Java” action. Simply open the class file in the IDE (usually seen as a Kotlin bytecode class) then run the “decompile to Java” action.

For JVM projects they are under build/classes.

For Android projects, it’s build/intermediates/built_in_kotlinc or build/tmp/kotlin-classes (legacy, pre AGP 9).