Implementing Binary Plugins
- Using the Plugin Development plugin
- Creating a plugin ID
- Working with files
- Making a plugin configurable using extensions
- Declaring a DSL configuration container
- Modeling DSL-like APIs
- Mapping extension properties to task properties
- Adding default configuration with conventions
- Separating capabilities from conventions
- Reacting to plugins
- Reacting to build features
- Using a custom
dependencies
block - Providing default dependencies
- Providing multiple variants of a plugin
- Reporting problems
Binary plugins refer to plugins that are compiled and distributed as JAR files. These plugins are usually written in Java or Kotlin and provide custom functionality or tasks to a Gradle build.
Using the Plugin Development plugin
The Gradle Plugin Development plugin can be used to assist in developing Gradle plugins.
This plugin will automatically apply the Java Plugin, add the gradleApi()
dependency to the api
configuration, generate the required plugin descriptors in the resulting JAR file, and configure the Plugin Marker Artifact to be used when publishing.
To apply and configure the plugin, add the following code to your build file:
plugins {
`java-gradle-plugin`
}
gradlePlugin {
plugins {
create("simplePlugin") {
id = "org.example.greeting"
implementationClass = "org.example.GreetingPlugin"
}
}
}
plugins {
id 'java-gradle-plugin'
}
gradlePlugin {
plugins {
simplePlugin {
id = 'org.example.greeting'
implementationClass = 'org.example.GreetingPlugin'
}
}
}
Writing and using custom task types is recommended when developing plugins as it automatically benefits from incremental builds.
As an added benefit of applying the plugin to your project, the task validatePlugins
automatically checks for an existing input/output annotation for every public property defined in a custom task type implementation.
Creating a plugin ID
Plugin IDs are meant to be globally unique, similar to Java package names (i.e., a reverse domain name). This format helps prevent naming collisions and allows grouping plugins with similar ownership.
An explicit plugin identifier simplifies applying the plugin to a project.
Your plugin ID should combine components that reflect the namespace (a reasonable pointer to you or your organization) and the name of the plugin it provides.
For example, if your Github account is named foo
and your plugin is named bar
, a suitable plugin ID might be com.github.foo.bar
.
Similarly, if the plugin was developed at the baz
organization, the plugin ID might be org.baz.bar
.
Plugin IDs should adhere to the following guidelines:
-
May contain any alphanumeric character, '.', and '-'.
-
Must contain at least one '.' character separating the namespace from the plugin’s name.
-
Conventionally use a lowercase reverse domain name convention for the namespace.
-
Conventionally use only lowercase characters in the name.
-
org.gradle
,com.gradle
, andcom.gradleware
namespaces may not be used. -
Cannot start or end with a '.' character.
-
Cannot contain consecutive '.' characters (i.e., '..').
A namespace that identifies ownership and a name is sufficient for a plugin ID.
When bundling multiple plugins in a single JAR artifact, adhering to the same naming conventions is recommended. This practice helps logically group related plugins.
There is no limit to the number of plugins that can be defined and registered (by different identifiers) within a single project.
The identifiers for plugins written as a class should be defined in the project’s build script containing the plugin classes.
For this, the java-gradle-plugin
needs to be applied:
plugins {
id("java-gradle-plugin")
}
gradlePlugin {
plugins {
create("androidApplicationPlugin") {
id = "com.android.application"
implementationClass = "com.android.AndroidApplicationPlugin"
}
create("androidLibraryPlugin") {
id = "com.android.library"
implementationClass = "com.android.AndroidLibraryPlugin"
}
}
}
plugins {
id 'java-gradle-plugin'
}
gradlePlugin {
plugins {
androidApplicationPlugin {
id = 'com.android.application'
implementationClass = 'com.android.AndroidApplicationPlugin'
}
androidLibraryPlugin {
id = 'com.android.library'
implementationClass = 'com.android.AndroidLibraryPlugin'
}
}
}
Working with files
When developing plugins, it’s a good idea to be flexible when accepting input configuration for file locations.
It is recommended to use Gradle’s managed properties and project.layout
to select file or directory locations.
This will enable lazy configuration so that the actual location will only be resolved when the file is needed and can be reconfigured at any time during build configuration.
This Gradle build file defines a task GreetingToFileTask
that writes a greeting to a file.
It also registers two tasks: greet
, which creates the file with the greeting, and sayGreeting
, which prints the file’s contents.
The greetingFile
property is used to specify the file path for the greeting:
abstract class GreetingToFileTask : DefaultTask() {
@get:OutputFile
abstract val destination: RegularFileProperty
@TaskAction
fun greet() {
val file = destination.get().asFile
file.parentFile.mkdirs()
file.writeText("Hello!")
}
}
val greetingFile = objects.fileProperty()
tasks.register<GreetingToFileTask>("greet") {
destination = greetingFile
}
tasks.register("sayGreeting") {
dependsOn("greet")
val greetingFile = greetingFile
doLast {
val file = greetingFile.get().asFile
println("${file.readText()} (file: ${file.name})")
}
}
greetingFile = layout.buildDirectory.file("hello.txt")
abstract class GreetingToFileTask extends DefaultTask {
@OutputFile
abstract RegularFileProperty getDestination()
@TaskAction
def greet() {
def file = getDestination().get().asFile
file.parentFile.mkdirs()
file.write 'Hello!'
}
}
def greetingFile = objects.fileProperty()
tasks.register('greet', GreetingToFileTask) {
destination = greetingFile
}
tasks.register('sayGreeting') {
dependsOn greet
doLast {
def file = greetingFile.get().asFile
println "${file.text} (file: ${file.name})"
}
}
greetingFile = layout.buildDirectory.file('hello.txt')
$ gradle -q sayGreeting Hello! (file: hello.txt)
In this example, we configure the greet
task destination
property as a closure/provider, which is evaluated with
the Project.file(java.lang.Object) method to turn the return value of the closure/provider into a File
object at the last minute.
Note that we specify the greetingFile
property value after the task configuration.
This lazy evaluation is a key benefit of accepting any value when setting a file property and then resolving that value when reading the property.
You can learn more about working with files lazily in Working with Files.
Making a plugin configurable using extensions
Most plugins offer configuration options for build scripts and other plugins to customize how the plugin works. Plugins do this using extension objects.
A Project has an associated ExtensionContainer object that contains all the settings and properties for the plugins that have been applied to the project. You can provide configuration for your plugin by adding an extension object to this container.
An extension object is simply an object with Java Bean properties representing the configuration.
Let’s add a greeting
extension object to the project, which allows you to configure the greeting:
interface GreetingPluginExtension {
val message: Property<String>
}
class GreetingPlugin : Plugin<Project> {
override fun apply(project: Project) {
// Add the 'greeting' extension object
val extension = project.extensions.create<GreetingPluginExtension>("greeting")
// Add a task that uses configuration from the extension object
project.task("hello") {
doLast {
println(extension.message.get())
}
}
}
}
apply<GreetingPlugin>()
// Configure the extension
the<GreetingPluginExtension>().message = "Hi from Gradle"
interface GreetingPluginExtension {
Property<String> getMessage()
}
class GreetingPlugin implements Plugin<Project> {
void apply(Project project) {
// Add the 'greeting' extension object
def extension = project.extensions.create('greeting', GreetingPluginExtension)
// Add a task that uses configuration from the extension object
project.task('hello') {
doLast {
println extension.message.get()
}
}
}
}
apply plugin: GreetingPlugin
// Configure the extension
greeting.message = 'Hi from Gradle'
$ gradle -q hello Hi from Gradle
In this example, GreetingPluginExtension
is an object with a property called message
.
The extension object is added to the project with the name greeting
.
This object becomes available as a project property with the same name as the extension object.
the<GreetingPluginExtension>()
is equivalent to project.extensions.getByType(GreetingPluginExtension::class.java)
.
Often, you have several related properties you need to specify on a single plugin. Gradle adds a configuration block for each extension object, so you can group settings:
interface GreetingPluginExtension {
val message: Property<String>
val greeter: Property<String>
}
class GreetingPlugin : Plugin<Project> {
override fun apply(project: Project) {
val extension = project.extensions.create<GreetingPluginExtension>("greeting")
project.task("hello") {
doLast {
println("${extension.message.get()} from ${extension.greeter.get()}")
}
}
}
}
apply<GreetingPlugin>()
// Configure the extension using a DSL block
configure<GreetingPluginExtension> {
message = "Hi"
greeter = "Gradle"
}
interface GreetingPluginExtension {
Property<String> getMessage()
Property<String> getGreeter()
}
class GreetingPlugin implements Plugin<Project> {
void apply(Project project) {
def extension = project.extensions.create('greeting', GreetingPluginExtension)
project.task('hello') {
doLast {
println "${extension.message.get()} from ${extension.greeter.get()}"
}
}
}
}
apply plugin: GreetingPlugin
// Configure the extension using a DSL block
greeting {
message = 'Hi'
greeter = 'Gradle'
}
$ gradle -q hello Hi from Gradle
In this example, several settings can be grouped within the configure<GreetingPluginExtension>
block.
The configure
function is used to configure an extension object.
It provides a convenient way to set properties or apply configurations to these objects.
The type used in the build script’s configure
function (GreetingPluginExtension
) must match the extension type.
Then, when the block is executed, the receiver of the block is the extension.
In this example, several settings can be grouped within the greeting
closure. The name of the closure block in the build script (greeting
) must match the extension object name.
Then, when the closure is executed, the fields on the extension object will be mapped to the variables within the closure based on the standard Groovy closure delegate feature.
Declaring a DSL configuration container
Using an extension object extends the Gradle DSL to add a project property and DSL block for the plugin. Because an extension object is a regular object, you can provide your own DSL nested inside the plugin block by adding properties and methods to the extension object.
Let’s consider the following build script for illustration purposes.
plugins {
id("org.myorg.server-env")
}
environments {
create("dev") {
url = "http://localhost:8080"
}
create("staging") {
url = "http://staging.enterprise.com"
}
create("production") {
url = "http://prod.enterprise.com"
}
}
plugins {
id 'org.myorg.server-env'
}
environments {
dev {
url = 'http://localhost:8080'
}
staging {
url = 'http://staging.enterprise.com'
}
production {
url = 'http://prod.enterprise.com'
}
}
The DSL exposed by the plugin exposes a container for defining a set of environments. Each environment the user configures has an arbitrary but declarative name and is represented with its own DSL configuration block. The example above instantiates a development, staging, and production environment, including its respective URL.
Each environment must have a data representation in code to capture the values. The name of an environment is immutable and can be passed in as a constructor parameter. Currently, the only other parameter the data object stores is a URL.
The following ServerEnvironment
object fulfills those requirements:
abstract public class ServerEnvironment {
private final String name;
@javax.inject.Inject
public ServerEnvironment(String name) {
this.name = name;
}
public String getName() {
return name;
}
abstract public Property<String> getUrl();
}
Gradle exposes the factory method ObjectFactory.domainObjectContainer(Class, NamedDomainObjectFactory) to create a container of data objects. The parameter the method takes is the class representing the data. The created instance of type NamedDomainObjectContainer can be exposed to the end user by adding it to the extension container with a specific name.
It’s common for a plugin to post-process the captured values within the plugin implementation, e.g., to configure tasks:
public class ServerEnvironmentPlugin implements Plugin<Project> {
@Override
public void apply(final Project project) {
ObjectFactory objects = project.getObjects();
NamedDomainObjectContainer<ServerEnvironment> serverEnvironmentContainer =
objects.domainObjectContainer(ServerEnvironment.class, name -> objects.newInstance(ServerEnvironment.class, name));
project.getExtensions().add("environments", serverEnvironmentContainer);
serverEnvironmentContainer.all(serverEnvironment -> {
String env = serverEnvironment.getName();
String capitalizedServerEnv = env.substring(0, 1).toUpperCase() + env.substring(1);
String taskName = "deployTo" + capitalizedServerEnv;
project.getTasks().register(taskName, Deploy.class, task -> task.getUrl().set(serverEnvironment.getUrl()));
});
}
}
In the example above, a deployment task is created dynamically for every user-configured environment.
You can find out more about implementing project extensions in Developing Custom Gradle Types.
Modeling DSL-like APIs
DSLs exposed by plugins should be readable and easy to understand.
For example, let’s consider the following extension provided by a plugin. In its current form, it offers a "flat" list of properties for configuring the creation of a website:
plugins {
id("org.myorg.site")
}
site {
outputDir = layout.buildDirectory.file("mysite")
websiteUrl = "https://gradle.org"
vcsUrl = "https://github.com/gradle/gradle-site-plugin"
}
plugins {
id 'org.myorg.site'
}
site {
outputDir = layout.buildDirectory.file("mysite")
websiteUrl = 'https://gradle.org'
vcsUrl = 'https://github.com/gradle/gradle-site-plugin'
}
As the number of exposed properties grows, you should introduce a nested, more expressive structure.
The following code snippet adds a new configuration block named siteInfo
as part of the extension.
This provides a stronger indication of what those properties mean:
plugins {
id("org.myorg.site")
}
site {
outputDir = layout.buildDirectory.file("mysite")
siteInfo {
websiteUrl = "https://gradle.org"
vcsUrl = "https://github.com/gradle/gradle-site-plugin"
}
}
plugins {
id 'org.myorg.site'
}
site {
outputDir = layout.buildDirectory.file("mysite")
siteInfo {
websiteUrl = 'https://gradle.org'
vcsUrl = 'https://github.com/gradle/gradle-site-plugin'
}
}
Implementing the backing objects for such an extension is simple.
First, introduce a new data object for managing the properties websiteUrl
and vcsUrl
:
abstract public class SiteInfo {
abstract public Property<String> getWebsiteUrl();
abstract public Property<String> getVcsUrl();
}
In the extension, create an instance of the siteInfo
class and a method to delegate the captured values to the data instance.
To configure underlying data objects, define a parameter of type Action.
The following example demonstrates the use of Action
in an extension definition:
abstract public class SiteExtension {
abstract public RegularFileProperty getOutputDir();
@Nested
abstract public SiteInfo getSiteInfo();
public void siteInfo(Action<? super SiteInfo> action) {
action.execute(getSiteInfo());
}
}
Mapping extension properties to task properties
Plugins commonly use an extension to capture user input from the build script and map it to a custom task’s input/output properties. The build script author interacts with the extension’s DSL, while the plugin implementation handles the underlying logic:
// Extension class to capture user input
class MyExtension {
@Input
var inputParameter: String? = null
}
// Custom task that uses the input from the extension
class MyCustomTask : org.gradle.api.DefaultTask() {
@Input
var inputParameter: String? = null
@TaskAction
fun executeTask() {
println("Input parameter: $inputParameter")
}
}
// Plugin class that configures the extension and task
class MyPlugin : Plugin<Project> {
override fun apply(project: Project) {
// Create and configure the extension
val extension = project.extensions.create("myExtension", MyExtension::class.java)
// Create and configure the custom task
project.tasks.register("myTask", MyCustomTask::class.java) {
group = "custom"
inputParameter = extension.inputParameter
}
}
}
// Extension class to capture user input
class MyExtension {
@Input
String inputParameter = null
}
// Custom task that uses the input from the extension
class MyCustomTask extends DefaultTask {
@Input
String inputParameter = null
@TaskAction
def executeTask() {
println("Input parameter: $inputParameter")
}
}
// Plugin class that configures the extension and task
class MyPlugin implements Plugin<Project> {
void apply(Project project) {
// Create and configure the extension
def extension = project.extensions.create("myExtension", MyExtension)
// Create and configure the custom task
project.tasks.register("myTask", MyCustomTask) {
group = "custom"
inputParameter = extension.inputParameter
}
}
}
In this example, the MyExtension
class defines an inputParameter
property that can be set in the build script.
The MyPlugin
class configures this extension and uses its inputParameter
value to configure the MyCustomTask
task.
The MyCustomTask
task then uses this input parameter in its logic.
You can learn more about types you can use in task implementations and extensions in Lazy Configuration.
Adding default configuration with conventions
Plugins should provide sensible defaults and standards in a specific context, reducing the number of decisions users need to make.
Using the project
object, you can define default values.
These are known as conventions.
Conventions are properties that are initialized with default values and can be overridden by the user in their build script. For example:
interface GreetingPluginExtension {
val message: Property<String>
}
class GreetingPlugin : Plugin<Project> {
override fun apply(project: Project) {
// Add the 'greeting' extension object
val extension = project.extensions.create<GreetingPluginExtension>("greeting")
extension.message.convention("Hello from GreetingPlugin")
// Add a task that uses configuration from the extension object
project.task("hello") {
doLast {
println(extension.message.get())
}
}
}
}
apply<GreetingPlugin>()
interface GreetingPluginExtension {
Property<String> getMessage()
}
class GreetingPlugin implements Plugin<Project> {
void apply(Project project) {
// Add the 'greeting' extension object
def extension = project.extensions.create('greeting', GreetingPluginExtension)
extension.message.convention('Hello from GreetingPlugin')
// Add a task that uses configuration from the extension object
project.task('hello') {
doLast {
println extension.message.get()
}
}
}
}
apply plugin: GreetingPlugin
$ gradle -q hello Hello from GreetingPlugin
In this example, GreetingPluginExtension
is a class that represents the convention.
The message property is the convention property with a default value of 'Hello from GreetingPlugin'.
Users can override this value in their build script:
GreetingPluginExtension {
message = "Custom message"
}
GreetingPluginExtension {
message = 'Custom message'
}
$ gradle -q hello
Custom message
Separating capabilities from conventions
Separating capabilities from conventions in plugins allows users to choose which tasks and conventions to apply.
For example, the Java Base plugin provides un-opinionated (i.e., generic) functionality like SourceSets
, while the Java plugin adds tasks and conventions familiar to Java developers like classes
, jar
or javadoc
.
When designing your own plugins, consider developing two plugins — one for capabilities and another for conventions — to offer flexibility to users.
In the example below, MyPlugin
contains conventions, and MyBasePlugin
defines capabilities.
Then, MyPlugin
applies MyBasePlugin
, this is called plugin composition.
To apply a plugin from another one:
import org.gradle.api.Plugin;
import org.gradle.api.Project;
public class MyBasePlugin implements Plugin<Project> {
public void apply(Project project) {
// define capabilities
}
}
import org.gradle.api.Plugin;
import org.gradle.api.Project;
public class MyPlugin implements Plugin<Project> {
public void apply(Project project) {
project.getPlugins().apply(MyBasePlugin.class);
// define conventions
}
}
Reacting to plugins
A common pattern in Gradle plugin implementations is configuring the runtime behavior of existing plugins and tasks in a build.
For example, a plugin could assume that it is applied to a Java-based project and automatically reconfigure the standard source directory:
public class InhouseStrongOpinionConventionJavaPlugin implements Plugin<Project> {
public void apply(Project project) {
// Careful! Eagerly appyling plugins has downsides, and is not always recommended.
project.getPlugins().apply(JavaPlugin.class);
SourceSetContainer sourceSets = project.getExtensions().getByType(SourceSetContainer.class);
SourceSet main = sourceSets.getByName(SourceSet.MAIN_SOURCE_SET_NAME);
main.getJava().setSrcDirs(Arrays.asList("src"));
}
}
The drawback to this approach is that it automatically forces the project to apply the Java plugin, imposing a strong opinion on it (i.e., reducing flexibility and generality). In practice, the project applying the plugin might not even deal with Java code.
Instead of automatically applying the Java plugin, the plugin could react to the fact that the consuming project applies the Java plugin. Only if that is the case, then a certain configuration is applied:
public class InhouseConventionJavaPlugin implements Plugin<Project> {
public void apply(Project project) {
project.getPlugins().withType(JavaPlugin.class, javaPlugin -> {
SourceSetContainer sourceSets = project.getExtensions().getByType(SourceSetContainer.class);
SourceSet main = sourceSets.getByName(SourceSet.MAIN_SOURCE_SET_NAME);
main.getJava().setSrcDirs(Arrays.asList("src"));
});
}
}
Reacting to plugins is preferred over applying plugins if there is no good reason to assume that the consuming project has the expected setup.
The same concept applies to task types:
public class InhouseConventionWarPlugin implements Plugin<Project> {
public void apply(Project project) {
project.getTasks().withType(War.class).configureEach(war ->
war.setWebXml(project.file("src/someWeb.xml")));
}
}
Reacting to build features
Plugins can access the status of build features in the build. The Build Features API allows checking whether the user requested a particular Gradle feature and if it is active in the current build. An example of a build feature is the configuration cache.
There are two main use cases:
-
Using the status of build features in reports or statistics.
-
Incrementally adopting experimental Gradle features by disabling incompatible plugin functionality.
Below is an example of a plugin that utilizes both of the cases.
public abstract class MyPlugin implements Plugin<Project> {
@Inject
protected abstract BuildFeatures getBuildFeatures(); (1)
@Override
public void apply(Project p) {
BuildFeatures buildFeatures = getBuildFeatures();
Boolean configCacheRequested = buildFeatures.getConfigurationCache().getRequested() (2)
.getOrNull(); // could be null if user did not opt in nor opt out
String configCacheUsage = describeFeatureUsage(configCacheRequested);
MyReport myReport = new MyReport();
myReport.setConfigurationCacheUsage(configCacheUsage);
boolean isolatedProjectsActive = buildFeatures.getIsolatedProjects().getActive() (3)
.get(); // the active state is always defined
if (!isolatedProjectsActive) {
myOptionalPluginLogicIncompatibleWithIsolatedProjects();
}
}
private String describeFeatureUsage(Boolean requested) {
return requested == null ? "no preference" : requested ? "opt-in" : "opt-out";
}
private void myOptionalPluginLogicIncompatibleWithIsolatedProjects() {
}
}
1 | The BuildFeatures service can be injected into plugins, tasks, and other managed types. |
2 | Accessing the requested status of a feature for reporting. |
3 | Using the active status of a feature to disable incompatible functionality. |
Build feature properties
A BuildFeature
status properties are represented with Provider<Boolean>
types.
The BuildFeature.getRequested()
status of a build feature determines if the user requested to enable or disable the feature.
When the requested
provider value is:
-
true
— the user opted in for using the feature -
false
— the user opted out from using the feature -
undefined
— the user neither opted in nor opted out from using the feature
The BuildFeature.getActive()
status of a build feature is always defined.
It represents the effective state of the feature in the build.
When the active
provider value is:
-
true
— the feature may affect the build behavior in a way specific to the feature -
false
— the feature will not affect the build behavior
Note that the active
status does not depend on the requested
status.
Even if the user requests a feature, it may still not be active due to other build options being used in the build.
Gradle can also activate a feature by default, even if the user did not specify a preference.
Using a custom dependencies
block
Custom dependencies blocks are based on incubating APIs.
|
A plugin can provide dependency declarations in custom blocks that allow users to declare dependencies in a type-safe and context-aware way.
For instance, instead of users needing to know and use the underlying Configuration
name to add dependencies, a custom dependencies
block lets the plugin pick a meaningful name that
can be used consistently.
Adding a custom dependencies
block
To add a custom dependencies
block, you need to create a new type that will represent the set of dependency scopes available to users.
That new type needs to be accessible from a part of your plugin (from a domain object or extension).
Finally, the dependency scopes need to be wired back to underlying Configuration
objects that will be used during dependency resolution.
See JvmComponentDependencies and JvmTestSuite for an example of how this is used in a Gradle core plugin.
1. Create an interface that extends Dependencies
You can also extend GradleDependencies to get access to Gradle-provided dependencies like gradleApi() .
|
/**
* Custom dependencies block for the example plugin.
*/
public interface ExampleDependencies extends Dependencies {
2. Add accessors for dependency scopes
For each dependency scope your plugin wants to support, add a getter method that returns a DependencyCollector
.
/**
* Dependency scope called "implementation"
*/
DependencyCollector getImplementation();
3. Add accessors for custom dependencies
block
To make the custom dependencies
block configurable, the plugin needs to add a getDependencies
method that returns the new type from above and a configurable block method named dependencies
.
By convention, the accessors for your custom dependencies
block should be called getDependencies()
/dependencies(Action)
.
This method could be named something else, but users would need to know that a different block can behave like a dependencies
block.
/**
* Custom dependencies for this extension.
*/
@Nested
ExampleDependencies getDependencies();
/**
* Configurable block
*/
default void dependencies(Action<? super ExampleDependencies> action) {
action.execute(getDependencies());
}
4. Wire dependency scope to Configuration
Finally, the plugin needs to wire the custom dependencies
block to some underlying Configuration
objects. If this is not done, none of the dependencies declared in the custom block will
be available to dependency resolution.
project.getConfigurations().dependencyScope("exampleImplementation", conf -> {
conf.fromDependencyCollector(example.getDependencies().getImplementation());
});
In this example, the name users will use to add dependencies is "implementation", but the underlying Configuration is named exampleImplementation .
|
example {
dependencies {
implementation("junit:junit:4.13")
}
}
example {
dependencies {
implementation("junit:junit:4.13")
}
}
Differences between the custom dependencies
and the top-level dependencies
blocks
Each dependency scope returns a DependencyCollector
that provides strongly-typed methods to add and configure dependencies.
There is also a DependencyFactory
with factory methods to create new dependencies from different notations.
Dependencies can be created lazily using these factory methods, as shown below.
A custom dependencies
block differs from the top-level dependencies
block in the following ways:
-
Dependencies must be declared using a
String
, an instance ofDependency
, aFileCollection
, aProvider
ofDependency
, or aProviderConvertible
ofMinimalExternalModuleDependency
. -
Outside of Gradle build scripts, you must explicitly call a getter for the
DependencyCollector
andadd
.-
dependencies.add("implementation", x)
becomesgetImplementation().add(x)
-
-
You cannot declare dependencies with the
Map
notation from Kotlin and Java. Use multi-argument methods instead in Kotlin and Java.-
Kotlin:
compileOnly(mapOf("group" to "foo", "name" to "bar"))
becomescompileOnly(module(group = "foo", name = "bar"))
-
Java:
compileOnly(Map.of("group", "foo", "name", "bar"))
becomesgetCompileOnly().add(module("foo", "bar", null))
-
-
You cannot add a dependency with an instance of
Project
. You must turn it into aProjectDependency
first. -
You cannot add version catalog bundles directly. Instead, use the
bundle
method on each configuration.-
Kotlin and Groovy:
implementation(libs.bundles.testing)
becomesimplementation.bundle(libs.bundles.testing)
-
-
You cannot use providers for non-
Dependency
types directly. Instead, map them to aDependency
using theDependencyFactory
.-
Kotlin and Groovy:
implementation(myStringProvider)
becomesimplementation(myStringProvider.map { dependencyFactory.create(it) })
-
Java:
implementation(myStringProvider)
becomesgetImplementation().add(myStringProvider.map(getDependencyFactory()::create)
-
-
Unlike the top-level
dependencies
block, constraints are not in a separate block.-
Instead, constraints are added by decorating a dependency with
constraint(…)
likeimplementation(constraint("org:foo:1.0"))
.
-
Keep in mind that the dependencies
block may not provide access to the same methods as the top-level dependencies
block.
Plugins should prefer adding dependencies via their own dependencies block.
|
Providing default dependencies
The implementation of a plugin sometimes requires the use of an external dependency.
You might want to automatically download an artifact using Gradle’s dependency management mechanism and later use it in the action of a task type declared in the plugin. Ideally, the plugin implementation does not need to ask the user for the coordinates of that dependency - it can simply predefine a sensible default version.
Let’s look at an example of a plugin that downloads files containing data for further processing. The plugin implementation declares a custom configuration that allows for assigning those external dependencies with dependency coordinates:
public class DataProcessingPlugin implements Plugin<Project> {
public void apply(Project project) {
Configuration dataFiles = project.getConfigurations().create("dataFiles", c -> {
c.setVisible(false);
c.setCanBeConsumed(false);
c.setCanBeResolved(true);
c.setDescription("The data artifacts to be processed for this plugin.");
c.defaultDependencies(d -> d.add(project.getDependencies().create("org.myorg:data:1.4.6")));
});
project.getTasks().withType(DataProcessing.class).configureEach(
dataProcessing -> dataProcessing.getDataFiles().from(dataFiles));
}
}
abstract public class DataProcessing extends DefaultTask {
@InputFiles
abstract public ConfigurableFileCollection getDataFiles();
@TaskAction
public void process() {
System.out.println(getDataFiles().getFiles());
}
}
This approach is convenient for the end user as there is no need to actively declare a dependency. The plugin already provides all the details about this implementation.
But what if the user wants to redefine the default dependency?
No problem. The plugin also exposes the custom configuration that can be used to assign a different dependency. Effectively, the default dependency is overwritten:
plugins {
id("org.myorg.data-processing")
}
dependencies {
dataFiles("org.myorg:more-data:2.6")
}
plugins {
id 'org.myorg.data-processing'
}
dependencies {
dataFiles 'org.myorg:more-data:2.6'
}
You will find that this pattern works well for tasks that require an external dependency when the task’s action is executed.
You can go further and abstract the version to be used for the external dependency by exposing an extension property (e.g.
toolVersion
in the JaCoCo plugin).
Minimizing the use of external libraries
Using external libraries in your Gradle projects can bring great convenience, but be aware that they can introduce complex dependency graphs.
Gradle’s buildEnvironment
task can help you visualize these dependencies, including those of your plugins.
Keep in mind that plugins share the same classloader, so conflicts may arise with different versions of the same library.
To demonstrate let’s assume the following build script:
plugins {
id("org.asciidoctor.jvm.convert") version "4.0.2"
}
plugins {
id 'org.asciidoctor.jvm.convert' version '4.0.2'
}
The output of the task clearly indicates the classpath of the classpath
configuration:
$ gradle buildEnvironment > Task :buildEnvironment ------------------------------------------------------------ Root project 'external-libraries' ------------------------------------------------------------ classpath \--- org.asciidoctor.jvm.convert:org.asciidoctor.jvm.convert.gradle.plugin:4.0.2 \--- org.asciidoctor:asciidoctor-gradle-jvm:4.0.2 +--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 | \--- org.tukaani:xz:1.6 +--- org.ysb33r.gradle:grolifant-herd:3.0.0 | +--- org.tukaani:xz:1.6 | +--- org.ysb33r.gradle:grolifant40:3.0.0 | | +--- org.tukaani:xz:1.6 | | +--- org.apache.commons:commons-collections4:4.4 | | +--- org.ysb33r.gradle:grolifant-core:3.0.0 | | | +--- org.tukaani:xz:1.6 | | | +--- org.apache.commons:commons-collections4:4.4 | | | \--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 (*) | | \--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 (*) | +--- org.ysb33r.gradle:grolifant50:3.0.0 | | +--- org.tukaani:xz:1.6 | | +--- org.ysb33r.gradle:grolifant40:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant-core:3.0.0 (*) | | \--- org.ysb33r.gradle:grolifant40-legacy-api:3.0.0 | | +--- org.tukaani:xz:1.6 | | +--- org.apache.commons:commons-collections4:4.4 | | +--- org.ysb33r.gradle:grolifant-core:3.0.0 (*) | | \--- org.ysb33r.gradle:grolifant40:3.0.0 (*) | +--- org.ysb33r.gradle:grolifant60:3.0.0 | | +--- org.tukaani:xz:1.6 | | +--- org.ysb33r.gradle:grolifant40:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant50:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant-core:3.0.0 (*) | | \--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 (*) | +--- org.ysb33r.gradle:grolifant70:3.0.0 | | +--- org.tukaani:xz:1.6 | | +--- org.ysb33r.gradle:grolifant40:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant50:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant60:3.0.0 (*) | | \--- org.ysb33r.gradle:grolifant-core:3.0.0 (*) | +--- org.ysb33r.gradle:grolifant80:3.0.0 | | +--- org.tukaani:xz:1.6 | | +--- org.ysb33r.gradle:grolifant40:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant50:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant60:3.0.0 (*) | | +--- org.ysb33r.gradle:grolifant70:3.0.0 (*) | | \--- org.ysb33r.gradle:grolifant-core:3.0.0 (*) | +--- org.ysb33r.gradle:grolifant-core:3.0.0 (*) | \--- org.ysb33r.gradle:grolifant-rawhide:3.0.0 (*) +--- org.asciidoctor:asciidoctor-gradle-base:4.0.2 | \--- org.ysb33r.gradle:grolifant-herd:3.0.0 (*) \--- org.asciidoctor:asciidoctorj-api:2.5.7 (*) - Indicates repeated occurrences of a transitive dependency subtree. Gradle expands transitive dependency subtrees only once per project; repeat occurrences only display the root of the subtree, followed by this annotation. A web-based, searchable dependency report is available by adding the --scan option. BUILD SUCCESSFUL in 0s 1 actionable task: 1 executed
A Gradle plugin does not run in its own, isolated classloader, so you must consider whether you truly need a library or if a simpler solution suffices.
For logic that is executed as part of task execution, use the Worker API that allows you to isolate libraries.
Providing multiple variants of a plugin
Variants of a plugin refer to different flavors or configurations of the plugin that are tailored to specific needs or use cases. These variants can include different implementations, extensions, or configurations of the base plugin.
The most convenient way to configure additional plugin variants is to use feature variants, a concept available in all Gradle projects that apply one of the Java plugins:
dependencies {
implementation 'com.google.guava:guava:30.1-jre' // Regular dependency
featureVariant 'com.google.guava:guava-gwt:30.1-jre' // Feature variant dependency
}
In the following example, each plugin variant is developed in isolation. A separate source set is compiled and packaged in a separate jar for each variant.
The following sample demonstrates how to add a variant that is compatible with Gradle 7.0+ while the "main" variant is compatible with older versions:
val gradle7 = sourceSets.create("gradle7")
java {
registerFeature(gradle7.name) {
usingSourceSet(gradle7)
capability(project.group.toString(), project.name, project.version.toString()) (1)
}
}
configurations.configureEach {
if (isCanBeConsumed && name.startsWith(gradle7.name)) {
attributes {
attribute(GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE, (2)
objects.named("7.0"))
}
}
}
tasks.named<Copy>(gradle7.processResourcesTaskName) { (3)
val copyPluginDescriptors = rootSpec.addChild()
copyPluginDescriptors.into("META-INF/gradle-plugins")
copyPluginDescriptors.from(tasks.pluginDescriptors)
}
dependencies {
"gradle7CompileOnly"(gradleApi()) (4)
}
def gradle7 = sourceSets.create('gradle7')
java {
registerFeature(gradle7.name) {
usingSourceSet(gradle7)
capability(project.group.toString(), project.name, project.version.toString()) (1)
}
}
configurations.configureEach {
if (canBeConsumed && name.startsWith(gradle7.name)) {
attributes {
attribute(GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE, (2)
objects.named(GradlePluginApiVersion, '7.0'))
}
}
}
tasks.named(gradle7.processResourcesTaskName) { (3)
def copyPluginDescriptors = rootSpec.addChild()
copyPluginDescriptors.into('META-INF/gradle-plugins')
copyPluginDescriptors.from(tasks.pluginDescriptors)
}
dependencies {
gradle7CompileOnly(gradleApi()) (4)
}
Only Gradle versions 7 or higher can be explicitly targeted by a variant, as support for this was only added in Gradle 7. |
First, we declare a separate source set and a feature variant for our Gradle 7 plugin variant. Then, we do some specific wiring to turn the feature into a proper Gradle plugin variant:
1 | Assign the implicit capability that corresponds to the components GAV to the variant. |
2 | Assign the Gradle API version attribute to all consumable configurations of our Gradle7 variant. Gradle uses this information to determine which variant to select during plugin resolution. |
3 | Configure the processGradle7Resources task to ensure the plugin descriptor file is added to the Gradle7 variant Jar. |
4 | Add a dependency to the gradleApi() for our new variant so that the API is visible during compilation time. |
Note that there is currently no convenient way to access the API of other Gradle versions as the one you are building the plugin with. Ideally, every variant should be able to declare a dependency on the API of the minimal Gradle version it supports. This will be improved in the future.
The above snippet assumes that all variants of your plugin have the plugin class at the same location.
That is, if your plugin class is org.example.GreetingPlugin
, you need to create a second variant of that class in src/gradle7/java/org/example
.
Using version-specific variants of multi-variant plugins
Given a dependency on a multi-variant plugin, Gradle will automatically choose its variant that best matches the current Gradle version when it resolves any of:
-
plugins specified in the
plugins {}
block; -
buildscript
classpath dependencies; -
dependencies in the root project of the build source (
buildSrc
) that appear on the compile or runtime classpath; -
dependencies in a project that applies the Java Gradle Plugin Development plugin or the Kotlin DSL plugin, appearing on the compile or runtime classpath.
The best matching variant is the variant that targets the highest Gradle API version and does not exceed the current build’s Gradle version.
In all other cases, a plugin variant that does not specify the supported Gradle API version is preferred if such a variant is present.
In projects that use plugins as dependencies, requesting the variants of plugin dependencies that support a different Gradle version is possible. This allows a multi-variant plugin that depends on other plugins to access their APIs, which are exclusively provided in their version-specific variants.
This snippet makes the plugin variant gradle7
defined above consume the matching variants of its dependencies on other multi-variant plugins:
configurations.configureEach {
if (isCanBeResolved && name.startsWith(gradle7.name)) {
attributes {
attribute(GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE,
objects.named("7.0"))
}
}
}
configurations.configureEach {
if (canBeResolved && name.startsWith(gradle7.name)) {
attributes {
attribute(GradlePluginApiVersion.GRADLE_PLUGIN_API_VERSION_ATTRIBUTE,
objects.named(GradlePluginApiVersion, '7.0'))
}
}
}
Reporting problems
Plugins can report problems through Gradle’s problem-reporting APIs. The APIs report rich, structured information about problems happening during the build. This information can be used by different user interfaces such as Gradle’s console output, Build Scans, or IDEs to communicate problems to the user in the most appropriate way.
The following example shows an issue reported from a plugin:
public class ProblemReportingPlugin implements Plugin<Project> {
private final ProblemReporter problemReporter;
@Inject
public ProblemReportingPlugin(Problems problems) { (1)
this.problemReporter = problems.forNamespace("org.myorg"); (2)
}
public void apply(Project project) {
this.problemReporter.reporting(builder -> builder (3)
.id("adhoc-deprecation", "Plugin 'x' is deprecated")
.details("The plugin 'x' is deprecated since version 2.5")
.solution("Please use plugin 'y'")
.severity(Severity.WARNING)
);
}
}
1 | The Problem service is injected into the plugin. |
2 | A problem reporter, is created for the plugin. While the namespace is up to the plugin author, it is recommended that the plugin ID be used. |
3 | A problem is reported. This problem is recoverable so that the build will continue. |
For a full example, see our end-to-end sample.
Problem building
When reporting a problem, a wide variety of information can be provided. The ProblemSpec describes all the information that can be provided.
Reporting problems
When it comes to reporting problems, we support three different modes:
-
Reporting a problem is used for reporting problems that are recoverable, and the build should continue.
-
Throwing a problem is used for reporting problems that are not recoverable, and the build should fail.
-
Rethrowing a problem is used to wrap an already thrown exception. Otherwise, the behavior is the same as
Throwing
.
For more details, see the ProblemReporter documentation.
Problem aggregation
When reporting problems, Gradle will aggregate similar problems by sending them through the Tooling API based on the problem’s category label.
-
When a problem is reported, the first occurrence is going to be reported as a ProblemDescriptor, containing the complete information about the problem.
-
Any subsequent occurrences of the same problem will be reported as a ProblemAggregationDescriptor. This descriptor will arrive at the end of the build and contain the number of occurrences of the problem.
-
If for any bucket (i.e., category and label pairing), the number of collected occurrences is greater than 10.000, then it will be sent immediately instead of at the end of the build.