Anvil

https://github.com/square/anvil
Admin
Anvil is a Kotlin compiler plugin that simplifies dependency injection with Dagger by automatically...
Tokens:3,579
Snippets:38
Trust Score:-
License:Apache-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install to Maven Local (Gradle)

Source: https://github.com/square/anvil/blob/main/RELEASING.md

Executes the Gradle publishToMavenLocal task to build and install the project's artifacts into the local Maven repository for testing or local use.

```shell
./gradlew publishToMavenLocal
```

--------------------------------

### Generated Dagger Component Interface - Kotlin

Source: https://github.com/square/anvil/blob/main/README.md

Illustrates the Dagger component interface that Anvil generates based on the `@MergeComponent` and `@ContributesTo` annotations. It shows how Anvil automatically adds the contributed modules and extends the contributed interfaces, simplifying the final Dagger setup.

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

--------------------------------

### Defining an Anvil Scope Marker Class - Kotlin

Source: https://github.com/square/anvil/blob/main/README.md

Provides an example of a simple Kotlin class used as a scope marker for Anvil annotations like `@ContributesTo` and `@MergeComponent`. These classes are purely markers and do not require any special implementation logic.

```kotlin
abstract class AppScope private constructor()
```

--------------------------------

### Defining Anvil Components and Contributions - Kotlin

Source: https://github.com/square/anvil/blob/main/README.md

Shows how to use Anvil's `@ContributesTo` annotation on Dagger modules and interfaces, and `@MergeComponent` on the main component interface. This setup allows Anvil to automatically include the contributed elements in the merged component based on the specified scope.

```kotlin
@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
```

--------------------------------

### Configuring Anvil Dependencies in Gradle (Groovy)

Source: https://github.com/square/anvil/blob/main/docs/INTERNALS.md

Example showing how to add Anvil code generator and annotation dependencies to a Gradle project using the Groovy DSL. This configuration is typically placed within the `dependencies` block of a module's `build.gradle` file.

```Groovy
dependencies {
  anvil project(':sample:code-generator')
  implementation project(':sample:annotation')
}
```

--------------------------------

### Modifying Interface with @MergeComponent (Kotlin)

Source: https://github.com/square/anvil/blob/main/docs/INTERNALS.md

This Kotlin example illustrates how Anvil processes an interface annotated with `@MergeComponent`. In the compiler backend, Anvil adds the Dagger `@Component` annotation, includes necessary modules, and adds contributed component interfaces as supertypes, effectively merging contributions into the target interface.

```kotlin
@MergeComponent(Scope::class)
interface MyComponent
```

```kotlin
@MergeComponent(Scope::class)
@Component(modules = [ContributedModule::class])
interface MyComponent : ContributedComponentInterface
```

--------------------------------

### Enabling Dagger Factory Generation (Gradle Properties)

Source: https://github.com/square/anvil/blob/main/README.md

Shows how to enable Anvil's Dagger factory generation feature globally or per-project using the gradle.properties file. This provides an alternative way to configure the feature compared to the Groovy DSL.

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

--------------------------------

### Applying Anvil Gradle Plugin (apply plugin) - Groovy

Source: https://github.com/square/anvil/blob/main/README.md

Shows the older method for applying the Anvil Gradle plugin in a `build.gradle` file using the `buildscript` block and `apply plugin`. This is an alternative way to include the plugin in your project.

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

apply plugin: 'com.squareup.anvil'
```

--------------------------------

### Applying Anvil Gradle Plugin (plugins block) - Groovy

Source: https://github.com/square/anvil/blob/main/README.md

Demonstrates the modern way to apply the Anvil Gradle plugin in a `build.gradle` file using the `plugins` block. This plugin must be applied in all modules that either contribute classes to the dependency graph or merge them.

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

--------------------------------

### Enabling Dagger Factory Generation (Gradle Groovy)

Source: https://github.com/square/anvil/blob/main/README.md

Shows how to enable Anvil's Dagger factory generation feature in a Gradle module's build.gradle file using the Groovy DSL. This feature can significantly speed up builds by replacing the Dagger annotation processor.

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

--------------------------------

### Declaring Project Dependencies - Build Configuration

Source: https://github.com/square/anvil/blob/main/annotations-optional/dependencies/runtimeClasspath.txt

These lines declare external library dependencies for the project build. Each line specifies a dependency using the format 'groupId:artifactId:version'.

```Build Configuration
javax.inject:javax.inject:1
org.jetbrains.kotlin:kotlin-stdlib:2.0.21
org.jetbrains:annotations:13.0
```

--------------------------------

### Using Anvil @ContributesBinding - Kotlin

Source: https://github.com/square/anvil/blob/main/README.md

Shows how the `@ContributesBinding` annotation can replace the boilerplate of a traditional `@Binds` Dagger module. By annotating the implementation class (`RealAuthenticator`) with `@ContributesBinding` and a scope, Anvil automatically generates the necessary binding method.

```kotlin
interface Authenticator

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

--------------------------------

### Manually Publish Release (Gradle)

Source: https://github.com/square/anvil/blob/main/RELEASING.md

Executes the Gradle publish task to manually upload a release artifact. Includes options to disable daemon, parallel execution, and build cache for a clean build.

```shell
./gradlew clean publish --no-daemon --no-parallel --no-build-cache
```

--------------------------------

### Using @ContributesBinding in Kotlin

Source: https://github.com/square/anvil/blob/main/CHANGELOG.md

Demonstrates how to use the new @ContributesBinding annotation to automatically generate Dagger binding methods without writing a full Dagger module. It shows the interface, the annotated implementation, and the equivalent generated Dagger module.

```Kotlin
interface Authenticator

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

// The generated and automatically included Dagger module would look similar like this:
@Module
@ContributesTo(AppScope::class)
abstract class AuthenticatorModule {
  @Binds abstract fun bindRealAuthenticator(authenticator: RealAuthenticator): Authenticator
}
```

--------------------------------

### Push Commits and Tags (Production)

Source: https://github.com/square/anvil/blob/main/RELEASING.md

Pushes the committed changes and the newly created tags to the remote repository, initiating the automated release process via GitHub Actions.

```shell
git push && git push --tags
```

--------------------------------

### Using @ContributesBinding with Qualifiers - Kotlin

Source: https://github.com/square/anvil/blob/main/README.md

Demonstrates how to use Dagger qualifiers, such as `@Named`, in conjunction with the `@ContributesBinding` annotation. Anvil will include the qualifier on the automatically generated binding method, preserving the binding's specificity.

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

--------------------------------

### Contributing Map Multibinding with MapKey (Kotlin)

Source: https://github.com/square/anvil/blob/main/README.md

Shows how to contribute a class to a Dagger map multibinding using @ContributesMultibinding and a custom @MapKey annotation. Anvil generates the corresponding @Binds @IntoMap method.

```Kotlin
@MapKey
annotation class BindingKey(val value: String)

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

--------------------------------

### Add Anvil Compiler Utilities Test Fixtures Dependency (Groovy)

Source: https://github.com/square/anvil/blob/main/compiler-utils/README.md

This Groovy snippet demonstrates how to include the Anvil `compiler-utils` test fixtures artifact as a test dependency in a build script (e.g., Gradle). These fixtures provide utilities for easier end-to-end testing of `CodeGenerator`s.

```Groovy
testImplementation testFixtures('com.squareup.anvil:compiler-utils:VERSION')
```

--------------------------------

### Replacing Modules with ContributesTo (Kotlin)

Source: https://github.com/square/anvil/blob/main/README.md

Illustrates how to use the replaces parameter in @ContributesTo to indicate that a module should replace another module within a specific scope. This is useful for providing alternative bindings, such as for testing.

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

--------------------------------

### Traditional Dagger @Binds Module - Kotlin

Source: https://github.com/square/anvil/blob/main/README.md

Illustrates the standard Dagger pattern for binding an interface (`Authenticator`) to a concrete implementation (`RealAuthenticator`) using an abstract `@Module` and an `@Binds` method. This is the boilerplate that Anvil's `@ContributesBinding` annotation aims to simplify.

```kotlin
interface Authenticator

class RealAuthenticator @Inject constructor() : Authenticator

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

--------------------------------

### Commit Next Development Version (Production)

Source: https://github.com/square/anvil/blob/main/RELEASING.md

Commits the version update that includes the -SNAPSHOT suffix, preparing the repository for ongoing development after a production release.

```shell
git commit -am "Prepare next development version."
```

--------------------------------

### Contributing Set Multibinding with Qualifier (Kotlin)

Source: https://github.com/square/anvil/blob/main/README.md

Demonstrates how to contribute a class to a Dagger set multibinding within a specific scope using @ContributesMultibinding and apply a qualifier using @Named. Anvil automatically generates the necessary @Binds @IntoSet method.

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

--------------------------------

### Combining Dagger and Anvil Scopes - Kotlin

Source: https://github.com/square/anvil/blob/main/README.md

Demonstrates how to apply both a Dagger scope (e.g., `@Singleton`) and an Anvil scope (`@MergeComponent`) to the same component interface. Anvil scopes are independent of Dagger scopes and serve to group contributed elements.

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

--------------------------------

### Running Gradle Build for Anvil Debugging - Shell

Source: https://github.com/square/anvil/blob/main/docs/INTERNALS.md

This command executes a specific Gradle task (`assemble` for `:your:project`) with flags configured for debugging. `--no-daemon` prevents using the Gradle daemon, `-Dorg.gradle.debug=true` enables JVM debugging, and `-Pkotlin.compiler.execution.strategy=in-process` forces the Kotlin compiler to run in the same process, allowing breakpoints to be hit.

```Shell
./gradlew :your:project:assemble --no-daemon -Dorg.gradle.debug=true -Pkotlin.compiler.execution.strategy=in-process
```

--------------------------------

### Commit Version Update and Tag Release (Production)

Source: https://github.com/square/anvil/blob/main/RELEASING.md

Commits the changes made for a production release, including the version update, and creates a Git tag for the release version.

```shell
git commit -am "Releasing v0.1.0."
git tag v1.0.0
```

--------------------------------

### Generated @Binds Method with Qualifier - Kotlin

Source: https://github.com/square/anvil/blob/main/README.md

Illustrates the Dagger `@Binds` method that Anvil generates when `@ContributesBinding` is used on a class annotated with a qualifier like `@Named`. The generated method includes the qualifier, matching the behavior of a manually written `@Binds` method.

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

--------------------------------

### Enable Incremental Compilation via Gradle DSL (Groovy)

Source: https://github.com/square/anvil/blob/main/CHANGELOG.md

This snippet demonstrates how to enable Anvil's experimental incremental compilation feature using the Gradle DSL in a `build.gradle` file. Set the `trackSourceFiles` property to `true` within the `anvil` configuration block. The default value is `false`.

```groovy
// build.gradle
anvil {
  trackSourceFiles = true // default is false
}
```

--------------------------------

### Enable Incremental Compilation via Gradle Properties

Source: https://github.com/square/anvil/blob/main/CHANGELOG.md

This snippet shows how to enable Anvil's experimental incremental compilation feature by setting the `com.squareup.anvil.trackSourceFiles` property to `true` in the `gradle.properties` file. The default value for this property is `false`.

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

--------------------------------

### Generating Anvil Hint Properties (Kotlin)

Source: https://github.com/square/anvil/blob/main/docs/INTERNALS.md

This Kotlin snippet shows the structure of hint properties generated by Anvil in the `anvil.hint` package. These properties point to the contributed class (`_reference`) and its associated scopes (`_scope_X`), allowing Anvil to quickly find contributions during the merge phase without resolving the full type.

```kotlin
package anvil.hint.binding.com.squareup.anvil.test

val com_squareup_anvil_test_AppBinding_reference: KClass<AppBinding> = AppBinding::class

val com_squareup_anvil_test_AppBinding_scope_1: KClass<AppScope> = AppScope::class

val com_squareup_anvil_test_AppBinding_scope_2: KClass<AppScope> = OtherScope::class
```

--------------------------------

### Implementing Anvil CodeGenerator Interface in Kotlin

Source: https://github.com/square/anvil/blob/main/compiler-api/README.md

Implement the CodeGenerator interface to define your custom code generation logic. The generateCode function receives project files and the output directory, allowing you to create new source files based on specific criteria, such as the presence of your custom annotation. Using @AutoService is recommended for automatic discovery.

```kotlin
@AutoService(CodeGenerator::class)
class SampleCodeGenerator : CodeGenerator {
  override fun isApplicable(context: AnvilContext): Boolean = true

  override fun generateCode(
    codeGenDir: File,
    module: ModuleDescriptor,
    projectFiles: Collection<KtFile>
  ): Collection<GeneratedFile> {
    return projectFiles
      .classAndInnerClassReferences(module)
      .filter { it.isAnnotatedWith(FqName("sample.MyAnnotation")) }
      .map { clazz ->
        // ...
        createGeneratedFile(
          codeGenDir = codeGenDir,
          packageName = // ...
          fileName = // ...
          content = // ...
        )
      }
      .toList()
  }
}
```

--------------------------------

### Disabling Anvil Source File Tracking via Gradle DSL

Source: https://github.com/square/anvil/blob/main/README.md

This snippet demonstrates how to disable Anvil's source file tracking feature using the Gradle DSL within a `build.gradle` file. Configuring the `anvil` block and setting `trackSourceFiles` to `false` achieves the same result as the Gradle property. This provides an alternative configuration method.

```Groovy
// build.gradle
anvil {
  trackSourceFiles = false // default is true
}
```

--------------------------------

### Excluding Modules/Components with MergeComponent (Kotlin)

Source: https://github.com/square/anvil/blob/main/README.md

Demonstrates how to explicitly exclude a Dagger module or component interface from being merged into a component using the exclude parameter in @MergeComponent. This provides fine-grained control over the component's contents.

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

--------------------------------

### Disabling Anvil Source File Tracking via Gradle Properties

Source: https://github.com/square/anvil/blob/main/README.md

This snippet shows how to disable Anvil's source file tracking feature using a Gradle property in the `gradle.properties` file. Setting `com.squareup.anvil.trackSourceFiles` to `false` overrides the default behavior. This is relevant for managing incremental compilation behavior.

```Properties
# gradle.properties
com.squareup.anvil.trackSourceFiles=false # default is true
```

--------------------------------

### Killing Java Processes for Debugging - Shell

Source: https://github.com/square/anvil/blob/main/docs/INTERNALS.md

This command is used to terminate all running Java processes, including Kotlin and Gradle daemons, which is a necessary step before debugging Anvil in-process with Gradle. It ensures a clean state for the build execution.

```Shell
killall -9 java
```

--------------------------------

### Configuring Anvil Plugin with Custom Code Generator in Groovy

Source: https://github.com/square/anvil/blob/main/compiler-api/README.md

Apply the Anvil plugin in the module where you want to use the custom code generator. Add the code generator module to the 'anvil' configuration and the annotation module to the 'implementation' configuration.

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

dependencies {
  anvil project(':sample:code-generator')
  implementation project(':sample:annotation')
}
```

--------------------------------

### Defining Custom Annotation for Anvil Code Generator

Source: https://github.com/square/anvil/blob/main/compiler-api/README.md

Define a custom annotation in a separate module to serve as a marker for the Anvil code generator. This avoids conflicts with Anvil's built-in annotations and provides a clear hint for the generator.

```kotlin
annotation class MyAnnotation
```

--------------------------------

### Adding Compiler API Dependency in Groovy

Source: https://github.com/square/anvil/blob/main/compiler-api/README.md

Include the Anvil compiler-api artifact in your code generator module's build script dependencies. Optionally, add AutoService dependencies for automatic registration via ServiceLoader.

```groovy
dependencies {
  api "com.squareup.anvil:compiler-api:${latest_version}"

  // Optional:
  compileOnly "com.google.auto.service:auto-service-annotations:1.0"
  kapt "com.google.auto.service:auto-service:1.0"
}
```

--------------------------------

### Adding Custom Anvil Code Generator Dependency - Groovy

Source: https://github.com/square/anvil/blob/main/docs/INTERNALS.md

This Groovy snippet demonstrates how to add a custom Anvil code generator module as a dependency in a build script. Adding a module this way makes its CodeGenerator implementations discoverable by Anvil via Java's ServiceLoader API, allowing them to participate in the frontend code generation process.

```groovy
dependencies {
  anvil project(':sample:code-generator')
}
```
Tokens:
Raw