21.3. Conventions

Plugins can pre-configure the project in smart ways to support convention-over-configuration. Gradle provides mechanisms and sophisticated support and it's a key ingredient i powerful-yet-concise build scripts.

We saw in the example above that the Java plugins adds a task named compileJava that has a property named destinationDir (that configures where the compiled Java source should be placed). The Java plugin defaults this property to point to build/classes/main in the project directory. This is an example of convention-over-configuration via a reasonable default.

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

Example 21.5. Changing plugin defaults

build.gradle

apply plugin: 'java'

compileJava.destinationDir = file("$buildDir/output/classes")

task show << {

println relativePath(compileJava.destinationDir)

}

Output of gradle -q show

> gradle -q show build/output/classes

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

The Java plugin adds the concept of source sets (see SourceSet) to describe the aspects of a set of source, one aspect being where the class files should be written to when it is compiled. The Java plugin maps the destinationDir property of the compileJava task to this aspect of the source set.

We can change where the class files are written via the source set.

Page 128 of 343

Example 21.6. Plugin convention object

build.gradle

apply plugin: 'java'

sourceSets.main.output.classesDir = file("$buildDir/output/classes")

task show << {

println relativePath(compileJava.destinationDir)

}

Output of gradle -q show

> gradle -q show build/output/classes

In the above example, we applied the Java plugin which, among other things, did the following:

Added a new domain object type: SourceSet

Configured a main source set with default (i.e. conventional) values for properties Configured supporting tasks to use these properties to perform work

All of this happened during the apply plugin: "java" step. In the example above we changed the desired location of the class files after this conventional configuration had been performed. Notice by the output with the example that the value for compileJava.destinationDir also changed to reflect the configuration change.

Consider the case where another task is to consume the classes files. If this task is configured to use the value from sourceSets.main.output.classesDir, then changing it in this location will update both the compileJava task and this other consumer task whenever it is changed.

This ability to configure properties of objects to reflect the value of another object's task at all time (i.e. even when it changes) is known as “convention mapping”. It allows Gradle to provide conciseness through convention-over-configuration and sensible defaults yet not require complete reconfiguration if a conventional default needs to be changed. Without this, in the above example we would have had to reconfigure every object that needs to work with the class files.

21.4. More on 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 51, Writing Custom Plugins.

Page 129 of 343

22

Standard Gradle plugins

There are a number of plugins included in the Gradle distribution. These are listed below.

22.1. Language plugins

These plugins add support for various languages which can be compiled and executed in the JVM.

Table 22.1. Language plugins

Plugin	Automatically	Works	Description
Id	applies	with
java	java-base	-	Adds Java compilation, testing and bundling
			capabilities to a project. It serves as the basis for
			many of the other Gradle plugins. See also Chapter 7,
			Java Quickstart.
groovy	java, groovy-base-		Adds support for building Groovy projects. See also
			Chapter 9, Groovy Quickstart.
scala	java, scala-base-		Adds support for building Scala projects.
antlr	java	-	Adds support for generating parsers using Antlr.

22.2. Experimental language plugins

These experimental plugins add support for various languages:

Page 130 of 343

Table 22.2. Language plugins
Plugin	Automatically	Works	Description
Id	applies	with
cpp	-	-	Adds C++ source compilation capabilities to a
			project.
cpp-exe	cpp	-	Adds C++ executable compilation and linking
			capabilities to a project.
cpp-lib	cpp	-	Adds C++ library compilation and linking
			capabilities to a project.

22.3. Integration plugins

These plugins provide some integration with various build and runtime technologies.

Page 131 of 343