compileSdkVersion: βασικές αρχές, νέα API και ρύθμιση στο Gradle

Τι είναι το compileSdkVersion στο Android;

compileSdkVersion — μια ακέραια παράμετρος στο build.gradle που καθορίζει προς ποια έκδοση του Android SDK θα μεταγλωττιστεί ο κώδικας. Όταν γράφετε κώδικα που χρησιμοποιεί κλάσεις από android.* ή androidx.*, ο μεταγλωττιστής τις ελέγχει με τα API που είναι διαθέσιμα στην καθορισμένη έκδοση compileSdk. Εάν μια μέθοδος εμφανίστηκε στο API 36 και compileSdk = 35, ο κώδικας δεν θα μεταγλωττιστεί. Εάν compileSdk = 36 — ο κώδικας θα μεταγλωττιστεί, αλλά σε μια συσκευή με API 35 κατά την κλήση αυτής της μεθόδου χωρίς έλεγχο θα προκύψει σφάλμα.

Το compileSdkVersion φορτώνεται από το Android SDK Platform, που εγκαθίσταται μέσω του SDK Manager στο Android Studio. Κάθε API Level έχει τη δική του πλατφόρμα: android-21, android-29, android-34, android-35, android-36. Η πλατφόρμα περιέχει το android.jar — ένα σύνολο κλάσεων, μεθόδων και σταθερών με τις οποίες εργάζεται ο μεταγλωττιστής Kotlin/Java. Εάν η πλατφόρμα δεν είναι εγκατεστημένη, το Gradle θα την κατεβάσει αυτόματα μέσω του sdkmanager κατά την πρώτη δημιουργία.

AGP (Android Gradle Plugin) έκδοσης 8.7+ συνιστά τον καθορισμό του compileSdk ως ακέραιου αριθμού μέσω compileSdk = 36 σε Kotlin DSL, χωρίς το πρόθεμα android-. Το compileSdk μπορεί επίσης να καθοριστεί μέσω compileSdkVersion 36 σε Groovy DSL ή compileSdkPreview για προεπισκοπήσεις SDK (developer previews). Το compileSdkPreview χρησιμοποιείται για τη δοκιμή μελλοντικών API Level πριν από την επίσημη κυκλοφορία.

// build.gradle.kts — ρύθμιση compileSdkVersion
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — τελευταίο σταθερό API Level (Android 16)
    compileSdk = 36

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

// Εναλλακτικά: compileSdkPreview για εκδόσεις προεπισκόπησης
// compileSdkPreview = "Baklava"

Στο παράδειγμα, το compileSdk = 36 παρέχει πρόσβαση σε όλα τα API του Android 16 (Baklava). Το Android SDK Platform 36 πρέπει να είναι εγκατεστημένο στο SDK Manager. Το compileSdkPreview με όνομα "Baklava" μπορεί να χρησιμοποιηθεί για δοκιμή ασταθών API πριν από την επίσημη κυκλοφορία της πλατφόρμας. Μετά την κυκλοφορία, το preview αντικαθίσταται από το σταθερό compileSdk = 36.

compileSdkVersion εναντίον targetSdkVersion εναντίον minSdkVersion

Τρεις παράμετροι API Level στο build.gradle — compileSdkVersion, targetSdkVersion και minSdkVersion — συχνά μπερδεύονται. Κάθε μία είναι υπεύθυνη για διαφορετική πτυχή συμβατότητας και οι τιμές τους πρέπει να συντονίζονται σύμφωνα με τον κανόνα compileSdk >= targetSdk >= minSdk. minSdk — κατώτερο όριο: συσκευές κάτω από αυτό δεν θα δουν την εφαρμογή. targetSdk — σημείο δοκιμής: οι behavioural changes ενεργοποιούνται έως αυτό το επίπεδο. compileSdk — οροφή: τα API πάνω από αυτό το επίπεδο δεν είναι διαθέσιμα στον μεταγλωττιστή.

Βασικός πρακτικός κανόνας: το compileSdk μπορεί να αυξηθεί χωρίς καμία δοκιμή σε συσκευές. Αυτή είναι μια ασφαλής λειτουργία που απλά δίνει στον μεταγλωττιστή μια νέα έκδοση του android.jar. Ο μόνος κίνδυνος — deprecated API που μπορεί να αφαιρεθούν στη νέα έκδοση της πλατφόρμας, αλλά αυτό ανιχνεύεται στο στάδιο της μεταγλώττισης και διορθώνεται εύκολα. Η αύξηση του targetSdk, αντίθετα, απαιτεί πλήρη κύκλο QA.

Γιατί το compileSdk μπορεί να είναι υψηλότερο από το targetSdk; Φανταστείτε ότι κυκλοφόρησε το Android 16 (API 36) με νέα API που θέλετε να χρησιμοποιήσετε στον κώδικα, αλλά τις behavioural changes του API 36 δεν τις έχετε δοκιμάσει ακόμα. Ορίζετε compileSdk = 36 (νέα API διαθέσιμα), targetSdk = 35 (behavioural changes API 36 απενεργοποιημένες). Ο κώδικας θα μεταγλωττιστεί, θα χρησιμοποιεί νέες μεθόδους υπό ελέγχους SDK_INT, και οι behavioural changes του API 36 δεν θα σπάσουν την εφαρμογή επειδή targetSdk = 35.

Παραδείγματα σωστών συνδυασμών

compileSdk = 36, targetSdk = 36, minSdk = 26 — πλήρης συμβατότητα με τα τελευταία API και behavioural changes, κάλυψη 85% συσκευών. compileSdk = 36, targetSdk = 34, minSdk = 26 — νέα API διαθέσιμα, behavioural changes μόνο έως API 34. compileSdk = 35, targetSdk = 36 — λανθασμένο: compileSdk χαμηλότερο από targetSdk, τα API 36 δεν είναι διαθέσιμα, αν και οι behavioural changes 36 είναι ενεργές.

Πώς να ενημερώσετε το compileSdkVersion: οδηγός βήμα προς βήμα

Η ενημέρωση του compileSdkVersion — μια από τις απλούστερες και ασφαλέστερες λειτουργίες σε ένα έργο Android. Σε αντίθεση με το targetSdk, δεν απαιτεί μακροχρόνια δοκιμή behavioural changes. Ωστόσο, υπάρχουν μερικά βήματα που πρέπει να εκτελεστούν για να αποφευχθούν σφάλματα μεταγλώττισης και προειδοποιήσεις deprecated.

Βήμα 1 — εγκαταστήστε τη νέα πλατφόρμα μέσω του SDK Manager στο Android Studio: Tools → SDK Manager → SDK Platforms → επιλέξτε το νέο API Level. Εάν δεν εγκαταστήσετε την πλατφόρμα, το Gradle θα προσπαθήσει να την κατεβάσει αυτόματα, αλλά αυτό μπορεί να επιβραδύνει την πρώτη δημιουργία. Βήμα 2 — αλλάξτε το compileSdk στο build.gradle στη νέα τιμή. Βήμα 3 — εκτελέστε τη δημιουργία (Build → Make Project) και διορθώστε τα σφάλματα μεταγλώττισης.

Βήμα 4 — ελέγξτε τα deprecated API. Μετά την αύξηση του compileSdk, ορισμένες μέθοδοι μπορεί να επισημανθούν με @Deprecated με τη σημείωση "removed in API X". Το Android Studio τα επισημαίνει με διαγραφή και εμφανίζει προειδοποίηση. Αντικαταστήστε τις deprecated κλήσεις με νέες εναλλακτικές. Εάν η εναλλακτική απαιτεί API Level υψηλότερο από το minSdk, προσθέστε έλεγχο runtime. Βήμα 5 — ελέγξτε τα dependencies: ορισμένες βιβλιοθήκες μπορεί να απαιτούν συγκεκριμένη έκδοση compileSdk. Το AGP 8.7+ συνιστά compileSdk = 36.

// Μετά την αύξηση compileSdk: αντικατάσταση deprecated API
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.os.Process
import android.app.ActivityManager

class CompileSdkMigration {

    // ΠΡΙΝ: deprecated μέθοδος (μπορεί να αφαιρεθεί στο νέο API)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Μπορεί να είναι deprecated στο API 36
    }

    // ΜΕΤΑ: νέα εναλλακτική (εάν είναι διαθέσιμη)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Νέο API από compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Παράδειγμα νέου API
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

Η κλάση CompileSdkMigration δείχνει το σωστό μοτίβο μετεγκατάστασης. Η παλιά μέθοδος memoryClass μπορεί να αφαιρεθεί στο νέο API — ο μεταγλωττιστής θα δώσει σφάλμα. Η νέα εναλλακτική getMemoryClassSafe είναι διαθέσιμη μόνο σε API 36+, επομένως καλείται υπό τον έλεγχο SDK_INT >= BAKLAVA. Για παλιές συσκευές χρησιμοποιείται fallback με @Suppress("DEPRECATION").

Εργασία με νέα API: conditional checks και fallback

Νέα API, διαθέσιμα χάρη στην αύξηση του compileSdkVersion, δεν μπορούν να κληθούν άμεσα εάν το minSdkVersion είναι χαμηλότερο από αυτό το API Level. Χωρίς έλεγχο runtime, η εφαρμογή θα καταρρεύσει με AbstractMethodError, NoSuchMethodError ή VerifyError σε παλιές συσκευές. Ο κύριος μηχανισμός προστασίας — έλεγχος του Build.VERSION.SDK_INT με κλήση του νέου API μόνο σε επαρκές API Level και fallback για παλιές εκδόσεις.

AndroidX παρέχει backport πολλών νέων API, επιτρέποντας τη χρήση σύγχρονων μεθόδων ακόμα και με χαμηλό compileSdk. Για παράδειγμα, το Activity Result API από το androidx.activity:activity-ktx:1.9.3 λειτουργεί σε όλες τις εκδόσεις Android από API 14. Το NotificationCompat από το AndroidX επιτρέπει τη χρήση σύγχρονων ειδοποιήσεων σε παλιά API. Το PhotoPicker είναι διαθέσιμο μέσω του ActivityResultContracts.PickVisualMedia από API 34+.

// Ασφαλής κλήση νέου API με compileSdk 36 και minSdk 26
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+: νέα μέθοδος εργασίας με χρώμα
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Νέο API από compileSdk 36 — απαιτεί API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: χειροκίνητη μορφοποίηση για παλιά API
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: backport δεν απαιτείται — έλεγχος SDK_INT
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Χρήση σε Activity
class ColorActivity : android.app.Activity() {
    override fun onCreate(savedInstanceState: android.os.Bundle?) {
        super.onCreate(savedInstanceState)
        val helper = NewApiHelper()
        val colorStr = helper.formatColor(0xFF6200EE)
        println("Color: $colorStr")
    }
}

Η κλάση NewApiHelper παρουσιάζει ασφαλή κλήση του νέου API Color.toArgbHexString (υποθετικό API 36) με fallback μορφοποίηση για παλιές εκδόσεις. Βασική αρχή: το compileSdk παρέχει πρόσβαση στην κλήση νέων μεθόδων στον κώδικα, αλλά ο έλεγχος runtime SDK_INT προστατεύει από κατάρρευση σε παλιές συσκευές. Χωρίς έλεγχο SDK_INT, η εφαρμογή με minSdk 26 και compileSdk 36 θα καταρρεύσει σε Android 8-15.

AGP (Android Gradle Plugin) και compileSdkVersion

Android Gradle Plugin (AGP) — το κύριο εργαλείο δημιουργίας εφαρμογών Android. Κάθε έκδοση AGP υποστηρίζει ένα συγκεκριμένο εύρος compileSdkVersion. Το AGP 8.7.x (κυκλοφόρησε το 2026) απαιτεί compileSdk >= 34 και συνιστά compileSdk = 36. Το AGP 8.5.x υποστηρίζει compileSdk 33-35. Εάν το compileSdk είναι χαμηλότερο από το ελάχιστο για AGP, η δημιουργία θα τερματιστεί με σφάλμα "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) συνδέεται επίσης με το compileSdkVersion. Εάν το έργο χρησιμοποιεί εγγενή κώδικα σε C/C++ μέσω NDK, το compileSdk καθορίζει την έκδοση των αρχείων κεφαλίδας και βιβλιοθηκών. Το NDK r27+ συνιστά compileSdk 36. Για βιβλιοθήκες με αρχεία .so, το compileSdk επηρεάζει το ελάχιστο API Level για εγγενή κώδικα μέσω APP_MIN_SDK_VERSION στο Application.mk.

Gradle (7.6+) και Kotlin (2.0+) επηρεάζουν επίσης τη συμβατότητα με compileSdk. Το AGP 8.7+ απαιτεί Gradle 8.9+ και Kotlin 2.0+. Κατά την αύξηση του compileSdk, συνιστάται η ενημέρωση των AGP, Gradle και Kotlin στις τελευταίες σταθερές εκδόσεις. Ελέγξτε τη συμβατότητα στον επίσημο πίνακα Android Gradle Plugin compatibility.

Τυπικά προβλήματα κατά την αύξηση του compileSdk

Προβλήματα κατά την αύξηση του compileSdkVersion χωρίζονται σε τρεις κατηγορίες: compilation errors, deprecated warnings και runtime incompatibilities. Compilation errors — μέθοδοι αφαιρέθηκαν από το API και ο κώδικας δεν μεταγλωττίζεται. Deprecated warnings — μέθοδοι επισημασμένες με @Deprecated, ο κώδικας μεταγλωττίζεται με προειδοποιήσεις. Runtime incompatibilities — νέα API είναι υποχρεωτικά για συγκεκριμένη λειτουργικότητα και προκαλούν σφάλμα όταν το API Level στη συσκευή είναι ανεπαρκές.

Το πρώτο τυπικό πρόβλημα — "Cannot resolve symbol X". Αυτό σημαίνει ότι μια κλάση ή μέθοδος αφαιρέθηκε από το δημόσιο API στη νέα έκδοση SDK. Λύση: βρείτε εναλλακτική στη νέα πλατφόρμα ή χρησιμοποιήστε το αντίστοιχο AndroidX. Για παράδειγμα, η κλάση AsyncTaskLoader ήταν deprecated στο API 28 και αφαιρέθηκε από το δημόσιο API σε νεότερες εκδόσεις. Εναλλακτική — Kotlin Coroutines ή WorkManager.

Το δεύτερο πρόβλημα — αλλαγή υπογραφής μεθόδου. Στη νέα έκδοση API, η μέθοδος μπορεί να έχει αλλάξει τον αριθμό ή τους τύπους παραμέτρων. Ο μεταγλωττιστής Kotlin/Java δίνει σφάλμα "None of the following functions can be called with the arguments supplied". Λύση: ενημερώστε την κλήση της μεθόδου στη νέα υπογραφή ή προσθέστε έλεγχο SDK_INT με κλήση της παλιάς υπογραφής για παλιές συσκευές.

// Επίλυση προβλημάτων κατά την αύξηση compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Πρόβλημα: η μέθοδος hasSystemFeature άλλαξε υπογραφή στο API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Νέα υπογραφή: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Παλιά υπογραφή: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Πρόβλημα: κλάση αφαιρέθηκε, χρησιμοποιούμε αντίστοιχο AndroidX
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // Αντί για android.app.FragmentManager (αφαιρέθηκε) χρησιμοποιούμε
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

Η κλάση CompileSdkProblemFixer λύνει τυπικά προβλήματα: η αλλαγμένη υπογραφή hasSystemFeature (υποθετική αλλαγή στο API 36) αντιμετωπίζεται μέσω ελέγχου SDK_INT με κλήση της σωστής έκδοσης της μεθόδου. Η αφαιρεθείσα κλάση android.app.FragmentManager αντικαταστάθηκε με το αντίστοιχο AndroidX. Για παλιές κλήσεις όπου δεν υπάρχει εναλλακτική, χρησιμοποιείται @Suppress("DEPRECATION") με σχόλιο σχετικά με τον λόγο διατήρησης.