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 срещу 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 модули. Ако модулът е библиотека, вместо приложение се използва библиотечният плъгин и в android блока няма applicationId.

compileSdk — версията на SDK, с която се компилира кодът. Трябва да е равна на най-новия Android API (към момента на писане — 35). minSdk — минималната API версия за поддръжка. targetSdk — версията, към която приложението е насочено (поведенческите промени на тази версия се прилагат). Разликата между compileSdk и targetSdk: compileSdk определя наличните API, targetSdk — поведението по време на изпълнение. Препоръка: 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 (само по време на изпълнение), 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 автоматично изгражда модула, ако конфигурацията му се е променила. Мултимодулната архитектура подобрява времето за изграждане (инкрементално изграждане, паралелизъм) и разделя отговорността между функционални модули, основни модули и библиотеки.

Ключовият проблем на мултимодулните проекти — дублиране на конфигурация. Ако 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"))
}