settings.gradle: menyertakan modul dan pluginManagement

Apa itu settings.gradle?

settings.gradle (atau settings.gradle.kts untuk Kotlin DSL) adalah file yang dijalankan Gradle pada fase Initialization. Di dalamnya didefinisikan hierarki proyek, modul disertakan, repositori untuk plugin dan dependensi dikonfigurasi. Tanpa settings.gradle, Gradle tidak tahu modul mana yang akan dibangun dan plugin apa yang tersedia. Dalam proyek satu modul, settings.gradle mungkin tidak ada — Gradle menggunakan nilai default, tetapi untuk proyek multi-modul wajib ada.

File settings.gradle terletak di root proyek, di samping build.gradle root. Struktur tipikal root proyek: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle dijalankan sebelum build.gradle — pada fase Initialization, Gradle membangun pohon proyek (Project di API Gradle). Setelah Initialization selesai, Configuration dimulai — eksekusi build.gradle setiap modul.

Secara historis, settings.gradle muncul di Gradle 0.7 (2010) dan awalnya hanya berisi direktif include. Seiring perkembangan Gradle, pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0), dan versionCatalogs (Gradle 7.4) ditambahkan ke settings.gradle. settings.gradle modern adalah file konfigurasi kuat yang memusatkan manajemen plugin, repositori, dan versi untuk seluruh proyek. Google mengukuhkan kemampuan ini di Android Gradle Plugin mulai AGP 8.0.

settings.gradle vs build.gradle

settings.gradle mengelola struktur proyek dan pengaturan global (plugin, repositori). build.gradle mengelola build (dependensi, konfigurasi Android, tugas). settings.gradle dijalankan pertama dan memiliki akses ke Settings API. build.gradle dijalankan setelahnya dan memiliki akses ke Project API. Tidak ada konfigurasi modul (blok android, dependencies) yang boleh ada di settings.gradle — itu adalah kesalahan.

Menyertakan modul melalui include

Direktif include adalah direktif utama di settings.gradle. Ini memberi tahu Gradle modul mana yang harus berpartisipasi dalam build. Argumen include adalah jalur modul: include(":app") — menyertakan modul di root, include(":core:network") — modul di subdirektori core/network/. Tanda titik dua di awal menunjukkan bahwa jalur relatif terhadap root proyek. Setelah include, Gradle secara otomatis menemukan build.gradle di direktori yang ditentukan dan menambahkan modul ke pohon proyek.

Setiap include membuat Project di API Gradle dengan nama yang sama dengan string include. Nama proyek digunakan dalam implementation(project(":module")) di build.gradle modul lain. Jika modul tidak disertakan melalui include, referensi ke modul tersebut dari modul lain akan menyebabkan kesalahan "Project not found". Android Studio IDE juga menggunakan settings.gradle untuk menampilkan modul di panel Project — modul tanpa include tidak terlihat di pohon file.

include mendukung included builds dan composite builds melalui includeBuild("../library-project"). Ini memungkinkan menyertakan seluruh proyek Gradle sebagai modul eksternal. Included builds berguna untuk mengembangkan pustaka secara paralel dengan aplikasi: perubahan di pustaka langsung terlihat di aplikasi tanpa publikasi ke repositori maven. Dalam build produksi, includeBuild diganti dengan dependensi maven biasa.

// settings.gradle.kts — struktur tipikal
rootProject.name = "MyApp"

// Modul aplikasi
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Menyertakan pustaka eksternal (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Blok Plugin Management

Resolution Strategy

pluginManagement — blok di settings.gradle yang menentukan dari mana plugin Gradle dimuat. Muncul di Gradle 6.8 untuk manajemen terpusat plugin sebelum diterapkan. Di dalam pluginManagement terdapat: repositories (daftar repositori untuk mencari plugin), resolutionStrategy (aturan resolusi versi) dan plugins (penentuan versi plugin secara eksplisit). Jika pluginManagement tidak diatur, Gradle menggunakan repositori dari build.gradle — tetapi plugin hanya dicari setelah dideklarasikan, yang menyebabkan kesalahan jika plugin tidak ditemukan.

Dalam proyek Android, pluginManagement wajib jika menggunakan Katalog Versi atau Convention Plugins. Tanpa pluginManagement, Gradle tidak akan dapat menemukan plugin com.android.application saat diterapkan di build.gradle.kts. Konfigurasi tipikal: repositories berisi google() (plugin Android), mavenCentral() (plugin pihak ketiga), dan gradlePluginPortal() (plugin resmi Gradle).

pluginManagement juga mendukung plugins — deklarasi plugin dengan versi yang kemudian diterapkan di build.gradle tanpa menyebutkan versi. Ini memusatkan versi plugin: jika 10 modul menerapkan kotlin-android, versi ditentukan sekali di pluginManagement. Penting: pluginManagement.plugins hanya deklarasi. Plugin itu sendiri diterapkan di build.gradle melalui plugins { id("org.jetbrains.kotlin.android") }.

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

    // Versi plugin — terpusat
    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 {
        // Versi plugin paksa untuk semua modul
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Menerapkan plugin — apply false (jangan terapkan ke root)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Dependency Resolution Management

Mode repositoriesMode

dependencyResolutionManagement — blok di settings.gradle yang mengelola repositori secara terpusat untuk semua modul. Muncul di Gradle 7.0 sebagai alternatif untuk mendeklarasikan repositories di setiap build.gradle. Di dalam blok diatur repositoriesMode (mode: PREFER_PROJECT, PREFER_SETTINGS atau FAIL_ON_PROJECT_REPOS) dan repositories (daftar repositori). Jika repositoriesMode = PREFER_SETTINGS, repositories modul diabaikan — hanya daftar terpusat yang digunakan.

repositoriesMode dapat memiliki tiga nilai. PREFER_SETTINGS — repositori dari build.gradle diabaikan, hanya dari settings.gradle yang digunakan. PREFER_PROJECT — repositori build.gradle memiliki prioritas di atas settings.gradle. FAIL_ON_PROJECT_REPOS — jika modul mendeklarasikan repositori sendiri, Gradle mengeluarkan kesalahan. Untuk proyek baru, PREFER_SETTINGS direkomendasikan — ini menjamin semua modul menggunakan repositori yang sama dan menghilangkan duplikasi.

repositoriesMode = FAIL_ON_PROJECT_REPOS sangat berguna dalam tim: jika pengembang menambahkan repositori hanya ke satu modul, sementara yang lain tidak melihatnya, muncullah situasi "works on my machine". FAIL_ON_PROJECT_REPOS memaksa semua repositori dideklarasikan secara terpusat di settings.gradle, yang mencegah situasi seperti itu. Google merekomendasikan FAIL_ON_PROJECT_REPOS untuk semua proyek Android mulai AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — semua repositori hanya di sini
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

        // Repositori maven pribadi
        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") ?: ""
            }
        }
    }
}

// Di build.gradle modul, repositories tidak diperlukan lagi!
// Semua repositori terpusat di settings.gradle

Katalog Versi di settings.gradle

Katalog Versi adalah cara terpusat untuk mengelola versi dependensi melalui file TOML. Mulai Gradle 7.4, Katalog Versi adalah mekanisme yang direkomendasikan untuk semua proyek Android. File gradle/libs.versions.toml berisi tiga bagian: [versions] (versi), [libraries] (dependensi), [plugins] (plugin). Di settings.gradle, Katalog Versi disertakan melalui @Suppress("UnstableApiUsage") dan enableFeaturePreview("VERSION_CATALOGS") (di versi Gradle lama).

Setelah Katalog Versi disertakan, di build.gradle modul dependensi ditentukan melalui libs: implementation(libs.retrofit). IDE memberikan pelengkapan otomatis untuk libs. Katalog secara otomatis menghasilkan type-safe accessors: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles adalah grup dependensi yang dapat disertakan dengan satu baris. Katalog Versi juga mendukung pewarisan — beberapa file TOML dapat disertakan.

Keuntungan Katalog Versi: satu tempat untuk versi (tidak perlu mencari di semua build.gradle); akses type-safe (kesalahan nama libs terdeteksi pada fase kompilasi, bukan runtime); pembaruan otomatis (Dependabot dan Renovate mendukung TOML); kompatibilitas dengan Convention Plugins. Google Firebase dan AndroidX mendistribusikan katalog TOML mereka sendiri. Untuk migrasi ke Katalog Versi, ada plugin yang secara otomatis memindahkan versi dari build.gradle ke 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" }

Pengaturan Lanjutan: includeBuild dan fitur inkubasi

includeBuild adalah direktif untuk membuat composite build: menyertakan proyek Gradle eksternal sebagai bagian dari build saat ini. Berbeda dengan include (menyertakan modul), includeBuild menyertakan seluruh proyek dengan settings.gradle, modul, dan plugin sendiri. Composite builds digunakan untuk: pengembangan pustaka (analitik, jaringan) secara paralel dengan aplikasi; menyertakan Convention Plugins dari repositori terpisah; integrasi modul build-logic.

Fitur Inkubasi (Incubating Features) — opsi eksperimental Gradle yang diaktifkan melalui enableFeaturePreview("FEATURE_NAME"). Di AGP 8.7+ tersedia: TYPESAFE_PROJECT_ACCESSORS (akses type-safe ke proyek dalam proyek multi-modul: alih-alih project(":core:network") dapat menulis projects.core.network), STABLE_CONFIGURATION_CACHE (cache konfigurasi stabil), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (transformasi artefak). Fitur inkubasi dapat diaktifkan di produksi, tetapi API dapat berubah di versi mendatang.

Gradle Enterprise dan Build Scan juga dikonfigurasi melalui settings.gradle: plugins { id("com.gradle.enterprise") } dengan blok gradleEnterprise. Build Scan adalah layanan cloud yang menampilkan informasi detail tentang setiap build: waktu eksekusi setiap tugas, caching, kesalahan. Mengaktifkan Build Scan membantu mendiagnosis masalah kecepatan build. Untuk proyek opensource, Build Scan gratis.

// Fitur inkubasi
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)
    }
}

// Menggunakan type-safe project accessors di build.gradle
// Alih-alih: implementation(project(":core:network"))
// Bisa: implementation(projects.core.network)