compileSdkVersion: basi, nuove API e configurazione in Gradle

Cos'è compileSdkVersion in Android?

compileSdkVersion è un parametro intero in build.gradle che specifica contro quale versione dell'Android SDK compilare il codice. Quando scrivi codice usando classi da android.* o androidx.*, il compilatore le confronta con le API disponibili nella versione compileSdk specificata. Se un metodo è stato introdotto nell'API 36 e compileSdk = 35, il codice non verrà compilato. Se compileSdk = 36, il codice verrà compilato, ma chiamare quel metodo su un dispositivo con API 35 senza un controllo causerà un arresto anomalo.

compileSdkVersion viene caricato dalla piattaforma Android SDK installata tramite SDK Manager in Android Studio. Ogni livello API ha la propria piattaforma: android-21, android-29, android-34, android-35, android-36. La piattaforma contiene android.jar — un insieme di classi, metodi e costanti che il compilatore Kotlin/Java utilizza. Se la piattaforma non è installata, Gradle la scaricherà automaticamente tramite sdkmanager al primo build.

AGP (Android Gradle Plugin) versione 8.7+ raccomanda di specificare compileSdk come intero tramite compileSdk = 36 in Kotlin DSL, senza il prefisso android-. compileSdk può anche essere impostato tramite compileSdkVersion 36 in Groovy DSL o compileSdkPreview per versioni di anteprima dell'SDK (developer previews). compileSdkPreview viene utilizzato per testare i livelli API imminenti prima del rilascio ufficiale.

// build.gradle.kts — configurazione di compileSdkVersion
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — ultimo livello API stabile (Android 16)
    compileSdk = 36

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

// Alternativamente: compileSdkPreview per versioni di anteprima
// compileSdkPreview = "Baklava"

Nell'esempio, compileSdk = 36 fornisce accesso a tutte le API di Android 16 (Baklava). La piattaforma Android SDK 36 deve essere installata in SDK Manager. compileSdkPreview con il nome "Baklava" può essere utilizzato per testare API instabili prima del rilascio ufficiale della piattaforma. Dopo il rilascio, l'anteprima viene sostituita con compileSdk = 36 stabile.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Tre parametri di livello API in build.gradle — compileSdkVersion, targetSdkVersion e minSdkVersion — sono spesso confusi. Ognuno è responsabile di un diverso aspetto della compatibilità e i loro valori devono seguire la regola compileSdk >= targetSdk >= minSdk. minSdk è il limite inferiore: i dispositivi al di sotto non vedranno l'app. targetSdk è il punto di test: i cambiamenti comportamentali sono abilitati fino a questo livello. compileSdk è il soffitto: le API al di sopra di questo livello non sono disponibili per il compilatore.

Regola pratica chiave: compileSdk può essere aumentato senza alcun test sui dispositivi. Questa è un'operazione sicura che fornisce semplicemente al compilatore una nuova versione di android.jar. L'unico rischio sono le API deprecate che potrebbero essere rimosse nella nuova versione della piattaforma, ma questo viene rilevato in fase di compilazione e facilmente risolto. Aumentare targetSdk, d'altra parte, richiede un ciclo QA completo.

Perché compileSdk può essere superiore a targetSdk? Immagina che Android 16 (API 36) sia stato rilasciato con nuove API che vuoi utilizzare nel codice, ma non hai ancora testato i cambiamenti comportamentali dell'API 36. Imposti compileSdk = 36 (nuove API disponibili), targetSdk = 35 (cambiamenti comportamentali dell'API 36 disabilitati). Il codice verrà compilato, utilizzerà nuovi metodi sotto controlli SDK_INT e i cambiamenti comportamentali dell'API 36 non romperanno l'app perché targetSdk = 35.

Esempi di combinazioni corrette

compileSdk = 36, targetSdk = 36, minSdk = 26 — compatibilità completa con le ultime API e cambiamenti comportamentali, copertura dell'85% dei dispositivi. compileSdk = 36, targetSdk = 34, minSdk = 26 — nuove API disponibili, cambiamenti comportamentali solo fino all'API 34. compileSdk = 35, targetSdk = 36 — non corretto: compileSdk è inferiore a targetSdk, l'API 36 non è disponibile mentre i cambiamenti comportamentali della 36 sono attivi.

Come aggiornare compileSdkVersion: guida passo passo

Aggiornare compileSdkVersion è una delle operazioni più semplici e sicure in un progetto Android. A differenza di targetSdk, non richiede test approfonditi dei cambiamenti comportamentali. Tuttavia, ci sono alcuni passaggi da seguire per evitare errori di compilazione e avvisi di deprecazione.

Passo 1 — installa la nuova piattaforma tramite SDK Manager in Android Studio: Tools → SDK Manager → SDK Platforms → seleziona il nuovo livello API. Se non installi la piattaforma, Gradle proverà a scaricarla automaticamente, ma ciò potrebbe rallentare il primo build. Passo 2 — modifica compileSdk in build.gradle con il nuovo valore. Passo 3 — esegui il build (Build → Make Project) e correggi eventuali errori di compilazione.

Passo 4 — verifica le API deprecate. Dopo aver aggiornato compileSdk, alcuni metodi potrebbero essere contrassegnati come @Deprecated con la nota "removed in API X". Android Studio li evidenzia con barratura e mostra un avviso. Sostituisci le chiamate deprecate con nuove alternative. Se l'alternativa richiede un livello API superiore a minSdk, aggiungi un controllo in fase di esecuzione. Passo 5 — verifica le dipendenze: alcune librerie potrebbero richiedere una versione specifica di compileSdk. AGP 8.7+ raccomanda compileSdk = 36.

// Dopo l'aggiornamento di compileSdk: sostituzione API deprecate
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 {

    // PRIMA: metodo deprecato (può essere rimosso nella nuova API)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Può essere deprecato in API 36
    }

    // DOPO: nuova alternativa (se disponibile)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nuova API da compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Esempio di nuova API
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

La classe CompileSdkMigration mostra il pattern di migrazione corretto. Il vecchio metodo memoryClass potrebbe essere rimosso nella nuova API — il compilatore genererà un errore. La nuova alternativa getMemoryClassSafe è disponibile solo su API 36+, quindi viene chiamata sotto un controllo SDK_INT >= BAKLAVA. Per i dispositivi vecchi, viene utilizzato un fallback con @Suppress("DEPRECATION").

Lavorare con nuove API: controlli condizionali e fallback

Le nuove API rese disponibili dall'aggiornamento di compileSdkVersion non possono essere chiamate direttamente se minSdkVersion è inferiore a quel livello API. Senza un controllo in fase di esecuzione, l'app si arresta in modo anomalo con AbstractMethodError, NoSuchMethodError o VerifyError su dispositivi vecchi. Il meccanismo di protezione principale è controllare Build.VERSION.SDK_INT, chiamare la nuova API solo quando il livello API è sufficiente e fornire un fallback per le versioni vecchie.

AndroidX fornisce backport per molte nuove API, consentendo l'uso di metodi moderni anche con un compileSdk basso. Ad esempio, l'API Activity Result da androidx.activity:activity-ktx:1.9.3 funziona su tutte le versioni di Android a partire dall'API 14. NotificationCompat da AndroidX consente notifiche moderne su API vecchie. PhotoPicker è disponibile tramite ActivityResultContracts.PickVisualMedia a partire dall'API 34+.

// Chiamata sicura di nuova API con compileSdk 36 e 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+: nuovo metodo per lavorare con il colore
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nuova API da compileSdk 36 — richiede API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Fallback: formattazione manuale per API vecchie
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX: nessun backport necessario — controllo SDK_INT
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Utilizzo in 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")
    }
}

La classe NewApiHelper dimostra la chiamata sicura della nuova API Color.toArgbHexString (API 36 ipotetica) con formattazione di fallback per le versioni vecchie. Il principio chiave: compileSdk fornisce l'accesso per chiamare nuovi metodi nel codice, ma un controllo SDK_INT in fase di esecuzione protegge da arresti anomali su dispositivi vecchi. Senza un controllo SDK_INT, un'app con minSdk 26 e compileSdk 36 si arresterà in modo anomalo su Android 8-15.

AGP (Android Gradle Plugin) e compileSdkVersion

Android Gradle Plugin (AGP) è lo strumento di build principale per le applicazioni Android. Ogni versione di AGP supporta un intervallo specifico di compileSdkVersion. AGP 8.7.x (rilasciato nel 2026) richiede compileSdk >= 34 e raccomanda compileSdk = 36. AGP 8.5.x supporta compileSdk 33-35. Se compileSdk è inferiore al minimo per AGP, il build fallirà con l'errore: "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) è anche legato a compileSdkVersion. Se il tuo progetto utilizza codice nativo in C/C++ tramite NDK, compileSdk determina la versione dei file di intestazione e delle librerie. NDK r27+ raccomanda compileSdk 36. Per le librerie con file .so, compileSdk influisce sul livello API minimo per il codice nativo tramite APP_MIN_SDK_VERSION in Application.mk.

Gradle (7.6+) e Kotlin (2.0+) influenzano anche la compatibilità con compileSdk. AGP 8.7+ richiede Gradle 8.9+ e Kotlin 2.0+. Quando si aggiorna compileSdk, si consiglia di aggiornare AGP, Gradle e Kotlin alle ultime versioni stabili. Verifica la compatibilità nella tabella ufficiale di compatibilità di Android Gradle Plugin.

Problemi comuni durante l'aggiornamento di compileSdk

I problemi durante l'aggiornamento di compileSdkVersion si dividono in tre categorie: errori di compilazione, avvisi di deprecazione e incompatibilità in fase di esecuzione. Errori di compilazione — i metodi vengono rimossi dall'API e il codice non viene compilato. Avvisi di deprecazione — i metodi sono contrassegnati come @Deprecated, il codice viene compilato con avvisi. Incompatibilità in fase di esecuzione — le nuove API sono necessarie per determinate funzionalità e causano errori se il livello API sul dispositivo è insufficiente.

Il primo problema comune — "Cannot resolve symbol X". Ciò significa che una classe o un metodo è stato rimosso dall'API pubblica nella nuova versione dell'SDK. Soluzione: trova un'alternativa nella nuova piattaforma o utilizza un equivalente AndroidX. Ad esempio, la classe AsyncTaskLoader è stata deprecata nell'API 28 e rimossa dall'API pubblica nelle versioni più recenti. Le alternative includono Kotlin Coroutines o WorkManager.

Il secondo problema — cambiamento della firma del metodo. Nella nuova versione dell'API, un metodo potrebbe aver cambiato il numero o il tipo dei suoi parametri. Il compilatore Kotlin/Java genera un errore: "None of the following functions can be called with the arguments supplied". Soluzione: aggiorna la chiamata del metodo per corrispondere alla nuova firma o aggiungi un controllo SDK_INT con la chiamata della vecchia firma per i dispositivi vecchi.

// Risoluzione dei problemi durante l'aggiornamento di compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Problema: il metodo hasSystemFeature ha cambiato firma in API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nuova firma: hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Vecchia firma: hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Problema: classe rimossa, utilizzare equivalente AndroidX
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // Invece di android.app.FragmentManager (rimosso) utilizzare
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

La classe CompileSdkProblemFixer risolve i problemi comuni: la firma cambiata di hasSystemFeature (cambiamento ipotetico nell'API 36) viene gestita tramite un controllo SDK_INT che chiama la versione corretta del metodo. La classe rimossa android.app.FragmentManager viene sostituita con l'equivalente AndroidX. Per le chiamate vecchie in cui non esiste alternativa, viene utilizzato @Suppress("DEPRECATION") con un commento che spiega il motivo del mantenimento.