Build Script Basics
This chapter introduces you to the basics of writing Gradle build scripts. It uses toy examples to explain basic functionality of Gradle, which is helpful to get an understanding of the basic concepts. Especially if you move to Gradle from other build tools like Ant and want to understand differences and advantages.
However, to get started with a standard project setup, you don’t even need to go into these concepts in detail. Instead, you can have a quick hands-on introduction, through our step-by-step tutorial.
Projects, plugins and tasks
Every Gradle build is made up of one or more projects. What a project represents depends on what it is that you are doing with Gradle. For example, a project might represent a library JAR or a web application. It might represent a distribution ZIP assembled from the JARs produced by other projects. A project does not necessarily represent a thing to be built. It might represent a thing to be done, such as deploying your application to staging or production environments. Don’t worry if this seems a little vague for now. Gradle’s build-by-convention support adds a more concrete definition for what a project is.
The work that Gradle can do on a project is defined by one or more tasks. A task represents some atomic piece of work which a build performs. This might be compiling some classes, creating a JAR, generating Javadoc, or publishing some archives to a repository.
Typically, tasks are provided by applying a plugin so that you do not have to define them yourself. Still, to give you an idea of what a task is, we will look at defining some simple tasks in a build with one project in this chapter.
Hello world
You run a Gradle build using the gradle command. The gradle command looks for a file called build.gradle.kts in the current directory.[1] We call this build.gradle.kts file a build script, although strictly speaking it is a build configuration script, as we will see later. The build script defines a project and its tasks.
To try this out, create the following build script named build.gradle.kts.
You run a Gradle build using the gradle command. The gradle command looks for a file called build.gradle in the current directory.[2] We call this build.gradle file a build script, although strictly speaking it is a build configuration script, as we will see later. The build script defines a project and its tasks.
To try this out, create the following build script named build.gradle.
tasks.register("hello") {
doLast {
println("Hello world!")
}
}tasks.register('hello') {
doLast {
println 'Hello world!'
}
}In a command-line shell, move to the containing directory and execute the build script with gradle -q hello:
|
What does
-q do?Most of the examples in this user guide are run with the |
gradle -q hello> gradle -q hello Hello world!
What’s going on here? This build script defines a single task, called hello, and adds an action to it. When you run gradle hello, Gradle executes the hello task, which in turn executes the action you’ve provided. The action is simply a block containing some code to execute.
If you think this looks similar to Ant’s targets, you would be right. Gradle tasks are the equivalent to Ant targets, but as you will see, they are much more powerful. We have used a different terminology than Ant as we think the word task is more expressive than the word target. Unfortunately this introduces a terminology clash with Ant, as Ant calls its commands, such as javac or copy, tasks. So when we talk about tasks, we always mean Gradle tasks, which are the equivalent to Ant’s targets. If we talk about Ant tasks (Ant commands), we explicitly say Ant task.
Build scripts are code
Gradle’s build scripts give you the full power of Groovy and Kotlin. As an appetizer, have a look at this:
tasks.register("upper") {
doLast {
val someString = "mY_nAmE"
println("Original: $someString")
println("Upper case: ${someString.toUpperCase()}")
}
}tasks.register('upper') {
doLast {
String someString = 'mY_nAmE'
println "Original: $someString"
println "Upper case: ${someString.toUpperCase()}"
}
}gradle -q upper> gradle -q upper Original: mY_nAmE Upper case: MY_NAME
or
tasks.register("count") {
doLast {
repeat(4) { print("$it ") }
}
}tasks.register('count') {
doLast {
4.times { print "$it " }
}
}gradle -q count> gradle -q count 0 1 2 3
Task dependencies
As you probably have guessed, you can declare tasks that depend on other tasks.
tasks.register("hello") {
doLast {
println("Hello world!")
}
}
tasks.register("intro") {
dependsOn("hello")
doLast {
println("I'm Gradle")
}
}tasks.register('hello') {
doLast {
println 'Hello world!'
}
}
tasks.register('intro') {
dependsOn tasks.hello
doLast {
println "I'm Gradle"
}
}gradle -q intro> gradle -q intro Hello world! I'm Gradle
To add a dependency, the corresponding task does not need to exist.
tasks.register("taskX") {
dependsOn("taskY")
doLast {
println("taskX")
}
}
tasks.register("taskY") {
doLast {
println("taskY")
}
}tasks.register('taskX') {
dependsOn 'taskY'
doLast {
println 'taskX'
}
}
tasks.register('taskY') {
doLast {
println 'taskY'
}
}gradle -q taskX> gradle -q taskX taskY taskX
The dependency of taskX to taskY may be declared before taskY is defined.
Task dependencies are discussed in more detail in Adding dependencies to a task.
Flexible task registration
The power of Groovy or Kotlin can be used for more than defining what a task does. For example, you can use it to register multiple tasks of the same type in a loop.
repeat(4) { counter ->
tasks.register("task$counter") {
doLast {
println("I'm task number $counter")
}
}
}4.times { counter ->
tasks.register("task$counter") {
doLast {
println "I'm task number $counter"
}
}
}gradle -q task1> gradle -q task1 I'm task number 1
Manipulating existing tasks
Once tasks are registered, they can be accessed via an API. For instance, you could use this to dynamically add dependencies to a task, at runtime. Ant doesn’t allow anything like this.
repeat(4) { counter ->
tasks.register("task$counter") {
doLast {
println("I'm task number $counter")
}
}
}
tasks.named("task0") { dependsOn("task2", "task3") }4.times { counter ->
tasks.register("task$counter") {
doLast {
println "I'm task number $counter"
}
}
}
tasks.named('task0') { dependsOn('task2', 'task3') }gradle -q task0> gradle -q task0 I'm task number 2 I'm task number 3 I'm task number 0
Or you can add behavior to an existing task.
tasks.register("hello") {
doLast {
println("Hello Earth")
}
}
tasks.named("hello") {
doFirst {
println("Hello Venus")
}
}
tasks.named("hello") {
doLast {
println("Hello Mars")
}
}
tasks.named("hello") {
doLast {
println("Hello Jupiter")
}
}tasks.register('hello') {
doLast {
println 'Hello Earth'
}
}
tasks.named('hello') {
doFirst {
println 'Hello Venus'
}
}
tasks.named('hello') {
doLast {
println 'Hello Mars'
}
}
tasks.named('hello') {
doLast {
println 'Hello Jupiter'
}
}gradle -q hello> gradle -q hello Hello Venus Hello Earth Hello Mars Hello Jupiter
The calls doFirst and doLast can be executed multiple times. They add an action to the beginning or the end of the task’s actions list. When the task executes, the actions in the action list are executed in order.
Using Ant Tasks
Ant tasks are first-class citizens in Gradle. Gradle provides excellent integration for Ant tasks by simply relying on Groovy. Groovy is shipped with the fantastic AntBuilder. Using Ant tasks from Gradle is as convenient and more powerful than using Ant tasks from a build.xml file. And it is usable from Kotlin too. From the example below, you can learn how to execute Ant tasks and how to access Ant properties:
tasks.register("loadfile") {
val resourceDirectory = file("./antLoadfileResources")
doLast {
val files = resourceDirectory.listFiles().sorted()
files.forEach { file ->
if (file.isFile) {
ant.withGroovyBuilder {
"loadfile"("srcFile" to file, "property" to file.name)
}
println(" *** ${file.name} ***")
println("${ant.properties[file.name]}")
}
}
}
}tasks.register('loadfile') {
def resourceDirectory = file('./antLoadfileResources')
doLast {
def files = resourceDirectory.listFiles().sort()
files.each { File file ->
if (file.isFile()) {
ant.loadfile(srcFile: file, property: file.name)
println " *** $file.name ***"
println "${ant.properties[file.name]}"
}
}
}
}gradle -q loadfile> gradle -q loadfile *** agile.manifesto.txt *** Individuals and interactions over processes and tools Working software over comprehensive documentation Customer collaboration over contract negotiation Responding to change over following a plan *** gradle.manifesto.txt *** Make the impossible possible, make the possible easy and make the easy elegant. (inspired by Moshe Feldenkrais)
There is lots more you can do with Ant in your build scripts. You can find out more in Ant.
Using methods
Gradle scales in how you can organize your build logic. The first level of organizing your build logic for the example above, is extracting a method.
tasks.register("checksum") {
doLast {
fileList("./antLoadfileResources").forEach { file ->
ant.withGroovyBuilder {
"checksum"("file" to file, "property" to "cs_${file.name}")
}
println("$file.name Checksum: ${ant.properties["cs_${file.name}"]}")
}
}
}
tasks.register("loadfile") {
doLast {
fileList("./antLoadfileResources").forEach { file ->
ant.withGroovyBuilder {
"loadfile"("srcFile" to file, "property" to file.name)
}
println("I'm fond of ${file.name}")
}
}
}
fun fileList(dir: String): List<File> =
file(dir).listFiles { file: File -> file.isFile }.sorted()tasks.register('checksum') {
doLast {
fileList('./antLoadfileResources').each { File file ->
ant.checksum(file: file, property: "cs_$file.name")
println "$file.name Checksum: ${ant.properties["cs_$file.name"]}"
}
}
}
tasks.register('loadfile') {
doLast {
fileList('./antLoadfileResources').each { File file ->
ant.loadfile(srcFile: file, property: file.name)
println "I'm fond of $file.name"
}
}
}
File[] fileList(String dir) {
file(dir).listFiles({file -> file.isFile() } as FileFilter).sort()
}gradle -q loadfile> gradle -q loadfile I'm fond of agile.manifesto.txt I'm fond of gradle.manifesto.txt
| Accessing top-level methods and variables is not yet compatible with the configuration cache. |
Later you will see that such methods can be shared among subprojects in multi-project builds. If your build logic becomes more complex, Gradle offers you other very convenient ways to organize it. We have devoted a whole chapter to this. See Organizing Gradle Projects.
Default tasks
Gradle allows you to define one or more default tasks that are executed if no other tasks are specified.
defaultTasks("clean", "run")
tasks.register("clean") {
doLast {
println("Default Cleaning!")
}
}
tasks.register("run") {
doLast {
println("Default Running!")
}
}
tasks.register("other") {
doLast {
println("I'm not a default task!")
}
}defaultTasks 'clean', 'run'
tasks.register('clean') {
doLast {
println 'Default Cleaning!'
}
}
tasks.register('run') {
doLast {
println 'Default Running!'
}
}
tasks.register('other') {
doLast {
println "I'm not a default task!"
}
}gradle -q> gradle -q Default Cleaning! Default Running!
This is equivalent to running gradle clean run. In a multi-project build every subproject can have its own specific default tasks. If a subproject does not specify default tasks, the default tasks of the parent project are used (if defined).
External dependencies for the build script
| Instead of manipulating the script classpath directly, it is recommended to apply plugins that come with their own classpath. For custom build logic, the recommendation is to use a custom plugin. |
If your build script needs to use external libraries, you can add them to the script’s classpath in the build script itself. You do this using the buildscript() method, passing in a block which declares the build script classpath.
buildscript {
repositories {
mavenCentral()
}
dependencies {
"classpath"(group = "commons-codec", name = "commons-codec", version = "1.2")
}
}buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath group: 'commons-codec', name: 'commons-codec', version: '1.2'
}
}The block passed to the buildscript() method configures a ScriptHandler instance.
You declare the build script classpath by adding dependencies to the classpath configuration.
This is the same way you declare, for example, the Java compilation classpath.
You can use any of the dependency types except project dependencies.
Having declared the build script classpath, you can use the classes in your build script as you would any other classes on the classpath. The following example adds to the previous example, and uses classes from the build script classpath.
import org.apache.commons.codec.binary.Base64
buildscript {
repositories {
mavenCentral()
}
dependencies {
"classpath"(group = "commons-codec", name = "commons-codec", version = "1.2")
}
}
tasks.register("encode") {
doLast {
val encodedString = Base64().encode("hello world\n".toByteArray())
println(String(encodedString))
}
}import org.apache.commons.codec.binary.Base64
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath group: 'commons-codec', name: 'commons-codec', version: '1.2'
}
}
tasks.register('encode') {
doLast {
def byte[] encodedString = new Base64().encode('hello world\n'.getBytes())
println new String(encodedString)
}
}gradle -q encode> gradle -q encode aGVsbG8gd29ybGQK
For multi-project builds, the dependencies declared with a project’s buildscript() method are available to the build scripts of all its sub-projects.
Build script dependencies may be Gradle plugins. Please consult Using Gradle Plugins for more information on Gradle plugins.
| Gradle instruments the bytecode on the build script classpath to provide backward compatibility and improved usability. Some libraries may fail integrity self-checks because of this. In this case, the use of such libraries should be isolated. |
Every project automatically has a buildEnvironment task of type BuildEnvironmentReportTask that can be invoked to report on the resolution of the build script dependencies.
Further Reading
This chapter only scratched the surface with what’s possible. Here are some other topics that may be interesting: