Extending Gradle with a Custom Enhanced Task: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
No edit summary
Line 1: Line 1:
=External=
* https://docs.gradle.org/current/userguide/custom_tasks.html
=Internal=
* [[Gradle_Task#Custom_Tasks|Gradle Tasks]]
* [[Extending_Gradle#Custom_Task|Extending Gradle]]
=Enhanced Task=
=TODO=
<br>
<br>
<br>
<br>
<center>Review everything after Task Concepts update.</center>
<br>
<br>
<br>
<br>
=Overview=
The simplest way of extending Gradle is write a custom [[Gradle_Task#Overview|task]]. The custom task can be declared [[Extending_Gradle#In-line_in_build.gradle|in-line in the default build script build.gradle]], as a [[#Simple_Task|simple task]]. The [[#Simple_Task|simple task]] can also be declared [[Extending_Gradle#In-line_in_a_script_plugin|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, which in turn can be declared in [[Extending_Gradle#In_the_Project.27s_buildSrc_Directory|a special area of the Gradle project]], or can be shared with other projects as part of a library, developed in [[Extending_Gradle#External_to_Project|its own project]]. Such a task is referred to as a [[#Enhanced_Task|enhanced task]].
=Simple Task=
=Simple Task=
<font color=darkgray>A simple task is defined with an [[Gradle_Task#Task_Configuration_Closure|in-line task configuration closure]] or [[Gradle_Task#Task_Action_Closure|in-line task action closure]] in the build script or another script imported from the build script. The task is declared with DSL elements, starting with the "task" DSL keyword, which corresponds to the Project's [https://docs.gradle.org/current/javadoc/org/gradle/api/Project.html#task-java.lang.String-groovy.lang.Closure- task() method].</font>
<font color=darkgray>A simple task is defined with an [[Gradle_Task#Task_Configuration_Closure|in-line task configuration closure]] or [[Gradle_Task#Task_Action_Closure|in-line task action closure]] in the build script or another script imported from the build script. The task is declared with DSL elements, starting with the "task" DSL keyword, which corresponds to the Project's [https://docs.gradle.org/current/javadoc/org/gradle/api/Project.html#task-java.lang.String-groovy.lang.Closure- task() method].</font>

Revision as of 21:18, 4 October 2020

Simple Task

A simple task is defined with an in-line task configuration closure or in-line task action closure in the build script or another script imported from the build script. The task is declared with DSL elements, starting with the "task" DSL keyword, which corresponds to the Project's task() method.

task customSimpleTask {
    println 'this is a simple task'
}

Examples:

Enhanced Task

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.

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: Custom ehanced Java task declared in-line in build.gradle

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: Custom enhanced task developed in buildSrc.

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:

Build Script Classpath

Examples:

Enhanced Custom Task Implementation Details

The name of the method annotated with @TaskAction is arbitrary. TODO:

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