settings.gradle: включване на модули и pluginManagement

Какво е settings.gradle?

settings.gradle (или settings.gradle.kts за Kotlin DSL) е файлът, който Gradle изпълнява във фазата Initialization. В него се определя йерархията на проекта, включват се модули, конфигурират се хранилища за плъгини и зависимости. Без settings.gradle Gradle не знае кои модули да изгражда и кои плъгини са налични. В едномодулен проект settings.gradle може да липсва — Gradle използва стойности по подразбиране, но за мултимодулни проекти е задължителен.

Файлът settings.gradle се намира в корена на проекта, до кореновия build.gradle. Типична структура на корена на проекта: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle се изпълнява преди build.gradle — във фазата Initialization Gradle изгражда дървото на проекта (Project в Gradle API). След завършване на Initialization започва Configuration — изпълнение на build.gradle на всеки модул.

Исторически, settings.gradle се появява в Gradle 0.7 (2010) и първоначално съдържа само include директиви. С развитието на Gradle към settings.gradle бяха добавени pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) и versionCatalogs (Gradle 7.4). Модерният settings.gradle е мощен конфигурационен файл, който централизира управлението на плъгини, хранилища и версии за целия проект. Google затвърждава тези възможности в Android Gradle Plugin, започвайки от AGP 8.0.

settings.gradle срещу build.gradle

settings.gradle управлява структурата на проекта и глобалните настройки (плъгини, хранилища). build.gradle управлява изграждането (зависимости, Android конфигурации, задачи). settings.gradle се изпълнява първи и има достъп до Settings API. build.gradle се изпълнява по-късно и има достъп до Project API. Никакви модулни конфигурации (android блок, dependencies) не могат да бъдат в settings.gradle — това е грешка.

Включване на модули чрез include

Директивата include е основната директива в settings.gradle. Тя уведомява Gradle кои модули трябва да участват в изграждането. Аргументът на include е пътят на модула: include(":app") — включва модул в корена, include(":core:network") — модул в поддиректорията core/network/. Двоеточието в началото показва, че пътят е относителен спрямо корена на проекта. След include Gradle автоматично намира build.gradle в указаната директория и добавя модула към дървото на проекта.

Всяко include създава Project в Gradle API с име, равно на низа include. Името на проекта се използва в implementation(project(":module")) в build.gradle на други модули. Ако модул не е включен чрез include, препратка към него от друг модул ще причини грешка "Project not found". Android Studio IDE също използва settings.gradle за показване на модули в панела Project — модулите без include не се виждат в дървото на файловете.

include поддържа included builds и composite builds чрез includeBuild("../library-project"). Това позволява включването на цели Gradle проекти като външни модули. Included builds са полезни за паралелно разработване на библиотеки с приложението: промените в библиотеката са незабавно видими в приложението без публикуване в maven хранилище. В продукционно изграждане includeBuild се заменя с обикновена maven зависимост.

// settings.gradle.kts — типична структура
rootProject.name = "MyApp"

// Модули на приложението
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Включване на външна библиотека (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Блок Plugin Management

Resolution Strategy

pluginManagement — блок в settings.gradle, който определя откъде да се зареждат Gradle плъгини. Появи се в Gradle 6.8 за централизирано управление на плъгини преди тяхното прилагане. Вътре в pluginManagement се намират: repositories (списък с хранилища за търсене на плъгини), resolutionStrategy (правила за разрешаване на версии) и plugins (изрично посочване на версии на плъгини). Ако pluginManagement не е настроен, Gradle използва хранилищата от build.gradle — но плъгините се търсят едва след като бъдат декларирани, което води до грешки, ако плъгин не бъде намерен.

В Android проект pluginManagement е задължителен, ако се използват Каталози с версии или Convention Plugins. Без pluginManagement Gradle няма да може да намери плъгина com.android.application при прилагане в build.gradle.kts. Типична конфигурация: repositories съдържа google() (Android плъгини), mavenCentral() (плъгини на трети страни) и gradlePluginPortal() (официални Gradle плъгини).

pluginManagement поддържа също plugins — деклариране на плъгини с версии, които след това се прилагат в build.gradle без посочване на версия. Това централизира версиите на плъгини: ако 10 модула прилагат kotlin-android, версията се посочва веднъж в pluginManagement. Важно: pluginManagement.plugins е само декларация. Самият плъгин се прилага в build.gradle чрез plugins { id("org.jetbrains.kotlin.android") }.

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        maven { url = "https://jitpack.io" }
    }

    // Версии на плъгини — централизирано
    plugins {
        id("com.android.application") version "8.7.0"
        id("com.android.library") version "8.7.0"
        id("org.jetbrains.kotlin.android") version "2.0.21"
        id("com.google.devtools.ksp") version "2.0.21-1.0.25"
    }

    resolutionStrategy {
        // Принудителна версия на плъгин за всички модули
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Прилагане на плъгини — apply false (да не се прилага към корена)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Dependency Resolution Management

Режими на repositoriesMode

dependencyResolutionManagement — блок в settings.gradle, който централизирано управлява хранилищата за всички модули. Появи се в Gradle 7.0 като алтернатива на декларирането на repositories във всеки build.gradle. Вътре в блока се настройват repositoriesMode (режим: PREFER_PROJECT, PREFER_SETTINGS или FAIL_ON_PROJECT_REPOS) и repositories (списък с хранилища). Ако repositoriesMode = PREFER_SETTINGS, модулните repositories се игнорират — използва се само централизираният списък.

repositoriesMode може да приема три стойности. PREFER_SETTINGS — хранилищата от build.gradle се игнорират, използват се само от settings.gradle. PREFER_PROJECT — хранилищата на build.gradle имат приоритет пред settings.gradle. FAIL_ON_PROJECT_REPOS — ако модул декларира собствени хранилища, Gradle дава грешка. За нови проекти се препоръчва PREFER_SETTINGS — това гарантира, че всички модули използват едни и същи хранилища, и елиминира дублирането.

repositoriesMode = FAIL_ON_PROJECT_REPOS е особено полезен в екипи: ако разработчик добави хранилище само в един модул, а останалите не го виждат, възниква ситуация "works on my machine". FAIL_ON_PROJECT_REPOS принуждава всички хранилища да се декларират централизирано в settings.gradle, което предотвратява подобни ситуации. Google препоръчва FAIL_ON_PROJECT_REPOS за всички Android проекти, започвайки от AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — всички хранилища само тук
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

    repositories {
        google()
        mavenCentral()
        maven { url = "https://jitpack.io" }

        // Частно maven хранилище
        maven {
            url = "https://maven.pkg.github.com/company/internal-lib"
            credentials {
                username = providers.gradleProperty("gpr.user")
                    .getOrNull() ?: System.getenv("GPR_USER") ?: ""
                password = providers.gradleProperty("gpr.key")
                    .getOrNull() ?: System.getenv("GPR_KEY") ?: ""
            }
        }
    }
}

// В build.gradle на модула repositories вече не са необходими!
// Всички хранилища централизирани в settings.gradle

Каталози с версии в settings.gradle

Каталози с версии са централизиран начин за управление на версии на зависимости чрез TOML файл. От Gradle 7.4 Каталозите с версии са препоръчителният механизъм за всички Android проекти. Файлът gradle/libs.versions.toml съдържа три секции: [versions] (версии), [libraries] (зависимости), [plugins] (плъгини). В settings.gradle Каталогът с версии се включва чрез @Suppress("UnstableApiUsage") и enableFeaturePreview("VERSION_CATALOGS") (в стари версии на Gradle).

След включване на Каталога с версии, в build.gradle на модулите зависимостите се посочват чрез libs: implementation(libs.retrofit). IDE предоставя автоматично довършване за libs. Каталогът автоматично генерира type-safe accessors: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles са групи от зависимости, които могат да бъдат включени с един ред. Каталозите с версии поддържат също наследяване — могат да бъдат включени множество TOML файлове.

Предимства на Каталозите с версии: единно място за версии (не е необходимо търсене във всички build.gradle); type-safe достъп (грешка в името на libs се открива във фазата на компилация, а не в runtime); автоматични актуализации (Dependabot и Renovate поддържат TOML); съвместимост с Convention Plugins. Google Firebase и AndroidX разпространяват собствени TOML каталози. За миграция към Каталози с версии съществуват плъгини, които автоматично прехвърлят версии от build.gradle в TOML.

# gradle/libs.versions.toml
[versions]
agp = "8.7.0"
kotlin = "2.0.21"
composeBom = "2024.12.01"
retrofit = "2.11.0"
coroutines = "1.9.0"

[libraries]
retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
retrofit-gson = { module = "com.squareup.retrofit2:converter-gson", version.ref = "retrofit" }
kotlin-coroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
compose-bom = { module = "androidx.compose:compose-bom", version.ref = "composeBom" }
compose-ui = { module = "androidx.compose.ui:ui" }

[bundles]
compose = ["compose-ui", "compose-material3"]

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

Разширени настройки: includeBuild и инкубиращи функции

includeBuild е директива за създаване на composite build: включване на външен Gradle проект като част от текущото изграждане. За разлика от include (включва модул), includeBuild включва цял проект със собствен settings.gradle, модули и плъгини. Composite builds се използват за: паралелно разработване на библиотеки (аналитика, мрежа) с приложението; включване на Convention Plugins от отделно хранилище; интегриране на build-logic модула.

Инкубиращи функции (Incubating Features) — експериментални опции на Gradle, които се включват чрез enableFeaturePreview("FEATURE_NAME"). В AGP 8.7+ са налични: TYPESAFE_PROJECT_ACCESSORS (type-safe достъп до проекти в мултимодулен проект: вместо project(":core:network") може да се пише projects.core.network), STABLE_CONFIGURATION_CACHE (стабилен кеш на конфигурацията), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (трансформация на артефакти). Инкубиращите функции могат да бъдат включени в продукция, но API може да се промени в бъдещи версии.

Gradle Enterprise и Build Scan също се конфигурират чрез settings.gradle: plugins { id("com.gradle.enterprise") } с блок gradleEnterprise. Build Scan е облачна услуга, която показва подробна информация за всяко изграждане: време за изпълнение на всяка задача, кеширане, грешки. Включването на Build Scan помага за диагностициране на проблеми със скоростта на изграждане. За проекти с отворен код Build Scan е безплатен.

// Инкубиращи функции
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
enableFeaturePreview("STABLE_CONFIGURATION_CACHE")

// Gradle Enterprise / Build Scan
plugins {
    id("com.gradle.enterprise") version "3.18"
}

gradleEnterprise {
    buildScan {
        termsOfServiceUrl = "https://gradle.com/terms-of-service"
        termsOfServiceAgree = "yes"
        publishAlwaysIf(true)
    }
}

// Използване на type-safe project accessors в build.gradle
// Вместо: implementation(project(":core:network"))
// Може: implementation(projects.core.network)