build.gradle: co to jest, składnia i konfiguracja w Android

Co to jest build.gradle?

build.gradle to skrypt kompilacji w języku Groovy (rozszerzenie .gradle) lub Kotlin (.gradle.kts), który zarządza wszystkimi aspektami kompilacji aplikacji Android. Gradle to system automatycznej kompilacji przyjęty przez Google w 2013 roku jako standard dla Android. build.gradle opisuje: jakie pluginy są zastosowane (Android, Kotlin, biblioteki), jakie zależności są podłączone, jakie wersje SDK są używane, jak podpisywać aplikację i gdzie publikować.

Proces kompilacji obejmuje trzy fazy: Initialization (określenie modułów), Configuration (wykonanie skryptów build.gradle), Execution (wykonanie zadań). build.gradle jest wykonywany w fazie Configuration, kiedy Gradle tworzy graf zadań. W tym momencie określane są Build Variants, obliczane zależności i konfigurowane taski. Ważne: build.gradle to kod, a nie tylko konfiguracja. Można w nim używać warunków, pętli, wywołań metod i zewnętrznych skryptów.

Pliki Gradle znajdują się w katalogu głównym modułu (app/build.gradle) i katalogu głównym projektu (build.gradle). Ponadto Gradle obsługuje apply from — podłączanie zewnętrznych skryptów Gradle. Pozwala to na wyodrębnienie powtarzalnej logiki do plików ze wspólnymi ustawieniami. Wraz z pojawieniem się Convention Plugins (AGP 7+) apply from jest uznawany za przestarzały — Convention Plugins zapewniają type-safe i kompozytowy sposób ponownego wykorzystania konfiguracji między modułami.

Ewolucja build.gradle

Od 2013 roku składnia build.gradle przeszła znaczące zmiany: od Groovy z dynamicznymi konfiguracjami do Kotlin DSL z kontrolą w czasie kompilacji. AGP ewoluował od wersji 1.0 do 8.7 (2025). Kluczowe kamienie milowe: AGP 3.0 (Java 8 desugar, new variant API), AGP 4.0 (view binding, Java 11), AGP 7.0 (Kotlin DSL domyślnie, Java 11 min), AGP 8.0 (non-transitive R classes, build config in Kotlin), AGP 8.7 (KSP zamiast kapt, szybka konfiguracja).

Project-level i Module-level build.gradle

Project-level build.gradle (główny) określa pluginy, repozytoria i konfiguracje wspólne dla wszystkich modułów. Główne bloki: plugins (podłączanie pluginów Gradle), repositories (źródła zależności: mavenCentral, google, jitpack). W głównym build.gradle zwykle nie ma bloku android — pojawia się on w modułach. Project-level może również zawierać blok subprojects dla wspólnej konfiguracji wszystkich podprojektów, chociaż Convention Plugins są preferowane.

Module-level build.gradle (np. app/build.gradle) opisuje konkretny moduł. Jeśli moduł jest aplikacją, stosuje plugin com.android.application. Jeśli biblioteką — com.android.library. W module-level znajdują się: blok android (compileSdk, defaultConfig, buildTypes, productFlavors), blok dependencies (zależności modułu) i opcjonalnie bloki do konfiguracji testów i kompilacji. Module-level jest wykonywany po project-level i może nadpisywać wspólne ustawienia.

Od AGP 8.0 główny build.gradle może używać version catalogs (libs.versions.toml) do scentralizowanego zarządzania wersjami zależności. Version catalog to plik w katalogu gradle/, który zawiera wersje, biblioteki i pluginy. W build.gradle zależności są podłączane przez libs: implementation(libs.retrofit). Version catalogs są obowiązkowe dla nowych projektów i zalecane dla wszystkich projektów z trzema lub więcej modułami.

// settings.gradle.kts — katalog główny projektu
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (poziom 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 (poziom modułu)
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 to dynamiczny język JVM, który był oryginalną składnią Gradle. Skrypty Groovy (.gradle) używają dynamicznego typowania: można nie określać typów, używać cudzysłowów lub nie, wywoływać metody, które nie istnieją na etapie kompilacji. Elastyczność Groovy jest także jego wadą: IDE nie może sprawdzić składni i typów przed wykonaniem skryptu, co prowadzi do błędów w czasie wykonania przy nieprawidłowej nazwie parametru lub typie.

Kotlin DSL (.gradle.kts) używa statycznego typowania Kotlin. IDE sprawdza typy, podpowiada dostępne parametry przez autouzupełnianie i podświetla błędy na etapie edycji. Kotlin DSL jest wolniejszy w fazie Configuration (z powodu kompilacji plików .kts do kodu bajtowego), ale Google stale poprawia wydajność: AGP 8.5+ używa Gradle Configuration Cache i Caching Kotlin DSL compilation, co sprowadza różnicę do 1-2 sekund.

Google zaleca Kotlin DSL dla wszystkich nowych projektów i stopniową migrację istniejących. Migracja z Groovy do Kotlin DSL jest prosta: cudzysłowy zastępowane są nawiasami, dodawane są typy, operatory przekształcane w funkcje. Większość bibliotek udostępnia przykłady Kotlin DSL w dokumentacji. W skomplikowanych przypadkach (Custom Plugin, Task Graph) Kotlin DSL zapewnia type-safe API i zapobiega błędom, które w Groovy wykrywane są dopiero w runtime. Version catalogs (libs.versions.toml) działają tak samo z obiema składniami.

Blok android: konfiguracja aplikacji

compileSdk, minSdk i targetSdk

Blok android — centralny element module-level build.gradle. Wewnątrz niego konfiguruje się: namespace (dla R i BuildConfig), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Wszystkie parametry bloku android mają zastosowanie tylko do modułów Android. Jeśli moduł jest biblioteką, zamiast aplikacji stosowany jest plugin biblioteczny, a w bloku android nie ma applicationId.

compileSdk — wersja SDK, z którą kompilowany jest kod. Powinna być równa najnowszej Android API (w momencie pisania — 35). minSdk — minimalna wersja API do obsługi. targetSdk — wersja, na którą zorientowana jest aplikacja (zmiany behawioralne tej wersji są stosowane). Różnica między compileSdk a targetSdk: compileSdk określa dostępne API, targetSdk — zachowanie runtime. Zalecenie: compileSdk = latest, targetSdk = latest - 1 (do testowania adaptacji do nowych zmian).

compileOptions określa zgodność Java: sourceCompatibility i targetCompatibility. AGP 8+ wymaga Java 17+ do kompilacji. packaging zarządza dołączaniem plików z bibliotek: exclude, merge, pickFirst do rozwiązywania konfliktów META-INF. buildFeatures włącza/wyłącza ViewBinding, DataBinding, Compose. aaptOptions konfiguruje przetwarzanie zasobów: ignoreAssetsPattern, cruncherEnabled. Każdy element bloku android optymalizuje konkretny aspekt kompilacji.

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

Zarządzanie zależnościami

BOM (Bill of Materials)

Zależności w build.gradle to biblioteki i moduły, które są podłączane do projektu. Blok dependencies znajduje się na tym samym poziomie co blok android. Gradle obsługuje kilka konfiguracji: implementation (biblioteka dostępna w tym module, nie przechodnia), api (biblioteka przechodnio dostępna dla zależnych modułów), compileOnly (tylko do kompilacji, nie dołączana do APK), runtimeOnly (tylko w runtime), annotationProcessor / ksp (procesory adnotacji), testImplementation (tylko dla testów), androidTestImplementation (tylko dla testów instrumentalnych).

Od AGP 8.0 Non-Transitive R classes — każda biblioteka ma własną klasę R, co zapobiega konfliktom zasobów. W bloku dependencies ważne jest używanie prawidłowych konfiguracji: implementation nie ujawnia zależności przechodnich, co przyspiesza kompilację. api ujawnia — stosowane gdy biblioteka eksportuje typy z innej biblioteki (np. Retrofit używa typów OkHttp w swoim publicznym API).

Do zarządzania wersjami zaleca się używanie BOM (Bill of Materials) — pliku kompilacji, który określa zgodne wersje bibliotek. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). Po podłączeniu BOM można podawać tylko nazwę biblioteki bez wersji — BOM automatycznie wybierze zgodną wersję. Eliminuje to konflikty między przechodnimi zależnościami różnych bibliotek. BOM są dostępne dla Firebase, Compose, Kotlin, Ktor, AndroidX.

dependencies {
    // BOM — zarządzanie wersjami
    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 (wersje z BOM)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

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

build.gradle w projektach wielomodułowych

W projektach wielomodułowych każdy moduł ma własny build.gradle. Do podłączenia jednego modułu do drugiego używa się składni implementation(project(":module-name")). Gradle automatycznie kompiluje moduł, jeśli jego konfiguracja się zmieniła. Architektura wielomodułowa poprawia czas kompilacji (kompilacja inkrementalna, równoległość) i dzieli odpowiedzialność między moduły funkcjonalne, moduły core i biblioteki.

Kluczowy problem projektów wielomodułowych — duplikowanie konfiguracji. Jeśli 10 modułów ma te same minSdk, compileSdk i zależności Compose, to 10 kopii w różnych build.gradle. Rozwiązanie — Convention Plugins (dawniej buildSrc). Convention Plugin to plugin Gradle napisany w Kotlin, który jest stosowany do modułów: plugins { id("myapp.android.library") }. Plugin zawiera wspólną konfigurację, a zmiany są stosowane natychmiast do wszystkich modułów.

Do organizacji Convention Plugins używa się katalogu build-logic/ w katalogu głównym projektu. Zawiera on includeBuild w settings.gradle i pluginy Kotlin. Convention Plugins mogą być publikowane w repozytorium maven w celu ponownego wykorzystania między projektami. Google zaleca Convention Plugins jako standard dla projektów wielomodułowych, zastępujący subprojects { } i apply from. Przejście na Convention Plugins skraca build.gradle modułu do 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 — po zastosowaniu Convention Plugin
plugins {
    id("myapp.android.library")
}

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