Interop¶

Annotations¶

Metro supports user-defined annotations for common annotations. This means that a user doesn’t necessarily have to use Metro’s annotations if they’re introducing it to an existing codebase. Support varies depending on the annotation’s use case.

Compile-only annotations are mostly supported. This includes the following:

@AssistedFactory
@AssistedInject
@Assisted
Includes Dagger’s @Assisted.value custom identifiers. While Metro’s native @Assisted uses parameter names for matching, Dagger’s explicit value identifiers are fully supported when using Dagger’s annotations.
@BindsInstance
@Binds
@ContributesBinding
@ContributesTo
@DependencyGraph.Factory
@DependencyGraph
@ElementsIntoSet
@Inject
@IntoMap
@IntoSet
@MapKey
@Module
@Multibinds
@Provides
@Qualifier
@Scope

These are configurable via Metro’s Gradle extension.

metro {
  interop {
    assisted.add("dagger/assisted/Assisted")
  }
}

For Dagger and KI specifically, there are convenience helper functions.

metro {
  interop {
    // Dagger
    includeDagger()
    includeAnvilForDagger()

    // kotlin-inject
    includeKotlinInject()
    includeAnvilForKotlinInject()

    // Guice
    includeGuice()
  }
}

Warning

Dagger’s special-case @Reusable and @LazyClassKey annotations are not supported in Metro.

@DependencyGraph is replaceable but your mileage may vary if you use Anvil or modules, since Metro’s annotation unifies Anvil’s @MergeComponent functionality and doesn’t support modules.

Similarly, @ContributesBinding is replaceable but there are not direct analogues for Anvil’s @ContributesMultibinding or kotlin-inject-anvil’s @ContributesBinding(multibinding = …) as these annotations are implemented as @ContributesInto* annotations in Metro.

binding in Metro uses a more flexible mechanism to support generics, but interop with Anvil’s boundType: KClass<*> property is supported.

Components¶

Metro graphs can interop with components generated by Dagger and Kotlin-Inject. These work exclusively through their public accessors and can be depended on like any other graph dependency.

@DependencyGraph
interface MetroGraph {
  val message: String

  @DependencyGraph.Factory
  fun interface Factory {
    fun create(
      @Includes daggerComponent: DaggerComponent
    ): MetroGraph
  }
}

@dagger.Component
interface DaggerComponent {
  val message: String

  @dagger.Component.Factory
  fun interface Factory {
    fun create(@Provides message: String): DaggerComponent
  }
}

Conversely, kotlin-inject and Dagger components can also depend on Metro graphs.

@DependencyGraph
interface MessageGraph {
  val message: String

  // ...
}

// Dagger
@Component(dependencies = [MessageGraph::class])
interface DaggerComponent {
  val message: String

  @Component.Factory
  fun interface Factory {
    fun create(messageGraph: MessageGraph): DaggerComponent
  }
}

// kotlin-inject
@Component
abstract class KotlinInjectComponent(
  @Component val messageGraph: MessageGraph
) {
  abstract val message: String
}

Runtime¶

Dagger¶

Enabling dagger interop also enables more advanced runtime interop with Dagger/Javax/Jakarta’s Provider/Lazy types.

metro {
  interop {
    includeDagger()
  }
}

This specifically enables three features.

Interop with Dagger/Javax/Jakarta’s Provider and Lazy runtime intrinsics.
Interop with generated Dagger factories for constructor-injected classes, assisted-injected classes, member-injected classes, and Dagger modules. This means that Metro can natively reuse an upstream class or module that was processed with the dagger compiler (or Anvil, if using its factory generation) and has a generated factory/injector class.
Interop with Dagger’s @BindsOptionalOf annotation.

Note the companion Gradle plugin automatically adds an extra dev.zacsweers.metro:interop-dagger runtime dependency to support this interop. If you only want annotation interop, just replace the annotations only.

`Class`/`KClass` map key interop¶

A special opt-in form of interop exists for java.lang.Class and kotlin.reflect.KClass on JVM/android compilations. While these types are not intrinsics of each other in regular code, they are in annotations and are often used in Map multibindings. Metro can support these if you enable the enableKClassToClassMapKeyInterop option. When enabled, java.lang.Class and kotlin.reflect.KClass are treated as interchangeable in map key types, matching Kotlin’s own annotation compilation behavior. This only applies to map keys because these are the only scenario where annotation arguments are materialized into non-annotation code (i.e. @ClassKey(Foo::class) -> Map<Class<*>, V>).

This is disabled by default (even if other framework interops like includeDagger are enabled) because this is purely for annotations interop and potentially comes at some runtime overhead cost to interop since KClass types are still used under the hood and must be mapped in some cases. It’s recommended to migrate these to KClass and call .java where necessary if possible.

Guice¶

Enabling Guice interop enables annotation interop with the following Guice annotations:

@Inject (but not @Inject.optional)
@Provides
@Assisted
Includes Guice’s @Assisted.value custom identifiers. While Metro’s native @Assisted uses parameter names for matching, Guice’s explicit value identifiers are fully supported when using Guice’s annotations.
@AssistedInject
@BindingAnnotation
@ScopeAnnotation
@MapKey
@ProvidesIntoMap
@ProvidesIntoSet

Enabling this also enables runtime interop with:

Guice’s Provider type. This means that you can use Guice’s Provider type interchangeably with Metro’s Provider type.
Jakarta’s Provider type.
Guice modules
- Only @Provides declarations are supported. configure implementations (including anything that would go in them) are not.

metro {
  interop {
    includeGuice()
  }
}

Note the companion Gradle plugin automatically adds an extra dev.zacsweers.metro:interop-guice runtime dependency to support this interop.

Why not javax.inject?

Guice dropped support for javax.inject in 7.0.0.

Diagnostics¶

When interoping with annotations that are written in Kotlin and have parameters, it may be unsafe to rely on positional arguments. Metro’s own annotations often have the same indices, but not always! If you want to be super safe, you can enable the interopAnnotationsNamedArgSeverity to WARN or ERROR to report diagnostics for positional arguments in any custom annotations that Metro is configured to look at.

Why only Kotlin annotations?

This is because the Kotlin compiler doesn’t support positional arguments for annotations that are written in Java.