Crash Course in Building Gradle Plugins

A Gradle plugin is something that we use every day, but have you ever considered how they're created? What's behind the magic of the Kotlin DSLs provided by the plugins we use daily?

In this talk, we'll try to uncover the magic behind the Gradle plugin APIs and how to use them to build your own plugin. We'll explore the process of developing, debugging, testing, and finally publishing your grade plugin just like any other piece of software.

By the end of this, you'll learn how you can turn that custom Gradle task you've been copying and pasting across projects into a fully-fledged Gradle plugin!

Transcript

1. Crash Course Building Gradle Plugins @iurysza iurysouza.dev
2. • Senior Engineer @ Klarna • Currently building a browser • Working with android since 2016 @iurysza iurysouza.dev About me
3. 〉Section Title What is this about?
4. 〉Section Title What is this about? A quick starter guide on how to approach building gradle plugins.
5. 〉Section Title What is this NOT about?
6. 〉Section Title What is this NOT about? An exhaustive Gradle API tutorial.
7. *record scratch* *freeze frame* "Yup, that's me. You're probably wondering how I ended up in this situation…" Background Story
8. Another project, another task copy/paste Background Story
9. A plugin is born Background Story
10. A plugin is born Background Story
11. 〉Gradle Plugins Overview Gradle Plugin Overview
12. What It’s an add-on for your build, which you can apply using the Gradle plugin DSL
13. plugins { id("com.android.application") } For example, we have the android application plugin What
14. How
15. How There's basically two ways to do this
16. Performing some behavior when the plugin is applied How
17. For example, the android plugin configures the main, test and androidTest source sets. How
18. Build tasks ----------- assemble - Assemble main outputs for all the variants. build - Assembles and tests this project. clean - Deletes the build directory. Exposing tasks that allow you to run some specific action How
19. 〉Getting started The Gradle Plugin Puzzle
20. 〉Getting started
21. 〉Getting started
22. 〉Getting started
23. 〉Getting started Implementation Testing Publishing Consuming Running Setup
24. 〉Getting started Implementation Testing Publishing Consuming Running Setup
25. What do you need to do to configure a gradle plugin project. Setup
26. The project's folder structure Setup
27. $ tree ├── build.gradle.kts ├── gradle │ └── wrapper │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradle.properties ├── gradlew ├── gradlew.bat ├── myplugin │ ├── build.gradle.kts │ └── src │ ├── main │ │ └── kotlin │ │ └── dev │ │ └── iurysouza │ │ └── myplugin │ └── test │ └── kotlin │ └── dev │ └── iurysouza │ └── myplugin └── settings.gradle.kts The project's folder structure Setup
28. $ tree ├── build.gradle.kts ├── gradle │ └── wrapper │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradle.properties ├── gradlew ├── gradlew.bat ├── myplugin │ ├── build.gradle.kts │ └── src │ ├── main │ │ └── kotlin │ │ └── dev │ │ └── iurysouza │ │ └── myplugin │ └── test │ └── kotlin │ └── dev │ └── iurysouza │ └── myplugin └── settings.gradle.kts Pretty standard Setup
29. $ tree ├── build.gradle.kts ├── gradle │ └── wrapper │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradle.properties ├── gradlew ├── gradlew.bat ├── myplugin │ ├── build.gradle.kts │ └── src │ ├── main │ │ └── kotlin │ │ └── dev │ │ └── iurysouza │ │ └── myplugin │ └── test │ └── kotlin │ └── dev │ └── iurysouza │ └── myplugin └── settings.gradle.kts Pretty standard Setup
30. $ tree ├── build.gradle.kts ├── gradle │ └── wrapper │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradle.properties ├── gradlew ├── gradlew.bat ├── app │ ├── build.gradle.kts │ └── src │ ├── main │ │ └── kotlin │ │ └── dev │ │ └── iurysouza │ │ └── app │ └── test │ └── kotlin │ └── dev │ └── iurysouza │ └── app └── settings.gradle.kts Pretty standard Setup
31. 〉myplugin 〉build.gradle.kts Build configuration Setup
32. plugins { kotlin("jvm") `java-gradle-plugin` } dependencies { implementation(kotlin("stdlib")) implementation(gradleApi()) } Build configuration Setup
33. plugins { kotlin("jvm") `java-gradle-plugin` } dependencies { implementation(kotlin("stdlib")) implementation(gradleApi()) } A plugin for building plugins Setup
34. plugins { kotlin("jvm") `java-gradle-plugin` } dependencies { implementation(kotlin("stdlib")) implementation(gradleApi()) } A plugin for building plugins Setup
35. plugins { kotlin("jvm") `java-gradle-plugin` } dependencies { implementation(kotlin("stdlib")) implementation(gradleApi()) } A plugin for building plugins Setup
36. gradlePlugin { plugins { create("myplugin") { id = "dev.iurysouza.myplugin" implementationClass = "dev.iurysouza.myplugin.MyPlugin" version = "0.0.1" description = "My plugin description" displayName = "My plugin name" } } } Defining the plugin Setup
37. gradlePlugin { plugins { create("myplugin") { id = "dev.iurysouza.myplugin" implementationClass = "dev.iurysouza.myplugin.MyPlugin" version = "0.0.1" description = "My plugin description" displayName = "My plugin name" } } } Defining the plugin Setup
38. 〉Getting started Implementation Testing Publishing Consuming Running Setup
39. Implementation
40. The basic building blocks Implementation
41. The basic building blocks Implementation
42. The Extension Class is a glorified data object. It helps us pass in configuration to the plugin. Implementation
43. import javax.inject.Inject import org.gradle.api.Project import org.gradle.api.provider.Property abstract class MyPluginExtension @Inject constructor( project: Project, ) { val shouldDoSomething: Property<Boolean> = project.objects.property(Boolean-:class.java) } Implementing an Extension Class Implementation
44. import javax.inject.Inject import org.gradle.api.Project import org.gradle.api.provider.Property abstract class MyPluginExtension @Inject constructor( project: Project, ) { val shouldDoSomething: Property<Boolean> = project.objects.property(Boolean-:class.java) } Implementing an Extension Class Implementation
45. import javax.inject.Inject import org.gradle.api.Project import org.gradle.api.provider.Property abstract class MyPluginExtension @Inject constructor( project: Project, ) { val shouldDoSomething: Property<Boolean> = project.objects.property(Boolean-:class.java) } Implementing an Extension Class Implementation
46. import javax.inject.Inject import org.gradle.api.Project import org.gradle.api.provider.Property abstract class MyPluginExtension @Inject constructor( project: Project, ) { val shouldDoSomething: Property<Boolean> = project.objects.property(Boolean-:class.java) } Implementing an Extension Class Implementation
47. import javax.inject.Inject import org.gradle.api.Project import org.gradle.api.provider.Property abstract class MyPluginExtension @Inject constructor( project: Project, ) { val shouldDoSomething: Property<Boolean> = project.objects.property(Boolean-:class.java) } Implementing an Extension Class Implementation
48. The basic building blocks Implementation
49. The basic building blocks Implementation
50. The Task encapsulates an action Implementation
51. Defining our plugin's Task Class Implementation
52. import org.gradle.api.DefaultTask import org.gradle.api.provider.Property import org.gradle.api.tasks.Input import org.gradle.api.tasks.TaskAction abstract class MyPluginTask : DefaultTask() { @get:Input abstract val shouldDoSomething: Property<Boolean> @TaskAction fun execute() { if (shouldDoSomething.get()) { println("Did something") } else { println("Did something else") } } } Defining our plugin's Task Class Implementation
53. import org.gradle.api.DefaultTask import org.gradle.api.provider.Property import org.gradle.api.tasks.Input import org.gradle.api.tasks.TaskAction abstract class MyPluginTask : DefaultTask() { @get:Input abstract val shouldDoSomething: Property<Boolean> @TaskAction fun execute() { if (shouldDoSomething.get()) { println("Did something") } else { println("Did something else") } } } Defining our plugin's Task Class Implementation
54. import org.gradle.api.DefaultTask import org.gradle.api.provider.Property import org.gradle.api.tasks.Input import org.gradle.api.tasks.TaskAction abstract class MyPluginTask : DefaultTask() { @get:Input abstract val shouldDoSomething: Property<Boolean> @TaskAction fun execute() { if (shouldDoSomething.get()) { println("Did something") } else { println("Did something else") } } } Defining our plugin's Task Class Implementation
55. import org.gradle.api.DefaultTask import org.gradle.api.provider.Property import org.gradle.api.tasks.Input import org.gradle.api.tasks.TaskAction abstract class MyPluginTask : DefaultTask() { @get:Input abstract val shouldDoSomething: Property<Boolean> @TaskAction fun execute() { if (shouldDoSomething.get()) { println("Did something") } else { println("Did something else") } } } Defining our plugin's Task Class Implementation
56. import org.gradle.api.DefaultTask import org.gradle.api.provider.Property import org.gradle.api.tasks.Input import org.gradle.api.tasks.TaskAction abstract class MyPluginTask : DefaultTask() { @get:Input abstract val shouldDoSomething: Property<Boolean> @TaskAction fun execute() { if (shouldDoSomething.get()) { println("Did something") } else { println("Did something else") } } } Defining our plugin's Task Class Implementation
57. The basic building blocks Implementation
58. The basic building blocks Implementation
59. The plugin, finally! Implementation
60. gradlePlugin { plugins { create("myplugin") { id = "dev.iurysouza.myplugin" implementationClass = "dev.iurysouza.myplugin.MyPlugin" version = "0.0.1" description = "My plugin description" displayName = "My plugin name" } } } Remember this? Implementation
61. It's our entry point. It defines what happens when we the plugin is applied. Implementation
62. import org.gradle.api.Plugin import org.gradle.api.Project class MyPlugin : Plugin<Project> { override fun apply(project: Project) { println("MyPlugin was applied!") } } Implementation Defining our Plugin Class
63. import org.gradle.api.Plugin import org.gradle.api.Project class MyPlugin : Plugin<Project> { override fun apply(project: Project) { println("MyPlugin was applied!") } } Implementation Defining our Plugin Class
64. import org.gradle.api.Plugin import org.gradle.api.Project class MyPlugin : Plugin<Project> { override fun apply(project: Project) { println("MyPlugin was applied!") } } Implementation Defining our Plugin Class
65. import org.gradle.api.Plugin import org.gradle.api.Project class MyPlugin : Plugin<Project> { override fun apply(project: Project) { println("MyPlugin was applied!") } } Implementation Defining our Plugin Class
66. import org.gradle.api.Plugin import org.gradle.api.Project class MyPlugin : Plugin<Project> { override fun apply(project: Project) { println("MyPlugin was applied!") } } Implementation Defining our Plugin Class
67. import org.gradle.api.Plugin import org.gradle.api.Project class MyPlugin : Plugin<Project> { override fun apply(project: Project) { val extension = project.extensions.create( "myPluginConfig", MyPluginExtension-:class.java, project ) project.tasks.register( "myPluginTask", MyPluginTask-:class.java ) { task -> task.shouldDoSomething.set( extension.shouldDoSomething ) } } } Implementation Putting things together
68. import org.gradle.api.Plugin import org.gradle.api.Project class MyPlugin : Plugin<Project> { override fun apply(project: Project) { val extension = project.extensions.create( "myPluginConfig", MyPluginExtension-:class.java, project ) project.tasks.register( “myPluginTask”, MyPluginTask-:class.java ) { task -> task.shouldDoSomething.set( extension.shouldDoSomething ) } } } Implementation Putting things together
69. import org.gradle.api.Plugin import org.gradle.api.Project class MyPlugin : Plugin<Project> { override fun apply(project: Project) { val extension = project.extensions.create( "myPluginConfig", MyPluginExtension-:class.java, project ) project.tasks.register( "myPluginTask", MyPluginTask-:class.java ) { task -> task.shouldDoSomething.set( extension.shouldDoSomething ) } } } Implementation Putting things together
70. 〉Getting started Implementation Testing Publishing Consuming Running Setup
71. Testing Because we're pros, right?
72. Testing A bit of setup first 〉myplugin 〉build.gradle.kts
73. Testing A bit of setup first plugins { kotlin("jvm") `java-gradle-plugin` } dependencies { implementation(kotlin("stdlib")) implementation(gradleApi()) }
74. Testing A bit of setup first plugins { kotlin("jvm") `java-gradle-plugin` } dependencies { implementation(kotlin("stdlib")) implementation(gradleApi()) testRuntimeOnly(libs.junit5Engine) testImplementation(libs.junit5Api) } tasks.test { useJUnitPlatform() }
75. Testing Just add your tests here $ tree ├── build.gradle.kts ├── gradle │ └── wrapper │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── gradle.properties ├── gradlew ├── gradlew.bat ├── myplugin │ ├── build.gradle.kts │ └── src │ │── main │ │ └── kotlin │ │ └── dev │ │ └── iurysouza │ │ └── myplugin │ └── test │ └── kotlin │ └── dev │ └── iurysouza │ └── myplugin └── settings.gradle.kts
76. Testing Gradle offers support for writing both unit and functional tests.
77. Testing Unit Tests with the ProjectBuilder org.gradle.testfixtures.ProjectBuilder
78. class MyPluginTest { @Test fun `When plugin is applied, the task is added to the build`() { val project = ProjectBuilder.builder().build() project.pluginManager.apply("myPlugin") assert(project.tasks.getByName("myPluginTask") is MyPluginTask) } } Testing Unit tests with ProjectBuilder
79. Testing Fast & lightweight. Great for sanity checks. org.gradle.testfixtures.ProjectBuilder
80. org.gradle.testkit.runner.GradleRunner Testing Functional Tests with testKit
81. plugins { kotlin("jvm") `java-gradle-plugin` } dependencies { implementation(kotlin("stdlib")) implementation(gradleApi()) testImplementation(libs.junit5Api) testRuntimeOnly(libs.junit5Engine) testImplementation(gradleTestKit()) } tasks.test { useJUnitPlatform() } Testing Setting up
82. class MyPluginFunctionalTest { @TempDir lateinit var projDir: File private lateinit var settingsFile: File private lateinit var buildFile: File @BeforeEach fun setup() { settingsFile = File(projDir, "settings.gradle.kts") buildFile = File(projDir, "build.gradle.kts") } } Testing Functional Tests with testKit
83. class MyPluginFunctionalTest { @TempDir lateinit var projDir: File private lateinit var settingsFile: File private lateinit var buildFile: File @BeforeEach fun setup() { settingsFile = File(projDir, "settings.gradle.kts") buildFile = File(projDir, "build.gradle.kts") } } Testing Functional Tests with testKit
84. class MyPluginFunctionalTest { @TempDir lateinit var projDir: File private lateinit var settingsFile: File private lateinit var buildFile: File @BeforeEach fun setup() { settingsFile = File(projDir, "settings.gradle.kts") buildFile = File(projDir, "build.gradle.kts") } } Testing Functional Tests with testKit
85. class MyPluginFunctionalTest { @BeforeEach fun setup() {...} } Testing Functional Tests with testKit
86. class MyPluginFunctionalTest { @BeforeEach fun setup() {...} } Testing Functional Tests with testKit
87. class MyPluginFunctionalTest { @BeforeEach fun setup() {--.} @Test fun `when plugin's task is ran it produces the expected output`() { settingsFile.writeText( """ rootProject.name = "example" """.trimIndent() ) buildFile.writeText( """ plugins { java id("dev.iurysouza.myplugin") } myPluginConfig { shouldDoSomething.set(true) } """.trimIndent() ) -/ Run the plugin task val buildResult: BuildResult = GradleRunner.create() .withProjectDir(testProjectDir) .withArguments("myPluginTask") .build() -/ Check if the output matches the expected result val expectedOutput = "didSomething" assertEquals(expectedOutput, buildResult.output) } } Testing Functional Tests with testKit
88. class MyPluginFunctionalTest { @BeforeEach fun setup() {--.} @Test fun `when plugin's task is ran it produces the expected output`() { settingsFile.writeText( """ rootProject.name = "example" """.trimIndent() ) buildFile.writeText( """ plugins { java id("dev.iurysouza.myplugin") } myPluginConfig { shouldDoSomething.set(true) } """.trimIndent() ) -/ Run the plugin task val buildResult: BuildResult = GradleRunner.create() .withProjectDir(testProjectDir) .withArguments("myPluginTask") .build() -/ Check if the output matches the expected result val expectedOutput = "didSomething" assertEquals(expectedOutput, buildResult.output) } } Testing Functional Tests with testKit
89. class MyPluginFunctionalTest { @BeforeEach fun setup() {--.} @Test fun `when plugin's task is ran it produces the expected output`() { settingsFile.writeText( """ rootProject.name = "example" """.trimIndent() ) buildFile.writeText( """ plugins { java id("dev.iurysouza.myplugin") } myPluginConfig { shouldDoSomething.set(true) } """.trimIndent() ) -/ Run the plugin task val buildResult: BuildResult = GradleRunner.create() .withProjectDir(testProjectDir) .withArguments("myPluginTask") .build() -/ Check if the output matches the expected result val expectedOutput = "Did something" assertEquals(expectedOutput, buildResult.output) } } Testing Functional Tests with testKit
90. class MyPluginFunctionalTest { @BeforeEach fun setup() {--.} @Test fun `when plugin is ran it produces the expected output`() { settingsFile.writeText( """ rootProject.name = "example" """.trimIndent() ) buildFile.writeText( """ plugins { java id("dev.iurysouza.myplugin") } myPluginConfig { shouldDoSomething.set(true) } """.trimIndent() ) -/ Run the plugin task val buildResult: BuildResult = GradleRunner.create() .withProjectDir(testProjectDir) .withArguments("myPluginTask") .build() -/ Check if the output matches the expected result val expectedOutput = "Did something" assertEquals(expectedOutput, buildResult.output) } } Testing Functional Tests with testKit
91. class MyPluginFunctionalTest { @BeforeEach fun setup() {--.} @Test fun `when plugin is ran it produces the expected output`() { settingsFile.writeText( """ rootProject.name = "example" """.trimIndent() ) buildFile.writeText( """ plugins { java id("dev.iurysouza.myplugin") } myPluginConfig { shouldDoSomething.set(true) } """.trimIndent() ) -/ Run the plugin task val buildResult: BuildResult = GradleRunner.create() .withProjectDir(testProjectDir) .withArguments("myPluginTask") .build() -/ Check if the output matches the expected result val expectedOutput = "Did Something" assertEquals(expectedOutput, buildResult.output) } } Testing Functional Tests with testKit
92. Testing When to use unit or functional tests?
93. 〉Getting started Implementation Testing Publishing Consuming Running Setup
94. Publishing How to share you plugin with the world
95. plugins { kotlin("jvm") `java-gradle-plugin` } dependencies { implementation(kotlin("stdlib")) implementation(gradleApi()) testRuntimeOnly(libs.junit5Engine) testImplementation(libs.junit5Api) testImplementation(gradleTestKit()) } tasks.test { useJUnitPlatform() } Publishing Setup plugin-publish
96. plugins { kotlin("jvm") `java-gradle-plugin` id("com.gradle.plugin-publish") version "1.1.0" } dependencies { implementation(kotlin("stdlib")) implementation(gradleApi()) testRuntimeOnly(libs.junit5Engine) testImplementation(libs.junit5Api) testImplementation(gradleTestKit()) } tasks.test { useJUnitPlatform() } Publishing Setup plugin-publish
97. Publishing Setup plugin-publish $ ./gradlew :myplugin:tasks Plugin Portal tasks ------------------- publishPlugins - Publishes this plugin to the Gradle Plugin portal. Publishing tasks ---------------- publishToMavenLocal - Publishes all Maven publications produced by this project to the local Maven cache.
98. Publishing Setup plugin-publish $ ./gradlew :myplugin:tasks Plugin Portal tasks ------------------- publishPlugins - Publishes this plugin to the Gradle Plugin portal. Publishing tasks ---------------- publishToMavenLocal - Publishes all Maven publications produced by this project to the local Maven cache.
99. Publishing Setup plugin-publish $ ./gradlew :myplugin:tasks Plugin Portal tasks ------------------- publishPlugins - Publishes this plugin to the Gradle Plugin portal. Publishing tasks ---------------- publishToMavenLocal - Publishes all Maven publications produced by this project to the local Maven cache.
100. Publishing Publishing locally $ ./gradlew :myplugin:publishToMavenLocal
101. Publishing Publishing locally $ cd ~/.m2/repository/dev/iurysouza/myplugin/0.0.1 -& ls -la .rw-r--r-- 261 myplugin-0.0.1-javadoc.jar .rw-r--r-- 4.9k myplugin-0.0.1-sources.jar .rw-r--r-- 28k myplugin-0.0.1.jar .rw-r--r-- 3.9k myplugin-0.0.1.module .rw-r--r-- 973 myplugin-0.0.1.pom
102. 〉Getting started Implementation Testing Publishing Consuming Running Setup
103. 〉settings.gradle.kts pluginManagement { repositories { mavenCentral() } } Consuming How to add your plugin to a build
104. 〉settings.gradle.kts pluginManagement { repositories { mavenCentral() } } Consuming Add the local gradle repository
105. 〉settings.gradle.kts pluginManagement { repositories { mavenCentral() mavenLocal() } } Consuming Add the local gradle repository
106. 〉sample 〉build.gradle.kts plugins { id("dev.iurysouza.myplugin") version ("0.0.1") } Consuming Finally, apply the plugin
107. 〉sample 〉build.gradle.kts plugins { id("dev.iurysouza.myplugin") version ("0.0.1") } Finally, apply the plugin
108. 〉Getting started Implementation Testing Publishing Consuming Running Setup
109. $ ./gradlew > Configure project :sample MyPlugin was applied! Running Is this thing on?
110. $ ./gradlew > Configure project :sample MyPlugin was applied! Running Yes!
111. import org.gradle.api.Plugin import org.gradle.api.Project class MyPlugin : Plugin<Project> { override fun apply(project: Project) { println("MyPlugin was applied!") } } Running Remember this?
112. 〉sample 〉build.gradle.kts plugins { id("dev.iurysouza.myplugin") version ("0.0.1") } myPluginConfig { shouldDoSomething.set(true) } Running Configuring the plugin
113. 〉sample 〉build.gradle.kts plugins { id("dev.iurysouza.myplugin") version ("0.0.1") } myPluginConfig { shouldDoSomething.set(true) } Running Configuring the plugin
114. $ ./gradlew myPluginTask Did Something Running Is this thing on?
115. $ ./gradlew myPluginTask Did Something Running Is this thing on?
116. import org.gradle.api.DefaultTask import org.gradle.api.provider.Property import org.gradle.api.tasks.Input import org.gradle.api.tasks.TaskAction abstract class MyPluginTask : DefaultTask() { @get:Input abstract val shouldDoSomething: Property<Boolean> @TaskAction fun execute() { if (shouldDoSomething.get()) { println("Did something") } else { println("Did something else") } } } Running Remember this?
117. $ ./gradlew myPluginTask Did Something Running Is this thing on?
118. $ ./gradlew myPluginTask Did Something Running You may be thinking: "Is that it?"
119. $ ./gradlew myPluginTask Did Something Running Think of it as your starting point
120. 〉Getting started Implementation Testing Publishing Consuming Running Setup
121. 〉Getting started Implementation Testing Publishing Consuming Running Setup
122. 〉Getting started
123. 〉Getting started
124. 〉Getting started
125. 〉Getting started The Gradle Plugin Puzzle
126. 〉Getting started The Gradle Plugin Puzzle 🤨
127. Live Demo time!
128. Where to go from Here? - Rules for Gradle plugin authors - Defensive development Gradle plugin development for busy engineers - Module Graph plugin
129. Thanks! @iurysza iurysouza.dev