compileSdkVersion : bases, nouvelles API et configuration dans Gradle

Qu'est-ce que compileSdkVersion dans Android ?

compileSdkVersion est un paramètre entier dans build.gradle qui spécifie contre quelle version du SDK Android compiler le code. Lorsque vous écrivez du code utilisant des classes de android.* ou androidx.*, le compilateur les vérifie par rapport aux API disponibles dans la version compileSdk spécifiée. Si une méthode a été introduite dans l'API 36 et que compileSdk = 35, le code ne sera pas compilé. Si compileSdk = 36, le code sera compilé, mais appeler cette méthode sur un appareil avec API 35 sans vérification provoquera un plantage.

compileSdkVersion est chargé à partir de la plateforme Android SDK installée via le SDK Manager dans Android Studio. Chaque niveau d'API a sa propre plateforme : android-21, android-29, android-34, android-35, android-36. La plateforme contient android.jar — un ensemble de classes, méthodes et constantes utilisées par le compilateur Kotlin/Java. Si la plateforme n'est pas installée, Gradle la téléchargera automatiquement via sdkmanager lors de la première construction.

AGP (Android Gradle Plugin) version 8.7+ recommande de spécifier compileSdk comme un entier via compileSdk = 36 dans Kotlin DSL, sans le préfixe android-. compileSdk peut également être défini via compileSdkVersion 36 dans Groovy DSL ou compileSdkPreview pour les versions préliminaires du SDK (developer previews). compileSdkPreview est utilisé pour tester les niveaux d'API à venir avant la publication officielle.

// build.gradle.kts — configuration de compileSdkVersion
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — dernier niveau d'API stable (Android 16)
    compileSdk = 36

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

// Alternative : compileSdkPreview pour les versions préliminaires
// compileSdkPreview = "Baklava"

Dans l'exemple, compileSdk = 36 donne accès à toutes les API d'Android 16 (Baklava). La plateforme Android SDK 36 doit être installée dans le SDK Manager. compileSdkPreview avec le nom "Baklava" peut être utilisé pour tester des API instables avant la publication officielle de la plateforme. Après la publication, la prévisualisation est remplacée par compileSdk = 36 stable.

compileSdkVersion vs targetSdkVersion vs minSdkVersion

Trois paramètres de niveau d'API dans build.gradle — compileSdkVersion, targetSdkVersion et minSdkVersion — sont souvent confondus. Chacun est responsable d'un aspect différent de la compatibilité, et leurs valeurs doivent suivre la règle compileSdk >= targetSdk >= minSdk. minSdk est la limite inférieure : les appareils en dessous ne verront pas l'application. targetSdk est le point de test : les changements de comportement sont activés jusqu'à ce niveau. compileSdk est le plafond : les API au-dessus de ce niveau sont indisponibles pour le compilateur.

Règle pratique essentielle : compileSdk peut être augmenté sans aucun test sur les appareils. C'est une opération sûre qui fournit simplement au compilateur une nouvelle version d'android.jar. Le seul risque est les API obsolètes qui peuvent être supprimées dans la nouvelle version de la plateforme, mais cela est détecté au moment de la compilation et facilement corrigé. Augmenter targetSdk, en revanche, nécessite un cycle QA complet.

Pourquoi compileSdk peut-il être supérieur à targetSdk ? Imaginez qu'Android 16 (API 36) soit sorti avec de nouvelles API que vous souhaitez utiliser dans le code, mais que vous n'ayez pas encore testé les changements de comportement de l'API 36. Vous définissez compileSdk = 36 (nouvelles API disponibles), targetSdk = 35 (changements de comportement de l'API 36 désactivés). Le code sera compilé, utilisera de nouvelles méthodes sous des vérifications SDK_INT, et les changements de comportement de l'API 36 ne casseront pas l'application car targetSdk = 35.

Exemples de combinaisons correctes

compileSdk = 36, targetSdk = 36, minSdk = 26 — compatibilité totale avec les dernières API et changements de comportement, couvrant 85% des appareils. compileSdk = 36, targetSdk = 34, minSdk = 26 — nouvelles API disponibles, changements de comportement seulement jusqu'à l'API 34. compileSdk = 35, targetSdk = 36 — incorrect : compileSdk est inférieur à targetSdk, l'API 36 est indisponible alors que les changements de comportement de la 36 sont actifs.

Comment mettre à jour compileSdkVersion : guide étape par étape

Mettre à jour compileSdkVersion est l'une des opérations les plus simples et les plus sûres dans un projet Android. Contrairement à targetSdk, cela ne nécessite pas de tests approfondis des changements de comportement. Cependant, quelques étapes sont à suivre pour éviter les erreurs de compilation et les avertissements d'obsolescence.

Étape 1 — installez la nouvelle plateforme via le SDK Manager dans Android Studio : Tools → SDK Manager → SDK Platforms → sélectionnez le nouveau niveau d'API. Si vous n'installez pas la plateforme, Gradle essaiera de la télécharger automatiquement, mais cela peut ralentir la première construction. Étape 2 — modifiez compileSdk dans build.gradle avec la nouvelle valeur. Étape 3 — construisez (Build → Make Project) et corrigez les éventuelles erreurs de compilation.

Étape 4 — vérifiez les API obsolètes. Après avoir augmenté compileSdk, certaines méthodes peuvent être marquées @Deprecated avec la mention "removed in API X". Android Studio les surligne avec un barré et affiche un avertissement. Remplacez les appels obsolètes par de nouvelles alternatives. Si l'alternative nécessite un niveau d'API supérieur à minSdk, ajoutez une vérification d'exécution. Étape 5 — vérifiez les dépendances : certaines bibliothèques peuvent nécessiter une version spécifique de compileSdk. AGP 8.7+ recommande compileSdk = 36.

// Après l'augmentation de compileSdk : remplacement des API obsolètes
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 {

    // AVANT : méthode obsolète (peut être supprimée dans la nouvelle API)
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // Peut être obsolète dans l'API 36
    }

    // APRÈS : nouvelle alternative (si disponible)
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nouvelle API de compileSdk 36
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // Exemple de nouvelle API
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

La classe CompileSdkMigration montre le modèle de migration correct. L'ancienne méthode memoryClass peut être supprimée dans la nouvelle API — le compilateur émettra une erreur. La nouvelle alternative getMemoryClassSafe n'est disponible que sur API 36+, elle est donc appelée sous une vérification SDK_INT >= BAKLAVA. Pour les anciens appareils, un fallback avec @Suppress("DEPRECATION") est utilisé.

Travailler avec les nouvelles API : vérifications conditionnelles et fallback

Les nouvelles API rendues disponibles par l'augmentation de compileSdkVersion ne peuvent pas être appelées directement si minSdkVersion est inférieur à ce niveau d'API. Sans vérification d'exécution, l'application plantera avec AbstractMethodError, NoSuchMethodError ou VerifyError sur les anciens appareils. Le mécanisme de protection principal est de vérifier Build.VERSION.SDK_INT, d'appeler la nouvelle API uniquement lorsque le niveau d'API est suffisant, et de fournir un fallback pour les anciennes versions.

AndroidX fournit des rétroportages pour de nombreuses nouvelles API, permettant d'utiliser des méthodes modernes même avec un compileSdk bas. Par exemple, l'API Activity Result de androidx.activity:activity-ktx:1.9.3 fonctionne sur toutes les versions d'Android à partir de l'API 14. NotificationCompat d'AndroidX permet des notifications modernes sur les anciennes API. PhotoPicker est disponible via ActivityResultContracts.PickVisualMedia à partir de l'API 34+.

// Appel sécurisé d'une nouvelle API avec compileSdk 36 et 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+ : nouvelle méthode pour travailler avec la couleur
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nouvelle API de compileSdk 36 — nécessite API 36+
            return Color.toArgbHexString(colorInt)
        }
        // Fallback : formatage manuel pour les anciennes API
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX : aucun rétroportage nécessaire — vérification SDK_INT
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Utilisation dans 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 démontre l'appel sécurisé de la nouvelle API Color.toArgbHexString (API 36 hypothétique) avec un formatage de fallback pour les anciennes versions. Le principe clé : compileSdk donne accès à l'appel de nouvelles méthodes dans le code, mais une vérification SDK_INT au moment de l'exécution protège contre les plantages sur les anciens appareils. Sans vérification SDK_INT, une application avec minSdk 26 et compileSdk 36 plantera sur Android 8-15.

AGP (Android Gradle Plugin) et compileSdkVersion

Android Gradle Plugin (AGP) est l'outil de construction principal pour les applications Android. Chaque version d'AGP prend en charge une plage spécifique de compileSdkVersion. AGP 8.7.x (publié en 2026) nécessite compileSdk >= 34 et recommande compileSdk = 36. AGP 8.5.x prend en charge compileSdk 33-35. Si compileSdk est inférieur au minimum pour AGP, la construction échouera avec l'erreur : "The SDK platform (X) is not supported by this version of the Android Gradle Plugin".

NDK (Native Development Kit) est également lié à compileSdkVersion. Si votre projet utilise du code natif en C/C++ via NDK, compileSdk détermine la version des fichiers d'en-tête et des bibliothèques. NDK r27+ recommande compileSdk 36. Pour les bibliothèques avec des fichiers .so, compileSdk affecte le niveau d'API minimum pour le code natif via APP_MIN_SDK_VERSION dans Application.mk.

Gradle (7.6+) et Kotlin (2.0+) affectent également la compatibilité avec compileSdk. AGP 8.7+ nécessite Gradle 8.9+ et Kotlin 2.0+. Lors de l'augmentation de compileSdk, il est recommandé de mettre à jour AGP, Gradle et Kotlin vers les dernières versions stables. Vérifiez la compatibilité dans le tableau officiel de compatibilité d'Android Gradle Plugin.

Problèmes courants lors de l'augmentation de compileSdk

Les problèmes lors de l'augmentation de compileSdkVersion se divisent en trois catégories : erreurs de compilation, avertissements d'obsolescence et incompatibilités d'exécution. Erreurs de compilation — les méthodes sont supprimées de l'API et le code ne compile pas. Avertissements d'obsolescence — les méthodes sont marquées @Deprecated, le code compile avec des avertissements. Incompatibilités d'exécution — les nouvelles API sont nécessaires pour certaines fonctionnalités et provoquent des erreurs si le niveau d'API sur l'appareil est insuffisant.

Le premier problème courant — "Cannot resolve symbol X". Cela signifie qu'une classe ou une méthode a été supprimée de l'API publique dans la nouvelle version du SDK. Solution : trouvez une alternative dans la nouvelle plateforme ou utilisez un équivalent AndroidX. Par exemple, la classe AsyncTaskLoader a été obsolète dans l'API 28 et supprimée de l'API publique dans les versions plus récentes. Les alternatives incluent Kotlin Coroutines ou WorkManager.

Le deuxième problème — changement de signature de méthode. Dans la nouvelle version de l'API, une méthode peut avoir changé le nombre ou le type de ses paramètres. Le compilateur Kotlin/Java émet une erreur : "None of the following functions can be called with the arguments supplied". Solution : mettez à jour l'appel de méthode pour correspondre à la nouvelle signature ou ajoutez une vérification SDK_INT avec l'appel de l'ancienne signature pour les anciens appareils.

// Résolution des problèmes lors de l'augmentation de compileSdk
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // Problème : la méthode hasSystemFeature a changé de signature dans l'API 36
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // Nouvelle signature : hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // Ancienne signature : hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // Problème : classe supprimée, utilisez l'équivalent AndroidX
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // Au lieu de android.app.FragmentManager (supprimé) utilisez
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

La classe CompileSdkProblemFixer résout les problèmes courants : la signature modifiée de hasSystemFeature (changement hypothétique dans l'API 36) est traitée via une vérification SDK_INT appelant la version correcte de la méthode. La classe supprimée android.app.FragmentManager est remplacée par son équivalent AndroidX. Pour les anciens appels où il n'existe pas d'alternative, @Suppress("DEPRECATION") est utilisé avec un commentaire expliquant la raison du maintien.