Tasks are the cornerstone of getting things done in Gradle. They represent single atomic pieces of work within a build such as creating a JAR or linking an executable. This guide will walk you through the process of customising your build using small, tailored tasks.

What you’ll create

You’ll start by creating an ad-hoc Gradle task that prints Hello, World to the console. You’ll then move to making it configurable to print any message. In this process you’ll learn about ad-hoc tasks and custom task types.

What you’ll need

  • About NN

  • A text editor or IDE

  • A Java Development Kit (JDK), version 1.7 or better

  • A Gradle distribution, version 4.0 or better

Create an ad-hoc task

In a new folder create a build.gradle and enter the following

build.gradle
task hello { (1)
    doLast { (2)
        println 'Hello, World!'
    }
}
1 Create a new ad-hoc task called hello.
2 Add a task action to print to the console.

Save the file and on the command-line and type:

Save the file and on the command-line type gradle tasks --all. Your new task will appear under Other tasks.

Verifying that your task has been created
$ gradle tasks --all

Other tasks
-----------
hello
If you are using Gradle 4.0 or later you may see less output from the console that you might see in this guide. This is because in this guide output is shown as when --console-plain is also passed to Gradle as a command-line. This is done to show the tasks that Gradle is executing.

Run your task.

Output from executing your ad-hoc task
$ gradle hello

:hello (1)
Hello, World (2)
1 This indicates that your hello task has executed.
2 This is the output from your ad-hoc task.

Congratulations! You have you added your first ad-hoc task.

Do not use << as an alternative to doLast
task hello << {
  println 'Hello, World!'
}

You may comes across an alternative form for creating ad-hoc tasks in some older documentation and blog posts whereby the left-shift operator (<<) is used.

This form has caused too much confusion in the past especially among people that are new to Gradle. It also reduces readability. We have deprecated this behaviour and the functionality will be removed in Gradle 5.0.

Add a task description

Although you have tested your new ad-hoc task and know that it works, it is good practice to tell others who will use your build script what the purpose of your new task is. It is also useful to categorise your task.

When you ran gradle tasks --all earlier you would have seen other tasks in the listing which contain descriptions and are grouped according to function. Also (and since Gradle 3.3) if a task does not have a group it will not be listed unless --all is specified.

Well-documented tasks
Build Setup tasks
-----------------
init - Initializes a new Gradle build.
wrapper - Generates Gradle wrapper files.

This is achieved by setting the group and description properties on the task. Edit your ad-hoc task and add the following:

build.gradle
task hello {
    group 'Welcome'
    description 'Produces a greeting'

    doLast {
        println 'Hello, World'
    }
}

Run gradle tasks again.

Output from 'tasks' task
$ gradle tasks

Welcome tasks
-------------
hello - Produces a greeting

Well done!

Make the message configurable

This is the point where you need to convert your ad-hoc task into a custom task type, and this is achieved by creating a class within the build script.

Return to your build script and add the following class and refactor your hello task.

build.gradle
class Greeting extends DefaultTask {  (1) (2)
    String message (3)
    String recipient

    @TaskAction (4)
    void sayGreeting() {
        println "${message}, ${recipient}!" (5)
    }
}

task hello (type : Greeting) { (6)
    group 'Welcome'
    description 'Produces a world greeting'
    message 'Hello' (7)
    recipient 'World'
}
1 As the build DSL in a build.gradle file is a Groovy-base DSL, the class will be a Groovy class.
2 Although other task classes from the Gradle API can be used in specific circumstances, extending {javadoc}/org/gradle/api/DefaultTask.html[DefaultTask] is the most common scenario.
3 Adding message and recipient properties allow instances of this custom task type to be configurable
4 Annotate the default task action.
5 Print the message using a standard Groovy interpolated string.
6 Specify the task type by referencing the class type Greeting you have added above.
7 Configure the message and the recipient.

Test your modification. You should see the same output.

Output after conversion to a custom task type
$ gradle hello

:hello
Hello, World!

Now that you have the custom task type, you can add additional tasks. Add a German version of the greeting by just creating an additional task.

Adding a second task
task gutenTag( type : Greeting ) {
    group 'Welcome'
    description 'Produces a German greeting'
    message 'Guten Tag'
    recipient 'Welt'
}
No assignment is required during configuration as Gradle decorates the properties to allow for a more declarative DSL.

Run gradle tasks again to verify that the new task has been added.

Output of 'gradle tasks' after adding second task.
$ gradle tasks

Welcome tasks
-------------
gutenTag - Produces a German greeting
hello - Produces a world greeting

Finally, run the new task by doing gradle gutenTag

Output of your second task.
$ gradle gutenTag

:gutenTag
Guten Tag, Welt!

Summary

That’s it! You’ve worked through the steps necessary to create a custom Gradle Task. You should now have learned how to

  • Create an ad-hoc task and add an action using doLast.

  • Document a task.

  • Convert an ad-hoc task to a custom Gradle task type and creating task instances.

  • Using @TaskAction to set a default action for a task type.

Next steps

Help improve this guide

Have feedback or a question? Found a typo? Like all Gradle guides, help is just a GitHub issue away. Please add an issue or pull request to gradle-guides/writing-gradle-tasks and we’ll get back to you.