build.gradle: mi ez, szintaxis és konfiguráció Androidban

Mi az a build.gradle?

build.gradle egy build szkript Groovy (.gradle kiterjesztés) vagy Kotlin (.gradle.kts) nyelven, amely az Android alkalmazás fordításának minden aspektusát kezeli. A Gradle egy automatikus build rendszer, amelyet a Google 2013-ban fogadott el szabványként Androidra. A build.gradle leírja: milyen plugineket alkalmaztak (Android, Kotlin, könyvtárak), milyen függőségek kapcsolódtak, milyen SDK verziók használatosak, hogyan kell aláírni az alkalmazást és hol kell publikálni.

A build folyamat három fázisból áll: Initialization (modulok meghatározása), Configuration (build.gradle szkriptek végrehajtása), Execution (feladatok végrehajtása). A build.gradle a Configuration fázisban hajtódik végre, amikor a Gradle létrehozza a feladatgráfot. Ekkor határozódnak meg a Build Variants, számolódnak ki a függőségek és konfigurálódnak a feladatok. Fontos: a build.gradle kód, nem csak konfiguráció. Használhatók benne feltételek, ciklusok, metódushívások és külső szkriptek.

A Gradle fájlok a modul gyökerében (app/build.gradle) és a projekt gyökerében (build.gradle) tárolódnak. Ezen kívül a Gradle támogatja az apply from — külső Gradle szkriptek csatlakoztatását. Ez lehetővé teszi az ismétlődő logika kiemelését közös beállításokkal rendelkező fájlokba. A Convention Plugins (AGP 7+) megjelenésével az apply from elavultnak számít — a Convention Plugins type-safe és kompozit módszert biztosít a konfiguráció modulok közötti újrafelhasználására.

A build.gradle fejlődése

2013 óta a build.gradle szintaxisa jelentős változásokon ment keresztül: a dinamikus konfigurációjú Groovy-tól a compile-time ellenőrzésekkel rendelkező Kotlin DSL-ig. Az AGP az 1.0 verziótól 8.7-ig (2025) fejlődött. Kulcsfontosságú mérföldkövek: AGP 3.0 (Java 8 desugar, new variant API), AGP 4.0 (view binding, Java 11), AGP 7.0 (Kotlin DSL alapértelmezett, Java 11 min), AGP 8.0 (non-transitive R classes, build config Kotlinban), AGP 8.7 (KSP a kapt helyett, gyors konfiguráció).

Project-level és Module-level build.gradle

Project-level build.gradle (gyökér) meghatározza az összes modul számára közös plugineket, repository-kat és konfigurációkat. Fő blokkok: plugins (Gradle pluginek csatlakoztatása), repositories (függőségi források: mavenCentral, google, jitpack). A gyökér build.gradle-ben általában nincs android blokk — az a modulokban jelenik meg. A Project-level tartalmazhat subprojects blokkot is az összes alprojekt közös konfigurálásához, bár a Convention Plugins előnyösebb.

Module-level build.gradle (pl. app/build.gradle) egy adott modult ír le. Ha a modul egy alkalmazás, akkor a com.android.application plugint alkalmazza. Ha könyvtár — com.android.library. A module-level tartalmazza: az android blokkot (compileSdk, defaultConfig, buildTypes, productFlavors), a dependencies blokkot (modul függőségei) és opcionális blokkokat a tesztek és build konfigurálásához. A Module-level a project-level után hajtódik végre, és felülírhatja a közös beállításokat.

AGP 8.0-tól kezdve a gyökér build.gradle használhat version catalogs-ot (libs.versions.toml) a függőségi verziók központi kezelésére. A version catalog egy fájl a gradle/ könyvtárban, amely verziókat, könyvtárakat és plugineket tartalmaz. A build.gradle-ben a függőségek a libs-en keresztül csatlakoznak: implementation(libs.retrofit). A version catalogs kötelező az új projektekhez és ajánlott minden három vagy több modullal rendelkező projekthez.

// settings.gradle.kts — projekt gyökere
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (projekt szint)
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 (modul szint)
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 egy dinamikus JVM nyelv, amely a Gradle eredeti szintaxisa volt. A Groovy szkriptek (.gradle) dinamikus típusosztást használnak: a típusok elhagyhatók, az idézőjelek használhatók vagy nem, a fordítási fázisban nem létező metódusok is meghívhatók. A Groovy rugalmassága egyben a hátránya is: az IDE nem tudja ellenőrizni a szintaxist és a típusokat a szkript végrehajtása előtt, ami runtime hibákhoz vezet hibás paraméternév vagy típus esetén.

Kotlin DSL (.gradle.kts) a Kotlin statikus típusosztását használja. Az IDE ellenőrzi a típusokat, javasolja az elérhető paramétereket automatikus kiegészítéssel, és kiemeli a hibákat a szerkesztési fázisban. A Kotlin DSL lassabb a Configuration fázisban (a .kts fájlok bájtkóddá fordítás miatt), de a Google folyamatosan javítja a teljesítményt: az AGP 8.5+ Gradle Configuration Cache-t és Caching Kotlin DSL compilation-t használ, ami 1-2 másodpercre csökkenti a különbséget.

A Google a Kotlin DSL-t ajánlja az összes új projekthez és a meglévők fokozatos migrálásához. A Groovy-ról Kotlin DSL-re való migrálás egyszerű: az idézőjeleket zárójelek váltják fel, típusok kerülnek hozzáadásra, az operátorok függvényekké alakulnak. A legtöbb könyvtár Kotlin DSL példákat biztosít a dokumentációban. Összetett esetekben (Custom Plugin, Task Graph) a Kotlin DSL type-safe API-t biztosít és megelőzi azokat a hibákat, amelyek Groovy-ban csak runtime-ban derülnek ki. A version catalogs (libs.versions.toml) mindkét szintaxissal azonos módon működik.

Android blokk: az alkalmazás konfigurálása

compileSdk, minSdk és targetSdk

Android blokk — a module-level build.gradle központi eleme. Belül konfigurálható: namespace (R és BuildConfig számára), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Az android blokk összes paramétere csak Android modulokra alkalmazható. Ha a modul egy könyvtár, akkor alkalmazás helyett a könyvtár plugin kerül használatra, és az android blokkban nincs applicationId.

compileSdk — az SDK verzió, amellyel a kód fordítódik. Meg kell egyeznie a legfrissebb Android API-val (a cikk írásakor — 35). minSdk — a támogatáshoz szükséges minimális API verzió. targetSdk — az a verzió, amelyre az alkalmazás irányul (ezen verzió viselkedésbeli változásai érvényesülnek). Különbség a compileSdk és targetSdk között: a compileSdk az elérhető API-kat, a targetSdk a runtime viselkedést határozza meg. Ajánlás: compileSdk = latest, targetSdk = latest - 1 (az új változásokhoz való alkalmazkodás teszteléséhez).

compileOptions beállítja a Java kompatibilitást: sourceCompatibility és targetCompatibility. Az AGP 8+ Java 17+-t igényel a fordításhoz. packaging kezeli a fájlok könyvtárakból való beillesztését: exclude, merge, pickFirst a META-INF konfliktusok megoldásához. buildFeatures be-/kikapcsolja a ViewBinding, DataBinding, Compose funkciókat. aaptOptions konfigurálja az erőforrások feldolgozását: ignoreAssetsPattern, cruncherEnabled. Az android blokk minden eleme a build egy adott aspektusát optimalizálja.

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

Függőségek kezelése

BOM (Bill of Materials)

Függőségek a build.gradle-ben a projekthez csatlakoztatott könyvtárak és modulok. A dependencies blokk ugyanazon a szinten található, mint az android blokk. A Gradle több konfigurációt támogat: implementation (könyvtár elérhető ebben a modulban, nem tranzitív), api (könyvtár tranzitíven elérhető a függő modulok számára), compileOnly (csak fordításhoz, nem kerül be az APK-ba), runtimeOnly (csak runtime-ban), annotationProcessor / ksp (annotáció feldolgozók), testImplementation (csak tesztekhez), androidTestImplementation (csak instrumentációs tesztekhez).

AGP 8.0-tól kezdve Non-Transitive R classes — minden könyvtárnak saját R osztálya van, ami megakadályozza az erőforrás konfliktusokat. A dependencies blokkban fontos a helyes konfigurációk használata: az implementation nem fedi fel a tranzitív függőségeket, ami gyorsítja a build-et. Az api felfedi — akkor használatos, amikor a könyvtár típusokat exportál egy másik könyvtárból (pl. a Retrofit OkHttp típusokat használ a publik API-jában).

A verziók kezeléséhez ajánlott a BOM (Bill of Materials) használata — egy build fájl, amely meghatározza a könyvtárak kompatibilis verzióit. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). A BOM csatlakoztatása után csak a könyvtár nevét kell megadni verzió nélkül — a BOM automatikusan kiválasztja a kompatibilis verziót. Ez kiküszöböli a különböző könyvtárak tranzitív függőségei közötti konfliktusokat. A BOM elérhető Firebase, Compose, Kotlin, Ktor, AndroidX számára.

dependencies {
    // BOM — verziókezelés
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX és 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 verziók)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // Tesztelés
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

build.gradle többmodulos projektekben

A többmodulos projektekben minden modulnak saját build.gradle-je van. Az egyik modul másikhoz csatlakoztatásához a implementation(project(":module-name")) szintaxis használatos. A Gradle automatikusan lefordítja a modult, ha a konfigurációja megváltozott. A többmodulos architektúra javítja a build időt (inkrementális build, párhuzamosság) és megosztja a felelősséget a feature modulok, core modulok és könyvtárak között.

A többmodulos projektek kulcsproblémája — a konfiguráció duplikálása. Ha 10 modulnak ugyanaz a minSdk, compileSdk és Compose függősége, az 10 másolat különböző build.gradle fájlokban. A megoldás — Convention Plugins (korábban buildSrc). A Convention Plugin egy Kotlinban írt Gradle plugin, amelyet a modulokra alkalmaznak: plugins { id("myapp.android.library") }. A plugin tartalmazza a közös konfigurációt, és a változtatások azonnal érvényesülnek az összes modulon.

A Convention Plugins szervezéséhez a build-logic/ könyvtár használatos a projekt gyökerében. Ez tartalmazza az includeBuild-t a settings.gradle-ben és a Kotlin plugineket. A Convention Plugins közzétehetők maven repository-ban a projektek közötti újrafelhasználáshoz. A Google a Convention Plugins-t ajánlja szabványként a többmodulos projektekhez, felváltva a subprojects { } és apply from használatát. A Convention Plugins-re való áttérés 10-15 sorra csökkenti a modul build.gradle-jét.

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

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