build.gradle: co to je, syntaxe a konfigurace v Androidu

Co je build.gradle?

build.gradle je sestavovací skript v jazyce Groovy (přípona .gradle) nebo Kotlin (.gradle.kts), který spravuje všechny aspekty kompilace Android aplikace. Gradle je automatický sestavovací systém přijatý Googlem v roce 2013 jako standard pro Android. build.gradle popisuje: jaké pluginy jsou použity (Android, Kotlin, knihovny), jaké závislosti jsou připojeny, jaké verze SDK se používají, jak podepsat aplikaci a kam publikovat.

Proces sestavení zahrnuje tři fáze: Initialization (určení modulů), Configuration (provedení build.gradle skriptů), Execution (provedení úloh). build.gradle se provádí ve fázi Configuration, když Gradle vytváří graf úloh. V tomto okamžiku se určují Build Variants, počítají se závislosti a konfigurují úlohy. Důležité: build.gradle je kód, nejen konfigurace. Lze v něm používat podmínky, cykly, volání metod a externí skripty.

Soubory Gradle jsou uloženy v kořenu modulu (app/build.gradle) a kořenu projektu (build.gradle). Kromě toho Gradle podporuje apply from — připojení externích Gradle skriptů. To umožňuje přesunout opakující se logiku do souborů se společnými nastaveními. S příchodem Convention Plugins (AGP 7+) je apply from považován za zastaralý — Convention Plugins poskytují type-safe a kompozitní způsob opětovného použití konfigurace mezi moduly.

Vývoj build.gradle

Od roku 2013 prošla syntaxe build.gradle významnými změnami: od Groovy s dynamickými konfiguracemi po Kotlin DSL s kontrolami v čase kompilace. AGP se vyvinul z verze 1.0 na 8.7 (2025). Klíčové milníky: AGP 3.0 (Java 8 desugar, new variant API), AGP 4.0 (view binding, Java 11), AGP 7.0 (Kotlin DSL ve výchozím nastavení, Java 11 min), AGP 8.0 (non-transitive R classes, konfigurace sestavení v Kotlinu), AGP 8.7 (KSP místo kapt, rychlá konfigurace).

Project-level a Module-level build.gradle

Project-level build.gradle (kořenový) určuje pluginy, repozitáře a konfigurace společné pro všechny moduly. Hlavní bloky: plugins (připojení Gradle pluginů), repositories (zdroje závislostí: mavenCentral, google, jitpack). V kořenovém build.gradle obvykle není blok android — objevuje se v modulech. Project-level může také obsahovat blok subprojects pro společnou konfiguraci všech podprojektů, i když Convention Plugins jsou preferovány.

Module-level build.gradle (např. app/build.gradle) popisuje konkrétní modul. Pokud je modul aplikace, aplikuje plugin com.android.application. Pokud je knihovna — com.android.library. V module-level se nachází: blok android (compileSdk, defaultConfig, buildTypes, productFlavors), blok dependencies (závislosti modulu) a volitelné bloky pro konfiguraci testů a sestavení. Module-level se provádí po project-level a může přepsat společná nastavení.

Od AGP 8.0 může kořenový build.gradle používat version catalogs (libs.versions.toml) pro centralizovanou správu verzí závislostí. Version catalog je soubor v adresáři gradle/, který obsahuje verze, knihovny a pluginy. V build.gradle se závislosti připojují přes libs: implementation(libs.retrofit). Version catalogs jsou povinné pro nové projekty a doporučené pro všechny projekty se třemi a více moduly.

// settings.gradle.kts — kořen projektu
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (úroveň projektu)
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 (úroveň modulu)
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 je dynamický jazyk JVM, který byl původní syntaxí Gradle. Groovy skripty (.gradle) používají dynamické typování: typy lze vynechat, uvozovky lze použít nebo ne, lze volat metody, které neexistují ve fázi kompilace. Flexibilita Groovy je také jeho nevýhodou: IDE nemůže zkontrolovat syntaxi a typy před provedením skriptu, což vede k runtime chybám při nesprávném názvu parametru nebo typu.

Kotlin DSL (.gradle.kts) používá statické typování Kotlinu. IDE kontroluje typy, navrhuje dostupné parametry pomocí automatického doplňování a zvýrazňuje chyby ve fázi úprav. Kotlin DSL je pomalejší ve fázi Configuration (kvůli kompilaci .kts souborů do bytecode), ale Google neustále zlepšuje výkon: AGP 8.5+ používá Gradle Configuration Cache a Caching Kotlin DSL compilation, což snižuje rozdíl na 1-2 sekundy.

Google doporučuje Kotlin DSL pro všechny nové projekty a postupnou migraci stávajících. Migrace z Groovy na Kotlin DSL je přímočará: uvozovky se nahrazují závorkami, přidávají se typy, operátory se převádějí na funkce. Většina knihoven poskytuje příklady Kotlin DSL v dokumentaci. Pro složité případy (Custom Plugin, Task Graph) poskytuje Kotlin DSL type-safe API a předchází chybám, které se v Groovy odhalí až za běhu. Version catalogs (libs.versions.toml) fungují stejně s oběma syntaxemi.

Blok android: konfigurace aplikace

compileSdk, minSdk a targetSdk

Blok android — centrální prvek module-level build.gradle. Uvnitř se konfiguruje: namespace (pro R a BuildConfig), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Všechny parametry bloku android jsou použitelné pouze pro Android moduly. Pokud je modul knihovna, místo aplikace se použije knihovní plugin a v bloku android není applicationId.

compileSdk — verze SDK, se kterou se kód kompiluje. Měla by být rovna nejnovějšímu Android API (v době psaní — 35). minSdk — minimální verze API pro podporu. targetSdk — verze, na kterou je aplikace zaměřena (změny chování této verze se aplikují). Rozdíl mezi compileSdk a targetSdk: compileSdk určuje dostupná API, targetSdk — chování za běhu. Doporučení: compileSdk = latest, targetSdk = latest - 1 (pro testování přizpůsobení novým změnám).

compileOptions nastavuje kompatibilitu Java: sourceCompatibility a targetCompatibility. AGP 8+ vyžaduje Java 17+ pro kompilaci. packaging spravuje zahrnutí souborů z knihoven: exclude, merge, pickFirst pro řešení konfliktů META-INF. buildFeatures zapíná/vypíná ViewBinding, DataBinding, Compose. aaptOptions konfiguruje zpracování zdrojů: ignoreAssetsPattern, cruncherEnabled. Každý prvek bloku android optimalizuje konkrétní aspekt sestavení.

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

Správa závislostí

BOM (Bill of Materials)

Závislosti v build.gradle jsou knihovny a moduly připojené k projektu. Blok dependencies je na stejné úrovni jako blok android. Gradle podporuje několik konfigurací: implementation (knihovna je dostupná v tomto modulu, není tranzitivní), api (knihovna je tranzitivně dostupná závislým modulům), compileOnly (pouze pro kompilaci, není zahrnuta v APK), runtimeOnly (pouze za běhu), annotationProcessor / ksp (zpracovatelé anotací), testImplementation (pouze pro testy), androidTestImplementation (pouze pro instrumentační testy).

Od AGP 8.0 mají Non-Transitive R classes — každá knihovna má svou vlastní třídu R, což zabraňuje konfliktům zdrojů. V bloku dependencies je důležité používat správné konfigurace: implementation neodhaluje tranzitivní závislosti, což urychluje sestavení. api odhaluje — používá se, když knihovna exportuje typy z jiné knihovny (např. Retrofit používá typy OkHttp ve svém veřejném API).

Pro správu verzí se doporučuje používat BOM (Bill of Materials) — sestavovací soubor, který určuje kompatibilní verze knihoven. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). Po připojení BOM lze zadat pouze název knihovny bez verze — BOM automaticky vybere kompatibilní verzi. To odstraňuje konflikty mezi tranzitivními závislostmi různých knihoven. BOM je k dispozici pro Firebase, Compose, Kotlin, Ktor, AndroidX.

dependencies {
    // BOM — správa verzí
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX a 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 (verze z BOM)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // Testování
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

build.gradle ve vícemodulových projektech

Ve vícemodulových projektech má každý modul svůj vlastní build.gradle. Pro připojení jednoho modulu k druhému se používá syntaxe implementation(project(":module-name")). Gradle automaticky sestaví modul, pokud se jeho konfigurace změnila. Vícemodulová architektura zlepšuje dobu sestavení (inkrementální sestavení, paralelismus) a rozděluje odpovědnost mezi feature moduly, core moduly a knihovny.

Klíčový problém vícemodulových projektů — duplikace konfigurace. Pokud má 10 modulů stejné minSdk, compileSdk a Compose závislosti, je to 10 kopií v různých build.gradle souborech. Řešení — Convention Plugins (dříve buildSrc). Convention Plugin je Gradle plugin napsaný v Kotlinu, který se aplikuje na moduly: plugins { id("myapp.android.library") }. Plugin obsahuje společnou konfiguraci a změny se okamžitě aplikují na všechny moduly.

Pro organizaci Convention Plugins se používá adresář build-logic/ v kořenu projektu. Obsahuje includeBuild v settings.gradle a Kotlin pluginy. Convention Pluginy lze publikovat v maven repozitáři pro opětovné použití mezi projekty. Google doporučuje Convention Plugins jako standard pro vícemodulové projekty, nahrazující subprojects { } a apply from. Přechod na Convention Plugins zkracuje build.gradle modulu na 10-15 řádků.

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

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