settings.gradle: συμπερίληψη ενοτήτων και pluginManagement

Τι είναι το settings.gradle;

settings.gradle (ή settings.gradle.kts για Kotlin DSL) είναι το αρχείο που εκτελεί το Gradle στη φάση Initialization. Σε αυτό ορίζεται η ιεραρχία του έργου, συμπεριλαμβάνονται ενότητες, διαμορφώνονται αποθετήρια για προσθήκες και εξαρτήσεις. Χωρίς settings.gradle, το Gradle δεν γνωρίζει ποιες ενότητες να δημιουργήσει και ποιες προσθήκες είναι διαθέσιμες. Σε ένα έργο μίας ενότητας, το settings.gradle μπορεί να λείπει — το Gradle χρησιμοποιεί προεπιλεγμένες τιμές, αλλά για πολυ-αρθρωτικά έργα είναι υποχρεωτικό.

Το αρχείο settings.gradle βρίσκεται στη ρίζα του έργου, δίπλα στο root build.gradle. Τυπική δομή της ρίζας του έργου: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. Το settings.gradle εκτελείται πριν από το build.gradle — στη φάση Initialization, το Gradle χτίζει το δέντρο του έργου (Project στο Gradle API). Μετά την ολοκλήρωση του 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 εδραιώνει αυτές τις δυνατότητες στο Android Gradle Plugin ξεκινώντας από AGP 8.0.

settings.gradle vs 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 στο Gradle API με όνομα ίσο με το string του 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. Σε παραγωγική μεταγλώττιση, το 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 χωρίς αναφορά έκδοσης. Αυτό κεντρικοποιεί τις εκδόσεις προσθηκών: εάν 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
}

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 δεν χρειάζονται πλέον!
// Όλα τα αποθετήρια κεντρικοποιημένα στο 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 ως μέρος της τρέχουσας μεταγλώττισης. Σε αντίθεση με το 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 (μετασχηματισμός τεχνουργημάτων). Οι πειραματικές λειτουργίες μπορούν να ενεργοποιηθούν σε παραγωγή, αλλά το ενδέχεται να αλλάξει σε μελλοντικές εκδόσεις.

Gradle Enterprise και Build Scan επίσης διαμορφώνονται μέσω settings.gradle: plugins { id("com.gradle.enterprise") } με μπλοκ gradleEnterprise. Το Build Scan είναι μια υπηρεσία cloud που εμφανίζει λεπτομερείς πληροφορίες για κάθε μεταγλώττιση: χρόνος εκτέλεσης κάθε εργασίας, προσωρινή αποθήκευση, σφάλματα. Η ενεργοποίηση του 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)