Performance¶

Metro strives to be a performant solution with minimal overhead at build-time and generating fast, efficient code at runtime.

Benchmarks¶

To benchmark against anvil-ksp + dagger-ksp, anvil-ksp + dagger-kapt, and kotlin-inject-anvil + kotlin-inject, there is a benchmark directory with a generator script. There are more details in its README, but in short it generates a nontrivial multi-module project (default is 500 modules but is configurable) and benchmarks with gradle-profiler.

The below sections describe the two scenarios Metro’s benchmarks run against using this project generation.

Modes

• Metro: Purely running metro
• Dagger (KSP): Running dagger-ksp with anvil-ksp for contribution merging.
• Dagger (KAPT): Running dagger-kapt with anvil-ksp for contribution merging.
• Kotlin-Inject: Running kotlin-inject with kotlin-inject-anvil for contribution merging.

Build Performance¶

Metro’s compiler plugin is designed to be fast. Running as a compiler plugin allows it to:
- Avoid generating new sources that need to be compiled
- Avoid running KSP/KAPT
- Generate IR that lowers directly into target platforms
- Hook directly into kotlinc’s IC APIs.

In a straightforward migration, it improves ABI-changing build performance by 80–85%.

Methodology¶

This benchmark uses gradle-profiler to benchmark build performance using different tools.

ABI Change¶

This benchmark makes ABI-breaking source changes in a lower level module. This is where Metro shines the most.

Non-ABI Change¶

This benchmark makes non-ABI-breaking source changes in a lower level module. The differences are less significant here as KSP is quite good at compilation avoidance now too. The outlier here is KAPT, which still has to run stub gen + apt and cannot fully avoid it.

Raw Graph/Component Processing¶

This benchmark reruns the top-level merging graph/component where all the downstream contributions are merged. This also builds the full dependency graph and any contributed graph extensions/subcomponents.

Metro again shines here. Dagger (KSP) seems to have a bottleneck that disproportionately affects it here too.

Runtime Performance¶

Metro’s compiler generates Dagger-style factory classes for every injection site. The same factory classes are reused across modules and downstream builds, so there’s no duplicated glue code or runtime discovery cost.

Because the full dependency graph is wired at compile-time, each binding is accessed through a direct provider field reference or direct invocation in the generated code. No reflection, no hashmap lookups, no runtime service locator hops, etc.

Methodology¶

To measure and compare runtime performance, Metro benchmarks graph initialization time across different DI frameworks. These benchmarks measure the time to create and initialize a dependency graph with 500 modules’ worth of bindings.

JVM Startup¶

These benchmarks run with JMH.

On the JVM, Metro, Dagger (KSP), and Dagger (KAPT) all perform nearly identically since they generate similar factory-based code. kotlin-inject is slightly slower due to its different code generation approach.

JVM Startup (R8 Minified)¶

These benchmarks run with JMH on an R8-minified jar of the same built project.

With R8 minification enabled, Metro shows a slight edge. The benefits of compile-time wiring become more apparent as R8 can further optimize the generated code.

Android Graph Init¶

On Android, the differences become more pronounced. Metro and Dagger perform similarly well, while kotlin-inject shows a significant performance gap.

Real-World Results¶

Below are some results from real-world projects, shared with the developers’ permission.

Scaling to Very Large Graphs¶

For graphs aggregating thousands of contributions, two opt-in knobs help work around JVM and Kotlin metadata size limits. Both are power-user features and unnecessary for typical graphs.

@MergeContributionsInIr¶

Annotating a graph with @MergeContributionsInIr opts it out of FIR-side contribution-supertype merging. Contributions are still merged into the graph during IR, so runtime behavior is unchanged. The trade-off is that contributions become invisible in the graph’s Kotlin metadata:

• Code consuming the graph as an @Includes dependency will not see contributed members.
• IDE support will not surface contributed members on the graph type.
• Kotlin/Native ObjC framework export will not include contributed interfaces in the graph’s supertype list.

This annotation is @DelicateMetroApi and requires explicit opt-in. You should only use this if you have a very specific reason to.

merged-supertype-chunk-size¶

The merged-supertype-chunk-size Metro compiler option groups merged contribution supertypes into synthetic intermediate interfaces of at most N contributions each. This is useful for graphs whose merged supertype list would otherwise exceed the JVM’s 65535-byte class signature limit, which the JVM emits whenever at least one supertype is generic.

metro {
  compilerOptions.put("merged-supertype-chunk-size", "200")
}

Default 0 disables chunking. Each chunk holds up to N contributions plus their promoted parent interfaces, so the chunk count tracks the contribution count rather than the raw supertype count. Most useful paired with @MergeContributionsInIr for the largest graphs.

Tracing¶

If you want to investigate the performance of Metro’s compiler pipeline, you can enable tracing in the Gradle DSL.

metro {
  traceDestination.set(layout.buildDirectory.dir("metro/trace"))
}

This will output one or more Perfetto trace files after the compilation that you can then load into https://ui.perfetto.dev.

Filenames follow the pattern <id>-<phase>-<moduleName>.perfetto-trace, where <id> is a yyMMdd-HHmmss timestamp shared across every file produced by the same compilation, <phase> is fir or ir, and <moduleName> identifies the FIR session or IR module fragment. KMP source-set hierarchies and multi-fragment IR each produce their own files. Load whichever file corresponds to the phase you want to inspect.

Note that these traces probably do require a bit of familiarity with the Metro compiler internals.