Chapter 40. Writing Custom Plugins

There are several places where you can put the source for the plugin.

In our examples, we will start with the plugin in the build script, to keep things simple. Then we will look at creating a standalone project.

To create a custom plugin, you need to write an implementation of Plugin. Gradle instantiates the plugin and calls the plugin instance's Plugin.apply() method when the plugin is used with a project. The project object is passed as a parameter, which the plugin can use to configure the project however it needs to. The following sample contains a greeting plugin, which adds a hello task to the project.

apply plugin: GreetingPlugin

class GreetingPlugin implements Plugin<Project> {
    def void apply(Project project) {
        project.task('hello') << {
            println "Hello from the GreetingPlugin"
        }
    }
}

> gradle -q hello
Hello from the GreetingPlugin

One thing to note is that a new instance of a given plugin is created for each project it is applied to.

Most plugins need to obtain some configuration from the build script. One method for doing this is to use convention objects. The Gradle Project has a Convention object that helps keep track of all the settings and properties being passed to plugins. You can capture user input by telling the Project Convention about your plugin. To capture input, simply add a Java Bean compliant class into the Convention's list of plugins. Groovy is a good language choice for a plugin because plain old Groovy objects contain all the getter and setter methods that a Java Bean requires.

Let's add a simple convention object to the project. Here we add a greeting property to the project, which allows you to configure the greeting.

apply plugin: GreetingPlugin

greeting = 'Hi from Gradle'

class GreetingPlugin implements Plugin<Project> {
    def void apply(Project project) {
        project.convention.plugins.greet = new GreetingPluginConvention()
        project.task('hello') << {
            println project.convention.plugins.greet.greeting
        }
    }
}

class GreetingPluginConvention {
    def String greeting = 'Hello from GreetingPlugin'
}

> gradle -q hello
Hi from Gradle

In this example, GreetingPluginConvention is a plain old Groovy object with a field called greeting. The convention object is added to the plugin list with the name greet. The name of the variable in the build needs to match the name of the field in the convention object. The name you choose for your plugin (greet) is arbitrary and can be whatever you choose.

Oftentimes, you have several related properties you need to specify on a single plugin. With Groovy plugins it is easy to offer a configuration closure block to group settings together. The following example shows you how to do this.

apply plugin: GreetingPlugin

greet {
    message = 'Hi from Gradle' 
}

class GreetingPlugin implements Plugin<Project> {
    def void apply(Project project) {

        project.convention.plugins.greet = new GreetingPluginConvention()
        project.task('hello') << {
            println project.convention.plugins.greet.message
        }
    }
}

class GreetingPluginConvention {
    String message

    def greet(Closure closure) {
        closure.delegate = this
        closure() 
    }
}

> gradle -q hello
Hi from Gradle

In this example, several convention settings can be grouped together within the greet closure. The name of the closure block in the build script (greet) needs a matching method on the convention object, and that method must take a closure as an argument. Then, when the closure is executed, the fields on the convention object will be mapped to the variables within the closure based on the standard Groovy closure delegate feature. This technique is possible in other JVM languages but may not be as convenient as in Groovy.

Now we will move our plugin to a standalone project, so we can publish it and share it with others. This project is simply a Groovy project that produces a JAR containing the plugin classes. Here is a simple build script for the project. It applies the Groovy plugin, and adds the Gradle API as a compile-time dependency.

apply plugin: 'groovy'

dependencies {
    compile gradleApi()
}

So how does Gradle find the Plugin implementation? The answer is you need to provide a properties file in the jar's META-INF/gradle-plugins directory that matches the name of your plugin.

implementation-class=org.gradle.GreetingPlugin

Notice that the properties filename matches the plugin's name and is placed in the resources folder, and that the implementation-class property identifies the Plugin implementation class.

buildscript {
    repositories {
        mavenRepo urls: uri('repo')
    }
    dependencies {
        classpath group: 'org.gradle', name: 'customPlugin', version: '1.0-SNAPSHOT'
    }
}

apply plugin: 'greeting'

class GreetingPluginTest {
    @Test
    public void greeterPluginAddsGreetingTaskToProject() {
        Project project = ProjectBuilder.builder().build()
        project.apply plugin: 'greeting'

        assertTrue(project.tasks.hello instanceof GreetingTask)
    }
}

Gradle provides some utility classes for maintaining collections of object, which work well with the Gradle build language.

apply plugin: DocumentationPlugin

books {
    quickStart {
        sourceFile = file('src/docs/quick-start')
    }
    userGuide {

    }
    developerGuide {

    }
}

task books << {
    books.each { book ->
        println "$book.name -> $book.sourceFile"
    }
}

class DocumentationPlugin implements Plugin<Project> {
    def void apply(Project project) {
        def books = project.container(Book) { name -> new Book(name) }
        books.all {
            sourceFile = project.file("src/docs/$name")
        }
        project.convention.plugins.documentation = new DocumentationPluginConvention(books)
    }
}

class Book {
    final String name
    File sourceFile

    Book(String name) {
        this.name = name
    }
}

class DocumentationPluginConvention {
    final NamedDomainObjectContainer<Book> books

    DocumentationPluginConvention(NamedDomainObjectContainer<Book> books) {
        this.books = books
    }

    def books(Closure cl) {
        books.configure(cl)
    }
}

> gradle -q books
developerGuide -> /home/user/gradle/samples/userguide/organizeBuildLogic/customPluginWithDomainObjectContainer/src/docs/developerGuide
quickStart -> /home/user/gradle/samples/userguide/organizeBuildLogic/customPluginWithDomainObjectContainer/src/docs/quick-start
userGuide -> /home/user/gradle/samples/userguide/organizeBuildLogic/customPluginWithDomainObjectContainer/src/docs/userGuide