Extending Gradle with a Custom Enhanced Task
Internal
Overview
An enhanced task requires writing Groovy or Java code either in in-line in build.gradle or a script plugin file, or into a source code file (or files) maintained in the project's buildSrc or externally. The behavior is built into the task and the task exposes some properties that can be configured from the build script.
In-Line Custom Enhanced Task
An in-line custom enhanced task can be declared as follows, either in build.gradle or in a script plugin:
...
class CustomEnhancedTask extends DefaultTask {
@TaskAction
void impl() {
System.out.println("this is an in-line enhanced task")
}
}
task customTask(type: CustomEnhancedTask)
...
Example:
This approach is not recommended as we are losing testability and reusability of the task.
File-Based Custom Enhanced Task
The same task can be defined in a Java/Groovy/Kotlin file either in the project's buildSrc or in an external project:
package playground.gradle;
import org.gradle.api.DefaultTask;
import org.gradle.api.tasks.TaskAction;
public class CustomEnhancedTask extends DefaultTask {
@TaskAction
void impl() {
System.out.println("this is an custom enhanced task developed in buildSrc");
}
}
If the task was defined in the project's buildSrc, then it can then be declared in build.gradle as follows. The task name is arbitrary, it does not have to match the class name, but matching names is intuitive and thus preferred.
task customEnhancedTask(type: playground.gradle.CustomEnhancedTask)
Example:
If the task was defined in an external project, the external project must publish the JAR containing the task in a repository, and the Gradle project using the task must declare the JAR as dependency in the buildScript block of the build.gradle file and pull it from the repository it was published in:
buildscript {
repositories {
mavenLocal()
}
dependencies {
classpath 'playground.gradle.standalone-task:06-enhanced-task-developed-in-standalone-project:0.1.0'
}
}
task custEnhTask(type: playground.gradle.CustomEnhancedTask)
More details on configuring the build script classpath are available in:
Examples:
Programming Custom Tasks
@TaskAction
Action Failure
If the action code fails in any way, we indicate that the action, and thus the task failed by throwing an unchecked exception. RuntimeException works. Gradle will display the exception message:
./gradlew example
> Task :example FAILED
FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':example'.
> this is the RuntimeException message
[...]
Logging
Allowing Configuration via a Task Constructor
Configuration values can be passed to a Task's class constructor, if the respective constructor was annotated with @javax.inject.Inject:
class CustomTask extends DefaultTask {
final String message
final int number
@Inject
CustomTask(String message, int number) {
this.message = message
this.number = number
}
}
The task can then be configured with constructor arguments using the task container, as shown below. This should be the preferred way of configuring tasks, as it improves the configuration time. For more details, see Gradle Tasks | Task Configuration Avoidance APIs.
tasks.create('myTask', CustomTask, 'hello', 42)
task myTask(type: CustomTask, constructorArgs: ['hello', 42])
In all circumstances, the values passed as constructor arguments must be non-null. If a null value is passed, Gradle will throw a NullPointerException.
Programmatic Access to Properties
TODO
The name of the method annotated with @TaskAction is arbitrary.
TODO:
- Gradle in Action Section 8.3.2 Using the CloudBees API from tasks.
- Gradle in Action Section 8.4 Writing custom task classes.
- https://docs.gradle.org/current/userguide/custom_tasks.html
Enhanced Task Testing
TODO https://docs.gradle.org/current/userguide/custom_tasks.html#sec:writing_tests_for_your_task_class
TODO/TODEPLETE
DEPLETE Gradle_Task_TODEPLETE#Explicit_Task_Declaration_.28Custom_Tasks.29