Repository files navigation

"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 withDaggereasier by automatically merging Dagger modules and component interfaces. In a nutshell, instead ofmanually adding modules to a Dagger component and making the Dagger component extend all componentinterfaces, these modules and interfaces can be included in a component automatically:

@Module@ContributesTo(AppScope::class)classDaggerModule {.. }@ContributesTo(AppScope::class)interfaceComponentInterface {fungetSomething():SomethingfuninjectActivity(activity:MyActivity)}// The real Dagger component.@MergeComponent(AppScope::class)interfaceAppComponent

The generatedAppComponent interface that Dagger sees looks like this:

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

Notice thatAppComponent automatically includesDaggerModule and extendsComponentInterface.

The plugin consists of a Gradle plugin and Kotlin compiler plugin. The Gradle plugin automaticallyadds the Kotlin compiler plugin and annotation dependencies. It needs to be applied in all modulesthat 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}"  }}applyplugin:'com.squareup.anvil'

There are three important annotations to work with Anvil.

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

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

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

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

abstractclassAppScope private constructor()

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

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

@Singleton@MergeComponent(AppScope::class)interfaceAppComponent

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

interfaceAuthenticatorclassRealAuthenticator @Inject constructor() : Authenticator@Module@ContributesTo(AppScope::class)abstractclassAuthenticatorModule {  @BindsabstractfunbindRealAuthenticator(authenticator:RealAuthenticator):Authenticator}

This is a lot of boilerplate if you always want to useRealAuthenticator when injectingAuthenticator. You can replace this entire Dagger module with the@ContributesBindingannotation. The equivalent would be:

interfaceAuthenticator@ContributesBinding(AppScope::class)classRealAuthenticator @Inject constructor() : Authenticator

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

@ContributesBinding(AppScope::class)@Named("Prod")classRealAuthenticator @Inject constructor() : Authenticator// Will generate:@Binds @Named("Prod")abstractfunbindRealAuthenticator(authenticator:RealAuthenticator):Authenticator

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

@ContributesMultibinding(AppScope::class)@Named("Prod")classMainListener @Inject constructor() : Listener// Will generate this binding method.@Binds @IntoSet @Named("Prod")abstractfunbindMainListener(listener:MainListener):Listener

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

@MapKeyannotationclassBindingKey(valvalue:String)@ContributesMultibinding(AppScope::class)@BindingKey("abc")classMainListener @Inject constructor() : Listener// Will generate this binding method.@Binds @IntoMap @BindingKey("abc")abstractfunbindMainListener(listener:MainListener):Listener

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 providedifferent bindings for instrumentation tests, e.g.

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

The compiler plugin will find both classes on the classpath. Adding both modulesDevelopmentApplicationModule andDevelopmentApplicationTestModule to the Dagger graph wouldlead to duplicate bindings. Anvil sees that the test module wants to replace the other andignores it. This replacement rule has a global effect for all applications which are including theclasses on the classpath.

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

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

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. Theexclusion rule does what it implies. In this specific exampleDaggerModule wishes to becontributed to this scope, but it has been excluded for this component and thus is not added.

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

anvil {  generateDaggerFactories=true// default is false}

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

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. SinceAnvil only processes Kotlin code, you shouldn't enable it in modules with mixed Kotlin / Javasources either.

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

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

Adding Dagger modules to components in a large modularized codebase with many application targetsis overhead. You need to know where components are defined when creating a new Dagger module andwhich modules to add when setting up a new application. This task involves many syncs in the IDEafter 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 testthe build.

Aligning the build graph and Dagger's dependency graph brings a lot of consistency. If code is onthe 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 moduleis clear without looking at any binding.

With Anvil you don't need any composite Dagger module anymore, which only purpose is tocombine multiple modules to avoid repeating the setup for multiple applications. Composite moduleseasily become hairballs. If one application wants to exclude a module, then it has to repeat thesetup. These forked graphs are painful and confusing. With Dagger you want to make the decisionwhich modules fulfill dependencies as late as possible, ideally in the application module.Anvil makes this approach a lot easier by generating the code for included modules. Compositemodules are redundant. You make the decision which bindings to use by importing the desired modulein the application module.

Anvil is a convenience tool. Similar to Dagger it doesn't improve build speed compared towriting all code manually before running a build. The savings are in developer time.

The median overhead of Anvil is around 4%, which often means only a few hundred millisecondson top. The overhead is marginal, because Kotlin code is still compiled incrementally and Kotlincompile tasks are skipped entirely, if nothing has changed. This doesn't change with Anvil.

On top of that, Anvil provides actual build time improvements by replacing the Dagger annotationprocessor in many modules if you enableDagger Factory generation.

We investigated whether other alternatives like a bytecode transformer and an annotation processorwould be a better option, but ultimately decided against them. For what we tried to achieve abytecode transformer runs too late in the build process; after the Dagger components have beengenerated. An annotation processor especially when using KAPT would be too slow. Even though theKotlin compiler plugin API isn't stable and contains bugs we decided to write a compiler plugin.

Anvil is a Kotlin compiler plugin, thus Java isn’t supported. You can use Anvil inmodules with mixed Java and Kotlin code for Kotlin classes, though.

KAPT has the option tocorrect non-existent types.This option however changes order of how compiler plugins and KAPT itself are invoked. The resultis that Anvil cannot merge supertypes before the Dagger annotation processor runs and abstractfunctions won't be implemented properly in the final Dagger component.

Anvil will automatically setcorrectErrorTypes to false to avoid this issue.

Anvil merges Dagger component interfaces and Dagger modules during the stub generating taskwhen@MergeComponent is used. This requires scanning the compile classpath for any contributions.Assume the scenario that a contributed type in a module dependency has changed, but the moduleusing@MergeComponent itself didn't change. With Kotlin incremental compilation enabled thecompiler will notice that the module using@MergeComponent doesn't need to be recompiled andtherefore doesn't invoke compiler plugins. Anvil will miss the new contributed type from the moduledependency.

To avoid this issue, Anvil must disable incremental compilation for the stub generating task, whichruns right before Dagger processes annotations. Normal Kotlin compilation isn't impacted by thisworkaround. The issue is captured inKT-54850 Provide mechanism for compiler plugins to add custom information into binaries.

Disabling incremental compilation for the stub generating task could have a negative impact oncompile times, if you heavily rely on KAPT. While Anvil cansignificantly help to improve build times, the wrong configurationand using KAPT in most modules could make things worse. Thesuggestion is to extract and isolate annotation processors in separate modules and avoid using Anvilin the same modules, e.g. a common practice is to move the Dagger component using@MergeComponentinto the final application module with little to no other code in the app module.

Hilt is Google's opinionated guide how to dependency injection onAndroid. It provides a similar feature with@InstallIn for entry points and modules as Anvil.If you use Hilt, then you don't need to use Anvil.

Hilt includes many other features and comes with some restrictions. For us it was infeasible tomigrate a codebase to Hilt with thousands of modules and many Dagger components while we onlyneeded the feature to merge modules and component interfaces automatically. We also restrict theusage of the Dagger annotation processor to onlyspecific modulesfor performance reasons. With Hilt we wouldn't be able to enforce this requirement anymore forcomponent interfaces. The development of Anvil started long before Hilt was announced and theinternal version is being used in production for a while.

Copyright 2020 Square, Inc.Licensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License at   http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.