build.gradle: шта је то, синтакса и конфигурација у Android-у

Шта је build.gradle?

build.gradle је скрипта за изградњу на језику Groovy (екстензија .gradle) или Kotlin (.gradle.kts) која управља свим аспектима компилације Android апликације. Gradle је систем аутоматске изградње који је Google усвојио 2013. године као стандард за Android. build.gradle описује: који су додаци примењени (Android, Kotlin, библиотеке), које су зависности повезане, које верзије SDK се користе, како потписати апликацију и где објавити.

Процес изградње укључује три фазе: Initialization (одређивање модула), Configuration (извршавање build.gradle скрипти), Execution (извршавање задатака). build.gradle се извршава у фази Configuration, када Gradle креира граф задатака. У овом тренутку се одређују Build Variants, израчунавају зависности и конфигуришу задаци. Важно: build.gradle је код, а не само конфигурација. У њему се могу користити услови, петље, позиви метода и екстерне скрипте.

Gradle датотеке се чувају у корену модула (app/build.gradle) и корену пројекта (build.gradle). Поред тога, Gradle подржава apply from — повезивање екстерних Gradle скрипти. Ово омогућава извлачење понављајуће логике у датотеке са заједничким подешавањима. Са појавом Convention Plugins (AGP 7+), apply from се сматра застарелим — Convention Plugins пружају type-safe и композитни начин поновне употребе конфигурације између модула.

Еволуција build.gradle

Од 2013. године, синтакса build.gradle је претрпела значајне промене: од Groovy-ја са динамичким конфигурацијама до Kotlin DSL-а са провером у време компилације. AGP је еволуирао од верзије 1.0 до 8.7 (2025). Кључне прекретнице: AGP 3.0 (Java 8 desugar, new variant API), AGP 4.0 (view binding, Java 11), AGP 7.0 (Kotlin DSL подразумевано, Java 11 min), AGP 8.0 (non-transitive R classes, конфигурација изградње у Kotlin-у), AGP 8.7 (KSP уместо kapt, брза конфигурација).

Project-level и Module-level build.gradle

Project-level build.gradle (корен) поставља додатке, репозиторијуме и конфигурације заједничке за све модуле. Главни блокови: plugins (повезивање Gradle додатака), repositories (извори зависности: mavenCentral, google, jitpack). У кореном build.gradle обично нема android блока — он се појављује у модулима. Project-level такође може садржати блок subprojects за заједничку конфигурацију свих подпројеката, иако су Convention Plugins пожељнији.

Module-level build.gradle (нпр. app/build.gradle) описује одређени модул. Ако је модул апликација, примењује додатак com.android.application. Ако је библиотека — com.android.library. У module-level се налазе: android блок (compileSdk, defaultConfig, buildTypes, productFlavors), dependencies блок (зависности модула) и опциони блокови за подешавање тестова и изградње. Module-level се извршава након project-level и може прегазити заједничка подешавања.

Од AGP 8.0, корени build.gradle може користити version catalogs (libs.versions.toml) за централизовано управљање верзијама зависности. Version catalog је датотека у gradle/ директоријуму која садржи верзије, библиотеке и додатке. У build.gradle зависности се повезују преко libs: implementation(libs.retrofit). Version catalogs су обавезни за нове пројекте и препоручују се за све пројекте са три или више модула.

// settings.gradle.kts — корен пројекта
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (ниво пројекта)
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 (ниво модула)
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 је динамички JVM језик који је био оригинална синтакса Gradle-а. Groovy скрипте (.gradle) користе динамичко типизирање: могу се изоставити типови, користити наводници или не, позивати методе које не постоје у фази компилације. Флексибилност Groovy-ја је и његов недостатак: IDE не може проверити синтаксу и типове пре извршавања скрипте, што доводи до runtime грешака при нетачном имену параметра или типу.

Kotlin DSL (.gradle.kts) користи статичко типизирање Kotlin-а. IDE проверава типове, предлаже доступне параметре кроз аутоматско довршавање и истиче грешке у фази уређивања. Kotlin DSL је спорији у фази Configuration (због компилације .kts датотека у бајткод), али Google константно побољшава перформансе: AGP 8.5+ користи Gradle Configuration Cache и Caching Kotlin DSL compilation, што своди разлику на 1-2 секунде.

Google препоручује Kotlin DSL за све нове пројекте и постепену миграцију постојећих. Миграција са Groovy-ја на Kotlin DSL је једноставна: наводници се замењују заградама, додају се типови, оператори се претварају у функције. Већина библиотека пружа примере Kotlin DSL-а у документацији. За сложене случајеве (Custom Plugin, Task Graph) Kotlin DSL пружа type-safe API и спречава грешке које се у Groovy-ју откривају само у runtime-у. Version catalogs (libs.versions.toml) раде исто са обе синтаксе.

Android блок: подешавање апликације

compileSdk, minSdk и targetSdk

Android блок — централни елемент module-level build.gradle. Унутар њега се конфигуришу: namespace (за R и BuildConfig), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Сви параметри android блока се примењују само на Android модуле. Ако је модул библиотека, уместо апликације користи се библиотечки додатак, а у android блоку нема applicationId.

compileSdk — верзија SDK-а са којом се компајлира код. Треба да буде једнака најновијем Android API-ју (у време писања — 35). minSdk — минимална API верзија за подршку. targetSdk — верзија на коју је апликација оријентисана (промене понашања ове верзије се примењују). Разлика између compileSdk и targetSdk: compileSdk одређује доступне API-је, targetSdk — понашање runtime-а. Препорука: compileSdk = latest, targetSdk = latest - 1 (за тестирање адаптације на нове промене).

compileOptions поставља Java компатибилност: sourceCompatibility и targetCompatibility. AGP 8+ захтева Java 17+ за компилацију. packaging управља укључивањем датотека из библиотека: exclude, merge, pickFirst за решавање META-INF конфликата. buildFeatures укључује/искључује ViewBinding, DataBinding, Compose. aaptOptions конфигурише обраду ресурса: ignoreAssetsPattern, cruncherEnabled. Сваки елемент android блока оптимизује одређени аспект изградње.

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

Управљање зависностима

BOM (Bill of Materials)

Зависности у build.gradle-у су библиотеке и модули који се повезују са пројектом. Блок dependencies се налази на истом нивоу као и android блок. Gradle подржава неколико конфигурација: implementation (библиотека је доступна у овом модулу, није транзитивна), api (библиотека је транзитивно доступна зависним модулима), compileOnly (само за компилацију, не укључује се у APK), runtimeOnly (само у runtime-у), annotationProcessor / ksp (обрађивачи анотација), testImplementation (само за тестове), androidTestImplementation (само за инструменталне тестове).

Од AGP 8.0, Non-Transitive R classes — свака библиотека има своју R класу, што спречава конфликте ресурса. У блоку dependencies је важно користити правилне конфигурације: implementation не открива транзитивне зависности, што убрзава изградњу. api открива — користи се када библиотека извози типове из друге библиотеке (нпр. Retrofit користи OkHttp типове у свом јавном API-ју).

За управљање верзијама препоручује се коришћење BOM (Bill of Materials) — датотеке за изградњу која одређује компатибилне верзије библиотека. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). Након повезивања BOM-а, може се навести само назив библиотеке без верзије — BOM ће аутоматски изабрати компатибилну верзију. Ово елиминише конфликте између транзитивних зависности различитих библиотека. BOM су доступни за Firebase, Compose, Kotlin, Ktor, AndroidX.

dependencies {
    // BOM — управљање верзијама
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX и 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-а)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // Тестирање
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

build.gradle у вишемодулним пројектима

У вишемодулним пројектима, сваки модул има свој build.gradle. За повезивање једног модула са другим користи се синтакса implementation(project(":module-name")). Gradle аутоматски гради модул ако му се конфигурација променила. Вишемодулна архитектура побољшава време изградње (инкрементална изградња, паралелизам) и дели одговорност између функционалних модула, core модула и библиотека.

Кључни проблем вишемодулних пројеката — дуплирање конфигурације. Ако 10 модула има исти minSdk, compileSdk и Compose зависности, то је 10 копија у различитим build.gradle датотекама. Решење — Convention Plugins (раније buildSrc). Convention Plugin је Gradle додатак написан у Kotlin-у који се примењује на модуле: plugins { id("myapp.android.library") }. Додатак садржи заједничку конфигурацију, а промене се одмах примењују на све модуле.

За организацију Convention Plugins-а користи се директоријум build-logic/ у корену пројекта. Он садржи includeBuild у settings.gradle и Kotlin додатке. Convention Plugins могу бити објављени у maven репозиторијуму за поновну употребу између пројеката. Google препоручује Convention Plugins као стандард за вишемодулне пројекте, замењујући subprojects { } и apply from. Прелазак на Convention Plugins скраћује build.gradle модула на 10-15 линија.

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

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