What Gradle actually is

The most-asked beginner question

Ask any group of new Android developers what confuses them most and this comes back more than anything else:

What is Gradle? Why is there a file called build.gradle.kts? Why does it keep failing at me about things I never wrote?

Here is the whole answer in one sentence, and then we will unpack every word of it.

Gradle is a program that reads your project's settings, downloads the libraries you asked for, compiles your code, and packs the result into an APK.

That is it. It is not a language, it is not part of Android, and it is not magic. It is a very literal-minded assistant that does four jobs in order.

The four jobs, in order

Every single build you ever run does these four things.

1. Read the settings. Which parts make up this project, where libraries may be downloaded from, which versions of everything.
2. Fetch what is missing. Download any library the project needs and does not already have, plus everything those libraries need.
3. Compile. Turn your Kotlin into bytecode, turn your res folder into a compiled lookup table, then turn the bytecode into dex.
4. Package and sign. Zip the lot into an APK and sign it so a phone will accept it.

Press Run in Pocket Studio and all four happen. Nothing else is going on behind the curtain.

Gradle knows nothing about Android

This is the fact that unlocks the rest.

Out of the box, Gradle is a general-purpose build tool. It can build a website, a game, a research paper. It has never heard of an Activity, an APK or the res folder.

Android arrives as a plugin — the Android Gradle Plugin, AGP for short. Adding it is what teaches Gradle every Android-specific step: merging manifests, compiling resources, making dex files, packaging APKs. This course pins AGP 8.7.3.

Two more plugins come along for the ride: the Kotlin plugin (Kotlin 2.1.0), which knows how to compile Kotlin, and the Compose plugin, which sets up the Compose compiler.

So when a build error mentions com.android.application, it is talking about AGP. When it mentions org.jetbrains.kotlin.android, it is the Kotlin plugin. Knowing which one is complaining halves the search.

The files that describe a build

A Dice Duel project has five build-related files. That is all of them.

settings.gradle.kts — the front door

app/build.gradle.kts — the recipe

This is the file you actually edit. Trimmed here to the parts that matter for this lesson:

libs.versions.toml — every version in one place

1[versions]
2agp = "8.7.3"
3kotlin = "2.1.0"
4composeBom = "2024.12.01"
5
6[plugins]
7android-application = { id = "com.android.application",
8  version.ref = "agp" }

Change a version once here and the whole project follows. That is the entire purpose of a version catalog, and it is why alias(libs.plugins.android.application) looks so indirect — the indirection is the point.

Tasks: the steps of the recipe

Gradle does not think in "builds". It thinks in tasks — small named units of work that declare what they need and what they produce.

Real task names from a real Android build:

1:app:preBuild
2:app:processDebugManifest
3:app:mergeDebugResources
4:app:processDebugResources
5:app:compileDebugKotlin
6:app:dexBuilderDebug
7:app:packageDebug
8:app:assembleDebug

Read those top to bottom and you have the four jobs again: settings, resources, compile, pack. The :app: prefix is the module name from settings.gradle.kts. Debug is the build type.

assembleDebug is the one Run uses. It does not do any work itself — it just depends on all the others, so asking for it drags the whole chain in behind it.

Gradle works out the order from the dependencies between tasks. You never write the order down.

Where the downloads come from

A dependency is written as three parts separated by colons:

1androidx.compose.material3:material3:1.3.1
2        group              name    version

Gradle asks google(), then mavenCentral(), until one of them has it. Then it asks that library what it needs, and fetches those too — the transitive dependencies. Ask for Material 3 and you also get Compose Foundation, Compose UI, Compose Runtime and a dozen more, without typing a word.

You can see the whole tree:

./gradlew :app:dependencies

Dice Duel declares eight lines of dependencies and resolves to about forty modules. That number matters a great deal on a phone, which is the whole of Lesson 2.6.

The wrapper and the daemon

Two pieces of Gradle machinery worth naming, because both show up in error messages.

The wrapper. Your project contains a small script, gradlew, and a properties file naming an exact Gradle version:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip

Nobody has to install Gradle. The wrapper downloads the pinned version on first use and every build after that uses it. This course pins Gradle 8.11.1 so that every reader, on every phone, runs an identical build.

The daemon. Gradle runs inside a JVM, and starting a JVM is slow. So Gradle leaves one running in the background after your build finishes. The next build hands its work to that already-warm process instead of starting from cold.

That is one of the main reasons your second build is dramatically faster than your first — and, on a phone, it is also a process quietly holding a couple of hundred megabytes of RAM. This line in gradle.properties is where its memory limit is set:

org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8