Anatomy of a Gradle Build

A Gradle build is made up of several key components that work together to automate tasks like compiling code, running tests, and packaging artifacts.

At a high level, a build includes:

Projects, which represent things you’re building (like apps or libraries)
Tasks, which define the work to do (like compiling or testing)
Build scripts, which configure the projects and tasks
Plugins, which extend the build with reusable logic

Let’s first quickly review the directories in a simple Gradle project to better understand the components of a build:

gradle-project          (1)
├── app
│   ├── build.gradle.kts    (2)
│   └── ...
├── settings.gradle.kts     (3)
├── gradle                  (4)
│   └── ...
├── gradlew             (5)
└── gradlew.bat         (5)

gradle-project      (1)
├── app
│   ├── build.gradle    (2)
│   └── ...
├── settings.gradle     (3)
├── gradle              (4)
│   └── ...
├── gradlew                 (5)
└── gradlew.bat             (5)

1	Root Directory - Gradle Project
2	Build Script - Project-level configuration
3	Settings File - Project inclusion and build identity
4	Gradle Files - Wrapper executables and version pinning
5	Gradle Wrapper - Script that automatically downloads and runs the correct Gradle version for a project

This basic Gradle build has a root project called gradle-project and contains one subproject called app.

The settings file in the root directory lets Gradle know about the structure of the build.

The build file in the app directory contains build logic specific to the app subproject such as declaring dependencies and applying plugins.

Build Directory

The build/ directory is the default output directory at the root of each project where Gradle places all generated files during a build.

It is created automatically when you run tasks like build, assemble, test, or others that produce outputs:

gradle-project
├── app
│   ├── build.gradle.kts
│   └── ...
├── settings.gradle.kts
├── gradle
│   └── ...
├── build                   (1)
├── gradlew
└── gradlew.bat

gradle-project
├── app
│   ├── build.gradle
│   └── ...
├── settings.gradle
├── gradle
│   └── ...
├── build                   (1)
├── gradlew
└── gradlew.bat

1	Build directory

To remove the entire build/ directory and all its contents, use:

$ ./gradlew clean

This is useful when you want to ensure a fresh build with no leftover outputs.

Gradle creates the build directory by default, so it must be writable. If a custom build directory is specified, it must exist and also be writable.

Gradle uses two main directories to perform and manage its work: the Gradle User Home Directory and the Project Root Directory.

Project Root Directory

The Project Root Directory contains all source files from your project.

It also contains files and directories Gradle generates, such as .gradle and build, as well as the Gradle configuration directory: gradle.

The gradle and .gradle directories are different.

While gradle is usually checked into source control, build and .gradle directories contain the output of your builds, caches, and other transient files Gradle uses to support features like incremental builds.

In this case, ./gradle-project is the project root directory:

gradle-project  (1)
├── .gradle         (2)
│   ├── 4.8             (3)
│   ├── 4.9             (3)
│   └── ⋮
├── build           (4)
├── gradle
│   └── wrapper (5)
├── gradle.properties   (6)
├── gradlew         (7)
├── gradlew.bat     (7)
├── settings.gradle(.kts)   (8)
├── subproject-one              (9)
|   └── build.gradle(.kts)  (10)
├── subproject-two              (9)
|   └── build.gradle(.kts)  (10)
└── ⋮

1	Root Project
2	Project-specific cache directory generated by Gradle.
3	Version-specific caches (e.g., to support incremental builds).
4	The build directory of this project.
5	Contains the JAR file and configuration of the Gradle Wrapper.
6	Project-specific Gradle configuration properties.
7	Scripts for executing builds using the Gradle Wrapper.
8	The project’s settings file where the list of subprojects is defined.
9	Usually, a project is organized into one or multiple subprojects.
10	Each subproject has its own Gradle build script.

Gradle User Home Directory

By default, the Gradle User Home (~/.gradle or C:\Users\<USERNAME>\.gradle) stores global configuration properties, initialization scripts, caches, and log files.

It can be set with the environment variable GRADLE_USER_HOME. Note that this directory is often abbreviated as GUH.

GRADLE_USER_HOME is not to be confused with the GRADLE_HOME, the optional installation directory for Gradle.

It is roughly structured as follows:

~/.gradle   (1)
├── caches      (2)
│   ├── 4.8     (3)
│   ├── 4.9     (3)
│   ├── ⋮
│   ├── jars-3      (4)
│   └── modules-2   (4)
├── daemon              (5)
│   ├── ⋮
│   ├── 4.8
│   └── 4.9
├── init.d                  (6)
│   └── my-setup.gradle
├── jdks                    (7)
│   ├── ⋮
│   └── jdk-14.0.2+12
├── wrapper
│   └── dists                   (8)
│       ├── ⋮
│       ├── gradle-4.8-bin
│       ├── gradle-4.9-all
│       └── gradle-4.9-bin
└── gradle.properties           (9)

1	Gradle User Home
2	Global cache directory (for everything that is not project-specific).
3	Version-specific caches (e.g., to support incremental builds).
4	Shared caches (e.g., for artifacts of dependencies).
5	Registry and logs of the Gradle Daemon.
6	Global initialization scripts.
7	JDKs downloaded by the toolchain support.
8	Distributions downloaded by the Gradle Wrapper.
9	Global Gradle configuration properties.

Next Step: Learn how to structure Multi-Project Builds >>