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 в API Gradle). Після завершення 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 vs 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 в API Gradle з іменем, рівним рядку 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-репозиторій. У production-збірці 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"))
    }
}

Блок керування плагінами

Стратегія вирішення

pluginManagement — блок у settings.gradle, який визначає, звідки завантажувати плагіни Gradle. З'явився в Gradle 6.8 для централізованого керування плагінами до їх застосування. Всередині pluginManagement знаходяться: repositories (список репозиторіїв для пошуку плагінів), resolutionStrategy (правила вирішення версій) та plugins (явне вказання версій плагінів). Якщо pluginManagement не заданий, Gradle використовує репозиторії з build.gradle — але плагіни шукаються тільки після того, як вони оголошені, що призводить до помилок, якщо плагін не знайдено.

У Android-проєкті pluginManagement обов'язковий, якщо використовуються Version Catalogs або 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
}

Керування вирішенням залежностей

Режими 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

Version Catalogs — це централізований спосіб керування версіями залежностей через 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 виявиться на етапі компіляції, а не під час виконання); автоматичні оновлення (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 (трансформація артефактів). Інкубаційні функції можна вмикати в production, але API може змінитися в наступних версіях.

Gradle Enterprise та Build Scan також конфігуруються через settings.gradle: plugins { id("com.gradle.enterprise") } з блоком gradleEnterprise. Build Scan — це хмарний сервіс, який показує детальну інформацію про кожну збірку: час виконання кожного завдання, кешування, помилки. Включення Build Scan допомагає діагностувати проблеми зі швидкістю збірки. Для opensource проєктів 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)