Merge pull request #299 from square/ralf/docs

Add documentation for `CodeGenerator`s.

Author: vRallev

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.3.0
+
+* Add option to extend Anvil with your own `CodeGenerator`, see [here](README.md#extending-anvil) and #265.
+* Use Gradle Property APIs in the Anvil extension. This is a source-breaking change (but binary-compatible) for Kotlin and .kts consumers of the Anvil Gradle plugin, see #284.
+* Upgrade Anvil to Kotlin `1.5.10`. The old legacy compiler backend is still supported and the IR backend not required yet.  
+
 ## 2.2.3 (2021-05-25)
 
 * Support the JVM and Android targets for Kotlin Multiplatform projects, see #222.

README.md

@@ -201,7 +201,48 @@ wrong imports and deeply nested dependency chains applications might need to mak
 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.
 
-## Advantages
+## 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.
+
+```groovy
+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.
+
+![Benchmark Dagger Factories](images/benchmark_dagger_factories.png?raw=true "Benchmark Dagger Factories")
+
+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](compiler-api/README.md)
+
+## 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
@@ -236,6 +277,9 @@ compile tasks are skipped entirely, if nothing has changed. This doesn't change
 
 ![Benchmark](images/benchmark.png?raw=true "Benchmark")
 
+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](#dagger-factory-generation).
+
 ## Kotlin compiler plugin
 
 We investigated whether other alternatives like a bytecode transformer and an annotation processor
@@ -276,40 +320,6 @@ for performance reasons. With Hilt we wouldn't be able to enforce this requireme
 component interfaces. The development of Anvil started long before Hilt was announced and the
 internal version is being used in production for a while.
 
-## 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.
-
-```groovy
-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.
-
-![Benchmark Dagger Factories](images/benchmark_dagger_factories.png?raw=true "Benchmark Dagger Factories")
-
-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.
-
 ## License
 
     Copyright 2020 Square, Inc.

compiler-api/README.md

@@ -0,0 +1,86 @@
+# Compiler-API
+
+Anvil is composed of several independent code generators that provide hints for the later stages
+in the build graph when all modules and components are merged together. These code generators 
+are similar to annotation processors in the way that they look for a specific annotation like 
+`@ContributesTo` and then generate necessary code. 
+
+If you see yourself repeating the same code structures and patterns for your dependency injection
+setup over and over again, then you can extend Anvil and implement your own code generator via the `CodeGenerator` interface.
+
+## Steps
+It's recommended to create your own annotation for your use case to not conflict with Anvil and
+its own annotations. The annotation needs to live in its own module separate from the code 
+generator, e.g. `:sample:annotation`.
+```kotlin
+annotation class MyAnnotation
+```
+Later you'll use this annotation to give your code generator a hint for work to perform.
+
+In the code generator module `:sample:code-generator` you need to import the `compiler-api` 
+artifact:
+```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"
+}
+```
+
+After that implement the `CodeGenerator` interface:
+```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
+      .classesAndInnerClass(module)
+      .filter { it.hasAnnotation(FqName("sample.MyAnnotation"), module) }
+      .map { clazz ->
+        // ...
+        createGeneratedFile(
+          codeGenDir = codeGenDir,
+          packageName = // ...
+          fileName = // ...
+          content = // ...
+        )
+      }
+      .toList()
+  }
+}
+```
+
+Note that the sample code generator is annotated with `@AutoService`. It's recommended to use the
+[AutoService](https://github.com/google/auto/tree/master/service) library to generate necessary 
+code for `ServiceLoader` API. Anvil uses this mechanism to load your custom code generator.
+
+You can generate as many classes and files as you wish. You can even generate code that uses Anvil
+or Dagger annotations and Anvil will process these files. The `generateCode()` function is called 
+multiple times until no code generators generate code anymore.
+
+To use your new code generator in any module you need to add the module to the Anvil classpath:
+```groovy
+plugins {
+  id 'com.squareup.anvil' version "${latest_version}"
+}
+
+dependencies {
+  anvil project(':sample:code-generator')
+  implementation project(':sample:annotation')
+}
+```
+
+## Limitations
+Anvil code generators are no replacement for Java annotation processing or Kotlin symbol processing.
+If you want to generate code independent of Anvil, then it's better to rely on an annotation 
+processor, KSP or your own Kotlin compiler plugin instead.
+
+Anvil code generators can only generate new code and not modify or remove existing code. For that
+you need to create your own compiler plugin.

gradle.properties

@@ -1,5 +1,5 @@
 GROUP=com.squareup.anvil
-VERSION_NAME=2.2.4-SNAPSHOT
+VERSION_NAME=2.3.0-SNAPSHOT
 
 POM_DESCRIPTION=A Kotlin compiler plugin to make dependency injection with Dagger 2 easier by automatically merging Dagger modules and component interfaces.
 POM_INCEPTION_YEAR=2020