We recommend that the configuration avoidance APIs be used whenever tasks are created.

Task configuration avoidance API

The configuration avoidance API avoids configuring tasks if they will not be used for a build, which can significantly impact total configuration time.

For example, when running a compile task (with the java plugin applied), other unrelated tasks (such as clean, test, javadocs), will not be executed.

To avoid creating and configuring a task not needed for a build, we can register that task instead.

When a task is registered, it is known to the build. It can be configured, and references to it can be passed around, but the task object itself has not been created, and its actions have not been executed. The registered task will remain in this state until something in the build needs the instantiated task object. If the task object is never needed, the task will remain registered, and the cost of creating and configuring the task will be avoided.

In Gradle, you register a task using TaskContainer.register(java.lang.String). Instead of returning a task instance, the register(…​) method returns a TaskProvider, which is a reference to the task that can be used in many places where a normal task object might be used (i.e., when creating task dependencies).

Guidelines

Defer task creation

Effective task configuration avoidance requires build authors to change instances of TaskContainer.create(java.lang.String) to TaskContainer.register(java.lang.String).

Older versions of Gradle only support the create(…​) API. The create(…​) API eagerly creates and configures tasks when called and should be avoided.

Using register(…​) alone may not be enough to avoid all task configuration completely. You may need to change other code that configures tasks by name or by type, see below.