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 с compile-time проверками. AGP эволюционировал от версии 1.0 до 8.7 (2025). Ключевые milestone: 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, build config in 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 не может проверить синтаксис и типы до выполнения скрипта, что приводит к 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-модулям. Если модуль — библиотека, вместо application указывается библиотечный плагин, а в 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 типы в своём public 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 (previously 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"))
}