Chapter 25. Gradle Plugins

Applying a plugin to a project allows the plugin to extend the project's capabilities. It can do things such as:

By applying plugins, rather than adding logic to the project build script, we can reap a number of benefits. Applying plugins:

There are two general types of plugins in Gradle, script plugins and binary plugins. Script plugins are additional build scripts that further configure the build and usually implement a declarative approach to manipulating the build. They are typically used within a build although they can be externalized and accessed from a remote location. Binary plugins are classes that implement the Plugin interface and adopt a programmatic approach to manipulating the build. Binary plugins can reside within a build script, within the project hierarchy or externally in a plugin jar.

Plugins are said to be applied, which is done via the Project.apply(java.util.Map) method. The application of plugins is idempotent. That is, the same plugin can be applied multiple times. If the plugin has previously been applied, any further applications are safe and will have no effect.

apply from: 'other.gradle'

apply plugin: 'java'

apply plugin: JavaPlugin

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 Section 41.6, “External dependencies for the build script”.

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

apply plugin: "com.jfrog.bintray"

The new plugins DSL provides a more succinct and convenient way to declare plugin dependencies. It works with the new Gradle plugin portal to provide easy access to both core and community plugins. The plugins script block configures an instance of PluginDependenciesSpec.

To apply a core plugin, the short name can be used:

plugins {
    id 'java'
}

To apply a community plugin from the portal, the fully qualified plugin id must be used:

plugins {
    id "com.jfrog.bintray" version "0.4.1"
}

No further configuration is necessary. Specifically, there is no need to configure the buildscript classpath. Gradle will resolve the plugin in the plugin portal, locate it, and make it available to the build.

See PluginDependenciesSpec for more information on using the Plugin DSL.

plugins {
    id «plugin id» version «plugin version»
}
                

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:

Gradle has a vibrant community of plugin developers who contribute plugins for a wide variety of capabilities. The Gradle plugin portal provides an interface for searching and exploring community plugins.

This chapter aims to serve as an introduction to plugins and Gradle and the role they play. For more information on the inner workings of plugins, see Chapter 39, Writing Custom Plugins.