settings.gradle: nedir, modül ekleme ve pluginManagement

settings.gradle nedir?

settings.gradle (Kotlin DSL için settings.gradle.kts), Gradle'ın Initialization aşamasında yürüttüğü bir dosyadır. Proje hiyerarşisini tanımlar, modülleri ekler ve eklentiler ile bağımlılıklar için depoları yapılandırır. settings.gradle olmadan, Gradle hangi modüllerin oluşturulacağını ve hangi eklentilerin mevcut olduğunu bilemez. Tek modüllü bir projede settings.gradle bulunmayabilir — Gradle varsayılan değerleri kullanır, ancak çok modüllü projeler için zorunludur.

settings.gradle dosyası, proje kökünde, kök build.gradle'ın yanında bulunur. Tipik bir kök proje yapısı: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle, build.gradle'dan önce yürütülür — Initialization aşamasında Gradle proje ağacını (Gradle API'sinde Project) oluşturur. Initialization tamamlandıktan sonra, Configuration başlar — her modülün build.gradle'ının yürütülmesi.

Tarihsel olarak, settings.gradle Gradle 0.7'de (2010) ortaya çıktı ve başlangıçta yalnızca include yönergelerini içeriyordu. Gradle'ın gelişmesiyle birlikte pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) ve versionCatalogs (Gradle 7.4) eklendi. Modern settings.gradle, tüm proje için eklentileri, depoları ve sürüm yönetimini merkezileştiren güçlü bir yapılandırma dosyasıdır. Google, AGP 8.0'den itibaren Android Gradle Plugin'de bu yetenekleri zorunlu kılar.

settings.gradle ve build.gradle karşılaştırması

settings.gradle proje yapısını ve genel ayarları (eklentiler, depolar) yönetir. build.gradle derlemeyi (bağımlılıklar, Android yapılandırmaları, görevler) yönetir. settings.gradle önce yürütülür ve Settings API'sine erişebilir. build.gradle daha sonra yürütülür ve Project API'sine erişebilir. Hiçbir modül düzeyi yapılandırması (android bloğu, dependencies) settings.gradle'da bulunamaz — bu bir hata olur.

include ile modül ekleme

include yönergesi settings.gradle'ın temelidir. Gradle'a hangi modüllerin derlemeye katılması gerektiğini söyler. include argümanı, modül yolunu içeren bir dizedir: include(":app") kök düzeyinde bir modül ekler, include(":core:network") core/network/ alt dizininde bir modül ekler. Baştaki iki nokta, yolun proje köküne göre olduğunu belirtir. include'dan sonra Gradle, belirtilen dizinde build.gradle'ı otomatik olarak bulur ve modülü proje ağacına ekler.

Her include, Gradle API'sinde include dizesine eşit bir ada sahip bir Project oluşturur. Proje adı, diğer modüllerin build.gradle dosyalarında implementation(project(":module")) içinde kullanılır. Bir modül include aracılığıyla eklenmemişse, başka bir modülden ona başvurmak “Project not found” hatasına neden olur. Android Studio IDE ayrıca Project panelinde modülleri görüntülemek için settings.gradle'ı kullanır — include olmayan modüller dosya ağacında görünmez.

include, includeBuild("../library-project") aracılığıyla included builds ve composite builds'i destekler. Bu, tüm Gradle projelerinin harici modüller olarak eklenmesine olanak tanır. Included builds, kitaplıkları uygulamayla paralel olarak geliştirmek için kullanışlıdır: kitaplıktaki değişiklikler, Maven deposunda yayınlanmadan uygulamada hemen görünür. Üretim derlemesinde, includeBuild normal bir Maven bağımlılığı ile değiştirilir.

// settings.gradle.kts — tipik yapı
rootProject.name = "MyApp"

// Uygulama modülleri
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Harici bir kitaplığın eklenmesi (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Eklenti yönetim bloğu

Çözümleme stratejisi

pluginManagement, settings.gradle'da Gradle eklentilerinin nereden yükleneceğini belirleyen bir bloktur. Gradle 6.8'de, eklentileri uygulamadan önce merkezi olarak yönetmek için ortaya çıktı. pluginManagement içinde şunlar bulunur: repositories (eklentileri bulmak için depoların listesi), resolutionStrategy (sürüm çözümleme kuralları) ve plugins (açık eklenti sürümü bildirimleri). pluginManagement tanımlanmazsa, Gradle build.gradle'daki depoları kullanır — ancak eklentiler yalnızca bildirildikten sonra aranır, bu da bir eklenti bulunamazsa hatalara yol açar.

Android projelerinde, Version Catalogs veya Convention Plugins kullanılıyorsa pluginManagement zorunludur. pluginManagement olmadan, Gradle build.gradle.kts'de uygulandığında com.android.application eklentisini bulamaz. Tipik bir yapılandırma: repositories, google() (Android eklentileri), mavenCentral() (üçüncü taraf eklentiler) ve gradlePluginPortal() (resmi Gradle eklentileri) içerir.

pluginManagement ayrıca plugins'i de destekler — sürümlerle birlikte eklentileri bildirir ve daha sonra build.gradle'da sürüm belirtmeden uygulanır. Bu, eklenti sürümlerini merkezileştirir: 10 modül kotlin-android uyguluyorsa, sürüm pluginManagement'da bir kez belirtilir. Önemli: pluginManagement.plugins yalnızca bir bildirimdir. Eklentinin kendisi build.gradle'da plugins { id("org.jetbrains.kotlin.android") } aracılığıyla uygulanır.

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

    // Eklenti sürümleri — merkezi
    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 {
        // Tüm modüller için zorunlu eklenti sürümü
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Eklentileri uygulama — apply false (köke uygulama)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Bağımlılık çözümleme yönetimi

repositoriesMode modları

dependencyResolutionManagement, tüm modüller için depoları merkezi olarak yöneten settings.gradle'daki bir bloktur. Gradle 7.0'da her build.gradle'da repositories bildirmeye alternatif olarak ortaya çıktı. Blok içinde repositoriesMode (mod: PREFER_PROJECT, PREFER_SETTINGS veya FAIL_ON_PROJECT_REPOS) ve repositories (depo listesi) ayarlanır. repositoriesMode = PREFER_SETTINGS ise, modül düzeyindeki depolar yok sayılır — yalnızca merkezi liste kullanılır.

repositoriesMode üç değer alabilir. PREFER_SETTINGS — build.gradle'daki depolar yok sayılır, yalnızca settings.gradle'dakiler kullanılır. PREFER_PROJECT — build.gradle depoları settings.gradle'a göre önceliklidir. FAIL_ON_PROJECT_REPOS — bir modül kendi depolarını bildirirse, Gradle hata verir. Yeni projeler için PREFER_SETTINGS önerilir — tüm modüllerin aynı depoları kullanmasını garanti eder ve tekrarı ortadan kaldırır.

repositoriesMode = FAIL_ON_PROJECT_REPOS özellikle ekiplerde kullanışlıdır: bir geliştirici yalnızca bir modüle depo ekler ve diğerleri onu görmezse, “works on my machine” sorunu oluşur. FAIL_ON_PROJECT_REPOS, tüm depoların settings.gradle'da merkezi olarak bildirilmesini zorunlu kılarak bu tür durumları önler. Google, AGP 8.0'den itibaren tüm Android projeleri için FAIL_ON_PROJECT_REPOS'u önerir.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — tüm depolar yalnızca burada
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

        // Özel Maven deposu
        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 modülünde repositories artık gerekli değil!
// Tüm depolar settings.gradle'da merkezileştirildi

settings.gradle'da sürüm katalogları

Version Catalogs, bir TOML dosyası aracılığıyla bağımlılık sürümlerini yönetmenin merkezi bir yoludur. Gradle 7.4'ten itibaren, sürüm katalogları tüm Android projeleri için önerilen mekanizmadır. gradle/libs.versions.toml dosyası üç bölüm içerir: [versions] (sürümler), [libraries] (bağımlılıklar), [plugins] (eklentiler). settings.gradle'da, sürüm kataloğu @Suppress("UnstableApiUsage") ve enableFeaturePreview("VERSION_CATALOGS") (eski Gradle sürümlerinde) aracılığıyla bağlanır.

Sürüm kataloğu bağlandıktan sonra, build.gradle'daki modül bağımlılıkları libs aracılığıyla belirtilir: implementation(libs.retrofit). IDE, libs için otomatik tamamlama sağlar. Katalog otomatik olarak tür güvenli erişimciler oluşturur: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles, tek bir satırda eklenebilen bağımlılık gruplarıdır. Sürüm katalogları ayrıca kalıtımı da destekler — birden çok TOML dosyası bağlanabilir.

Sürüm kataloglarının avantajları: sürümler için tek bir yer (tüm build.gradle dosyalarında arama gerektirmez); tür güvenli erişim (libs adındaki bir yazım hatası derleme zamanında yakalanır, çalışma zamanında değil); otomatik güncellemeler (Dependabot ve Renovate TOML'yi destekler); Convention Plugins ile uyumluluk. Google Firebase ve AndroidX kendi TOML kataloglarını dağıtır. Sürüm kataloglarına geçiş için, build.gradle'dan TOML'ye sürümleri otomatik olarak aktaran eklentiler mevcuttur.

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

Gelişmiş ayarlar: includeBuild ve kuluçka özellikleri

includeBuild, bir bileşik derleme oluşturmak için bir yönergedir: geçerli derlemenin bir parçası olarak harici bir Gradle projesini eklemek. include'dan (bir modül ekler) farklı olarak, includeBuild kendi settings.gradle'ı, modülleri ve eklentileri olan tüm bir projeyi ekler. Bileşik derlemeler şunlar için kullanılır: uygulamayla paralel olarak kitaplıklar (analitik, ağ) geliştirmek; ayrı bir depodan Convention Plugins eklemek; build-logic modüllerini entegre etmek.

Kuluçka özellikleri (Incubating Features), enableFeaturePreview("FEATURE_NAME") aracılığıyla etkinleştirilen deneysel Gradle seçenekleridir. AGP 8.7+'da mevcut olanlar: TYPESAFE_PROJECT_ACCESSORS (çok modüllü bir projede projelere tür güvenli erişim: project(":core:network") yerine projects.core.network yazılabilir), STABLE_CONFIGURATION_CACHE (kararlı yapılandırma önbelleği), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (yapıt dönüşümü). Kuluçka özellikleri üretimde etkinleştirilebilir, ancak API gelecek sürümlerde değişebilir.

Gradle Enterprise ve Build Scan da settings.gradle aracılığıyla yapılandırılır: plugins { id("com.gradle.enterprise") } bir gradleEnterprise bloğu ile. Build Scan, her derleme hakkında ayrıntılı bilgi gösteren bir bulut hizmetidir: her görevin yürütme süresi, önbellekleme, hatalar. Build Scan'ı etkinleştirmek, derleme hızı sorunlarını teşhis etmeye yardımcı olur. Build Scan, açık kaynak projeler için ücretsizdir.

// Kuluçka özellikleri
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)
    }
}

// build.gradle'da tür güvenli proje erişimcileri kullanma
// Bunun yerine: implementation(project(":core:network"))
// Mümkün: implementation(projects.core.network)