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

Шта је settings.gradle?

settings.gradle (или settings.gradle.kts за Kotlin DSL) је фајл који Gradle извршава у фази Initialization. У њему се дефинише хијерархија пројекта, укључују модули, подешавају репозиторијуми за plugin-ове и зависности. Без settings.gradle, Gradle не зна које модуле да гради и који plugin-ови су доступни. У једно-модулском пројекту 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 је моћан конфигурациони фајл који централизује управљање plugin-овима, репозиторијумима и верзијама за цијели пројекат. Google учвршћује ове могућности у Android Gradle Plugin-у почевши од AGP 8.0.

settings.gradle vs build.gradle

settings.gradle управља структуром пројекта и глобалним подешавањима (plugin-ови, репозиторијуми). 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 plugin-ови. Појавио се у Gradle 6.8 за централизовано управљање plugin-овима прије њихове примјене. Унутар pluginManagement се налазе: repositories (листа репозиторијума за претрагу plugin-ова), resolutionStrategy (правила рјешавања верзија) и plugins (експлицитно навођење верзија plugin-ова). Ако pluginManagement није подешен, Gradle користи репозиторијуме из build.gradle — али plugin-ови се траже тек након што су декларисани, што доводи до грешака ако plugin није пронађен.

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

pluginManagement такође подржава plugins — декларисање plugin-ова са верзијама које се затим примјењују у build.gradle без навођења верзије. Ово централизује верзије plugin-ова: ако 10 модула примјењује kotlin-android, верзија се наводи једном у pluginManagement. Важно: pluginManagement.plugins је само декларација. Сам plugin се примјењује у build.gradle преко plugins { id("org.jetbrains.kotlin.android") }.

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

    // Верзије plugin-ова — централизовано
    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 {
        // Принудна верзија plugin-а за све модуле
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Примјена plugin-ова — 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] (plugin-ови). У 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 каталоге. За миграцију на Каталоге верзија постоје plugin-ови који аутоматски преносе верзије из 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, модулима и plugin-овима. 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 је cloud сервис који приказује детаљне информације о свакој изградњи: вријеме извршења сваког задатка, кеширање, грешке. Укључивање 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)