As we’ve seen, tasks come with a set of intrinsic properties which are indispensable to the Gradle user. However, we can also assign any other properties we want to a task. A task object functions like a hash map, able to contain whatever other arbitrary property names and values we care to assign to it (as long as the names don’t collide with the built-in property names).

Leaving our familiar “hello, world” example, let’s suppose we had a task called createArtifact that depended on a task called copyFiles. The job of the copyFiles is to collect files from several sources and copy them into a staging directory, which the createArtifact task will later assemble into a deployment artifact. The list of files may change depending on the parameters of the build, but the artifact must contain a manifest listing them, to satisfy some requirement of the deployed application. This is a perfect occasion to use a dynamic property (Example 2-31 and Example 2-32).

task copyFiles {
  // Find files from wherever, copy them
  // (then hardcode a list of files for illustration)
  fileManifest = [ 'data.csv', 'config.json' ]
}

task createArtifact(dependsOn: copyFiles) << {
  println "FILES IN MANIFEST: ${copyFiles.fileManifest}"
}

$ gradle -b dynamic.gradle createArtifact
 FILES IN MANIFEST: [data.csv, config.json]
$

A copy task copies files from one place into another (Example 2-33). In its most basic form, it copies files from one directory into another, with optional restrictions on which file patterns are included or excluded.

task copyFiles(type: Copy) {
  from 'resources'
  into 'target'
  include '**/*.xml', '**/*.txt', '**/*.properties'
}

The copy task will create the destination directory if it doesn’t already exist. In this case, the copyFiles task will copy any files with the .xml, .properties, or .txt extensions from the resources directory to the target directory. Note that the from, into, and include methods are inherited from the Copy.

A Jar task creates a Jar file from source files (Example 2-34). The Java plug-in creates a task of this type, called unsurprisingly jar. It packages the main source set and resources together with a trivial manifest into a Jar bearing the project’s name in the build/libs directory. The task is highly customizable.

apply plugin: 'java'

task customJar(type: Jar) {
  manifest {
    attributes firstKey: 'firstValue', secondKey: 'secondValue'
  }
  archiveName = 'hello.jar'
  destinationDir = file("${buildDir}/jars")
  from sourceSets.main.classes
}

Note that the archive name and destination directory are easily configurable. Likewise, the manifest can be populated with custom attributes using a readable Groovy map syntax. The contents of the JAR are identified by the from sourceSets.main.classes line, which specifies that the compiled .class files of the main Java sources are to be included. The from method is identical to the one used in the CopyTask example, which reveals an interesting insight: the Jar task extends the Copy task. Even before we’ve seen exhaustive documentation of the Gradle object model and DSL, these details hint at the richness and order of the underlying structure.

The expression being assigned to destinationDir is worth noting. It would be natural just to assign a string to destinationDir, but the property expects an argument compatible with java.io.File. The file() method, which is always available inside a Gradle build file, converts the string to a File object.

A JavaExec task runs a Java class with a main() method. Command-line Java can be a hassle, but this task tries to take the hassle away and integrate command-line Java invocations into your build.

apply plugin: 'java'

repositories {
  mavenCentral()
}

dependencies {
  runtime 'commons-codec:commons-codec:1.5'
}

task encode(type: JavaExec, dependsOn: classes) {
  main = 'org.gradle.example.commandline.MetaphoneEncoder'
  args = "The rain in Spain falls mainly in the plain".split().toList()
  classpath sourceSets.main.classesDir
  classpath configurations.runtime
}

This build file declares an external dependency: the Apache Commons Codec library. Normally, we’d have to compile our Java file, then concoct a java command line including the path to the compiled class files and the JAR dependency. In this build file, however, we simply identify the main class to be run (org.gradle.example.commandline.MetaphoneEncoder), provide it with some command line arguments in the form of a List, and point it at the Gradle classpath elements it needs. In this case, we may symbolically refer to the classes of the main sourceSet and all of the dependencies declared in the compile configuration. If we had a complex set of dozens of dependencies from multiple repositories—including even some statically managed dependencies in the project directory—this simple task would still work.

Suppose your build file needs to issue arbitrary queries against a MySQL database. There are several ways to accomplish this in Gradle, but you decide a custom task is the most expressive way to do it. The easiest way to introduce the task is simply to create it in your build script as shown here:

task createDatabase(type: MySqlTask) {
  sql = 'CREATE DATABASE IF NOT EXISTS example'
}

task createUser(type: MySqlTask, dependsOn: createDatabase) {
  sql = "GRANT ALL PRIVILEGES ON example.* 
  TO exampleuser@localhost IDENTIFIED BY 'passw0rd'"
}

task createTable(type: MySqlTask, dependsOn: createUser) {
  username = 'exampleuser'
  password = 'passw0rd'
  database = 'example'
  sql = 'CREATE TABLE IF NOT EXISTS users 
  (id BIGINT PRIMARY KEY, username VARCHAR(100))'
}

class MySqlTask extends DefaultTask {
  def hostname = 'localhost'
  def port = 3306
  def sql
  def database
  def username = 'root'
  def password = 'password'

  @TaskAction
  def runQuery() {
    def cmd
    if(database) {
      cmd = "mysql -u ${username} -p${password} -h ${hostname} 
      -P ${port} ${database} -e "
    }
    else {
      cmd = "mysql -u ${username} -p${password} -h ${hostname} -P ${port} -e "
    }
    project.exec {
      commandLine = cmd.split().toList() + sql
    }
  }
}

The custom task, MySqlTask, extends the DefaultTask class. All custom tasks must extend this class or one of its descendants. (A custom task can extend any task types other than DefaultTask. See Task Types for a description of the most important built-in task types.) The task declares properties (i.e., hostname, database, sql, etc.) in conventional Groovy idiom. It then declares a single method, runQuery(), which is annotated with the @TaskAction annotation. This method will run when the task runs.

The actual build tasks at the top of the build file all declare themselves to be of the MySqlTask type. By doing this, they automatically inherit the properties and action of that task class. Because most of the properties have defaults (some of which, like username and password, are obviously specific to the build), each invocation of the task has very little to configure. The createDatabase and createUser tasks are able to configure just a single SQL query, and allow the defaults to take over from there.

The createTable task overrides the username, password, and database properties, since its task dependencies have created a new database and username separate from the default administrative settings. The pattern of providing a useful default configuration which can be overridden when necessary is a recurring theme in Gradle.

Significant custom task logic will not fit well into a build file. A few simple lines of scripting can pragmatically be inserted into a short task, as in the custom-task example. However, at some point, a sophisticated task will develop a class hierarchy of its own, might develop a reliance on external APIs, and will need automated testing. The build is code, and complex build code should be treated as a first-class citizen of the development world. Gradle makes this easy.

When custom task logic outgrows the build file, we can migrate it to the buildSrc directory at the project root. This directory is automatically compiled and added to the build classpath. Here is how we would alter the previous example to use the buildSrc directory.

task createDatabase(type: MySqlTask) {
  sql = 'CREATE DATABASE IF NOT EXISTS example'
}

task createUser(type: MySqlTask, dependsOn: createDatabase) {
  sql = "GRANT ALL PRIVILEGES ON example.* 
        TO exampleuser@localhost IDENTIFIED BY 'passw0rd'"
}

task createTable(type: MySqlTask, dependsOn: createUser) {
  username = 'exampleuser'
  password = 'passw0rd'
  database = 'example'
  sql = 'CREATE TABLE IF NOT EXISTS users 
        (id BIGINT PRIMARY KEY, username VARCHAR(100))'
}

import org.gradle.api.DefaultTask
import org.gradle.api.tasks.TaskAction

class MySqlTask extends DefaultTask {
  def hostname = 'localhost'
  def port = 3306
  def sql
  def database
  def username = 'root'
  def password = 'password'

  @TaskAction
  def runQuery() {
    def cmd
    if(database) {
      cmd = "mysql -u ${username} -p${password} -h ${hostname} 
            -P ${port} ${database} -e "
    }
    else {
      cmd = "mysql -u ${username} -p${password} -h ${hostname} -P ${port} -e "
    }
    project.exec {
      commandLine = cmd.split().toList() + sql
    }
  }
}

Note that the task definition in the buildSrc directory is very similar to the code included in the build script in the previous example. However, we now have a robust platform for elaborating on that simple task behavior, growing an object model, writing tests, and doing everything else we normally do when developing software.

.
├── build.gradle
├── buildSrc
│   └── src
│       └── main
│           └── groovy
│               └── org
│                   └── gradle
│                       └── example
│                           └── task
│                               └── MySqlTask.groovy