Anvil
"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.
anvil {
generateDaggerFactories = true // default is false
}
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 you don't need any composite Dagger module anymore, which only purpose is to combine multiple modules to avoid repeating the setup for multiple applications. Composite modules easily become hairballs. If one application wants to exclude a module, then it has to repeat the setup. These forked graphs are painful and confusing. With Dagger you want to make the decision which 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. Composite modules are redundant. You make the decision which bindings to use by importing the desired module in the application module.
Performance
Anvil is a convenience tool. Similar to Dagger it doesn't improve build speed compared to writing 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 milliseconds on top. The overhead is marginal, because Kotlin code is still compiled incrementally and Kotlin compile 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 annotation processor in many modules if you enable Dagger Factory generation.
Kotlin compiler plugin
We investigated whether other alternatives like a bytecode transformer and an annotation processor would be a better option, but ultimately decided against them. For what we tried to achieve a bytecode transformer runs too late in the build process; after the Dagger components have been generated. An annotation processor especially when using Kapt would be too slow. Even though the Kotlin compiler plugin API isn't stable and contains bugs we decided to write a compiler plugin.
Limitations
No Java support
Anvil is a Kotlin compiler plugin, thus Java isn’t supported. You can use Anvil in modules with mixed Java and Kotlin code for Kotlin classes, though.
Incremental Kotlin compilation breaks compiler plugins
There are two bugs that affect the Anvil Kotlin compiler plugin:
The Gradle plugin implements workarounds for these bugs, so you shouldn't notice them. Side effects
are that incremental Kotlin compilation is disabled for stub generating tasks (which don't run a
full compilation before KAPT anyways). The flag usePreciseJavaTracking
is disabled, if the
module contains Java code.
Hilt
Hilt is Google's opinionated guide how to dependency injection on
Android. 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 to migrate a codebase to Hilt with thousands of modules and many Dagger components while we only needed the feature to merge modules and component interfaces automatically. We also restrict the usage of the Dagger annotation processor to only specific modules for performance reasons. With Hilt we wouldn't be able to enforce this requirement anymore for component interfaces. The development of Anvil started long before Hilt was announced and the internal version is being used in production for a while.
License
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.0
Unless required by applicable law or agreed to in writing, software
distributed 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 and
limitations under the License.