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, новий 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 (project-level)
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 (module-level)
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 не може перевірити синтаксис і типи до виконання скрипту, що призводить до помилок під час виконання через неправильне ім'я параметра або тип.

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 виявляються лише під час виконання. 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-модулів. Якщо модуль — бібліотека, замість application використовується бібліотечний плагін, а в android-блоці відсутній applicationId.

compileSdk — версія SDK, з якою компілюється код. Вона повинна дорівнювати останньому Android API (на момент написання — 35). minSdk — мінімальна версія API для підтримки. targetSdk — версія, на яку орієнтовано застосунок (поведінкові зміни цієї версії застосовуються). Різниця між compileSdk та targetSdk: compileSdk визначає доступні API, targetSdk — поведінку під час виконання. Рекомендація: compileSdk = остання, targetSdk = остання - 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 (тільки під час виконання), 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 автоматично збирає модуль, якщо його конфігурація змінилася. Багатомодульна архітектура покращує час збірки (інкрементальна збірка, паралелізм) та розділяє відповідальність між feature-модулями, 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"))
}