settings.gradle: pagsama ng mga module at pluginManagement

Ano ang settings.gradle?

settings.gradle (o settings.gradle.kts para sa Kotlin DSL) ay ang file na isinasagawa ng Gradle sa phase na Initialization. Dito tinutukoy ang hierarchy ng proyekto, isinasama ang mga module, at kino-configure ang mga repository para sa mga plugin at dependency. Kung walang settings.gradle, hindi alam ng Gradle kung aling mga module ang bubuin at kung aling mga plugin ang available. Sa isang proyektong may isang module, maaaring wala ang settings.gradle — gumagamit ang Gradle ng mga default na halaga, ngunit para sa mga multi-module na proyekto ito ay sapilitan.

Ang file na settings.gradle ay matatagpuan sa root ng proyekto, katabi ng root build.gradle. Karaniwang istraktura ng root ng proyekto: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. Ang settings.gradle ay isinasagawa bago ang build.gradle — sa phase na Initialization, itinatayo ng Gradle ang puno ng proyekto (Project sa Gradle API). Pagkatapos ng Initialization, magsisimula ang Configuration — pagpapatakbo ng build.gradle ng bawat module.

Sa kasaysayan, lumitaw ang settings.gradle sa Gradle 0.7 (2010) at sa simula ay naglalaman lamang ng mga direktibang include. Sa pag-unlad ng Gradle, idinagdag ang pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0), at versionCatalogs (Gradle 7.4) sa settings.gradle. Ang modernong settings.gradle ay isang makapangyarihang configuration file na nagsasentro ng pamamahala ng mga plugin, repository, at bersyon para sa buong proyekto. Pinatatatag ng Google ang mga kakayahang ito sa Android Gradle Plugin simula AGP 8.0.

settings.gradle vs build.gradle

settings.gradle ay namamahala sa istraktura ng proyekto at mga pandaigdigang setting (plugin, repository). build.gradle ay namamahala sa build (mga dependency, configuration ng Android, mga task). Ang settings.gradle ay unang isinasagawa at may access sa Settings API. Ang build.gradle ay isinasagawa pagkatapos at may access sa Project API. Walang configuration ng module (android block, dependencies) ang maaaring nasa settings.gradle — iyon ay isang error.

Pagsama ng mga module sa pamamagitan ng include

Ang direktibang include ay ang pangunahing direktiba sa settings.gradle. Sinasabi nito sa Gradle kung aling mga module ang dapat lumahok sa build. Ang argumento ng include ay ang path ng module: include(":app") — isinasama ang module sa root, include(":core:network") — module sa subdirectory na core/network/. Ang tutuldok sa simula ay nagpapahiwatig na ang path ay relative sa root ng proyekto. Pagkatapos ng include, awtomatikong hinahanap ng Gradle ang build.gradle sa tinukoy na direktoryo at idinaragdag ang module sa puno ng proyekto.

Ang bawat include ay lumilikha ng Project sa Gradle API na may pangalang katumbas ng string ng include. Ang pangalan ng proyekto ay ginagamit sa implementation(project(":module")) sa build.gradle ng iba pang module. Kung ang module ay hindi isinama sa pamamagitan ng include, ang pag-reference dito mula sa ibang module ay magdudulot ng error na "Project not found". Ginagamit din ng Android Studio IDE ang settings.gradle para ipakita ang mga module sa panel ng Project — ang mga module na walang include ay hindi nakikita sa puno ng file.

Sinusuportahan ng include ang included builds at composite builds sa pamamagitan ng includeBuild("../library-project"). Pinapayagan nito na isama ang buong Gradle project bilang mga panlabas na module. Ang included builds ay kapaki-pakinabang para sa parallel na pag-develop ng mga library kasama ang application: ang mga pagbabago sa library ay agad na makikita sa application nang walang pag-publish sa maven repository. Sa production build, ang includeBuild ay pinapalitan ng ordinaryong maven dependency.

// settings.gradle.kts — karaniwang istraktura
rootProject.name = "MyApp"

// Mga module ng application
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Pagsama ng panlabas na library (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Bloke ng Plugin Management

Resolution Strategy

pluginManagement — isang bloke sa settings.gradle na tumutukoy kung saan nagmumula ang mga Gradle plugin. Lumitaw sa Gradle 6.8 para sa sentralisadong pamamahala ng mga plugin bago ilapat ang mga ito. Sa loob ng pluginManagement ay matatagpuan: repositories (listahan ng mga repository para sa paghahanap ng mga plugin), resolutionStrategy (mga patakaran sa pag-resolve ng bersyon) at plugins (eksplisitong pagtukoy ng mga bersyon ng plugin). Kung hindi naka-set ang pluginManagement, ginagamit ng Gradle ang mga repository mula sa build.gradle — ngunit ang mga plugin ay hinahanap lamang pagkatapos na ideklara ang mga ito, na nagdudulot ng mga error kung hindi natagpuan ang plugin.

Sa proyekto ng Android, ang pluginManagement ay sapilitan kung gumagamit ng Mga Version Catalog o Convention Plugins. Kung walang pluginManagement, hindi mahahanap ng Gradle ang plugin na com.android.application kapag inilapat sa build.gradle.kts. Karaniwang configuration: ang repositories ay naglalaman ng google() (mga plugin ng Android), mavenCentral() (mga third-party na plugin) at gradlePluginPortal() (mga opisyal na Gradle plugin).

Sinusuportahan din ng pluginManagement ang plugins — deklarasyon ng mga plugin na may mga bersyon na pagkatapos ay inilalapat sa build.gradle nang walang pagbanggit ng bersyon. Nagsasentro ito ng mga bersyon ng plugin: kung 10 module ang nag-aplay ng kotlin-android, ang bersyon ay tinukoy nang isang beses sa pluginManagement. Mahalaga: ang pluginManagement.plugins ay deklarasyon lamang. Ang plugin mismo ay inilalapat sa build.gradle sa pamamagitan ng plugins { id("org.jetbrains.kotlin.android") }.

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

    // Mga bersyon ng plugin — sentralisado
    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 {
        // Pilit na bersyon ng plugin para sa lahat ng module
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Paglalapat ng mga plugin — apply false (huwag ilapat sa root)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Dependency Resolution Management

Mga mode ng repositoriesMode

dependencyResolutionManagement — isang bloke sa settings.gradle na sentralisadong namamahala ng mga repository para sa lahat ng module. Lumitaw sa Gradle 7.0 bilang alternatibo sa pagdedeklara ng repositories sa bawat build.gradle. Sa loob ng bloke ay naka-set ang repositoriesMode (mode: PREFER_PROJECT, PREFER_SETTINGS o FAIL_ON_PROJECT_REPOS) at repositories (listahan ng mga repository). Kung repositoriesMode = PREFER_SETTINGS, ang mga repository ng module ay binabalewala — tanging ang sentralisadong listahan ang ginagamit.

Ang repositoriesMode ay maaaring magkaroon ng tatlong halaga. PREFER_SETTINGS — ang mga repository mula sa build.gradle ay binabalewala, tanging mula sa settings.gradle ang ginagamit. PREFER_PROJECT — ang mga repository ng build.gradle ay may priyoridad kaysa sa settings.gradle. FAIL_ON_PROJECT_REPOS — kung ang module ay nagdedeklara ng sarili nitong mga repository, nagbibigay ang Gradle ng error. Para sa mga bagong proyekto, inirerekomenda ang PREFER_SETTINGS — ginagarantiyahan nito na ang lahat ng module ay gumagamit ng parehong mga repository at inaalis ang pagdodoble.

Ang repositoriesMode = FAIL_ON_PROJECT_REPOS ay lalong kapaki-pakinabang sa mga team: kung ang isang developer ay nagdagdag ng repository sa isang module lamang, at ang iba ay hindi ito nakikita, lumilitaw ang sitwasyong "works on my machine". Pinipilit ng FAIL_ON_PROJECT_REPOS na ideklara ang lahat ng repository nang sentralisado sa settings.gradle, na pumipigil sa mga ganitong sitwasyon. Inirerekomenda ng Google ang FAIL_ON_PROJECT_REPOS para sa lahat ng Android project simula AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — lahat ng repository dito lamang
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

        // Pribadong maven repository
        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") ?: ""
            }
        }
    }
}

// Sa build.gradle ng module, hindi na kailangan ang repositories!
// Lahat ng repository ay sentralisado sa settings.gradle

Mga Version Catalog sa settings.gradle

Mga Version Catalog ay isang sentralisadong paraan ng pamamahala ng mga bersyon ng dependency sa pamamagitan ng TOML file. Simula Gradle 7.4, ang mga Version Catalog ay ang inirerekomendang mekanismo para sa lahat ng Android project. Ang file na gradle/libs.versions.toml ay naglalaman ng tatlong seksyon: [versions] (mga bersyon), [libraries] (mga dependency), [plugins] (mga plugin). Sa settings.gradle, ang Version Catalog ay isinasama sa pamamagitan ng @Suppress("UnstableApiUsage") at enableFeaturePreview("VERSION_CATALOGS") (sa mga lumang bersyon ng Gradle).

Pagkatapos isama ang Version Catalog, sa build.gradle ng mga module ang mga dependency ay tinutukoy sa pamamagitan ng libs: implementation(libs.retrofit). Ang IDE ay nagbibigay ng autocomplete para sa libs. Ang catalog ay awtomatikong bumubuo ng type-safe accessors: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Ang bundles ay mga grupo ng mga dependency na maaaring isama sa isang linya. Sinusuportahan din ng mga Version Catalog ang inheritance — maraming TOML file ang maaaring isama.

Mga bentahe ng Version Catalog: iisang lugar para sa mga bersyon (hindi na kailangang maghanap sa lahat ng build.gradle); type-safe na access (error sa pangalan ng libs ay matutukoy sa compilation phase, hindi sa runtime); awtomatikong pag-update (sinusuportahan ng Dependabot at Renovate ang TOML); compatibility sa Convention Plugins. Ang Google Firebase at AndroidX ay namamahagi ng sarili nilang mga TOML catalog. Para sa migration sa Version Catalog, may mga plugin na awtomatikong naglilipat ng mga bersyon mula build.gradle patungo sa 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" }

Mga Advanced na Setting: includeBuild at mga incubating feature

includeBuild ay isang direktiba para sa paggawa ng composite build: pagsama ng isang panlabas na Gradle project bilang bahagi ng kasalukuyang build. Hindi tulad ng include (nagsasama ng module), ang includeBuild ay nagsasama ng isang buong proyekto na may sariling settings.gradle, mga module at plugin. Ang composite builds ay ginagamit para sa: parallel na pag-develop ng mga library (analytics, network) kasama ang application; pagsama ng Convention Plugins mula sa isang hiwalay na repository; integrasyon ng build-logic module.

Mga Incubating Feature — mga eksperimental na opsyon ng Gradle na pinapagana sa pamamagitan ng enableFeaturePreview("FEATURE_NAME"). Sa AGP 8.7+ ay available: TYPESAFE_PROJECT_ACCESSORS (type-safe na access sa mga proyekto sa isang multi-module na proyekto: sa halip na project(":core:network") ay maaaring magsulat ng projects.core.network), STABLE_CONFIGURATION_CACHE (stable na cache ng configuration), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (transformasyon ng artifact). Ang mga incubating feature ay maaaring paganahin sa production, ngunit ang API ay maaaring magbago sa mga susunod na bersyon.

Gradle Enterprise at Build Scan ay kino-configure din sa pamamagitan ng settings.gradle: plugins { id("com.gradle.enterprise") } na may gradleEnterprise block. Ang Build Scan ay isang cloud service na nagpapakita ng detalyadong impormasyon tungkol sa bawat build: oras ng pagpapatupad ng bawat task, caching, mga error. Ang pagpapagana ng Build Scan ay tumutulong sa pag-diagnose ng mga problema sa bilis ng build. Para sa mga opensource project, ang Build Scan ay libre.

// Mga incubating feature
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)
    }
}

// Paggamit ng type-safe project accessors sa build.gradle
// Sa halip na: implementation(project(":core:network"))
// Puwede: implementation(projects.core.network)