build.gradle: ano ito, syntax at configuration sa Android

Ano ang build.gradle?

build.gradle ay isang build script sa wikang Groovy (.gradle extension) o Kotlin (.gradle.kts) na namamahala sa lahat ng aspeto ng compilation ng Android app. Ang Gradle ay isang automatic build system na pinagtibay ng Google noong 2013 bilang pamantayan para sa Android. Inilalarawan ng build.gradle: anong mga plugin ang inilapat (Android, Kotlin, mga library), anong mga dependencies ang konektado, anong mga bersyon ng SDK ang ginagamit, kung paano pumirma ng app at kung saan mag-publish.

Ang proseso ng build ay may tatlong yugto: Initialization (pagpapasiya ng mga module), Configuration (pag-execute ng build.gradle scripts), Execution (pag-execute ng mga task). Ang build.gradle ay na-execute sa Configuration phase, kapag gumagawa ang Gradle ng task graph. Sa puntong ito, tinutukoy ang Build Variants, kinakalkula ang mga dependencies, at kino-configure ang mga task. Mahalaga: ang build.gradle ay code, hindi lamang configuration. Maaari itong gumamit ng mga condition, loop, method calls, at external scripts.

Ang mga Gradle file ay naka-store sa root ng module (app/build.gradle) at root ng project (build.gradle). Bukod pa rito, sinusuportahan ng Gradle ang apply from — pagkonekta ng mga external na Gradle script. Pinapayagan nito na i-extract ang paulit-ulit na lohika sa mga file na may shared settings. Sa pagdating ng Convention Plugins (AGP 7+), ang apply from ay itinuturing na luma na — ang Convention Plugins ay nagbibigay ng type-safe at composite na paraan ng pag-reuse ng configuration sa pagitan ng mga module.

Ebolusyon ng build.gradle

Mula noong 2013, ang syntax ng build.gradle ay sumailalim sa malaking pagbabago: mula sa Groovy na may dynamic na configuration hanggang sa Kotlin DSL na may compile-time checks. Ang AGP ay umunlad mula sa bersyon 1.0 hanggang 8.7 (2025). Mga pangunahing milestone: AGP 3.0 (Java 8 desugar, new variant API), AGP 4.0 (view binding, Java 11), AGP 7.0 (Kotlin DSL bilang default, Java 11 min), AGP 8.0 (non-transitive R classes, build config sa Kotlin), AGP 8.7 (KSP imbes na kapt, mabilis na configuration).

Project-level at Module-level build.gradle

Project-level build.gradle (root) ay nagtatakda ng mga plugin, repository, at configuration na karaniwan sa lahat ng module. Mga pangunahing block: plugins (pagkonekta ng Gradle plugins), repositories (mga source ng dependencies: mavenCentral, google, jitpack). Sa root build.gradle ay karaniwang walang android block — ito ay lumalabas sa mga module. Ang Project-level ay maaari ring maglaman ng subprojects block para sa common configuration ng lahat ng subproject, kahit na mas gusto ang Convention Plugins.

Module-level build.gradle (halimbawa, app/build.gradle) ay naglalarawan ng isang partikular na module. Kung ang module ay isang app, inilalapat nito ang plugin na com.android.application. Kung library — com.android.library. Sa module-level matatagpuan: ang android block (compileSdk, defaultConfig, buildTypes, productFlavors), ang dependencies block (dependencies ng module), at opsyonal na mga block para sa configuration ng test at build. Ang Module-level ay na-execute pagkatapos ng project-level at maaaring mag-override ng mga common setting.

Mula sa AGP 8.0, ang root build.gradle ay maaaring gumamit ng version catalogs (libs.versions.toml) para sa sentralisadong pamamahala ng mga bersyon ng dependencies. Ang version catalog ay isang file sa gradle/ directory na naglalaman ng mga bersyon, library, at plugin. Sa build.gradle, ang mga dependencies ay kinokonekta sa pamamagitan ng libs: implementation(libs.retrofit). Ang version catalogs ay mandatory para sa mga bagong project at inirerekomenda para sa lahat ng project na may tatlo o higit pang module.

// settings.gradle.kts — root ng project
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (antas ng project)
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 (antas ng module)
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 ay isang dynamic na JVM language na orihinal na syntax ng Gradle. Ang Groovy scripts (.gradle) ay gumagamit ng dynamic typing: maaaring hindi tukuyin ang mga type, gamitin o hindi gumamit ng mga quote, tumawag ng mga method na wala sa compile phase. Ang flexibility ng Groovy ay ang kahinaan din nito: hindi masusuri ng IDE ang syntax at types bago i-execute ang script, na nagdudulot ng runtime errors sa maling pangalan ng parameter o type.

Kotlin DSL (.gradle.kts) ay gumagamit ng static typing ng Kotlin. Sinusuri ng IDE ang mga type, nagmumungkahi ng available na parameter sa pamamagitan ng autocomplete, at nagha-highlight ng mga error sa editing phase. Ang Kotlin DSL ay mas mabagal sa Configuration phase (dahil sa compilation ng .kts files sa bytecode), ngunit patuloy na pinapabuti ng Google ang performance: AGP 8.5+ ay gumagamit ng Gradle Configuration Cache at Caching Kotlin DSL compilation, na nagpapababa ng pagkakaiba sa 1-2 segundo.

Inirerekomenda ng Google ang Kotlin DSL para sa lahat ng bagong project at unti-unting paglipat ng mga umiiral na project. Ang paglipat mula Groovy patungong Kotlin DSL ay simple: ang mga quote ay pinapalitan ng mga parenthesis, ang mga type ay idinaragdag, ang mga operator ay ginagawang function. Karamihan sa mga library ay nagbibigay ng Kotlin DSL examples sa dokumentasyon. Para sa mga komplikadong kaso (Custom Plugin, Task Graph), ang Kotlin DSL ay nagbibigay ng type-safe API at pumipigil sa mga error na sa Groovy ay natutuklasan lamang sa runtime. Ang version catalogs (libs.versions.toml) ay parehong gumagana sa parehong syntax.

Android block: configuration ng app

compileSdk, minSdk at targetSdk

Android block — ang sentral na elemento ng module-level build.gradle. Sa loob nito ay kino-configure: namespace (para sa R at BuildConfig), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Lahat ng parameter ng android block ay nalalapat lamang sa Android modules. Kung ang module ay isang library, sa halip na app ay ginagamit ang library plugin, at walang applicationId sa android block.

compileSdk — ang bersyon ng SDK kung saan kino-compile ang code. Dapat katumbas ng pinakabagong Android API (sa oras ng pagsulat — 35). minSdk — ang pinakamababang bersyon ng API para sa suporta. targetSdk — ang bersyon kung saan naka-target ang app (ang mga pagbabago sa pag-uugali ng bersyong ito ay inilalapat). Ang pagkakaiba sa pagitan ng compileSdk at targetSdk: compileSdk ay tumutukoy sa mga available na API, targetSdk — runtime behavior. Rekomendasyon: compileSdk = latest, targetSdk = latest - 1 (para sa pagsubok ng adaptasyon sa mga bagong pagbabago).

compileOptions ay nagtatakda ng Java compatibility: sourceCompatibility at targetCompatibility. Ang AGP 8+ ay nangangailangan ng Java 17+ para sa compilation. packaging ay namamahala ng pagsasama ng mga file mula sa mga library: exclude, merge, pickFirst para sa paglutas ng mga META-INF conflict. buildFeatures ay nag-a-activate/nagde-deactivate ng ViewBinding, DataBinding, Compose. aaptOptions ay kino-configure ang pagproseso ng resources: ignoreAssetsPattern, cruncherEnabled. Bawat elemento ng android block ay nag-o-optimize ng isang partikular na aspeto ng build.

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

Pamamahala ng dependencies

BOM (Bill of Materials)

Dependencies sa build.gradle ay mga library at module na konektado sa project. Ang dependencies block ay nasa parehong antas ng android block. Sinusuportahan ng Gradle ang ilang configuration: implementation (library ay available sa modyul na ito, hindi transitive), api (library ay transitively available sa mga dependent module), compileOnly (para lamang sa compilation, hindi kasama sa APK), runtimeOnly (sa runtime lamang), annotationProcessor / ksp (mga annotation processor), testImplementation (para lamang sa mga test), androidTestImplementation (para lamang sa instrumental na mga test).

Mula sa AGP 8.0, Non-Transitive R classes — bawat library ay may sariling R class, na pumipigil sa mga resource conflict. Sa dependencies block, mahalagang gumamit ng tamang configuration: ang implementation ay hindi naglalantad ng transitive dependencies, na nagpapabilis ng build. Ang api ay naglalantad — ginagamit kapag ang library ay nag-e-export ng mga type mula sa ibang library (halimbawa, ang Retrofit ay gumagamit ng OkHttp types sa public API nito).

Para sa pamamahala ng bersyon, inirerekomenda ang paggamit ng BOM (Bill of Materials) — isang build file na tumutukoy sa mga compatible na bersyon ng mga library. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). Pagkatapos kumonekta ng BOM, tanging ang pangalan ng library na walang bersyon ang kailangang tukuyin — awtomatikong pipili ang BOM ng compatible na bersyon. Ito ay nag-aalis ng mga conflict sa pagitan ng transitive dependencies ng iba't ibang library. Ang BOM ay available para sa Firebase, Compose, Kotlin, Ktor, AndroidX.

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

    // AndroidX at 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 (mga bersyon mula sa BOM)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

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

build.gradle sa multi-module projects

Sa multi-module projects, bawat module ay may sariling build.gradle. Para sa pagkonekta ng isang module sa isa pa, ginagamit ang syntax na implementation(project(":module-name")). Awtomatikong binu-build ng Gradle ang module kung nagbago ang configuration nito. Ang multi-module architecture ay nagpapabuti ng build time (incremental build, parallelism) at naghahati ng responsibilidad sa pagitan ng feature modules, core modules, at mga library.

Ang pangunahing problema ng multi-module projects — pagdodoble ng configuration. Kung 10 module ay may parehong minSdk, compileSdk at Compose dependencies, iyon ay 10 kopya sa iba't ibang build.gradle. Ang solusyon — Convention Plugins (dating buildSrc). Ang Convention Plugin ay isang Gradle plugin na nakasulat sa Kotlin na inilalapat sa mga module: plugins { id("myapp.android.library") }. Ang plugin ay naglalaman ng shared configuration, at ang mga pagbabago ay agad na inilalapat sa lahat ng module.

Para sa organisasyon ng Convention Plugins, ginagamit ang direktoryo build-logic/ sa root ng project. Ito ay naglalaman ng includeBuild sa settings.gradle at Kotlin plugins. Ang Convention Plugins ay maaaring i-publish sa maven repository para sa pag-reuse sa pagitan ng mga project. Inirerekomenda ng Google ang Convention Plugins bilang pamantayan para sa multi-module projects, na pinapalitan ang subprojects { } at apply from. Ang paglipat sa Convention Plugins ay nagpapababa ng build.gradle ng module sa 10-15 linya.

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

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