A Custom Task in Gradle

1. Overview

In this article, we’ll cover how to create a custom task in Gradle. We’ll show a new task definition using a build script or a custom task type.

For the introduction to the Gradle, please see this article. It contains the basics of Gradle and – what’s the most important for this article – the introduction to Gradle tasks.

2. Custom Task Definition Inside build.gradle

To create a straightforward Gradle task, we need to add its definition to our build.gradle file:

task welcome {
    doLast {
        println 'Welcome in the Baeldung!'
    }
}

The main goal of the above task is just to print text “Welcome in the Baeldung!”. We can check if this task is available by running gradle tasks –all command:

gradle tasks --all

The task is on the list under the group Other tasks:

Other tasks
-----------
welcome

It can be executed just like any other Gradle task:

gradle welcome

The output is as expected – the “Welcome in the Baeldung!” message.

Remark: if option –all is not set, then tasks which belong to “Other” category aren’t visible. Custom Gradle task can belong to a different group than “Other” and can contain a description.

3. Set Group and Description

Sometimes it’s handy to group tasks by function, so they are visible under one category. We can quickly set group for our custom tasks, just by defining a group property:

task welcome {
    group 'Sample category'
    doLast {
        println 'Welcome on the Baeldung!'
    }
}

Now when we run Gradle command to list all available tasks (–all option isn’t needed anymore), we’ll see our task under new group:

Sample category tasks
---------------------
welcome

However, it’s also beneficial for others to see what a task is responsible for. We can create a description which contains short information:

task welcome {
    group 'Sample category'
    description 'Tasks which shows a welcome message'
    doLast {
        println 'Welcome in the Baeldung!'
    }
}

When we print a list of the available tasks the output will be as follow:

Sample category tasks
---------------------
welcome - Tasks which shows a welcome message

This kind of task definition is called ad-hoc definition.

Coming further, it’s beneficial to create a customizable task which definition can be reused. We’ll cover how to create a task from a type and how to make some customization available to the users of this task.

4. Define Gradle Task Type Inside build.gradle

The above “welcome” task cannot be customized, thus, in most cases, it’s not very useful. We can run it, but if we need it in a different project (or subproject), then we need to copy and paste its definition.

We can quickly enable customization of the task by creating a task type. Merely, a task type is defined inside the build script:

class PrintToolVersionTask extends DefaultTask {
    String tool

    @TaskAction
    void printToolVersion() {
        switch (tool) {
            case 'java':
                println System.getProperty("java.version")
                break
            case 'groovy':
                println GroovySystem.version
                break
            default:
                throw new IllegalArgumentException("Unknown tool")
        }
    }
}

A custom task type is a simple Groovy class which extends DefaultTask – the class which defines standard task implementation. There are other task types which we can extend from, but in most cases, the DefaultTask class is the appropriate choice.

PrintToolVersionTask task contains tool property which can be customized by instances of this task:

String tool

We can add as many properties as we want – keep in mind it is just a simple Groovy class field.

Additionally, it contains method annotated with @TaskAction. It defines what this task is doing. In this simple example it prints version of installed Java or Groovy – depends on the given parameter value.

To run a custom task based on created task type we need to create a new task instance of this type:

task printJavaVersion(type : PrintToolVersionTask) {
    tool 'java'
}

The most important parts are:

• our task is a PrintToolVersionTask type, so when executed it’ll trigger the action defined in the method annotated with @TaskAction
• we added a customized tool property value (java) which will be used by PrintToolVersionTask

When we run the above task the output is as expected (depends on the Java version installed):

> Task :printJavaVersion 
9.0.1

Now let’s create a task which prints the installed version of Groovy:

task printGroovyVersion(type : PrintToolVersionTask) {
    tool 'groovy'
}

It uses the same task type as we defined before, but it has a different tool property value. When we execute this task it prints the Groovy version:

> Task :printGroovyVersion 
2.4.12

If we have not too many custom tasks, then we can define them directly in the build.gradle file (like we did above). However, if there are more than a few then our build.gradle file becomes hard to read and understand.

Luckily, Gradle provides some solutions for that.

5. Define Task Type in the buildSrc Folder

We can define task types in the buildSrc folder which is located at the root project level. Gradle compiles everything that is inside and adds types to the classpath so our build script can use it.

Our task type which we defined before (PrintToolVersionTask) can be moved into the buildSrc/src/main/groovy/com/baeldung/PrintToolVersionTask.groovy. We have to only add some imports from Gradle API into a moved class.

We can define an unlimited number of tasks types in the buildSrc folder. It’s easier to maintain, read, and the task type declaration isn’t in the same place as the task instantiation.

We can use these types the same way we’re using types defined directly in the build script. We have to remember only to add appropriate imports.

6. Define Task Type in the Plugin

We can define a custom task types inside a custom Gradle plugin. Please refer to this article, which describes how to define a custom Gradle plugin, defined in the:

• build.gradle file
• buildSrc folder as other Groovy classes

These custom tasks will be available for our build when we define a dependency to this plugin. Please note that ad-hoc tasks are also available – not only custom task types.

7. Conclusion

In this tutorial, we covered how to create a custom task in Gradle. There are a lot of plugins available which you can use in your build.gradle file that will provide a lot of custom task types you need.