Gradle Task

External

• Task API: org.gradle.api.Task
• Task DSL: https://docs.gradle.org/current/dsl/org.gradle.api.Task.html
• DefaultTask API: https://docs.gradle.org/current/javadoc/org/gradle/api/DefaultTask.html
• Authoring Tasks | https://docs.gradle.org/current/userguide/more_about_tasks.html

Internal

• Gradle Concepts

Overview

A task represents a well defined piece of work that is executing during a build, such as compiling Java classes or creating a distribution file. The work executed by a task is further divided into individual task actions, defined and managed by the task. The goal of a Gradle build is to execute a set of tasks in a well defined sequence, after the task have been arranged in a directed acyclic graph, computed based on each task's implicit and explicit dependencies. Understanding how the directed acyclic graph is built and how tasks are scheduled for execution is key to understanding how Gradle works.

A tasks belongs to a project. Each project comes with a set of pre-defined, built-in tasks. Each declared plugin may add its own tasks. New simple tasks can be defined in-line in build.gradle or in script plugins. Tasks whose implementations are available on the build's classpath, and that usually have their own properties and methods, can be declared and configured in build.gradle, as enhanced tasks, and thus made available for use during the build. Complex tasks can even be fully defined in-line or in script plugins, by providing the task code in-line in the script, though this is not a recommended practice, as it does not encourage modularization, encapsulation and sharing.

Any task instance implements org.gradle.api.Task interface. By default, every newly created task is of type org.gradle.api.DefaultTask, the standard implementation of org.gradle.api.Task.

Declaring, configuring and defining tasks is done via corresponding Project API methods, directly accessible from build.gradle:

Project.task(String name)
Project.task(String name, Closure configureClosure)
Project.task(String name, Action<? super Task> configureAction)
Project.task(Map<String, ?> args, String name)
Project.task(Map<String, ?> args, String name, Closure configureClosure)

A Gradle build executes the task specified on command line, including all explicit and implicit dependencies of the task.

./gradlew build

Task Lifecycle

The tasks are instantiated and configured in the build configuration phase, by executing their configuration closures. The task's actions are executed in the execution phase. A task does not necessarily have to have actions, it could only exist to execute the configuration closure at the build configuration phase. Such a task is called "task configuration".

Task Configuration Closure

Task configuration closures declare code that configures the task during the build configuration phase. The configuration closure usually initializes properties, declares task dependencies and add actions. Note that the statements that are not part of a task action, declared outside doFirst and doLast closures, will be executed in the configuration phase, when the task is initialized and configured, not in the execution phase. For more details, see Task Lifecycle, above.

Task Structure

Name and Path

Each task has a name, which is unique within the context of the task's project. The name must not contain dashes. Since different projects may contain tasks with the same name, a task is uniquely identified by its path in the context of a multi-project build. The path is the concatenation of the task owning project name and the task name, separated by the ":" character:

:web:build

Action

An action is the place within a task that contains build logic. Each task contains a list of actions, which are executed when the task is executed, in order in which they were added to the task's internal list of actions.

Usually, actions can also be added in-line with corresponding DSL keywords doFirst and doLast, followed by closure that contain executable code, as shown in Defining a Simple Task section. However, actions can be added to the task by invoking the Task API methods doFirst(Action|Closure), which adds the action at the head of the list, and doLast(Action|Closure), which adds the action at the tail of the list, on the task reference.

Other Task State

Group

A task group defines the logical grouping of tasks. The task group is available via the "group" property of the task instance, and can be set within the task constructor or directly setting the property:

task example {
  group = "experimental"
  doLast {
    ...
  }
}
task example(group: "experimental") {
  doLast {
    ...
  }
}

The task grouping is reflected in the output of gradle tasks.

Inputs and Outputs

Task Inputs and Outputs

Dependencies and Ordering

Task Dependencies and Ordering

Task Outcome

https://docs.gradle.org/current/userguide/more_about_tasks.html#sec:task_outcomes

After execution, a task has one of the following outcomes, depending on whether a task has actions to execute, it should execute those actions, it did execute its actions and whether those actions made any changes: EXECUTED, EXECUTED, FROM-CACHE, SKIPPED, NO-SOURCE.

(no label) or EXECUTED

The task has this outcome if:

• the task has actions that should have been executed, and they were executed.
• the task has no actions, but has dependencies and any of its dependencies has been executed.

UP-TO-DATE

The task has this outcome if:

• the task has no actions and no dependencies.
• the task has no actions, it has dependencies, but none of its dependencies have been executed because they are up-to-date, skipped or from cache.
• the task has actions, but the task tells Gradle that it did not change its outputs. How?
• the task has inputs and outputs and they have not changed.

FROM-CACHE

The task has this outcome if its output have been generated from a previous execution and have been restored from the build cache.

SKIPPED

The task has this outcome if:

• The task has actions, but did not executed its actions because an onlyIf predicate returns false.
• The task has been explicitly excluded from command line.

NO-SOURCE

The task has this outcome if it did not execute its actions because even if it has inputs and outputs, it has no sources.

Defining Custom Tasks

Developing Custom Gradle Task Types | https://docs.gradle.org/current/userguide/custom_tasks.html

The simplest way of extending Gradle is to write a custom task. The custom task can be declared in-line in the default build script build.gradle, as a simple task. The simple task can also be declared in-line in a separate build script, which is then included from the default build script. The code of the custom task can live in a separate source file or multiple files, which in turn can be declared in buildSrc, which is a special area of the Gradle project, or can be shared with other projects as part of a library, developed in its own project. Such a task is referred to as a enhanced task.

Custom tasks is also how Gradle plugins extend the Gradle functionality. "Custom" in this context means new functionality defined either by plugins, or by us, as user of Gradle.

Simple Task

A simple task is an implementation of org.gradle.api.DefaultTask that can be declared in-line in build.gradle or in script plugin using DSL keywords ("task", "doFirst", "doLast", etc.) corresponding to Task API methods. The example below shows a syntax where the task name and a task configuration closure are provided.

task <task-name> { <configuration-closure> }

task customSimpleTask {

  // this is the task configuration closure, it is executed during the configuration phase
  println "this will be displayed during configuration phase"

  // will add the action defined in the closure at the head of the action list
  doFirst {
    println "this will be executed second when the action is executed in the build execution phase"
  }

  doFirst {
    println "this will be executed first when the action is executed in the build execution phase"
  }

  // will add the action defined in the closure at the tail of the action list
  doLast {
    println "this will be executed last when the action is executed in the build execution phase"
  }
}

Simple task state elements can be set by using the task constructor that accepts a map:

task example(group: "experimental", 
             description: "Example task",
             dependsOn: [task-a, task-b]) {
  doFirst {
     println "example"
  }
}

Examples:

• Custom simple task declared in-line in build.gradle
• Custom simple task declared in-line in a script plugin

Enhanced Task

An enhanced task is a Gradle task that has two components:

• a task class, written in Java or Groovy, that encapsulates the logic. This task class is also called the task type. Gradle comes with a number of predefined task types, mentioned in the Predefined Task Types section below, but new types can be defined: the code can be declared in-line in build.gradle or a script plugin file, or preferably into a source code file (or files) maintained in the project's buildSrc or externally. The behavior is built into the task. Also, the task may expose properties that can be configured from the build script.
• the actual task declaration that provides the values for the properties exposed by the task class to configure the behavior. The properties exposed by an enhanced task can be set individually from the build script.

Developing enhanced task is preferred because separating the implementation code from the configuration of the task increases the maintainability, the testability and the reusability of the enhanced task.

Example of using an existing enhanced class:

task customTask(type: CustomEnhancedTask)  { 
  // task configuration closure
  color = "blue"
}

task customTask(type: CustomEnhancedTask)
...
customTask {
  // task configuration closure
}

Configuring Tasks

https://docs.gradle.org/current/userguide/more_about_tasks.html#sec:configuring_tasks

Predefined Task Types

https://docs.gradle.org/current/dsl/#N104B9

These predefined task types are exposed by the core plugins.

Java Plugin Predefined Task Types

• JavaCompile

Extending Gradle with Custom Enhanced Tasks

Extending Gradle with Custom Enhanced Tasks

Built-in Tasks

Each build exposes a set of built-in tasks, that can be used right away without any additional configuration or loading any plugin:

• init
• wrapper
• buildEnvironment
• components
• dependencies
• dependencyInsight
• dependentComponents
• help
• model
• projects
• properties
• tasks

Incremental Builds

Gradle is designed to allow faster builds by detecting work that does not need to be done, because it was done by a previous build and nothing change since. The central element that enables such behavior are the tasks that analyze their inputs and outputs, detect that nothing changed and they decide that they don't need to run. Such tasks allow Incremental builds. An even more sophisticated behavior is identifying which of the input elements had changed and only performing the work for those elements. Incremental tasks do that. Gradle allows caching task output in build caches, if the tasks producing those outputs are cacheable tasks, hence enabling sharing of outputs between builds.

Incremental Builds

Builds Cache

Lifecycle Tasks

• https://docs.gradle.org/current/userguide/more_about_tasks.html#sec:lifecycle_tasks

A lifecycle task is a task that does not do work itself.

Task Operations

• Listing all available tasks.

TO DEPLETE

Gradle Task TODEPLETE