settings.gradle: что это, include модулей и 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 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 в 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-репозиторий. В 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"))
    }
}

Plugin Management Block

Resolution Strategy

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
}

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" }

        // Private 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

Version Catalogs в settings.gradle

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

После подключения Version Catalog, в build.gradle модулей зависимости указываются через libs: implementation(libs.retrofit). IDE даёт автодополнение для libs. Каталог автоматически генерирует type-safe accessors: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles — это группы зависимостей, которые можно подключить одной строкой. Version Catalogs также поддерживают наследование — можно подключать несколько TOML-файлов.

Преимущества Version Catalogs: единое место для версий (не надо искать по всем build.gradle); type-safe доступ (ошибка в имени libs выявится на этапе компиляции, а не runtime); автоматические обновления (Dependabot и Renovate поддерживают TOML); совместимость с Convention Plugins. Google Firebase и AndroidX распространяют собственные TOML-каталоги. Для миграции на Version Catalogs существуют плагины, которые автоматически переносят версии из 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)