Metro

https://github.com/zacsweers/metro
Admin
Metro is a compile-time dependency injection framework for Kotlin Multiplatform powered by a Kotlin...
Tokens:384,888
Snippets:2,423
Trust Score:9.6
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run a sandboxed IDE

Source: https://github.com/zacsweers/metro/blob/main/idea-plugin/README.md

Starts a sandboxed instance of the IDE with the plugin installed.

```shell
./gradlew -p idea-plugin runLocalIde
```

--------------------------------

### Example output for Android Studio versions

Source: https://github.com/zacsweers/metro/blob/main/ide-integration-tests/README.md

Example output showing available Android Studio versions and the required ide-versions.txt format.

```text
## Stable

  Android Studio Otter 3 Feature Drop | 2025.2.3
    Version: 2025.2.3.9
    ide-versions.txt: AS:2025.2.3.9

## Release Candidate

  Android Studio Panda 1 | 2025.3.1 RC 1
    Version: 2025.3.1.6
    ide-versions.txt: AS:2025.3.1.6:android-studio-panda1-rc1
```

--------------------------------

### Run a locally installed IDE

Source: https://github.com/zacsweers/metro/blob/main/idea-plugin/README.md

Starts a specific local IDE installation with the plugin installed using the intellijPlatformTesting.idePath property.

```shell
./gradlew -p idea-plugin runLocalIde "-PintellijPlatformTesting.idePath=/Applications/Android Studio.app"
```

--------------------------------

### Run Android app

Source: https://github.com/zacsweers/metro/blob/main/samples/compose-viewmodels/README.md

Command to install the Android app from the sample.

```bash
./gradlew -p samples :compose-viewmodels:androidApp:installDebug
```

--------------------------------

### Add IntelliJ IDEA version to ide-versions.txt

Source: https://github.com/zacsweers/metro/blob/main/ide-integration-tests/README.md

Example line to add a new IntelliJ IDEA version to the configuration file.

```text
IU:2025.3.2
```

--------------------------------

### Example function verifying dynamic graph

Source: https://github.com/zacsweers/metro/blob/main/compiler-tests/src/test/data/dump/ir/dependencygraph/dynamic/SimpleDynamicGraph.kt.txt

Shows the example function that checks the dynamic graph returns the expected value.

```kotlin
fun example() {
  check(value = EQEQ(arg0 = 5, arg1 = Example.DynamicAppGraphImpl_nc1a5(container0 = TestIntProvider(value = 5)).<get-int>()))
}
```

--------------------------------

### Prepare graph viewer and serve locally

Source: https://github.com/zacsweers/metro/blob/main/graph-viewer/README.md

Run prepareGraphViewer to combine resources, then start a local HTTP server on port 8766. Open http://127.0.0.1:8766/graph-viewer/index.html to view.

```shell
./gradlew prepareGraphViewer --quiet
python3 -m http.server 8766 --bind 127.0.0.1 --directory docs
```

--------------------------------

### Example class with dynamic graph usage

Source: https://github.com/zacsweers/metro/blob/main/compiler-tests/src/test/data/dump/ir/dependencygraph/dynamic/SimpleDynamicGraph.kt.txt

Shows the Example class that holds a property graph and a test function that creates a dynamic graph implementation with a provided value.

```kotlin
class Example {
  val propGraph: AppGraph
    field = DynamicAppGraphImpl_nc1a5(container0 = TestIntProvider(value = 4))
    get

  @DependencyGraph
  private class DynamicAppGraphImpl_nc1a5 : AppGraph {
    private val container0Instance: TestIntProvider
      field = container0

    constructor(container0: TestIntProvider) /* primary */ {
      super/*Any*/()
      /* <init>() */

    }

    override val int: Int
      override get(): Int {
        return <this>.#container0Instance.provideInt()
      }

  }

  constructor() /* primary */ {
    super/*Any*/()
    /* <init>() */

  }

  fun someTest(value: Int): Int {
    val testGraph: AppGraph = Example.DynamicAppGraphImpl_nc1a5(container0 = TestIntProvider(value = value))
    return testGraph.<get-int>()
  }

}
```

--------------------------------

### Define a simple AppGraph

Source: https://github.com/zacsweers/metro/blob/main/docs/designdoc.html

An example of a basic dependency graph interface with a @Provides function.

```kotlin
@DependencyGraph  
interface AppGraph { val message: String @Provides fun provideMessage(): String = "Hello, world!"  
}
```

--------------------------------

### Dependency Injection Bindings and Providers

Source: https://github.com/zacsweers/metro/blob/main/compiler-tests/src/test/data/dump/ir/dependencygraph/LazyPropertiesHaveDeterministicOrder.kt.txt

Examples of @Provides and @Binds annotations used to define set bindings and integer providers.

```kotlin
  @Provides
  @IntoSet
  fun bindDouble(int: Int): Double {
    return int.toDouble()
  }

  @Binds
  @IntoSet
  @ComptimeOnly
  fun Int.bindInt(): Int {
    return error(message = "Never called")
  }

  @Provides
  @IntoSet
  fun bindLong(int: Int): Long {
    return int.toLong()
  }

  @Provides
  fun provideInt(): Int {
    return 3
  }
```

--------------------------------

### Generate and run multiplatform startup benchmarks with kotlinx-benchmark

Source: https://github.com/zacsweers/metro/blob/main/benchmark/README.md

Generate the multiplatform benchmark project and run kotlinx-benchmark for all targets or specific targets. Results are saved to startup-multiplatform/build/reports/benchmarks/.

```bash
# First, generate the multiplatform benchmark project
kotlin generate-projects.main.kts --mode metro --multiplatform

# Run kotlinx-benchmark for all targets
./gradlew :startup-multiplatform:benchmark

# Run for specific targets
./gradlew :startup-multiplatform:jvmBenchmark
./gradlew :startup-multiplatform:jsBenchmark
./gradlew :startup-multiplatform:wasmJsBenchmark
./gradlew :startup-multiplatform:macosArm64Benchmark  # or macosX64Benchmark, linuxX64Benchmark

# Results are saved to startup-multiplatform/build/reports/benchmarks/

```

--------------------------------

### Run standard startup matrix for all four DI modes

Source: https://github.com/zacsweers/metro/blob/main/benchmark/README.md

Runs the standard startup benchmark matrix for all four DI modes: metro, dagger-ksp, kotlin-inject-anvil, and koin.

```bash
./run_startup_benchmarks.sh single --ref HEAD --seed 0 \
  --benchmark all --count 500 \
  --modes metro,dagger-ksp,kotlin-inject-anvil,koin
```

--------------------------------

### Install aria2 for faster downloads

Source: https://github.com/zacsweers/metro/blob/main/ide-integration-tests/README.md

Install aria2 to enable 16x parallel connections for downloading IDEs.

```bash
brew install aria2
```

--------------------------------

### Contribute Metro binding example

Source: https://github.com/zacsweers/metro/blob/main/idea-plugin/README.md

An example of an injectable class using @ContributesBinding to bind to a specific scope.

```kotlin
@Inject
@ContributesBinding(AppScope::class)
class RealHttpApi : HttpApi
```

--------------------------------

### Run JVM entry point

Source: https://github.com/zacsweers/metro/blob/main/samples/circuit-app/README.md

Executes the JVM entry point for the circuit-app sample using Gradle.

```bash
./gradlew -p samples :circuit-app:jvmRun
```

--------------------------------

### Install aria2 for faster downloads

Source: https://github.com/zacsweers/metro/blob/main/ide-integration-tests/README.md

Installs aria2 on macOS or Linux to enable up to 16 parallel connections per file during IDE downloads.

```bash
brew install aria2  # macOS

```

```bash
apt install aria2   # Linux

```

--------------------------------

### Run desktop app

Source: https://github.com/zacsweers/metro/blob/main/samples/compose-viewmodels/README.md

Command to run the desktop app from the sample.

```bash
./gradlew -p samples :compose-viewmodels:desktopApp:run
```

--------------------------------

### Metro MissingBinding diagnostic example

Source: https://github.com/zacsweers/metro/blob/main/docs/features.md

Example of a Metro compile-time diagnostic for a missing binding, showing the error ID, trace, similar bindings, help suggestion, and documentation link. Use this to understand how Metro reports missing dependencies.

```text
e: ExampleGraph.kt:8:3 
[Metro/MissingBinding] No binding found for Int

  trace (in test.ExampleGraph):
      Int is requested at test.ExampleGraph.int

  similar bindings:
      - @Named("qualified") Int (Different qualifier. Type: Provided) - ExampleGraph.kt:11:3
      - Number (Supertype. Type: Provided) - ExampleGraph.kt:10:3
      - Set<Int> (Multibinding. Type: Multibinding)

  help: ensure Int has an @Inject constructor or is provided by an @Provides or @Binds declaration
        visible to ExampleGraph
  docs: https://zacsweers.github.io/metro/latest/diagnostics/#missingbinding
```

--------------------------------

### Run traced Android startup benchmarks and save trace files

Source: https://github.com/zacsweers/metro/blob/main/benchmark/README.md

Runs Android startup benchmarks with runtime tracing and macrobenchmark, saving generated trace files.

```bash
./run_startup_benchmarks.sh android --modes metro --include-macrobenchmark --enable-runtime-tracing
```

--------------------------------

### Download IDEs and run tests

Source: https://github.com/zacsweers/metro/blob/main/ide-integration-tests/README.md

Commands to pre-download IDEs and execute the test suite.

```bash
./download-ides.sh
```

```bash
./gradlew test
```

--------------------------------

### Run Android startup benchmark with runner script

Source: https://github.com/zacsweers/metro/blob/main/benchmark/README.md

Runs the Android graph-initialization benchmark on a connected device using AndroidX Microbenchmark. Each returned component is passed to BlackHole.consume.

```bash
# Run the Android graph-initialization benchmark
./run_startup_benchmarks.sh android --seed 0

```

--------------------------------

### Supertype chunking before optimization

Source: https://github.com/zacsweers/metro/blob/main/docs/impl-notes/performance.md

Example of a large contribution graph before applying supertype chunking.

```kotlin
// Before
interface AppGraph {
  class Impl : AppGraph, Contribution1, Contribution2, Contribution3, Contribution4
}
```

--------------------------------

### Sharding Diagnostics Report Format

Source: https://github.com/zacsweers/metro/blob/main/compiler/sharding.md

Example output generated by ShardingDiagnostics.kt when reportsDestination is configured.

```text
=== Metro Graph Sharding Plan ===

Graph: com.example.AppGraph
Total bindings: 5000
Keys per shard limit: 2000
Shard count: 3

Initialization order: Shard1 → Shard2 → Shard3

Shard 1:
  Class: Shard1
  Bindings: 2000
  Outgoing cross-shard edges: 45
  Binding keys (first 5):
    - Service1
    - Service2
    ...
```

--------------------------------

### Run traced JVM startup benchmarks

Source: https://github.com/zacsweers/metro/blob/main/benchmark/README.md

Runs JVM startup benchmarks with runtime tracing enabled for Metro mode.

```bash
./run_startup_benchmarks.sh jvm --modes metro --enable-runtime-tracing
```

--------------------------------

### Run Wasm entry point

Source: https://github.com/zacsweers/metro/blob/main/samples/circuit-app/README.md

Executes the Wasm browser development run for the circuit-app sample using Gradle in continuous mode.

```bash
./gradlew -p samples :circuit-app:wasmJsBrowserDevelopmentRun --continuous
```

--------------------------------

### Metro and Dagger Component Interop

Source: https://github.com/zacsweers/metro/blob/main/docs/designdoc.html

Example showing a Metro graph depending on a Dagger component.

```kotlin
@DependencyGraph  
interface MetroGraph { val message: String @DependencyGraph.Factory fun interface Factory {   fun create(  
     daggerComponent: DaggerComponent   ): MetroGraph  
 }
}@dagger.Component  
interface DaggerComponent { val message: String @dagger.Component.Factory fun interface Factory {   fun create(@Provides message: String): DaggerComponent  
 }
}
```

--------------------------------

### Dependency Cycle Error Report

Source: https://github.com/zacsweers/metro/blob/main/docs/designdoc.html

Example of a dependency cycle error reported by Metro for a graph.

```text
ExampleGraph.kt:6:1 [Metro/DependencyCycle] Found a dependency cycle:  
		kotlin.Int is injected at  
			 [test.ExampleGraph] test.ExampleGraph.provideString(..., int)  
		kotlin.String is injected at  
			 [test.ExampleGraph] test.ExampleGraph.provideDouble(..., string)  
		kotlin.Double is injected at  
			 [test.ExampleGraph] test.ExampleGraph.provideInt(..., double)  
		kotlin.Int is injected at  
			 [test.ExampleGraph] test.ExampleGraph.provideString(..., int)
```

--------------------------------

### Run multiplatform startup benchmarks using runner script

Source: https://github.com/zacsweers/metro/blob/main/benchmark/README.md

Use the runner script to run all targets or a specific target. Results are saved to startup-benchmark-results/{timestamp}/multiplatform-{target}_metro/.

```bash
# Run all targets
./run_startup_benchmarks.sh multiplatform

# Run specific target
./run_startup_benchmarks.sh multiplatform --target jvm
./run_startup_benchmarks.sh multiplatform --target js
./run_startup_benchmarks.sh multiplatform --target wasmJs
./run_startup_benchmarks.sh multiplatform --target native

# Results are saved to startup-benchmark-results/{timestamp}/multiplatform-{target}_metro/

```

--------------------------------

### Service2 Definition and MetroFactory

Source: https://github.com/zacsweers/metro/blob/main/compiler-tests/src/test/data/dump/ir/dependencygraph/InitsAreChunked.kt.txt

Defines Service2 with a dependency on Service1, including the start of its synthesized MetroFactory.

```kotlin
@SingleIn(scope = AppScope::class)
@Inject
class Service2 {
  val s1: Service1
    field = s1
    get

  @Deprecated(message = "This synthesized declaration should not be used directly", level = DeprecationLevel.HIDDEN)
  class MetroFactory : Factory<Service2> {
    private /* final field */ val s1: Provider<Service1> = s1
    companion object Companion {
      private constructor() /* primary */ {
        super/*Any*/()
        /* <init>() */

      }
```

--------------------------------

### Generate and run JVM startup benchmarks with JMH

Source: https://github.com/zacsweers/metro/blob/main/benchmark/README.md

First generate the benchmark project with the metro mode, then run the JMH benchmarks. Results are saved to startup-jvm/build/results/jmh/.

```bash
# First, generate the benchmark project if not already done
kotlin generate-projects.main.kts --mode metro

# Run JMH benchmarks
./gradlew :startup-jvm:jmh

# Results are saved to startup-jvm/build/results/jmh/

```

--------------------------------

### Constructor injection examples

Source: https://github.com/zacsweers/metro/blob/main/docs/designdoc.html

Classes can use constructor injection by annotating the class or a specific constructor with @Inject.

```kotlin
@Inject
class ClassInjected

class SpecificConstructorInjection(val text: String) { @Inject constructor(value: Int) : this(value.toString()) 
}
```

--------------------------------

### ProvidedExample class

Source: https://github.com/zacsweers/metro/blob/main/compiler-tests/src/test/data/dump/ir/dependencygraph/membernaming/TypedMemberNamingOnSimpleGraph.kt.txt

A simple dependency class used by Config.

```kotlin
class ProvidedExample {
  constructor() /* primary */ {
    super/*Any*/()
    /* <init>() */

  }

}
```

--------------------------------

### Define a ViewModelGraph interface

Source: https://github.com/zacsweers/metro/blob/main/metrox-viewmodel/README.md

Create a graph interface extending ViewModelGraph to get multibindings for ViewModel providers.

```kotlin
@DependencyGraph(AppScope::class)
interface AppGraph : ViewModelGraph
```

--------------------------------

### List available Android Studio versions

Source: https://github.com/zacsweers/metro/blob/main/ide-integration-tests/README.md

Command to list available Android Studio versions and their corresponding configuration lines.

```bash
./list-android-studio-versions.sh
```

--------------------------------

### Graph Dependency Cycle Error Report

Source: https://github.com/zacsweers/metro/blob/main/docs/designdoc.html

Example of a dependency graph dependency cycle error reported by Metro.

```text
ExampleGraph.kt:6:1 [Metro/GraphDependencyCycle] Dependency graph dependency cycle detected! The below graph depends on itself.  
		test.CharSequenceGraph is requested at  
			 [test.CharSequenceGraph] test.CharSequenceGraph.Factory.create()
```

--------------------------------

### Run R8-minified JVM startup benchmarks

Source: https://github.com/zacsweers/metro/blob/main/benchmark/README.md

Runs the same JMH method against an R8-minified JAR. Results are saved to startup-jvm-minified/build/results/jmh/.

```bash
# Run JMH benchmarks with R8-minified Metro classes
./gradlew :startup-jvm-minified:jmh

# Results are saved to startup-jvm-minified/build/results/jmh/

```

--------------------------------

### Singleton Scope Example

Source: https://github.com/zacsweers/metro/blob/main/docs/designdoc.html

Demonstrates applying @Singleton to a provider function within a @DependencyGraph to cache the returned value.

```kotlin
@Singleton
@DependencyGraph
abstract class AppGraph { private var counter = 0 val count: Int @Singleton @Provides fun provideCount() = counter++
}
```

--------------------------------

### Graph Factory Usage for Top-level Functions

Source: https://github.com/zacsweers/metro/blob/main/docs/designdoc.html

Example of using a DependencyGraph factory to create and run an injected top-level function.

```kotlin
@DependencyGraph  
interface AppGraph { val app: AppClass @DependencyGraph.Factory fun interface Factory {    fun create(message: String): AppGraph  
 }  
}  
  
// Usage  
val app = createGraphFactory<AppGraph.Factory>()  
 .create("Hello, world!")  
 .app  
  
// Run the app  
app()
```

--------------------------------

### ExampleGraph interface with @IntoSet @Provides methods

Source: https://github.com/zacsweers/metro/blob/main/compiler-tests/src/test/data/dump/ir/MultibindingsHaveConsistentOrderAcrossContributedGraph.kt.txt

The ExampleGraph interface defines two @IntoSet @Provides methods, provide3 and provide4, that return TaskImpl3 and TaskImpl4 respectively. These are part of the multibinding contributions.

```kotlin
  @IntoSet
  @Provides
  fun provide3(): Task {
    return TaskImpl3()
  }

  @IntoSet
  @Provides
  fun provide4(): Task {
    return TaskImpl4()
  }
```

--------------------------------

### Run Metro benchmarks

Source: https://github.com/zacsweers/metro/blob/main/docs/impl-notes/performance.md

Commands to execute standard benchmarks, heap profiling, and startup benchmarks for the Metro project.

```bash
cd benchmark
./run_benchmarks.sh metro
./run_benchmarks.sh metro --profile async-profiler-heap
./run_startup_benchmarks.sh jvm --modes metro
```

--------------------------------

### Supertype chunking after optimization

Source: https://github.com/zacsweers/metro/blob/main/docs/impl-notes/performance.md

Example of a large contribution graph after applying supertype chunking to group markers into synthetic interfaces.

```kotlin
// After
interface AppGraph {
  class Impl : AppGraph, ContributionChunk_0, ContributionChunk_1 {
    interface ContributionChunk_0 : Contribution1, Contribution2
    interface ContributionChunk_1 : Contribution3, Contribution4
  }
}
```
Tokens:
Raw