build.gradle : qu'est-ce que c'est, syntaxe et configuration dans Android

Qu'est-ce que build.gradle ?

build.gradle est un script de compilation en langage Groovy (extension .gradle) ou Kotlin (.gradle.kts) qui gère tous les aspects de la compilation d'une application Android. Gradle est un système de compilation automatique adopté par Google en 2013 comme standard pour Android. build.gradle décrit : quels plugins sont appliqués (Android, Kotlin, bibliothèques), quelles dépendances sont connectées, quelles versions de SDK sont utilisées, comment signer l'application et où publier.

Le processus de compilation comprend trois phases : Initialization (découverte des modules), Configuration (exécution des scripts build.gradle), Execution (exécution des tâches). build.gradle s'exécute pendant la phase Configuration, lorsque Gradle crée le graphe de tâches. À ce moment, les Build Variants sont déterminés, les dépendances sont calculées et les tâches sont configurées. Important : build.gradle est du code, pas seulement une configuration. On peut y utiliser des conditions, des boucles, des appels de méthodes et des scripts externes.

Les fichiers Gradle sont stockés dans la racine du module (app/build.gradle) et la racine du projet (build.gradle). De plus, Gradle prend en charge apply from — l'inclusion de scripts Gradle externes. Cela permet d'extraire la logique répétitive dans des fichiers avec des paramètres partagés. Avec l'avènement des Convention Plugins (AGP 7+), apply from est considéré comme obsolète — les Convention Plugins fournissent un moyen type-safe et composable de réutiliser la configuration entre les modules.

Évolution de build.gradle

Depuis 2013, la syntaxe de build.gradle a connu des changements significatifs : de Groovy avec des configurations dynamiques à Kotlin DSL avec des vérifications à la compilation. AGP a évolué de la version 1.0 à 8.7 (2025). Jalons clés : AGP 3.0 (Java 8 desugar, nouvelle variant API), AGP 4.0 (view binding, Java 11), AGP 7.0 (Kotlin DSL par défaut, Java 11 minimum), AGP 8.0 (classes R non transitives, build config en Kotlin), AGP 8.7 (KSP au lieu de kapt, configuration rapide).

Project-level et Module-level build.gradle

Project-level build.gradle (racine) définit les plugins, dépôts et configurations communs à tous les modules. Blocs principaux : plugins (déclarations de plugins Gradle), repositories (sources de dépendances : mavenCentral, google, jitpack). Le build.gradle racine n'a généralement pas de bloc android — il apparaît dans les modules. Project-level peut également contenir un bloc subprojects pour la configuration commune de tous les sous-projets, bien que les Convention Plugins soient préférables.

Module-level build.gradle (par exemple, app/build.gradle) décrit un module spécifique. Si le module est une application, il applique le plugin com.android.application. S'il s'agit d'une bibliothèque — com.android.library. Module-level contient : bloc android (compileSdk, defaultConfig, buildTypes, productFlavors), bloc dependencies (dépendances du module) et optionnellement des blocs pour la configuration des tests et de l'empaquetage. Module-level s'exécute après project-level et peut remplacer les paramètres communs.

À partir d'AGP 8.0, le build.gradle racine peut utiliser version catalogs (libs.versions.toml) pour la gestion centralisée des versions de dépendances. Un version catalog est un fichier dans le répertoire gradle/ qui contient les versions, les bibliothèques et les plugins. Dans build.gradle, les dépendances sont connectées via libs : implementation(libs.retrofit). Les version catalogs sont obligatoires pour les nouveaux projets et recommandés pour tous les projets de trois modules ou plus.

// settings.gradle.kts — racine du projet
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (project-level)
plugins {
    id("com.android.application") version "8.7.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
}

// app/build.gradle.kts (module-level)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp")
}

android {
    namespace = "com.example.myapp"
    compileSdk = 35

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

Groovy vs Kotlin DSL

Groovy est un langage JVM dynamique qui était la syntaxe originale de Gradle. Les scripts Groovy (.gradle) utilisent le typage dynamique : on peut omettre les types, utiliser des chaînes avec ou sans guillemets, appeler des méthodes qui n'existent pas à la compilation. La flexibilité de Groovy est aussi son défaut : l'IDE ne peut pas vérifier la syntaxe et les types tant que le script n'est pas exécuté, ce qui entraîne des erreurs d'exécution dues à des noms de paramètres ou des types incorrects.

Kotlin DSL (.gradle.kts) utilise le typage statique de Kotlin. L'IDE vérifie les types, suggère les paramètres disponibles via l'autocomplétion et met en évidence les erreurs lors de l'édition. Kotlin DSL est plus lent pendant la phase Configuration (en raison de la compilation des fichiers .kts en bytecode), mais Google améliore continuellement les performances : AGP 8.5+ utilise le Gradle Configuration Cache et Caching Kotlin DSL compilation, réduisant la différence à 1 à 2 secondes.

Google recommande Kotlin DSL pour tous les nouveaux projets et la migration progressive des projets existants. La migration de Groovy vers Kotlin DSL est directe : les guillemets sont remplacés par des parenthèses, les types sont ajoutés, les opérateurs sont convertis en fonctions. La plupart des bibliothèques fournissent des exemples Kotlin DSL dans leur documentation. Pour les cas complexes (Custom Plugin, Task Graph), Kotlin DSL fournit une API type-safe et prévient les erreurs qui, dans Groovy, ne sont découvertes qu'à l'exécution. Les version catalogs (libs.versions.toml) fonctionnent de la même manière avec les deux syntaxes.

Bloc android : configuration de l'application

compileSdk, minSdk et targetSdk

Le bloc android est l'élément central du module-level build.gradle. À l'intérieur sont configurés : namespace (pour R et BuildConfig), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Tous les paramètres du bloc android s'appliquent uniquement aux modules Android. Si le module est une bibliothèque, le plugin de bibliothèque est utilisé à la place de application, et applicationId est absent du bloc android.

compileSdk est la version du SDK avec laquelle le code est compilé. Elle doit être la dernière API Android (au moment de la rédaction — 35). minSdk est la version API minimale prise en charge. targetSdk est la version ciblée par l'application (les changements de comportement de cette version s'appliquent). La différence entre compileSdk et targetSdk : compileSdk détermine les API disponibles, targetSdk détermine le comportement à l'exécution. Recommandation : compileSdk = latest, targetSdk = latest - 1 (pour tester l'adaptation aux nouveaux changements).

compileOptions définit la compatibilité Java : sourceCompatibility et targetCompatibility. AGP 8+ nécessite Java 17+ pour la compilation. packaging gère l'inclusion de fichiers provenant de bibliothèques : exclude, merge, pickFirst pour résoudre les conflits META-INF. buildFeatures active/désactive ViewBinding, DataBinding, Compose. aaptOptions configure le traitement des ressources : ignoreAssetsPattern, cruncherEnabled. Chaque élément du bloc android optimise un aspect spécifique de la compilation.

android {
    namespace = "com.example.myapp"
    compileSdk = 35
    buildToolsVersion = "35.0.0"

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 5
        versionName = "2.3.1"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        getByName("debug") { isDebuggable = true }
        getByName("release") {
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    buildFeatures {
        viewBinding = true
        compose = true
    }
}

Gestion des dépendances

BOM (Bill of Materials)

Les dépendances dans build.gradle sont les bibliothèques et modules connectés au projet. Le bloc dependencies se trouve au même niveau que le bloc android. Gradle prend en charge plusieurs configurations : implementation (la bibliothèque est disponible dans ce module, non transitive), api (la bibliothèque est disponible de manière transitive pour les modules dépendants), compileOnly (compilation uniquement, non incluse dans l'APK), runtimeOnly (exécution uniquement), annotationProcessor / ksp (processeurs d'annotations), testImplementation (tests uniquement), androidTestImplementation (tests instrumentés uniquement).

À partir d'AGP 8.0, classes R non transitives — chaque bibliothèque a sa propre classe R, ce qui évite les conflits de ressources. Dans le bloc dependencies, il est important d'utiliser les bonnes configurations : implementation n'expose pas les dépendances transitives, ce qui accélère la compilation. api les expose — utilisé lorsqu'une bibliothèque exporte des types d'une autre bibliothèque (par exemple, Retrofit utilise les types OkHttp dans son API publique).

Pour la gestion des versions, il est recommandé d'utiliser BOM (Bill of Materials) — un fichier de compilation qui définit des versions de bibliothèques compatibles. Firebase BOM : implementation(platform("com.google.firebase:firebase-bom:33.0.0")). Après avoir connecté le BOM, on peut spécifier uniquement le nom de la bibliothèque sans version — le BOM sélectionnera automatiquement une version compatible. Cela élimine les conflits entre les dépendances transitives de différentes bibliothèques. Les BOM sont disponibles pour Firebase, Compose, Kotlin, Ktor, AndroidX.

dependencies {
    // BOM — gestion des versions
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX et Compose
    implementation("androidx.core:core-ktx")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx")
    implementation("androidx.activity:activity-compose")
    implementation("androidx.compose.ui:ui")

    // Network
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")

    // Firebase (versions du BOM)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // Testing
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

build.gradle dans les projets multimodules

Dans les projets multimodules, chaque module a son propre build.gradle. Pour connecter un module à un autre, on utilise la syntaxe implementation(project(":module-name")). Gradle reconstruit automatiquement le module si sa configuration a changé. L'architecture multimodule améliore le temps de compilation (compilation incrémentale, parallélisme) et sépare les responsabilités entre les modules fonctionnels, les modules principaux et les bibliothèques.

Le problème clé des projets multimodules est la duplication de configuration. Si 10 modules ont le même minSdk, compileSdk et les mêmes dépendances Compose, cela fait 10 copies dans différents build.gradle. La solution est les Convention Plugins (anciennement buildSrc). Un Convention Plugin est un plugin Gradle écrit en Kotlin qui est appliqué aux modules : plugins { id("myapp.android.library") }. Le plugin contient une configuration commune et les modifications s'appliquent immédiatement à tous les modules.

Pour organiser les Convention Plugins, on utilise le répertoire build-logic/ à la racine du projet. Il contient includeBuild dans settings.gradle et des plugins Kotlin. Les Convention Plugins peuvent être publiés dans un dépôt maven pour être réutilisés entre projets. Google recommande les Convention Plugins comme standard pour les projets multimodules, remplaçant subprojects { } et apply from. Le passage aux Convention Plugins réduit le build.gradle du module à 10 à 15 lignes.

// build-logic/src/main/kotlin/AndroidLibraryConventionPlugin.kt
class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            with(plugins) {
                apply("com.android.library")
                apply("org.jetbrains.kotlin.android")
            }
            extensions.configure<CommonExtension<*, *, *, *>> {
                compileSdk = 35
                defaultConfig { minSdk = 26 }
                compileOptions {
                    sourceCompatibility = JavaVersion.VERSION_17
                    targetCompatibility = JavaVersion.VERSION_17
                }
            }
        }
    }
}

// module/build.gradle.kts — après Convention Plugin
plugins {
    id("myapp.android.library")
}

dependencies {
    implementation(project(":core:network"))
}