Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 104 ยท Getting Started

Gradle for Android

Understand Android's Gradle setup: the Android Gradle Plugin, version catalogs, compileSdk, minSdk and targetSdk, build types, flavors and how dependencies are resolved.

Every Android build is run by Gradle. When you press Run in Android Studio, Gradle compiles your Kotlin, processes resources, merges manifests, packages an APK and installs it. What Gradle does is controlled by two build.gradle.kts files and a version catalog. Reading them confidently is one of the most useful early skills, because almost every build problem ends there.

If you have not met Gradle at all, read Gradle Basics for Kotlin first. It explains plugins, tasks and coordinates for plain Kotlin projects. This lesson adds what is specific to Android. The real build files are read-only, since they need the Android SDK. The runnable stand-in resolves a small dependency graph the way Gradle picks versions, which is a good model of what happens when two libraries ask for different versions of a third.

The Android Gradle Plugin

Gradle itself knows nothing about APKs. The Android Gradle Plugin (AGP) teaches it. The plugin adds the android { } block, tasks such as assembleDebug and installDebug, resource and manifest processing and the connection to the Android SDK. Each AGP version needs a compatible Gradle version and a compatible Android Studio, which is why Studio offers an AGP Upgrade Assistant when you open an older project.

An app module applies the application plugin. A library module (reusable code without being an app) applies com.android.library instead.

The module build file

Here is a typical app/build.gradle.kts for a Compose app. It is a read-only example. Exact numbers change with each release.

Kotlin
// read-only example: app/build.gradle.kts
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
}

android {
    namespace = "com.example.notes"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.notes"
        minSdk = 24
        targetSdk = 36
        versionCode = 1
        versionName = "1.0"
    }

    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro",
            )
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    buildFeatures {
        compose = true
    }
}

dependencies {
    implementation(libs.androidx.core.ktx)
    implementation(libs.androidx.activity.compose)
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.compose.material3)
    testImplementation(libs.junit)
}

Read it from the top.

  • plugins. Applies the Android application plugin, Kotlin support and the Compose compiler plugin. The alias(...) form takes entries from the version catalog.
  • namespace. The package used to generate R and BuildConfig and to resolve relative names like .MainActivity in the manifest. It is separate from applicationId so you can rename one without breaking the other.
  • applicationId. The unique identity of the installed app, as seen by the device and Google Play.
  • versionCode and versionName. versionCode is an integer that must increase with every release uploaded to Play. versionName is the text users see.

The three SDK numbers

These three settings confuse beginners, and they do three different jobs.

Setting Meaning
compileSdk The Android API level you compile against. Decides which framework classes and methods exist at compile time. Use a recent one.
minSdk The oldest Android version your app installs on. Devices below this cannot install it.
targetSdk The version your app has been tested and adapted for. The system enables newer behaviour changes only for apps targeting them.

Raising compileSdk only gives you access to new APIs. It does not change behaviour on devices. Raising targetSdk does change behaviour, because Android applies new rules (for example, background and permission restrictions) to apps that target new versions, and Google Play requires recent targets for updates. If you call an API that is newer than your minSdk, check the device's version at runtime before using it, or lint will warn you.

Version catalogs

Look at libs.androidx.core.ktx above. It is not a string with a version. It is a typed accessor generated from gradle/libs.versions.toml, the version catalog: one file listing every library, plugin and version in the project.

TOML
# read-only example: gradle/libs.versions.toml
[versions]
agp = "8.13.0"
kotlin = "2.4.21"
coreKtx = "1.17.0"
composeBom = "2026.01.00"
junit = "4.13.2"

[libraries]
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
androidx-compose-material3 = { group = "androidx.compose.material3", name = "material3" }
junit = { group = "junit", name = "junit", version.ref = "junit" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

The version numbers in this listing are examples; use the versions your Studio proposes. Dashes in a catalog name become dots in code: androidx-core-ktx is libs.androidx.core.ktx. Advantages: versions live in one place, every module shares them and Studio can show available updates.

Notice that androidx-compose-material3 has no version. It is governed by the Bill of Materials (BOM): platform(libs.androidx.compose.bom) pins a set of compatible Compose library versions, so you do not align them by hand.

Dependency configurations

The word in front of each dependency says where it is used:

Configuration Available in
implementation The app's code, not exposed to modules that depend on this one
api Like implementation, and exposed to dependents (library modules only)
testImplementation Local unit tests (src/test)
androidTestImplementation Instrumented tests (src/androidTest)
debugImplementation Only the debug build type, such as inspection tools
ksp Annotation processors that generate code (for example Room)

Prefer implementation unless you have a reason to widen visibility. It keeps builds faster, because a change inside a dependency does not force recompiling every module that merely uses you.

Build types and flavors

A build type is a way of building the same code. Android Studio gives you debug and release.

  • debug is debuggable, signed with an automatic debug key and has no shrinking.
  • release is optimized, usually minified and shrunk by R8, and signed with your key. See Signing and Release Builds.

A product flavor is a variant of the product: a free and a paid edition, a staging and a production server. Flavors combine with build types, producing variants like freeDebug and paidRelease.

Kotlin
// read-only example: flavors in app/build.gradle.kts
android {
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            dimension = "tier"
            applicationIdSuffix = ".free"
        }
        create("paid") {
            dimension = "tier"
        }
    }
}
flowchart TD
    BT["Build types<br/>debug, release"] --> V["Build variants"]
    PF["Product flavors<br/>free, paid"] --> V
    V --> A["freeDebug"]
    V --> B["freeRelease"]
    V --> C["paidDebug"]
    V --> D["paidRelease"]

Every combination of a flavor and a build type is a separate variant with its own tasks.

A stand-in for dependency resolution

Real Gradle downloads libraries and their dependencies, which may overlap. If your app uses library A, which needs core:1.2, and library B, which needs core:1.5, Gradle must pick a single version. By default it picks the highest requested version. This stand-in resolves a small graph with that rule. It is a model of the idea: real Gradle also handles constraints, exclusions and platforms, such as the Compose BOM.

Kotlin Resolving a dependency graph

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The output shows core requested three times at three versions, with 1.5 winning. This is the reason a library can suddenly behave differently after you add an unrelated dependency: some other library pulled in a newer transitive version. In Android Studio you can see the real graph with the Gradle task dependencies or the Dependencies view in the Build tool window.

A stand-in for build variants and SDK levels

Variants are the product of build types and flavors, and each can carry its own settings. This stand-in generates them and applies the rule you learned for minSdk. It is a model of the naming and combination logic, not of the real Gradle task graph.

Kotlin Generating build variants

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The suffix .free gives the free edition a different application ID, so both editions can be installed side by side on one device.

Syncing and building from the command line

Two ideas to keep in mind. Sync reads the build files and updates the IDE's model, so run it after editing them. A build compiles and packages. From a terminal in the project folder you use the wrapper: ./gradlew assembleDebug builds an APK, ./gradlew installDebug installs it on a connected device and ./gradlew test runs local unit tests. Command-line builds are exactly what a CI server runs, as in CI/CD for Android.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does minSdk control?

    minSdk is the lowest API level that can install the app. compileSdk is about compile-time APIs and targetSdk is about the behaviour you were tested for.
  2. 2. Which change can alter how your app behaves on new devices because Android applies new rules to it?

    Behaviour changes in new Android versions apply to apps that target them. compileSdk only changes which APIs you can call when compiling.
  3. 3. Why do libraries like androidx-compose-material3 have no version in the catalog example?

    platform(libs.androidx.compose.bom) pins a compatible set of Compose library versions, so each entry can omit its own.
  4. 4. With two flavors (free, paid) and two build types (debug, release), how many build variants exist?

    Every flavor combines with every build type: freeDebug, freeRelease, paidDebug and paidRelease.
  5. 5. Which dependency configuration is visible to modules that depend on a library module?

    api exposes the dependency to consumers. implementation keeps it internal, which usually gives faster builds.

Summary

  • The Android Gradle Plugin adds the android { } block, Android tasks and SDK integration on top of Gradle.
  • compileSdk is what you compile against, minSdk is the oldest device supported and targetSdk is the behaviour level you tested for.
  • namespace generates R, while applicationId identifies the installed app; versionCode must increase on every release.
  • A version catalog (libs.versions.toml) centralizes versions, and a BOM aligns related libraries.
  • Prefer implementation; flavors and build types multiply into variants; Gradle resolves conflicting versions, by default picking the highest.

Next, learn what the manifest and resource files contain in The Manifest and Resources.