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

Anatomy of a Gradle build file

Last Updated on November 25, 2022

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.

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 {

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

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!

Get going with Gradle course
Gradle icon

Want to learn more about Gradle?
Check out the full selection of Gradle tutorials.

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

9 thoughts on “Anatomy of a Gradle build script: the key to understanding Gradle

  1. Thanks for the great article. I’m wondering why you have used Groovy instead of Kotlin. Isn’t Kotlin replacing Groovy for Gradle scripts?

    1. Lots of people are still using Groovy for Gradle scripts. Choose which you prefer. I’m using Kotlin more in recent articles.

  2. Hi Gregory, Great articles !!

    I am struggling to include one gradle file in another.

    I basically want to define all versions and configuration in one gradle file and just add dependencies in another. Kind of like a parent child relationship.

    E.g. java-build.gradle will have the java plugin defined and java version set to 11. An there will be one more build.gradle in a completely different application and folder which “includes” the java-build.gradle and adds the dependencies on top of it (like apache commons deps).

    I have even asked a question on StackOverflow here –>

    Thank you!

    1. Hi Shrinath. I tried a similar example and saw this error when trying to use plugins in an apply from build script.

      Only Project and Settings build scripts can contain plugins {} blocks

      So looks like what you want to do isn’t possible this way.

      I found this StackOverflow post which might be a similar requirement to yours? The suggestion is to create a plugin, which sounds reasonable.

      Would this work for you?

      1. Hi Tom,

        Thank you for the answer. I checked the StackOverflow question and it does match my requirement. But as you suggested and as it is mentioned there, looks like a custom plugin is the only way forward.

        I am not sure if it will solve more problems that it will create. Will give it a try. Once again, thank you for your response!

  3. Hello ,i have a gradle project and I want to convert this to spring boot application how can i achieve it,can you please help me with this

    Thanks in Advance

Leave a Reply

Your email address will not be published. Required fields are marked *

Scroll to top


Getting started with Gradle just got A LOT easier!

Get Going with Gradle is the fastest way to a working knowledge of Gradle.

✅ Work effectively in basic Gradle projects
✅ Know how to setup Java projects in Gradle
✅ Understand the Gradle fundamentals

And it's yours today for FREE!

Where shall I send your access details?

Please wait...

Thank you, check your e-mail inbox for all the details!