Anatomy of a Gradle build script: the key to understanding Gradle

Last Updated on March 22, 2021

Did you every look at a Gradle build script and end up scratching your head? Even the simple ones can be tricky to understand if you don’t know the basic building blocks of the build.gradle file, the Gradle build script.

To better understand Gradle, it’s helpful to know that the build script normally consists of nothing more than the following components.

1. Plugins

Plugins are Gradle-specific bundles of functionality to enhance how it runs your build. Define which plugins should be included like this:

plugins {
    id 'java'                          //core plugin, no version required
    id "org.sonarqube" version "2.8"   //community plugin, version required
}

There are loads of free plugins that do cool stuff in your build. ✅ Search for plugins over at the Gradle Plugin Portal.

2. Dependencies

Dependencies are requirements for building your application/library itself. For example:

dependencies {
    implementation group: 'org.apache.commons', name: 'commons-lang3', version: '3.0'
}

The above definition says that in order to build your application, the commons-lang3 library must be added to the Java classpath (that’s what implementation means). For a full description of what is an implementation dependency see Gradle implementation vs. compile dependencies.

Tip for preserving your sanity: if you’re reading a build script for a larger project, the list of dependencies can be very long. Fortunately in IDEs like IntelliJ IDEA you can hide blocks of the build script like this, so it just shows dependencies {...}.

3. Repositories

Not the most exciting part of the build script, but still very important, the repositories section says where you’re going to pull dependencies from.

Let’s take the commons-lang3 dependency mentioned above as an example. I happen to know that this artifact is published to Maven, like most good stuff in this world. 😊 Well you need to tell Gradle to look in Maven, which we do like this:

repositories {
    mavenCentral()
}

You can also tell Gradle to look in other places too, like:

• your local Maven repository
• a custom Maven repository
• jcenter

4. Tasks

Tasks are units of work executed during your build. They can be defined by plugins, or inline like this:

task copyDocs(type: Copy) {     
    from 'src/main/doc'     
    into 'build/doc' 
} 

The above task would copy the contents of src/main/doc to build/doc. I don’t know why you’d want to that, but it’s just an example! 👌

Once a task is defined, it can be run using ./gradlew <task-name>.

gradlew gradle what? In case you didn’t know, gradlew is just a script you use to run Gradle in a project. It makes sure you’re running the right version of Gradle for the project. Read all about this Gradle wrapper script in this article.

Normally plugins expose specific tasks that do useful stuff in your build. For example the java plugin adds the compileJava and jar tasks, amongst others. Could be pretty handy to build a Java project don’t you think?

5. Configuration blocks

Usually a plugin that gets applied has it’s own predefined way of configuring it. For example, if I apply the SonarQube plugin:

plugins {
   id "org.sonarqube" version "2.7"
}

I can then define a configuration block like this:

sonarqube {
    properties {
        property "sonar.sources", "src"
    }
}

This is important to know, because in many build.gradle files the majority of what you see is configurations for various plugins. If it’s not clear what plugin the configuration block refers to, check the list of plugins at the top, or Control + Click the configuration block name (in IntelliJ IDEA) to jump into the plugin source itself.

SonarQube what what? It’s just an example of a plugin with configuration, but since you asked SonarQube analyses your code to see if there are any problems as well as check how good is your test coverage. For full details about how to set it up in Gradle check out this article.

Full Gradle build file

Based on the components discussed above, here’s a build.gradle file with the contents of each section minimised.

If you want to see a real life build file in the wild, have a look at this GitHub repository’s build.gradle file. You can even clone the project and build it, if you’re feeling adventurous. 🐯

Next steps

Now you know about its basic building blocks, you should be able to better understand Gradle build files and more effectively write them. If you want to take your knowledge to the next level, check out my Gradle tutorials.

If you’re still feeling confused, I suggest you run through this official Gradle tutorial or perhaps watch the below introduction to Gradle video on the Tom Gregory Tech YouTube channel. People tell me it’s helpful!