settings.gradle: یہ کیا ہے، ماڈیولز شامل کرنا اور pluginManagement

settings.gradle کیا ہے؟

settings.gradle (Kotlin DSL کے لیے settings.gradle.kts) ایک فائل ہے جسے 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 پروجیکٹ کا درخت (Gradle API میں Project) بناتا ہے۔ Initialization مکمل ہونے کے بعد، Configuration شروع ہوتی ہے — ہر ماڈیول کے build.gradle کا نفاذ۔

تاریخی طور پر، settings.gradle Gradle 0.7 (2010) میں ظاہر ہوئی اور ابتدائی طور پر صرف include ہدایات پر مشتمل تھی۔ Gradle کی ترقی کے ساتھ، pluginManagement (Gradle 6.8)، dependencyResolutionManagement (Gradle 7.0) اور versionCatalogs (Gradle 7.4) شامل کیے گئے۔ جدید settings.gradle ایک طاقتور کنفیگریشن فائل ہے جو پورے پروجیکٹ کے لیے پلگ ان، ریپوزٹری اور ورژن کے انتظام کو مرکزی بناتی ہے۔ Google AGP 8.0 سے شروع ہو کر Android Gradle Plugin میں ان صلاحیتوں کو لازمی قرار دیتا ہے۔

settings.gradle بمقابلہ 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 کے بعد، Gradl خود بخود مخصوص ڈائریکٹری میں build.gradle تلاش کر لیتا ہے اور ماڈیول کو پروجیکٹ کے درخت میں شامل کر دیتا ہے۔

ہر include Gradle API میں ایک Project بناتا ہے جس کا نام include سٹرنگ کے برابر ہوتا ہے۔ پروجیکٹ کا نام دوسرے ماڈیولز کی build.gradle فائلوں میں implementation(project(":module")) میں استعمال ہوتا ہے۔ اگر کوئی ماڈیول include کے ذریعے شامل نہیں ہے، تو دوسرے ماڈیول سے اس کا حوالہ “Project not found” خرابی پیدا کرے گا۔ Android Studio IDE بھی Project پینل میں ماڈیولز دکھانے کے لیے settings.gradle استعمال کرتا ہے — include کے بغیر ماڈیول فائل کے درخت میں نظر نہیں آتے۔

include includeBuild("../library-project") کے ذریعے included builds اور composite builds کو سپورٹ کرتا ہے۔ یہ مکمل 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"))
    }
}

پلگ ان مینجمنٹ بلاک

ریزولوشن کی حکمت عملی

pluginManagement settings.gradle میں ایک بلاک ہے جو طے کرتا ہے کہ Gradle پلگ ان کہاں سے لوڈ کیے جائیں۔ یہ Gradle 6.8 میں پلگ ان کے اطلاق سے پہلے مرکزی انتظام کے لیے ظاہر ہوا۔ pluginManagement کے اندر ہیں: repositories (پلگ ان تلاش کرنے کے لیے ریپوزٹریز کی فہرست)، resolutionStrategy (ورژن حل کرنے کے قواعد) اور plugins (واضح پلگ ان ورژن کے اعلانات)۔ اگر pluginManagement متعین نہیں ہے، تو Gradle build.gradle سے ریپوزٹریز استعمال کرتا ہے — لیکن پلگ ان صرف اعلان کرنے کے بعد تلاش کیے جاتے ہیں، جس کی وجہ سے اگر پلگ ان نہ ملا تو خرابی پیدا ہوتی ہے۔

Android پروجیکٹس میں، اگر Version Catalogs یا Convention Plugins استعمال ہوں تو pluginManagement لازمی ہے۔ pluginManagement کے بغیر، Gradle build.gradle.kts میں اطلاق کرتے وقت com.android.application پلگ ان نہیں ڈھونڈ سکتا۔ ایک عام ترتیب: 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
}

انحصار ریزولوشن مینجمنٹ

repositoriesMode کے طریقے

dependencyResolutionManagement settings.gradle میں ایک بلاک ہے جو تمام ماڈیولز کے لیے ریپوزٹریز کو مرکزی طور پر منظم کرتا ہے۔ یہ Gradle 7.0 میں ہر build.gradle میں repositories کے اعلان کے متبادل کے طور پر ظاہر ہوا۔ بلاک کے اندر 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 AGP 8.0 سے شروع ہو کر تمام Android پروجیکٹس کے لیے FAIL_ON_PROJECT_REPOS تجویز کرتا ہے۔

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 میں ورژن کیٹلاگ

Version Catalogs TOML فائل کے ذریعے انحصار کے ورژن کے انتظام کا ایک مرکزی طریقہ ہے۔ Gradle 7.4 سے شروع ہو کر، ورژن کیٹلاگ تمام Android پروجیکٹس کے لیے تجویز کردہ طریقہ کار ہے۔ gradle/libs.versions.toml فائل میں تین حصے ہیں: [versions] (ورژن)، [libraries] (انحصار)، [plugins] (پلگ ان)۔ 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 کے نام میں ٹائپو مرتب کرتے وقت پکڑا جاتا ہے، چلنے کے وقت نہیں)؛ خودکار اپ ڈیٹس (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 ایک کمپوزٹ بلڈ بنانے کی ہدایت ہے: موجودہ بلڈ کے حصے کے طور پر ایک بیرونی Gradle پروجیکٹ شامل کرنا۔ include (جو ایک ماڈیول شامل کرتا ہے) کے برعکس، includeBuild اپنی settings.gradle، ماڈیولز اور پلگ ان کے ساتھ ایک مکمل پروجیکٹ شامل کرتا ہے۔ کمپوزٹ بلڈ اس کے لیے استعمال ہوتے ہیں: ایپلیکیشن کے متوازی لائبریریاں (تجزیہ، نیٹ ورکنگ) تیار کرنا؛ علیحدہ ریپوزٹری سے 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 ایک کلاؤڈ سروس ہے جو ہر بلڈ کے بارے میں تفصیلی معلومات دکھاتی ہے: ہر کام کا نفاذ وقت، کیشنگ، خرابیاں۔ Build Scan کو فعال کرنے سے بلڈ کی رفتار کے مسائل کی تشخیص میں مدد ملتی ہے۔ 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)
    }
}

// build.gradle میں type-safe project accessors کا استعمال
// اس کے بجائے: implementation(project(":core:network"))
// آپ کر سکتے ہیں: implementation(projects.core.network)