Chapter 25. Gradle Plugins

This way of adding plugins to a project is much more than a more convenient syntax. The plugins DSL is processed in a way which allows Gradle to determine the plugins in use very early and very quickly. This allows Gradle to do smart things such as:

This requires that plugins be specified in a way that Gradle can easily and quickly extract, before executing the rest of the build script. It also requires that the definition of plugins to use be somewhat static.

There are some key differences between the new plugin mechanism and the “traditional” apply() method mechanism. There are also some constraints, some of which are temporary limitations while the mechanism is still being developed and some are inherent to the new approach.

plugins {
    id «plugin id» version «plugin version» [apply «false»]
}

If the restrictions of the new syntax are prohibitive, the recommended approach is to apply plugins using the buildscript {} block.

If you have a multi-project build, you probably want to apply plugins to some or all of the subprojects in your build, but not to the root or master project. The default behavior of the plugins {} block is to immediately resolve and apply the plugins. But, you can use the apply false syntax to tell Gradle not to apply the plugin to the current project and then use apply plugin: «plugin version» in the subprojects block:

include 'helloA'
include 'helloB'
include 'goodbyeC'

plugins {
  id "org.gradle.sample.hello" version "1.0.0" apply false
  id "org.gradle.sample.goodbye" version "1.0.0" apply false
}

subprojects { subproject ->
    if (subproject.name.startsWith("hello")) {
        apply plugin: 'org.gradle.sample.hello'
    }
    if (subproject.name.startsWith("goodbye")) {
        apply plugin: 'org.gradle.sample.goodbye'
    }
}

If you then run gradle hello you'll see that only the helloA and helloB subprojects had the hello plugin applied.

gradle/subprojects/docs/src/samples/plugins/multiproject $> gradle hello
Parallel execution is an incubating feature.
:helloA:hello
:helloB:hello
Hello!
Hello!

BUILD SUCCESSFUL

By default, the plugins {} DSL resolves plugins from the public Gradle Plugin Portal. Many build authors would also like to resolve plugins from private Maven or Ivy repositories because the plugins contain proprietary implementation details, or just to have more control over what plugins are available to their builds.

To specify custom plugin repositories, add a pluginRepositories {} block to the settings.gradle file:

pluginRepositories {
  maven {
    url 'maven-repo'
  }
  gradlePluginPortal()
  ivy {
    url 'ivy-repo'
  }
}

This tells Gradle to first look in the Maven repository at maven-repo when resolving plugins and then to check the Gradle Plugin Portal if the plugins are not found in the Maven repository. If you don't want the Gradle Plugin Portal to be searched, omit the gradlePluginPortal() line. Finally, the Ivy repository at ivy-repo will be checked.

The pluginRepositories {} block may only appear in the settings.gradle file, and must be the first block in the file. Custom Maven and Ivy plugin repositories must contain plugin marker artifacts in addition to the artifacts which actually implement the plugin. For more information on publishing plugins to custom repositories read Chapter 40, The Java Gradle Plugin Development Plugin.

See PluginRepositoriesSpec for complete documentation for using the pluginRepositories {} block.

Since the plugins {} DSL block only allows for declaring plugins by their globally unique plugin id and version properties, Gradle needs a way to look up the coordinates of the plugin implementation artifact. To do so, Gradle will look for a Plugin Marker Artifact with the coordinates plugin.id:plugin.id.gradle.plugin:plugin.version. This marker needs to have a dependency on the actual plugin implementation. Publishing these markers is automated by the java-gradle-plugin.

For example, the following complete sample from the sample-plugins project shows how to publish a org.gradle.sample.hello plugin and a org.gradle.sample.goodbye plugin to both an Ivy and Maven repository using the combination of the java-gradle-plugin, the maven-publish plugin, and the ivy-publish plugin.

plugins {
  id 'java-gradle-plugin'
  id 'maven-publish'
  id 'ivy-publish'
}

group 'org.gradle.sample'
version '1.0.0'

gradlePlugin {
  plugins {
    hello {
      id = "org.gradle.sample.hello"
      implementationClass = "org.gradle.sample.hello.HelloPlugin"
    }
    goodbye {
      id = "org.gradle.sample.goodbye"
      implementationClass = "org.gradle.sample.goodbye.GoodbyePlugin"
    }
  }
}

publishing {
  repositories {
    maven {
      url "../consuming/maven-repo"
    }
    ivy {
      url "../consuming/ivy-repo"
    }
  }
}

Running gradle publish in the sample directory causes the following repo layouts to exist:

apply plugin: 'java'

Plugins can be applied using a plugin id. In the above case, we are using the short name ‘java’ to apply the JavaPlugin.

Rather than using a plugin id, plugins can also be applied by simply specifying the class of the plugin:

apply plugin: JavaPlugin

The JavaPlugin symbol in the above sample refers to the the JavaPlugin. This class does not strictly need to be imported as the org.gradle.api.plugins package is automatically imported in all build scripts (see Section 16.8, “Default imports”). Furthermore, it is not necessary to append .class to identify a class literal in Groovy as it is in Java.

Binary plugins that have been published as external jar files can be added to a project by adding the plugin to the build script classpath and then applying the plugin. External jars can be added to the build script classpath using the buildscript {} block as described in ???.

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath "com.jfrog.bintray.gradle:gradle-bintray-plugin:0.4.1"
    }
}

apply plugin: "com.jfrog.bintray"