Anvil

NOTE: Anvil is deprecated and will only be supported for K1 going forward, and development will end when K2 becomes a requirement. See Anvil Moves to Maintenance Mode for the full context.

"When all you have is an anvil, every problem looks like a hammer." - Abraham Maslow

Anvil is a Kotlin compiler plugin to make dependency injection with Dagger easier by automatically merging Dagger modules and component interfaces. In a nutshell, instead of manually adding modules to a Dagger component and making the Dagger component extend all component interfaces, these modules and interfaces can be included in a component automatically:

@Module
@ContributesTo(AppScope::class)
class DaggerModule { .. }

@ContributesTo(AppScope::class)
interface ComponentInterface {
  fun getSomething(): Something
  fun injectActivity(activity: MyActivity)
}

// The real Dagger component.
@MergeComponent(AppScope::class)
interface AppComponent

The generated AppComponent interface that Dagger sees looks like this:

@Component(modules = [DaggerModule::class])
interface AppComponent : ComponentInterface

Notice that AppComponent automatically includes DaggerModule and extends ComponentInterface.

Setup

The plugin consists of a Gradle plugin and Kotlin compiler plugin. The Gradle plugin automatically adds the Kotlin compiler plugin and annotation dependencies. It needs to be applied in all modules that either contribute classes to the dependency graph or merge them:

plugins {
  id 'com.squareup.anvil' version "${latest_version}"
}

Or you can use the old way to apply a plugin:

buildscript {
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath "com.squareup.anvil:gradle-plugin:${latest_version}"
  }
}

apply plugin: 'com.squareup.anvil'

Quick Start

There are three important annotations to work with Anvil.

@ContributesTo can be added to Dagger modules and component interfaces that should be included in the Dagger component. Classes with this annotation are automatically merged by the compiler plugin as long as they are on the compile classpath.

@MergeComponent is used instead of the Dagger annotation @Component. Anvil will generate the Dagger annotation and automatically include all modules and component interfaces that were contributed the same scope.

@MergeSubcomponent is similar to @MergeComponent and should be used for subcomponents instead.

Scopes

Scope classes are only markers. The class AppScope from the sample could look like this:

abstract class AppScope private constructor()

These scope classes help Anvil make a connection between the Dagger component and which Dagger modules and other component interfaces to include.

Scope classes are independent of the Dagger scopes. It's still necessary to set a scope for the Dagger component, e.g.

@Singleton
@MergeComponent(AppScope::class)
interface AppComponent

Contributed bindings

The @ContributesBinding annotation generates a Dagger binding method for an annotated class and contributes this binding method to the given scope. Imagine this example:

interface Authenticator

class RealAuthenticator @Inject constructor() : Authenticator

@Module
@ContributesTo(AppScope::class)
abstract class AuthenticatorModule {
  @Binds abstract fun bindRealAuthenticator(authenticator: RealAuthenticator): Authenticator
}

This is a lot of boilerplate if you always want to use RealAuthenticator when injecting Authenticator. You can replace this entire Dagger module with the @ContributesBinding annotation. The equivalent would be:

interface Authenticator

@ContributesBinding(AppScope::class)
class RealAuthenticator @Inject constructor() : Authenticator

@ContributesBinding also supports qualifiers. You can annotate the class with any qualifier and the generated binding method will preserve the qualifier, e.g.

@ContributesBinding(AppScope::class)
@Named("Prod")
class RealAuthenticator @Inject constructor() : Authenticator

// Will generate:
@Binds @Named("Prod") 
abstract fun bindRealAuthenticator(authenticator: RealAuthenticator): Authenticator

Contributed multibindings

Similar to contributed bindings, @ContributesMultibinding will generate a multibindings method for (all/an) annotated class(es). Qualifiers are supported the same way as normal bindings.

@ContributesMultibinding(AppScope::class)
@Named("Prod")
class MainListener @Inject constructor() : Listener

// Will generate this binding method.
@Binds @IntoSet @Named("Prod")
abstract fun bindMainListener(listener: MainListener): Listener

If the class is annotated with a map key annotation, then Anvil will generate a maps multibindings method instead of adding the element to a set:

@MapKey
annotation class BindingKey(val value: String)

@ContributesMultibinding(AppScope::class)
@BindingKey("abc")
class MainListener @Inject constructor() : Listener

// Will generate this binding method.
@Binds @IntoMap @BindingKey("abc")
abstract fun bindMainListener(listener: MainListener): Listener

Exclusions

Dagger modules and component interfaces can be excluded in two different levels.

One class can always replace another one. This is especially helpful for modules that provide different bindings for instrumentation tests, e.g.

@Module
@ContributesTo(
    scope = AppScope::class,
    replaces = [DevelopmentApplicationModule::class]
)
object DevelopmentApplicationTestModule {
  @Provides
  fun provideEndpointSelector(): EndpointSelector = TestingEndpointSelector
}

The compiler plugin will find both classes on the classpath. Adding both modules DevelopmentApplicationModule and DevelopmentApplicationTestModule to the Dagger graph would lead to duplicate bindings. Anvil sees that the test module wants to replace the other and ignores it. This replacement rule has a global effect for all applications which are including the classes on the classpath.

Applications can exclude Dagger modules and component interfaces individually without affecting other applications.

@MergeComponent(
  scope = AppScope::class,
  exclude = [
    DaggerModule::class
  ]
)
interface AppComponent

In a perfect build graph it’s unlikely that this feature is needed. However, due to legacy modules, wrong imports and deeply nested dependency chains applications might need to make use of it. The exclusion rule does what it implies. In this specific example DaggerModule wishes to be contributed to this scope, but it has been excluded for this component and thus is not added.

Dagger Factory Generation

Anvil allows you to generate Factory classes that usually the Dagger annotation processor would generate for @Provides methods, @Inject constructors and @Inject fields. The benefit of this feature is that you don't need to enable the Dagger annotation processor in this module. That often means you can skip KAPT and the stub generating task. In addition Anvil generates Kotlin instead of Java code, which allows Gradle to skip the Java compilation task. The result is faster builds.

<details open> <summary>Gradle DSL</summary>

// build.gradle
anvil {
  generateDaggerFactories = true // default is false
}

</details> <details> <summary>Gradle Properties</summary>

# gradle.properties
com.squareup.anvil.generateDaggerFactories=true # default is false

</details>

In our codebase we measured that modules using Dagger build 65% faster with this new Anvil feature compared to using the Dagger annotation processor:

|| Stub generation | Kapt | Javac | Kotlinc | Sum :--- | ---: | ---: | ---: | ---: | ---: Dagger | 12.976 | 40.377 | 8.571 | 10.241 | 72.165 Anvil | 0 | 0 | 6.965 | 17.748 | 24.713

For full builds of applications we measured savings of 16% on average.

This feature can only be enabled in Gradle modules that don't compile any Dagger component. Since Anvil only processes Kotlin code, you shouldn't enable it in modules with mixed Kotlin / Java sources either.

When you enable this feature, don't forget to remove the Dagger annotation processor. You should keep all other dependencies.

Extending Anvil

Every codebase has its own dependency injection patterns where certain code structures need to be repeated over and over again. Here Anvil comes to the rescue and you can extend the compiler plugin with your own CodeGenerator. For usage please take a look at the compiler-api artifact

Advantages of Anvil

Adding Dagger modules to components in a large modularized codebase with many application targets is overhead. You need to know where components are defined when creating a new Dagger module and which modules to add when setting up a new application. This task involves many syncs in the IDE after adding new module dependencies in the build graph. The process is tedious and cumbersome. With Anvil you only add a dependency in your build graph and then you can immediately test the build.

Aligning the build graph and Dagger's dependency graph brings a lot of consistency. If code is on the compile classpath, then it's also included in the Dagger dependency graph.

Modules implicitly have a scope, if provided objects are tied to a scope. Now the scope of a module is clear without looking at any binding.

With Anvil