build.gradle: wat is het, syntaxis en configuratie in Android

Wat is build.gradle?

build.gradle is een buildscript in de taal Groovy (.gradle extensie) of Kotlin (.gradle.kts) dat alle aspecten van de compilatie van een Android-app beheert. Gradle is een automatisch buildsysteem dat in 2013 door Google als standaard voor Android is aangenomen. build.gradle beschrijft: welke plugins zijn toegepast (Android, Kotlin, bibliotheken), welke afhankelijkheden zijn verbonden, welke SDK-versies worden gebruikt, hoe de app te ondertekenen en waar te publiceren.

Het buildproces omvat drie fasen: Initialization (bepalen van modules), Configuration (uitvoeren van build.gradle-scripts), Execution (uitvoeren van taken). build.gradle wordt uitgevoerd in de Configuration-fase, wanneer Gradle de taakgraaf maakt. Op dit moment worden Build Variants bepaald, afhankelijkheden berekend en taken geconfigureerd. Belangrijk: build.gradle is code, niet alleen configuratie. Het kan condities, lussen, methodeaanroepen en externe scripts bevatten.

Gradle-bestanden worden opgeslagen in de root van de module (app/build.gradle) en de root van het project (build.gradle). Bovendien ondersteunt Gradle apply from — het aansluiten van externe Gradle-scripts. Dit maakt het mogelijk om herhalende logica te verplaatsen naar bestanden met gedeelde instellingen. Met de komst van Convention Plugins (AGP 7+) wordt apply from als verouderd beschouwd — Convention Plugins bieden een type-safe en samengestelde manier om configuratie tussen modules te hergebruiken.

Evolutie van build.gradle

Sinds 2013 heeft de syntaxis van build.gradle aanzienlijke veranderingen ondergaan: van Groovy met dynamische configuraties tot Kotlin DSL met compile-time controles. AGP is geëvolueerd van versie 1.0 naar 8.7 (2025). Belangrijke mijlpalen: AGP 3.0 (Java 8 desugar, new variant API), AGP 4.0 (view binding, Java 11), AGP 7.0 (Kotlin DSL standaard, Java 11 min), AGP 8.0 (non-transitive R classes, build config in Kotlin), AGP 8.7 (KSP in plaats van kapt, snelle configuratie).

Project-level en Module-level build.gradle

Project-level build.gradle (root) bepaalt de plugins, repositories en configuraties die gemeenschappelijk zijn voor alle modules. Belangrijkste blokken: plugins (aansluiten van Gradle-plugins), repositories (bronnen van afhankelijkheden: mavenCentral, google, jitpack). In de root build.gradle is er meestal geen android-blok — dit verschijnt in de modules. Project-level kan ook het subprojects-blok bevatten voor gemeenschappelijke configuratie van alle subprojecten, hoewel Convention Plugins de voorkeur hebben.

Module-level build.gradle (bijv. app/build.gradle) beschrijft een specifieke module. Als de module een app is, past hij de plugin com.android.application toe. Als het een bibliotheek is — com.android.library. In module-level bevinden zich: het android-blok (compileSdk, defaultConfig, buildTypes, productFlavors), het dependencies-blok (afhankelijkheden van de module) en optionele blokken voor het configureren van tests en builds. Module-level wordt uitgevoerd na project-level en kan gemeenschappelijke instellingen overschrijven.

Vanaf AGP 8.0 kan de root build.gradle version catalogs (libs.versions.toml) gebruiken voor gecentraliseerd beheer van afhankelijkheidsversies. Een version catalog is een bestand in de gradle/ map dat versies, bibliotheken en plugins bevat. In build.gradle worden afhankelijkheden via libs aangesloten: implementation(libs.retrofit). Version catalogs zijn verplicht voor nieuwe projecten en aanbevolen voor alle projecten met drie of meer modules.

// settings.gradle.kts — projectroot
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (projectniveau)
plugins {
    id("com.android.application") version "8.7.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
}

// app/build.gradle.kts (moduleniveau)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp")
}

android {
    namespace = "com.example.myapp"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 1
        versionName = "1.0.0"
    }
}

Groovy vs Kotlin DSL

Groovy is een dynamische JVM-taal die de oorspronkelijke syntaxis van Gradle was. Groovy-scripts (.gradle) gebruiken dynamische typering: types kunnen worden weggelaten, aanhalingstekens kunnen wel of niet worden gebruikt, methoden die niet bestaan in de compile-fase kunnen worden aangeroepen. De flexibiliteit van Groovy is ook het nadeel: de IDE kan de syntaxis en types niet controleren vóór uitvoering van het script, wat leidt tot runtime-fouten bij een verkeerde parameternaam of type.

Kotlin DSL (.gradle.kts) gebruikt de statische typering van Kotlin. De IDE controleert types, suggereert beschikbare parameters via autocomplete en markeert fouten in de bewerkingsfase. Kotlin DSL is langzamer in de Configuration-fase (vanwege compilatie van .kts-bestanden naar bytecode), maar Google verbetert continu de prestaties: AGP 8.5+ gebruikt Gradle Configuration Cache en Caching Kotlin DSL compilation, wat het verschil terugbrengt tot 1-2 seconden.

Google beveelt Kotlin DSL aan voor alle nieuwe projecten en geleidelijke migratie van bestaande projecten. Migratie van Groovy naar Kotlin DSL is eenvoudig: aanhalingstekens worden vervangen door haakjes, types worden toegevoegd, operatoren worden omgezet in functies. De meeste bibliotheken bieden Kotlin DSL-voorbeelden in de documentatie. Voor complexe gevallen (Custom Plugin, Task Graph) biedt Kotlin DSL een type-safe API en voorkomt fouten die in Groovy alleen in runtime worden ontdekt. Version catalogs (libs.versions.toml) werken hetzelfde met beide syntaxissen.

Het android-blok: app configureren

compileSdk, minSdk en targetSdk

Het android-blok — het centrale element van module-level build.gradle. Binnenin worden geconfigureerd: namespace (voor R en BuildConfig), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Alle parameters van het android-blok zijn alleen van toepassing op Android-modules. Als de module een bibliotheek is, wordt in plaats van de app de bibliotheek-plugin gebruikt en is er geen applicationId in het android-blok.

compileSdk — de SDK-versie waarmee de code wordt gecompileerd. Moet gelijk zijn aan de nieuwste Android API (op het moment van schrijven — 35). minSdk — de minimale API-versie voor ondersteuning. targetSdk — de versie waarop de app is gericht (gedragsveranderingen van deze versie worden toegepast). Het verschil tussen compileSdk en targetSdk: compileSdk bepaalt de beschikbare API's, targetSdk — het runtime-gedrag. Aanbeveling: compileSdk = latest, targetSdk = latest - 1 (voor het testen van aanpassing aan nieuwe wijzigingen).

compileOptions stelt Java-compatibiliteit in: sourceCompatibility en targetCompatibility. AGP 8+ vereist Java 17+ voor compilatie. packaging beheert het opnemen van bestanden uit bibliotheken: exclude, merge, pickFirst voor het oplossen van META-INF-conflicten. buildFeatures schakelt ViewBinding, DataBinding, Compose in/uit. aaptOptions configureert de verwerking van bronnen: ignoreAssetsPattern, cruncherEnabled. Elk element van het android-blok optimaliseert een specifiek aspect van de build.

android {
    namespace = "com.example.myapp"
    compileSdk = 35
    buildToolsVersion = "35.0.0"

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 5
        versionName = "2.3.1"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        getByName("debug") { isDebuggable = true }
        getByName("release") {
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
        }
    }

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

    buildFeatures {
        viewBinding = true
        compose = true
    }
}

Afhankelijkheden beheren

BOM (Bill of Materials)

Afhankelijkheden in build.gradle zijn bibliotheken en modules die aan het project worden gekoppeld. Het dependencies-blok bevindt zich op hetzelfde niveau als het android-blok. Gradle ondersteunt verschillende configuraties: implementation (bibliotheek is beschikbaar in deze module, niet transitief), api (bibliotheek is transitief beschikbaar voor afhankelijke modules), compileOnly (alleen voor compilatie, niet opgenomen in APK), runtimeOnly (alleen in runtime), annotationProcessor / ksp (annotatieverwerkers), testImplementation (alleen voor tests), androidTestImplementation (alleen voor instrumentele tests).

Vanaf AGP 8.0 hebben Non-Transitive R classes — elke bibliotheek heeft zijn eigen R-klasse, wat resourceconflicten voorkomt. In het dependencies-blok is het belangrijk om de juiste configuraties te gebruiken: implementation onthult geen transitieve afhankelijkheden, wat de build versnelt. api onthult — wordt gebruikt wanneer de bibliotheek types uit een andere bibliotheek exporteert (bijv. Retrofit gebruikt OkHttp-types in zijn publieke API).

Voor versiebeheer wordt aanbevolen om BOM (Bill of Materials) te gebruiken — een buildbestand dat compatibele versies van bibliotheken bepaalt. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). Na het aansluiten van BOM kan alleen de bibliotheeknaam zonder versie worden opgegeven — BOM selecteert automatisch de compatibele versie. Dit elimineert conflicten tussen transitieve afhankelijkheden van verschillende bibliotheken. BOM is beschikbaar voor Firebase, Compose, Kotlin, Ktor, AndroidX.

dependencies {
    // BOM — versiebeheer
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX en Compose
    implementation("androidx.core:core-ktx")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx")
    implementation("androidx.activity:activity-compose")
    implementation("androidx.compose.ui:ui")

    // Network
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")

    // Firebase (BOM-versies)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // Testen
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

build.gradle in multimodulaire projecten

In multimodulaire projecten heeft elke module zijn eigen build.gradle. Voor het koppelen van de ene module aan de andere wordt de syntaxis implementation(project(":module-name")) gebruikt. Gradle bouwt de module automatisch als de configuratie is gewijzigd. Multimodulaire architectuur verbetert de buildtijd (incrementele build, parallellisme) en verdeelt de verantwoordelijkheid tussen feature-modules, core-modules en bibliotheken.

Het belangrijkste probleem van multimodulaire projecten — duplicatie van configuratie. Als 10 modules dezelfde minSdk, compileSdk en Compose-afhankelijkheden hebben, zijn dat 10 kopieën in verschillende build.gradle-bestanden. De oplossing — Convention Plugins (voorheen buildSrc). Convention Plugin is een Gradle-plugin geschreven in Kotlin die wordt toegepast op modules: plugins { id("myapp.android.library") }. De plugin bevat de gemeenschappelijke configuratie en wijzigingen worden onmiddellijk toegepast op alle modules.

Voor het organiseren van Convention Plugins wordt de map build-logic/ in de projectroot gebruikt. Deze bevat includeBuild in settings.gradle en Kotlin-plugins. Convention Plugins kunnen worden gepubliceerd in een maven-repository voor hergebruik tussen projecten. Google beveelt Convention Plugins aan als standaard voor multimodulaire projecten, ter vervanging van subprojects { } en apply from. De overstap naar Convention Plugins reduceert de build.gradle van een module tot 10-15 regels.

// build-logic/src/main/kotlin/AndroidLibraryConventionPlugin.kt
class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            with(plugins) {
                apply("com.android.library")
                apply("org.jetbrains.kotlin.android")
            }
            extensions.configure<CommonExtension<*, *, *, *>> {
                compileSdk = 35
                defaultConfig { minSdk = 26 }
                compileOptions {
                    sourceCompatibility = JavaVersion.VERSION_17
                    targetCompatibility = JavaVersion.VERSION_17
                }
            }
        }
    }
}

// module/build.gradle.kts — na Convention Plugin
plugins {
    id("myapp.android.library")
}

dependencies {
    implementation(project(":core:network"))
}