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
@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()
  }
}

@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.

Guice¶

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

@Inject (but not @Inject.optional)
@Provides
@Assisted
@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.