build.gradle: ce este, sintaxă și configurare în Android

Ce este build.gradle?

build.gradle este un script de compilare în limbajul Groovy (extensia .gradle) sau Kotlin (.gradle.kts) care gestionează toate aspectele compilării aplicației Android. Gradle este un sistem automat de compilare adoptat de Google în 2013 ca standard pentru Android. build.gradle descrie: ce pluginuri sunt aplicate (Android, Kotlin, biblioteci), ce dependențe sunt conectate, ce versiuni SDK sunt utilizate, cum să semnați aplicația și unde să publicați.

Procesul de compilare include trei faze: Initialization (determinarea modulelor), Configuration (executarea scripturilor build.gradle), Execution (executarea sarcinilor). build.gradle se execută în faza Configuration, când Gradle creează graful de sarcini. În acest moment sunt determinate Build Variants, calculate dependențele și configurate taskurile. Important: build.gradle este cod, nu doar configurare. În el pot fi folosite condiții, bucle, apeluri de metode și scripturi externe.

Fișierele Gradle sunt stocate în rădăcina modulului (app/build.gradle) și rădăcina proiectului (build.gradle). În plus, Gradle suportă apply from — conectarea scripturilor externe Gradle. Aceasta permite extragerea logicii repetitive în fișiere cu setări comune. Odată cu apariția Convention Plugins (AGP 7+), apply from este considerat învechit — Convention Plugins oferă un mod type-safe și compozit de reutilizare a configurării între module.

Evoluția build.gradle

Din 2013, sintaxa build.gradle a suferit modificări semnificative: de la Groovy cu configurări dinamice la Kotlin DSL cu verificări la compilare. AGP a evoluat de la versiunea 1.0 la 8.7 (2025). Repere cheie: AGP 3.0 (Java 8 desugar, new variant API), AGP 4.0 (view binding, Java 11), AGP 7.0 (Kotlin DSL implicit, Java 11 min), AGP 8.0 (non-transitive R classes, configurare compilare în Kotlin), AGP 8.7 (KSP în loc de kapt, configurare rapidă).

Project-level și Module-level build.gradle

Project-level build.gradle (rădăcină) definește pluginurile, repository-urile și configurările comune pentru toate modulele. Blocuri principale: plugins (conectarea pluginurilor Gradle), repositories (surse de dependențe: mavenCentral, google, jitpack). În build.gradle rădăcină de obicei nu există bloc android — acesta apare în module. Project-level poate conține și blocul subprojects pentru configurarea comună a tuturor subproiectelor, deși Convention Plugins sunt preferați.

Module-level build.gradle (de exemplu, app/build.gradle) descrie un modul specific. Dacă modulul este o aplicație, aplică pluginul com.android.application. Dacă este o bibliotecă — com.android.library. În module-level se află: blocul android (compileSdk, defaultConfig, buildTypes, productFlavors), blocul dependencies (dependențele modulului) și opțional blocuri pentru configurarea testelor și compilării. Module-level se execută după project-level și poate suprascrie setările comune.

Începând cu AGP 8.0, build.gradle rădăcină poate folosi version catalogs (libs.versions.toml) pentru gestionarea centralizată a versiunilor dependențelor. Version catalog este un fișier în directorul gradle/ care conține versiuni, biblioteci și pluginuri. În build.gradle dependențele se conectează prin libs: implementation(libs.retrofit). Version catalogs sunt obligatorii pentru proiecte noi și recomandate pentru toate proiectele cu trei sau mai multe module.

// settings.gradle.kts — rădăcina proiectului
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (nivel proiect)
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 (nivel modul)
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 este un limbaj dinamic JVM care a fost sintaxa originală a Gradle. Scripturile Groovy (.gradle) folosesc tipizare dinamică: se pot omite tipurile, se pot folosi sau nu ghilimele, se pot apela metode care nu există în faza de compilare. Flexibilitatea Groovy este și dezavantajul său: IDE nu poate verifica sintaxa și tipurile înainte de executarea scriptului, ceea ce duce la erori de runtime la nume de parametru sau tip incorect.

Kotlin DSL (.gradle.kts) folosește tipizarea statică a Kotlin. IDE verifică tipurile, sugerează parametrii disponibili prin autocompletare și evidențiază erorile în faza de editare. Kotlin DSL este mai lent în faza Configuration (din cauza compilării fișierelor .kts în bytecode), dar Google îmbunătățește constant performanța: AGP 8.5+ folosește Gradle Configuration Cache și Caching Kotlin DSL compilation, ceea ce reduce diferența la 1-2 secunde.

Google recomandă Kotlin DSL pentru toate proiectele noi și migrarea treptată a celor existente. Migrarea de la Groovy la Kotlin DSL este simplă: ghilimelele sunt înlocuite cu paranteze, se adaugă tipuri, operatorii sunt transformați în funcții. Majoritatea bibliotecilor oferă exemple Kotlin DSL în documentație. Pentru cazuri complexe (Custom Plugin, Task Graph), Kotlin DSL oferă API type-safe și previne erorile care în Groovy sunt descoperite doar în runtime. Version catalogs (libs.versions.toml) funcționează la fel cu ambele sintaxe.

Blocul android: configurarea aplicației

compileSdk, minSdk și targetSdk

Blocul android — elementul central al module-level build.gradle. În interiorul său se configurează: namespace (pentru R și BuildConfig), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Toți parametrii blocului android se aplică doar modulelor Android. Dacă modulul este o bibliotecă, în loc de aplicație se folosește pluginul de bibliotecă, iar în blocul android nu există applicationId.

compileSdk — versiunea SDK cu care se compilează codul. Trebuie să fie egală cu cel mai recent Android API (la momentul scrierii — 35). minSdk — versiunea API minimă pentru suport. targetSdk — versiunea la care aplicația este orientată (modificările comportamentale ale acestei versiuni se aplică). Diferența între compileSdk și targetSdk: compileSdk determină API-urile disponibile, targetSdk — comportamentul runtime. Recomandare: compileSdk = latest, targetSdk = latest - 1 (pentru testarea adaptării la modificări noi).

compileOptions stabilește compatibilitatea Java: sourceCompatibility și targetCompatibility. AGP 8+ necesită Java 17+ pentru compilare. packaging gestionează includerea fișierelor din biblioteci: exclude, merge, pickFirst pentru rezolvarea conflictelor META-INF. buildFeatures activează/dezactivează ViewBinding, DataBinding, Compose. aaptOptions configurează procesarea resurselor: ignoreAssetsPattern, cruncherEnabled. Fiecare element al blocului android optimizează un aspect specific al compilării.

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

Gestionarea dependențelor

BOM (Bill of Materials)

Dependențele în build.gradle sunt bibliotecile și modulele conectate la proiect. Blocul dependencies se află la același nivel cu blocul android. Gradle suportă mai multe configurații: implementation (biblioteca este disponibilă în acest modul, non-tranzitivă), api (biblioteca este disponibilă tranzitiv modulelor dependente), compileOnly (doar pentru compilare, nu este inclusă în APK), runtimeOnly (doar în runtime), annotationProcessor / ksp (procesoare de adnotări), testImplementation (doar pentru teste), androidTestImplementation (doar pentru teste instrumentale).

Începând cu AGP 8.0, Non-Transitive R classes — fiecare bibliotecă are propria sa clasă R, ceea ce previne conflictele de resurse. În blocul dependencies este important să folosiți configurații corecte: implementation nu dezvăluie dependențe tranzitive, ceea ce accelerează compilarea. api dezvăluie — se folosește când biblioteca exportă tipuri din altă bibliotecă (de exemplu, Retrofit folosește tipuri OkHttp în API-ul său public).

Pentru gestionarea versiunilor se recomandă utilizarea BOM (Bill of Materials) — un fișier de compilare care determină versiunile compatibile ale bibliotecilor. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). După conectarea BOM se poate specifica doar numele bibliotecii fără versiune — BOM va selecta automat versiunea compatibilă. Aceasta elimină conflictele între dependențele tranzitive ale diferitelor biblioteci. BOM sunt disponibile pentru Firebase, Compose, Kotlin, Ktor, AndroidX.

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

    // AndroidX și 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 (versiuni din BOM)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

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

build.gradle în proiecte multi-modul

În proiectele multi-modul, fiecare modul are propriul build.gradle. Pentru conectarea unui modul la altul se folosește sintaxa implementation(project(":module-name")). Gradle compilează automat modulul dacă configurația acestuia s-a schimbat. Arhitectura multi-modul îmbunătățește timpul de compilare (compilare incrementală, paralelism) și împarte responsabilitatea între module funcționale, module core și biblioteci.

Problema cheie a proiectelor multi-modul — duplicarea configurației. Dacă 10 module au aceleași minSdk, compileSdk și dependențe Compose, sunt 10 copii în diferite build.gradle. Soluția — Convention Plugins (fostul buildSrc). Convention Plugin este un plugin Gradle scris în Kotlin care se aplică modulelor: plugins { id("myapp.android.library") }. Pluginul conține configurația comună, iar modificările se aplică imediat tuturor modulelor.

Pentru organizarea Convention Plugins se folosește directorul build-logic/ în rădăcina proiectului. Acesta conține includeBuild în settings.gradle și pluginuri Kotlin. Convention Plugins pot fi publicate în repository maven pentru reutilizare între proiecte. Google recomandă Convention Plugins ca standard pentru proiecte multi-modul, înlocuind subprojects { } și apply from. Tranziția la Convention Plugins reduce build.gradle-ul modulului la 10-15 linii.

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

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