# Chapter 18. Using Plugins

Now we look at how Gradle provides build-by-convention and out of the box functionality. These features are decoupled from the core of Gradle, and are provided via plugins. Although the plugins are decoupled, we would like to point out that the Gradle core plugins are NEVER updated or changed for a particular Gradle distribution. If there is a bug in the compile functionality of Gradle, we will release a new version of Gradle. There is no change of behavior for the lifetime of a given distribution of Gradle.

## 18.1. Declaring plugins

If you want to use the plugin for building a Java project, simply include

Example 18.1. Using a plugin

`build.gradle`

    apply plugin: 'java'

in your script. That's all. From a technological point of view plugins use just the same operations as you can use from your build scripts. That is, they use the Project and Task API. The Gradle plugins generally use this API to:

- Add tasks to the project (e.g. compile, test)

- Create dependencies between those tasks to let them execute in the appropriate order.

- Add dependency configurations to the project.

- Add a so called convention object to the project.

Let's check this out:

Example 18.2. Applying a plugin by id

`build.gradle`

    apply plugin: 'java'

    task show << {
        println relativePath(compileJava.destinationDir)
        println relativePath(processResources.destinationDir)
    }

Output of `gradle -q show`

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

The Java plugin adds a `compileJava` task and a `processResources` task to the project object which can be accessed by a build script. It has configured the `destinationDir` property of both of these tasks.

The `apply()` method either takes a string or a class as an argument. You can write

Example 18.3. Applying a plugin by type

`build.gradle`

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

Thanks to Gradle's default imports (see Appendix D, Existing IDE Support and how to cope without it) you can also write in this case.

Example 18.4. Applying a plugin by type

`build.gradle`

    apply plugin: JavaPlugin

Any class, which implements the `Plugin` interface, can be used as a plugin. Just pass the class as an argument. You don't need to configure anything else for this.

If you want to use your own plugins, you must make sure that they are accessible via the build script classpath (see Chapter 43, Organizing Build Logic for more information). To learn more about how to write custom plugins, see Chapter 42, Writing Custom Plugins.

## 18.2. Using the convention object

If you use the Java plugin for example, there are a `compileJava` and a `processResources` task for your production code (the same is true for your test code). What if you want to change the default configuration? Let's try:

Example 18.5. Configuring a plugin task

`build.gradle`

    apply plugin: 'java'

    task show << {
        processResources.destinationDir = new File(buildDir, 'output')
        println relativePath(processResources.destinationDir)
        println relativePath(compileJava.destinationDir)
    }

Output of `gradle -q show`

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

Setting the `destinationDir` of the `processResources` task had only an effect on the `processResources` task. Maybe this was what you wanted. But what if you want to change the output directory for all tasks? It would be unfortunate if you had to do this for each task separately.

Gradle's tasks are usually convention aware. A plugin can add a convention object to your project, and map certain values of this convention object to task properties.

Example 18.6. Plugin convention object

`build.gradle`

    apply plugin: 'java'

    task show << {
        sourceSets.main.output.classesDir = new File(buildDir, 'output/classes')
        sourceSets.main.output.resourcesDir = new File(buildDir, 'output/resources')

        println relativePath(compileJava.destinationDir)
        println relativePath(processResources.destinationDir)
    }

Output of `gradle -q show`

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

The Java plugin has added a convention object with a `sourceSets` property, which we use to set the classes directory.

By setting a task attribute explicitly (as we have done in the first example) you overwrite the convention value for this particular task.

Not all of the tasks attributes are mapped to convention object values. It is the decision of the plugin to decide what are the shared properties and then bundle them in a convention object and map them to the tasks.

The properties of a convention object can be accessed as project properties. As shown in the following example, you can also access the convention object explicitly.

Example 18.7. Using the plugin convention object

`build.gradle`

    apply plugin: 'java'

    task show << {
        // Access the convention property as a project property
        println relativePath(sourceSets.main.output.classesDir)
        println relativePath(project.sourceSets.main.output.classesDir)

        // Access the convention property via the convention object
        println relativePath(project.convention.plugins.java.sourceSets.main.output.classesDir)
    }

Output of `gradle -q show`

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

Every project object has a `Convention` object which is a container for convention objects contributed by the plugins declared for your project. If you simply access or set a property or access a method in your build script, the project object first looks if this is a property of itself. If not, it delegates the request to its convention object. The convention object checks if any of the plugin convention objects can fulfill the request (first wins and the order is not defined). The plugin convention objects also introduce a namespace.

### 18.2.1. Declaring plugins multiple times

A plugin is only called once for a given project, even if you have multiple `apply()` statements. An additional call after the first call has no effect but doesn't hurt either. This can be important if you use plugins which extend other plugins. For example the Groovy plugin automatically applies the Java plugin. We say the Groovy plugin extends the Java plugin. But you might as well write:

Example 18.8. Explicit application of an implied plugin

`build.gradle`

    apply plugin: 'java'
    apply plugin: 'groovy'

If you use cross-project configuration in multi-project builds this is a useful feature.