Gradle Grad plug-in

Gradle plug-in

At its core, Gradle intentionally provides small but useful features for automation in the real world. A ll useful features, such as the ability to compile Java code, are added through plug-ins. Plug-ins add new tasks (such as JavaCompile), domain objects (such as SourceSet), conventions (such as the primary Java source code is located in src/main/java), and objects for extensions' core objects and other plug-ins.

In this chapter, we'll discuss how to use plug-ins and concepts related to terminology and plug-ins.

Apply the plug-in

Plug-ins are considered to be applied and are done through the Project.apply() method.

Apply the plug-in

build.gradle

apply plugin: 'java'  

Plug-ins have a short name that represents their own. In the example above, we use the short name java to apply JavaPlugin.

We can also use the following syntax:

Apply the plug-in by type

build.gradle

apply plugin: org.gradle.api.plugins.JavaPlugin  

Because of Gradle's default import, you can also write this:

Apply the plug-in by type

build.gradle

apply plugin: JavaPlugin  

The application of the plug-in is idempotent. T hat is, a plug-in can be applied multiple times. If the plug-in has been applied before, no further apps will have any effect.

A plug-in is any simple class that implements the Plugin interface. G radle provides the core plug-in as part of its distribution package, so simply applying the plug-in above is all you need to do. H owever, for third-party plug-ins, you need to configure them to make them available in the build class path. More information about how to do this.

What the plug-ins have done

Applying a plug-in to a project allows the plug-in to extend the functionality of the project. It can do things such as:

• Add tasks to a project (e.g. compilation, testing)
• Use useful default settings to pre-configure tasks that you have added.
• Add dependency configurations to your project (see Dependency Management Foundation).
• Add new properties and methods to existing types by extending them.

Let's take a look at:

Add tasks through plug-ins

build.gradle

apply plugin: 'java'
task show << {
    println relativePath(compileJava.destinationDir)
    println relativePath(processResources.destinationDir)
}  

The output of the gradle -q show

> gradle -q show
build/classes/main
build/resources/main  

The Java plug-in has added compileJava and processResources tasks to the project, and the destinationDir property for both tasks has been configured.

Conventions

Plug-ins can intelligently pre-configure projects to support conventions that are superior to configurations. Gradle provides mechanism and perfect support for this, and it is a key factor in a powerful - yet - concise build script.

As we saw in the example above, the Java plug-in added a task named compileJava with a property called destinationDir (that is, where the compiled Java code is stored). B y default, this property points to build/classes/main in the project directory. This is an example of a configuration that is superior by a reasonable default convention.

We can simply change this property by giving it a new value.

Change the default settings for the plug-in

build.gradle

apply plugin: 'java'
compileJava.destinationDir = file("$buildDir/output/classes")
task show << {
    println relativePath(compileJava.destinationDir)
}  

The output of the gradle -q show

> gradle -q show
build/output/classes  

However, the compileJava task is probably not the only one that needs to know where the class files are.

The Java plug-in adds the concept of source sets (see SourceSet) to describe various aspects of the source file set, one of which is where the class files should be written at compile time. The Java plug-in maps the destinationDir property of the compileJava task to this aspect of the source file set.

We can modify the location of the write class file through this source set.

The convention object in the plug-in

build.gradle

apply plugin: 'java'
sourceSets.main.output.classesDir = file("$buildDir/output/classes")
task show << {
    println relativePath(compileJava.destinationDir)
}  

The output of the gradle -q show

> gradle -q show
build/output/classes  

In the example above, we applied the Java plug-in and did the following, among other things:

• Added a new domain object type: SourceSet
• The main source set is configured by default (i.e. general) of the property
• Configure tasks that support the use of these properties to perform work

All of this happens during the apply plugin: "java" step. I n the example above, we modified the location required for the class file after the convention configuration was performed. As you can see in the example above, the value of compileJava.destinationDir has also been modified to reflect configuration changes.

Consider the task of another consumer file. If this task is configured using the value of sourceSets.main.output.classesDir, the value of this location is modified, and whenever it is modified, both the compileJava task and this consumer task are updated.

This ability to configure an object's properties to reflect the value of another object's task all the time, even when it changes, is called a "mapping convention." I t enables Gradle to achieve a concise configuration by convention over configuration and reasonable default values. A lso, if the default convention needs to be modified, there is no need for a complete reconfiguration. Without this, in the example above, we would have to reconfigure each object that needs to use a class file.