build.gradle: ما هو، بناء الجملة والتكوين في Android

ما هو build.gradle؟

build.gradle هو سكريبت بناء بلغة Groovy (امتداد .gradle) أو Kotlin (.gradle.kts) يدير جميع جوانب تجميع تطبيق Android. Gradle هو نظام بناء آلي اعتمدته Google في عام 2013 كمعيار لـ Android. يصف build.gradle: ما هي الإضافات المطبقة (Android و Kotlin والمكتبات)، وما هي التبعيات المتصلة، وما هي إصدارات SDK المستخدمة، وكيفية توقيع التطبيق وأين يتم النشر.

تتضمن عملية البناء ثلاث مراحل: Initialization (اكتشاف الوحدات)، Configuration (تنفيذ سكريبتات build.gradle)، Execution (تنفيذ المهام). يتم تنفيذ build.gradle خلال مرحلة Configuration، عندما يقوم Gradle بإنشاء رسم بياني للمهام. في هذه المرحلة يتم تحديد Build Variants وحساب التبعيات وتكوين المهام. مهم: build.gradle هو كود، وليس مجرد تكوين. يمكن استخدام الشروط والحلقات واستدعاءات الأساليب والسكريبتات الخارجية فيه.

يتم تخزين ملفات Gradle في جذر الوحدة (app/build.gradle) وجذر المشروع (build.gradle). بالإضافة إلى ذلك، يدعم Gradle apply from — تضمين سكريبتات Gradle الخارجية. يتيح ذلك استخراج المنطق المتكرر إلى ملفات بإعدادات مشتركة. مع ظهور Convention Plugins (AGP 7+) يعتبر apply from مهملاً — توفر Convention Plugins طريقة آمنة الأنواع وقابلة للتركيب لإعادة استخدام التكوين عبر الوحدات.

تطور build.gradle

منذ عام 2013، شهد بناء جملة build.gradle تغييرات كبيرة: من Groovy مع التكوينات الديناميكية إلى Kotlin DSL مع فحوصات وقت التجميع. تطور AGP من الإصدار 1.0 إلى 8.7 (2025). المعالم الرئيسية: AGP 3.0 (Java 8 desugar، واجهة برمجة متغيرات جديدة)، AGP 4.0 (view binding، Java 11)، AGP 7.0 (Kotlin DSL افتراضيًا، Java 11 كحد أدنى)، AGP 8.0 (فئات R غير متعدية، تكوين البناء في Kotlin)، AGP 8.7 (KSP بدلاً من kapt، تكوين سريع).

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 (project-level)
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 (module-level)
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 vs Kotlin DSL

Groovy هي لغة JVM ديناميكية كانت بناء الجملة الأصلي لـ Gradle. تستخدم سكريبتات Groovy (.gradle) الكتابة الديناميكية: يمكن حذف الأنواع، واستخدام السلاسل المقتبسة أو غير المقتبسة، واستدعاء أساليب غير موجودة في وقت التجميع. مرونة Groovy هي أيضًا عيبها: لا يمكن لـ IDE التحقق من بناء الجملة والأنواع حتى يتم تنفيذ السكريبت، مما يؤدي إلى أخطاء وقت التشغيل بسبب أسماء معلمات أو أنواع غير صحيحة.

Kotlin DSL (.gradle.kts) يستخدم الكتابة الثابتة لـ Kotlin. يتحقق IDE من الأنواع، ويقترح المعلمات المتاحة عبر الإكمال التلقائي ويبرز الأخطاء في وقت التحرير. Kotlin DSL أبطأ خلال مرحلة Configuration (بسبب تجميع ملفات .kts إلى bytecode)، لكن 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 واجهة برمجة آمنة الأنواع ويمنع الأخطاء التي تكتشف في 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. إذا كانت الوحدة مكتبة، يتم استخدام إضافة المكتبة بدلاً من application، ويكون applicationId غائبًا عن كتلة android.

compileSdk هو إصدار SDK الذي يتم تجميع الكود به. يجب أن يكون أحدث API Android (في وقت الكتابة — 35). minSdk هو الحد الأدنى لإصدار API المدعوم. targetSdk هو الإصدار الذي يستهدفه التطبيق (يتم تطبيق تغييرات السلوك لهذا الإصدار). الفرق بين compileSdk و targetSdk: compileSdk يحدد APIs المتاحة، targetSdk يحدد سلوك وقت التشغيل. توصية: compileSdk = الأحدث، targetSdk = الأحدث - 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، فئات R غير متعدية — لكل مكتبة فئة R خاصة بها، مما يمنع تعارضات الموارد. في كتلة dependencies من المهم استخدام التكوينات الصحيحة: implementation لا يكشف التبعيات المتعدية، مما يسرع البناء. api يكشفها — يُستخدم عندما تصدر مكتبة أنواعًا من مكتبة أخرى (مثل Retrofit الذي يستخدم أنواع OkHttp في واجهته العامة).

لإدارة الإصدارات يوصى باستخدام 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"))
}