build.gradle: چیست، نحو و پیکربندی در Android

build.gradle چیست؟

build.gradle یک اسکریپت ساخت به زبان Groovy (پسوند .gradle) یا Kotlin (.gradle.kts) است که تمام جنبه‌های کامپایل برنامه Android را مدیریت می‌کند. Gradle یک سیستم ساخت خودکار است که در سال 2013 توسط Google به عنوان استاندارد Android پذیرفته شد. build.gradle مشخص می‌کند: چه پلاگین‌هایی اعمال شده‌اند (Android، Kotlin، کتابخانه‌ها)، چه وابستگی‌هایی متصل شده‌اند، چه نسخه‌های SDK استفاده می‌شوند، چگونه برنامه را امضا کرده و کجا منتشر کنید.

فرآیند ساخت شامل سه فاز است: Initialization (تعیین ماژول‌ها)، Configuration (اجرای اسکریپت‌های build.gradle)، Execution (اجرای وظایف). build.gradle در فاز Configuration اجرا می‌شود، زمانی که Gradle گراف وظایف را می‌سازد. در این مرحله Build Variant‌ها تعیین می‌شوند، وابستگی‌ها محاسبه و وظایف پیکربندی می‌شوند. مهم: build.gradle کد است، نه فقط پیکربندی. در آن می‌توان از شرط‌ها، حلقه‌ها، فراخوانی متدها و اسکریپت‌های خارجی استفاده کرد.

فایل‌های Gradle در ریشه ماژول (app/build.gradle) و ریشه پروژه (build.gradle) ذخیره می‌شوند. علاوه بر این، Gradle از apply from — اتصال اسکریپت‌های خارجی Gradle پشتیبانی می‌کند. این امکان را می‌دهد تا منطق تکراری را به فایل‌هایی با تنظیمات مشترک منتقل کنید. با ظهور Convention Plugins (AGP 7+)، apply from منسوخ شده است — Convention Plugins روش type-safe و ترکیبی برای استفاده مجدد از پیکربندی بین ماژول‌ها فراهم می‌کنند.

تکامل build.gradle

از سال 2013، نحو build.gradle دستخوش تغییرات قابل توجهی شده است: از Groovy با پیکربندی‌های پویا تا Kotlin DSL با بررسی‌های زمان کامپایل. AGP از نسخه 1.0 به 8.7 (2025) تکامل یافته است. نقاط عطف کلیدی: AGP 3.0 (Java 8 desugar، new variant API)، AGP 4.0 (view binding، Java 11)، AGP 7.0 (Kotlin DSL پیش‌فرض، Java 11 min)، AGP 8.0 (non-transitive R classes، پیکربندی ساخت در Kotlin)، AGP 8.7 (KSP به جای kapt، پیکربندی سریع).

Project-level و Module-level build.gradle

Project-level build.gradle (ریشه) پلاگین‌ها، مخازن و پیکربندی‌های مشترک برای همه ماژول‌ها را تعیین می‌کند. بلوک‌های اصلی: plugins (اتصال پلاگین‌های Gradle)، repositories (منابع وابستگی: mavenCentral، google، jitpack). در build.gradle ریشه معمولاً بلوک android وجود ندارد — آن در ماژول‌ها ظاهر می‌شود. Project-level همچنین می‌تواند بلوک subprojects را برای پیکربندی مشترک همه زیرپروژه‌ها داشته باشد، اگرچه Convention Plugins ارجحیت دارند.

Module-level build.gradle (مثلاً app/build.gradle) ماژول خاصی را توصیف می‌کند. اگر ماژول یک برنامه باشد، پلاگین com.android.application را اعمال می‌کند. اگر کتابخانه باشد — com.android.library. در module-level قرار دارند: بلوک android (compileSdk، defaultConfig، buildTypes، productFlavors)، بلوک dependencies (وابستگی‌های ماژول) و بلوک‌های اختیاری برای پیکربندی تست و ساخت. Module-level بعد از project-level اجرا شده و می‌تواند تنظیمات مشترک را بازنویسی کند.

از AGP 8.0 به بعد، build.gradle ریشه می‌تواند از version catalogs (libs.versions.toml) برای مدیریت متمرکز نسخه‌های وابستگی استفاده کند. Version catalog فایلی در دایرکتوری gradle/ است که شامل نسخه‌ها، کتابخانه‌ها و پلاگین‌ها می‌باشد. در build.gradle وابستگی‌ها از طریق libs متصل می‌شوند: implementation(libs.retrofit). Version catalogs برای پروژه‌های جدید اجباری و برای همه پروژه‌های با سه ماژول یا بیشتر توصیه می‌شود.

// settings.gradle.kts — ریشه پروژه
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (سطح پروژه)
plugins {
    id("com.android.application") version "8.7.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
}

// app/build.gradle.kts (سطح ماژول)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp")
}

android {
    namespace = "com.example.myapp"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 1
        versionName = "1.0.0"
    }
}

Groovy در مقابل Kotlin DSL

Groovy یک زبان پویای JVM است که نحو اصلی Gradle بود. اسکریپت‌های Groovy (.gradle) از تایپ‌دهی پویا استفاده می‌کنند: می‌توان انواع را مشخص نکرد، از کوتیشن‌ها استفاده کرد یا نکرد، متدهایی را که در زمان کامپایل وجود ندارند فراخوانی کرد. انعطاف‌پذیری Groovy نقطه ضعف آن نیز هست: IDE نمی‌تواند نحو و انواع را قبل از اجرای اسکریپت بررسی کند، که منجر به خطاهای زمان اجرا با نام پارامتر یا نوع نادرست می‌شود.

Kotlin DSL (.gradle.kts) از تایپ‌دهی ایستای Kotlin استفاده می‌کند. IDE انواع را بررسی می‌کند، پارامترهای موجود را از طریق تکمیل خودکار پیشنهاد می‌دهد و خطاها را در مرحله ویرایش نشان می‌دهد. Kotlin DSL در فاز Configuration کندتر است (به دلیل کامپایل فایل‌های .kts به بایت‌کد)، اما Google دائماً عملکرد را بهبود می‌بخشد: AGP 8.5+ از Gradle Configuration Cache و Caching Kotlin DSL compilation استفاده می‌کند که تفاوت را به 1-2 ثانیه کاهش می‌دهد.

Google Kotlin DSL را برای همه پروژه‌های جدید و مهاجرت تدریجی پروژه‌های موجود توصیه می‌کند. مهاجرت از Groovy به Kotlin DSL ساده است: کوتیشن‌ها با پرانتز جایگزین می‌شوند، انواع اضافه می‌شوند، عملگرها به توابع تبدیل می‌شوند. اکثر کتابخانه‌ها مثال‌های Kotlin DSL را در مستندات خود ارائه می‌دهند. برای موارد پیچیده (Custom Plugin، Task Graph)، Kotlin DSL API type-safe ارائه می‌دهد و از خطاهایی که در Groovy فقط در زمان اجرا کشف می‌شوند جلوگیری می‌کند. Version catalogs (libs.versions.toml) با هر دو نحو یکسان کار می‌کنند.

بلوک android: پیکربندی برنامه

compileSdk، minSdk و targetSdk

بلوک android — عنصر مرکزی module-level build.gradle. در داخل آن پیکربندی می‌شوند: namespace (برای R و BuildConfig)، compileSdk، defaultConfig، buildTypes، productFlavors، sourceSets، compileOptions، packaging، bundle. همه پارامترهای بلوک android فقط برای ماژول‌های Android قابل اعمال هستند. اگر ماژول کتابخانه باشد، به جای برنامه از پلاگین کتابخانه استفاده می‌شود و در بلوک android applicationId وجود ندارد.

compileSdk — نسخه SDK که کد با آن کامپایل می‌شود. باید برابر با آخرین Android API باشد (در زمان نوشتن — 35). minSdk — حداقل نسخه API برای پشتیبانی. targetSdk — نسخه‌ای که برنامه به سمت آن نشانه رفته است (تغییرات رفتاری این نسخه اعمال می‌شوند). تفاوت بین compileSdk و targetSdk: compileSdk APIهای موجود را تعیین می‌کند، targetSdk — رفتار زمان اجرا را. توصیه: compileSdk = latest، targetSdk = latest - 1 (برای آزمایش سازگاری با تغییرات جدید).

compileOptions سازگاری Java را تعیین می‌کند: sourceCompatibility و targetCompatibility. AGP 8+ برای کامپایل به Java 17+ نیاز دارد. packaging گنجاندن فایل‌ها از کتابخانه‌ها را مدیریت می‌کند: exclude، merge، pickFirst برای حل تعارضات META-INF. buildFeatures ViewBinding، DataBinding، Compose را فعال/غیرفعال می‌کند. aaptOptions پردازش منابع را پیکربندی می‌کند: ignoreAssetsPattern، cruncherEnabled. هر عنصر بلوک android جنبه خاصی از ساخت را بهینه می‌کند.

android {
    namespace = "com.example.myapp"
    compileSdk = 35
    buildToolsVersion = "35.0.0"

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 5
        versionName = "2.3.1"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        getByName("debug") { isDebuggable = true }
        getByName("release") {
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    buildFeatures {
        viewBinding = true
        compose = true
    }
}

مدیریت وابستگی‌ها

BOM (Bill of Materials)

وابستگی‌ها در build.gradle کتابخانه‌ها و ماژول‌هایی هستند که به پروژه متصل می‌شوند. بلوک dependencies در همان سطح بلوک android قرار دارد. Gradle از چندین پیکربندی پشتیبانی می‌کند: implementation (کتابخانه در این ماژول موجود است، غیر ترانزیتیو)، api (کتابخانه به صورت ترانزیتیو برای ماژول‌های وابسته موجود است)، compileOnly (فقط برای کامپایل، در APK گنجانده نمی‌شود)، runtimeOnly (فقط در زمان اجرا)، annotationProcessor / ksp (پردازشگرهای حاشیه‌نویسی)، testImplementation (فقط برای تست‌ها)، androidTestImplementation (فقط برای تست‌های ابزاری).

از AGP 8.0 به بعد، Non-Transitive R classes — هر کتابخانه کلاس R خود را دارد که از تعارضات منابع جلوگیری می‌کند. در بلوک dependencies استفاده از پیکربندی‌های صحیح مهم است: implementation وابستگی‌های ترانزیتیو را فاش نمی‌کند که ساخت را تسریع می‌کند. api فاش می‌کند — زمانی استفاده می‌شود که کتابخانه انواعی را از کتابخانه دیگر صادر می‌کند (مثلاً Retrofit از انواع OkHttp در API عمومی خود استفاده می‌کند).

برای مدیریت نسخه‌ها توصیه می‌شود از BOM (Bill of Materials) استفاده کنید — فایل ساخت که نسخه‌های سازگار کتابخانه‌ها را تعیین می‌کند. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). پس از اتصال BOM می‌توان فقط نام کتابخانه را بدون نسخه مشخص کرد — BOM به طور خودکار نسخه سازگار را انتخاب می‌کند. این کار تعارضات بین وابستگی‌های ترانزیتیو کتابخانه‌های مختلف را برطرف می‌کند. BOM برای Firebase، Compose، Kotlin، Ktor، AndroidX در دسترس است.

dependencies {
    // BOM — مدیریت نسخه‌ها
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX و Compose
    implementation("androidx.core:core-ktx")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx")
    implementation("androidx.activity:activity-compose")
    implementation("androidx.compose.ui:ui")

    // Network
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")

    // Firebase (نسخه‌های BOM)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // تست
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

build.gradle در پروژه‌های چندماژوله

در پروژه‌های چندماژوله، هر ماژول build.gradle خود را دارد. برای اتصال یک ماژول به ماژول دیگر از نحو implementation(project(":module-name")) استفاده می‌شود. Gradle به طور خودکار ماژول را در صورت تغییر پیکربندی می‌سازد. معماری چندماژوله زمان ساخت را بهبود می‌بخشد (ساخت افزایشی، موازی‌سازی) و مسئولیت را بین ماژول‌های ویژگی، ماژول‌های هسته و کتابخانه‌ها تقسیم می‌کند.

مشکل کلیدی پروژه‌های چندماژوله — تکرار پیکربندی. اگر 10 ماژول minSdk، compileSdk و وابستگی‌های Compose یکسانی داشته باشند، این 10 کپی در build.gradleهای مختلف است. راه‌حل — Convention Plugins (قبلاً buildSrc). Convention Plugin یک پلاگین Gradle نوشته شده به Kotlin است که به ماژول‌ها اعمال می‌شود: plugins { id("myapp.android.library") }. پلاگین شامل پیکربندی مشترک است و تغییرات بلافاصله به همه ماژول‌ها اعمال می‌شوند.

برای سازماندهی Convention Plugins از دایرکتوری build-logic/ در ریشه پروژه استفاده می‌شود. این دایرکتوری شامل includeBuild در settings.gradle و پلاگین‌های Kotlin است. Convention Plugins می‌توانند در مخزن maven برای استفاده مجدد بین پروژه‌ها منتشر شوند. Google Convention Plugins را به عنوان استاندارد برای پروژه‌های چندماژوله توصیه می‌کند که جایگزین subprojects { } و apply from می‌شود. انتقال به Convention Plugins build.gradle ماژول را به 10-15 خط کاهش می‌دهد.

// build-logic/src/main/kotlin/AndroidLibraryConventionPlugin.kt
class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            with(plugins) {
                apply("com.android.library")
                apply("org.jetbrains.kotlin.android")
            }
            extensions.configure<CommonExtension<*, *, *, *>> {
                compileSdk = 35
                defaultConfig { minSdk = 26 }
                compileOptions {
                    sourceCompatibility = JavaVersion.VERSION_17
                    targetCompatibility = JavaVersion.VERSION_17
                }
            }
        }
    }
}

// module/build.gradle.kts — پس از Convention Plugin
plugins {
    id("myapp.android.library")
}

dependencies {
    implementation(project(":core:network"))
}