Did you ever 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.

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 {

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

  • your local Maven repository
  • a custom Maven repository
  • Google Maven

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>.

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 its 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.

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 Gradle Hero YouTube channel. People tell me it’s helpful!


Check out the accompanying video from the Gradle Hero YouTube channel.