build.gradle: Was es ist, Syntax und Konfiguration in Android

Was ist build.gradle?

build.gradle ist ein Build-Skript in der Sprache Groovy (Erweiterung .gradle) oder Kotlin (.gradle.kts), das alle Aspekte der Kompilierung einer Android-Anwendung verwaltet. Gradle ist ein automatisiertes Build-System, das Google 2013 als Standard für Android übernommen hat. build.gradle beschreibt: welche Plugins angewendet werden (Android, Kotlin, Bibliotheken), welche Abhängigkeiten verbunden sind, welche SDK-Versionen verwendet werden, wie die Anwendung signiert und wo sie veröffentlicht wird.

Der Build-Prozess umfasst drei Phasen: Initialization (Modulerkennung), Configuration (Ausführung von build.gradle-Skripten), Execution (Ausführung von Aufgaben). build.gradle wird während der Configuration-Phase ausgeführt, wenn Gradle den Aufgaben-Graphen erstellt. In diesem Moment werden Build-Varianten bestimmt, Abhängigkeiten berechnet und Aufgaben konfiguriert. Wichtig: build.gradle ist Code, nicht nur Konfiguration. Es können Bedingungen, Schleifen, Methodenaufrufe und externe Skripte verwendet werden.

Gradle-Dateien werden im Modul-Root (app/build.gradle) und im Projekt-Root (build.gradle) gespeichert. Darüber hinaus unterstützt Gradle apply from — Einbindung externer Gradle-Skripte. Dies ermöglicht das Auslagern wiederholter Logik in Dateien mit gemeinsamen Einstellungen. Mit dem Aufkommen von Convention Plugins (AGP 7+) gilt apply from als veraltet — Convention Plugins bieten eine typsichere und zusammensetzbare Möglichkeit zur Wiederverwendung von Konfigurationen zwischen Modulen.

Entwicklung von build.gradle

Seit 2013 hat sich die build.gradle-Syntax erheblich verändert: von Groovy mit dynamischen Konfigurationen zu Kotlin DSL mit Compile-Zeit-Prüfungen. AGP hat sich von Version 1.0 auf 8.7 (2025) weiterentwickelt. Wichtige Meilensteine: AGP 3.0 (Java 8 Desugar, neue Variant-API), AGP 4.0 (View Binding, Java 11), AGP 7.0 (Kotlin DSL standardmäßig, Java 11 Minimum), AGP 8.0 (nicht-transitive R-Klassen, Build-Konfiguration in Kotlin), AGP 8.7 (KSP statt kapt, schnelle Konfiguration).

Project-level und Module-level build.gradle

Project-level build.gradle (Root) definiert Plugins, Repositorys und Konfigurationen, die allen Modulen gemeinsam sind. Hauptblöcke: plugins (Gradle-Plugin-Deklarationen), repositories (Abhängigkeitsquellen: mavenCentral, google, jitpack). Das Root-build.gradle hat normalerweise keinen android-Block — dieser erscheint in den Modulen. Project-level kann auch einen subprojects-Block für die gemeinsame Konfiguration aller Unterprojekte enthalten, obwohl Convention Plugins vorzuziehen sind.

Module-level build.gradle (z. B. app/build.gradle) beschreibt ein bestimmtes Modul. Wenn das Modul eine Anwendung ist, wendet es das Plugin com.android.application an. Wenn es eine Bibliothek ist — com.android.library. Module-level enthält: android-Block (compileSdk, defaultConfig, buildTypes, productFlavors), dependencies-Block (Modulabhängigkeiten) und optional Blöcke für Test- und Paketierungskonfiguration. Module-level wird nach project-level ausgeführt und kann allgemeine Einstellungen überschreiben.

Ab AGP 8.0 kann das Root-build.gradle Version Catalogs (libs.versions.toml) für die zentrale Verwaltung von Abhängigkeitsversionen verwenden. Ein Version Catalog ist eine Datei im gradle/-Verzeichnis, die Versionen, Bibliotheken und Plugins enthält. In build.gradle werden Abhängigkeiten über libs verbunden: implementation(libs.retrofit). Version Catalogs sind für neue Projekte obligatorisch und für alle Projekte mit drei oder mehr Modulen empfohlen.

// settings.gradle.kts — Projekt-Root
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (project-level)
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 (module-level)
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 ist eine dynamische JVM-Sprache, die die ursprüngliche Gradle-Syntax war. Groovy-Skripte (.gradle) verwenden dynamische Typisierung: Typen können weggelassen werden, Zeichenketten mit oder ohne Anführungszeichen verwendet werden, Methoden aufgerufen werden, die zur Compile-Zeit nicht existieren. Die Flexibilität von Groovy ist auch sein Nachteil: Die IDE kann Syntax und Typen erst überprüfen, wenn das Skript ausgeführt wird, was zu Laufzeitfehlern durch falsche Parameternamen oder -typen führt.

Kotlin DSL (.gradle.kts) verwendet die statische Typisierung von Kotlin. Die IDE überprüft Typen, schlägt verfügbare Parameter per Autovervollständigung vor und hebt Fehler zur Bearbeitungszeit hervor. Kotlin DSL ist während der Configuration-Phase langsamer (aufgrund der Kompilierung von .kts-Dateien in Bytecode), aber Google verbessert kontinuierlich die Leistung: AGP 8.5+ verwendet Gradle Configuration Cache und Caching Kotlin DSL compilation, wodurch der Unterschied auf 1-2 Sekunden reduziert wird.

Google empfiehlt Kotlin DSL für alle neuen Projekte und die schrittweise Migration bestehender Projekte. Die Migration von Groovy zu Kotlin DSL ist straightforward: Anführungszeichen werden durch Klammern ersetzt, Typen hinzugefügt, Operatoren in Funktionen umgewandelt. Die meisten Bibliotheken bieten Kotlin-DSL-Beispiele in ihrer Dokumentation. Für komplexe Fälle (Custom Plugin, Task Graph) bietet Kotlin DSL eine typsichere API und verhindert Fehler, die in Groovy erst zur Laufzeit entdeckt werden. Version Catalogs (libs.versions.toml) funktionieren mit beiden Syntaxen identisch.

Der android-Block: Anwendungskonfiguration

compileSdk, minSdk und targetSdk

Der android-Block ist das zentrale Element des module-level build.gradle. Darin werden konfiguriert: namespace (für R und BuildConfig), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Alle Parameter des android-Blocks gelten nur für Android-Module. Wenn das Modul eine Bibliothek ist, wird das Bibliotheks-Plugin anstelle von application verwendet, und applicationId fehlt im android-Block.

compileSdk ist die SDK-Version, mit der der Code kompiliert wird. Sie sollte der neuesten Android-API entsprechen (zum Zeitpunkt der Erstellung — 35). minSdk ist die minimale API-Version für den Support. targetSdk ist die Version, auf die die Anwendung abzielt (die Verhaltensänderungen dieser Version werden angewendet). Der Unterschied zwischen compileSdk und targetSdk: compileSdk bestimmt die verfügbaren APIs, targetSdk bestimmt das Laufzeitverhalten. Empfehlung: compileSdk = neueste, targetSdk = neueste - 1 (zum Testen der Anpassung an neue Änderungen).

compileOptions legt die Java-Kompatibilität fest: sourceCompatibility und targetCompatibility. AGP 8+ erfordert Java 17+ für die Kompilierung. packaging verwaltet die Einbindung von Dateien aus Bibliotheken: exclude, merge, pickFirst zur Lösung von META-INF-Konflikten. buildFeatures aktiviert/deaktiviert ViewBinding, DataBinding, Compose. aaptOptions konfiguriert die Ressourcenverarbeitung: ignoreAssetsPattern, cruncherEnabled. Jedes Element des android-Blocks optimiert einen bestimmten Aspekt des Builds.

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

Abhängigkeitsverwaltung

BOM (Bill of Materials)

Abhängigkeiten in build.gradle sind Bibliotheken und Module, die mit dem Projekt verbunden sind. Der dependencies-Block befindet sich auf der gleichen Ebene wie der android-Block. Gradle unterstützt mehrere Konfigurationen: implementation (die Bibliothek ist in diesem Modul verfügbar, nicht transitiv), api (die Bibliothek ist transitiv für abhängige Module verfügbar), compileOnly (nur für die Kompilierung, nicht im APK enthalten), runtimeOnly (nur zur Laufzeit), annotationProcessor / ksp (Annotationsprozessoren), testImplementation (nur für Tests), androidTestImplementation (nur für instrumentierte Tests).

Ab AGP 8.0, nicht-transitive R-Klassen — jede Bibliothek hat ihre eigene R-Klasse, was Ressourcenkonflikte verhindert. Im dependencies-Block ist es wichtig, die richtigen Konfigurationen zu verwenden: implementation legt transitive Abhängigkeiten nicht offen, was den Build beschleunigt. api legt sie offen — wird verwendet, wenn eine Bibliothek Typen aus einer anderen Bibliothek exportiert (z. B. verwendet Retrofit OkHttp-Typen in seiner öffentlichen API).

Für die Versionsverwaltung wird die Verwendung von BOM (Bill of Materials) empfohlen — eine Build-Datei, die kompatible Bibliotheksversionen definiert. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). Nach dem Verbinden des BOM kann nur der Bibliotheksname ohne Version angegeben werden — das BOM wählt automatisch eine kompatible Version aus. Dies beseitigt Konflikte zwischen transitiven Abhängigkeiten verschiedener Bibliotheken. BOMs sind für Firebase, Compose, Kotlin, Ktor, AndroidX verfügbar.

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

    // AndroidX und 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 (Versionen aus BOM)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

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

build.gradle in Multi-Modul-Projekten

In Multi-Modul-Projekten hat jedes Modul seine eigene build.gradle. Um ein Modul mit einem anderen zu verbinden, wird die Syntax implementation(project(":module-name")) verwendet. Gradle baut das Modul automatisch neu, wenn sich seine Konfiguration geändert hat. Die Multi-Modul-Architektur verbessert die Build-Zeit (inkrementelle Builds, Parallelität) und trennt Verantwortlichkeiten zwischen Feature-Modulen, Kernmodulen und Bibliotheken.

Das Hauptproblem von Multi-Modul-Projekten ist die Konfigurationsduplizierung. Wenn 10 Module das gleiche minSdk, compileSdk und Compose-Abhängigkeiten haben, sind das 10 Kopien in verschiedenen build.gradle-Dateien. Die Lösung sind Convention Plugins (früher buildSrc). Ein Convention Plugin ist ein in Kotlin geschriebenes Gradle-Plugin, das auf Module angewendet wird: plugins { id("myapp.android.library") }. Das Plugin enthält gemeinsame Konfiguration, und Änderungen werden sofort auf alle Module angewendet.

Zur Organisation von Convention Plugins wird das Verzeichnis build-logic/ im Projekt-Root verwendet. Es enthält includeBuild in settings.gradle und Kotlin-Plugins. Convention Plugins können in einem Maven-Repository zur Wiederverwendung zwischen Projekten veröffentlicht werden. Google empfiehlt Convention Plugins als Standard für Multi-Modul-Projekte und ersetzt damit subprojects { } und apply from. Der Wechsel zu Convention Plugins reduziert die build.gradle des Moduls auf 10-15 Zeilen.

// 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 — nach Convention Plugin
plugins {
    id("myapp.android.library")
}

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