settings.gradle: اضافه کردن ماژول‌ها و pluginManagement

settings.gradle چیست؟

settings.gradle (یا settings.gradle.kts برای Kotlin DSL) فایلی است که Gradle در مرحله Initialization اجرا می‌کند. در آن سلسله‌مراتب پروژه تعریف می‌شود، ماژول‌ها اضافه می‌شوند، مخازن برای پلاگین‌ها و وابستگی‌ها پیکربندی می‌شوند. بدون settings.gradle، Gradle نمی‌داند کدام ماژول‌ها را build کند و کدام پلاگین‌ها در دسترس هستند. در پروژه تک‌ماژولی، 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 در API Gradle). پس از پایان 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 اضافه شدند. settings.gradle مدرن یک فایل پیکربندی قدرتمند است که مدیریت پلاگین‌ها، مخازن و نسخه‌ها را برای کل پروژه متمرکز می‌کند. Google این قابلیت‌ها را از AGP 8.0 در Android Gradle Plugin تثبیت می‌کند.

settings.gradle در مقابل build.gradle

settings.gradle ساختار پروژه و تنظیمات سراسری را مدیریت می‌کند (پلاگین‌ها، مخازن). build.gradle build را مدیریت می‌کند (وابستگی‌ها، پیکربندی‌های Android، tasks). settings.gradle اول اجرا می‌شود و به Settings API دسترسی دارد. build.gradle بعداً اجرا می‌شود و به Project API دسترسی دارد. هیچ پیکربندی ماژولی (بلوک android، dependencies) نمی‌تواند در settings.gradle باشد — این یک خطا است.

اضافه کردن ماژول‌ها با include

دستورالعمل include اصلی‌ترین دستور در settings.gradle است. این دستور به Gradle می‌گوید کدام ماژول‌ها باید در build شرکت کنند. آرگومان include مسیر ماژول است: include(":app") — ماژول در ریشه را اضافه می‌کند، include(":core:network") — ماژول در زیرمسیر core/network/. دو نقطه در ابتدا نشان می‌دهد که مسیر نسبت به ریشه پروژه است. پس از include، Gradle به طور خودکار build.gradle را در مسیر مشخص شده پیدا کرده و ماژول را به درخت پروژه اضافه می‌کند.

هر include یک Project در API Gradle با نامی برابر با رشته 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 قابل مشاهده است. در build تولیدی، 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 از کجا بارگذاری شوند. در Gradle 6.8 برای مدیریت متمرکز پلاگین‌ها قبل از اعمال آن‌ها ظاهر شد. در داخل pluginManagement قرار دارند: repositories (لیست مخازن برای جستجوی پلاگین‌ها)، resolutionStrategy (قوانین حل نسخه) و plugins (تعیین صریح نسخه‌های پلاگین‌ها). اگر pluginManagement تنظیم نشده باشد، Gradle از مخازن build.gradle استفاده می‌کند — اما پلاگین‌ها فقط پس از اعلام آن‌ها جستجو می‌شوند که در صورت پیدا نشدن پلاگین به خطا منجر می‌شود.

در پروژه Android، pluginManagement در صورت استفاده از کاتالوگ‌های نسخه یا Convention Plugins الزامی است. بدون pluginManagement، Gradle نمی‌تواند پلاگین com.android.application را هنگام اعمال در build.gradle.kts پیدا کند. پیکربندی معمول: repositories شامل google() (پلاگین‌های Android)، mavenCentral() (پلاگین‌های شخص ثالث) و gradlePluginPortal() (پلاگین‌های رسمی Gradle) است.

pluginManagement همچنین از plugins پشتیبانی می‌کند — اعلام پلاگین‌ها با نسخه‌ها که سپس در build.gradle بدون ذکر نسخه اعمال می‌شوند. این کار نسخه‌های پلاگین‌ها را متمرکز می‌کند: اگر ۱۰ ماژول از 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
}

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 دیگر needed نیست!
// همه مخازن در settings.gradle متمرکز شده‌اند

کاتالوگ‌های نسخه در settings.gradle

کاتالوگ‌های نسخه یک روش متمرکز برای مدیریت نسخه‌های وابستگی‌ها از طریق فایل 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 در مرحله کامپایل کشف می‌شود، نه runtime). به‌روزرسانی خودکار (Dependabot و Renovate از TOML پشتیبانی می‌کنند). سازگاری با Convention Plugins. Google Firebase و AndroidX کاتالوگ‌های TOML خود را منتشر می‌کنند. برای مهاجرت به کاتالوگ‌های نسخه، پلاگین‌هایی وجود دارند که به طور خودکار نسخه‌ها را از 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 به عنوان بخشی از build فعلی. برخلاف include (ماژول را اضافه می‌کند)، includeBuild یک پروژه کامل با settings.gradle، ماژول‌ها و پلاگین‌های خود را اضافه می‌کند. 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 یک سرویس ابری است که اطلاعات دقیق درباره هر build را نشان می‌دهد: زمان اجرای هر task، کش کردن، خطاها. فعال کردن Build Scan به تشخیص مشکلات سرعت build کمک می‌کند. برای پروژه‌های 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)