settings.gradle: ما هو، تضمين الوحدات و pluginManagement

ما هو settings.gradle؟

settings.gradle (أو settings.gradle.kts لـ Kotlin DSL) هو ملف يُنفذه 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 شجرة المشروع (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 الحديث هو ملف تكوين قوي يُمركز إدارة الإضافات والمستودعات والإصدارات للمشروع بأكمله. تُعزز Google هذه الإمكانيات في Android Gradle Plugin بدءًا من AGP 8.0.

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، يجد 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"). يتيح ذلك تضمين مشاريع Gradl كاملة كوحدات خارجية. تُعد 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، pluginManagement إلزامي إذا تم استخدام Version Catalogs أو Convention Plugins. بدون pluginManagement، لا يمكن لـ Gradle العثور على الإضافة com.android.application عند تطبيقها في build.gradle.kts. التكوين النموذجي: 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 كبديل للتصريح بـ 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 للوحدة!
// جميع المستودعات مركزية في 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") (في إصدارات Gradl القديمة).

بعد ربط فهرس الإصدارات، تُحدد تبعيات الوحدات في build.gradle عبر libs: implementation(libs.retrofit). يوفر IDE الإكمال التلقائي لـ libs. يُنشئ الفهرس تلقائيًا accessors آمنة الأنواع: libs.retrofit، libs.kotlin.coroutines، libs.bundles.compose. Bundles هي مجموعات من التبعيات يمكن تضمينها بسطر واحد. فهارس الإصدارات تدعم أيضًا الوراثة — يمكن ربط عدة ملفات TOML.

مزايا فهارس الإصدارات: مكان واحد للإصدارات (لا حاجة للبحث في جميع ملفات build.gradle)؛ وصول آمن الأنواع (خطأ في اسم libs يُكتشف في مرحلة الترجمة، وليس في وقت التشغيل)؛ تحديثات تلقائية (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 هو توجيه لإنشاء build مركب: تضمين مشروع Gradl خارجي كجزء من البناء الحالي. على عكس include (الذي يُضمّن وحدة)، يُضمّن includeBuild مشروعًا كاملًا مع settings.gradle ووحدات وإضافات خاصة به. تُستخدم الـ composite builds من أجل: تطوير المكتبات (التحليلات، الشبكة) بالتوازي مع التطبيق؛ تضمين Convention Plugins من مستودع منفصل؛ دمج وحدات build-logic.

الميزات التجريبية (Incubating Features) هي خيارات Gradle تجريبية يتم تفعيلها عبر enableFeaturePreview("FEATURE_NAME"). في AGP 8.7+، المتاحة تشمل: TYPESAFE_PROJECT_ACCESSORS (وصول آمن الأنواع إلى المشاريع في مشروع متعدد الوحدات: بدلاً من 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)
    }
}

// استخدام type-safe project accessors في build.gradle
// بدلاً من: implementation(project(":core:network"))
// يمكنك: implementation(projects.core.network)