Migrer votre configuration de compilation de Groovy vers Kotlin

Le plug-in Android Gradle 4.0 est désormais compatible avec l'utilisation de Kotlin dans votre configuration de compilation Gradle en remplacement de Groovy, le langage de programmation traditionnellement utilisé dans les fichiers de configuration Gradle.

Pour écrire des scripts Gradle, Kotlin est préférable à Groovy, car il est plus lisible et offre une meilleure vérification au moment de la compilation et une meilleure compatibilité avec l'IDE.

Bien que Kotlin offre actuellement une meilleure intégration dans l'éditeur de code d'Android Studio que Groovy, les compilations utilisant Kotlin ont tendance à être plus lentes que celles qui utilisent Groovy. Par conséquent, tenez compte des performances de compilation avant de procéder à la migration.

Cette page fournit des informations de base sur la conversion des fichiers de compilation Gradle de votre application Android de Groovy à Kotlin. Pour un guide de migration plus complet, consultez la documentation officielle de Gradle.

Vos trajets

À partir d'Android Studio Giraffe, les nouveaux projets utilisent le DSL Kotlin (build.gradle.kts) par défaut pour la configuration de compilation. Cela offre une meilleure expérience de modification que le DSL Groovy (build.gradle) avec la mise en surbrillance de la syntaxe, la saisie semi-automatique du code et la navigation vers les déclarations. Pour en savoir plus, consultez le Introduction au DSL Kotlin Kotlin.

Termes courants

DSL Kotlin : fait principalement référence au DSL Kotlin du plug-in Android Gradle ou, occasionnellement, au DSL Kotlin Gradle sous-jacent.

Dans ce guide de migration, les termes "Kotlin" et "DSL Kotlin" sont utilisés de manière interchangeable. De même, les termes "Groovy" et "Groovy DSL" sont utilisés de manière interchangeable.

Dénomination des fichiers de script

Les noms des extensions de fichier de script sont basés sur le langage dans lequel le fichier de compilation est écrit :

  • Les fichiers de compilation Gradle écrits en Groovy utilisent l'extension de nom de fichier .gradle.
  • Les fichiers de compilation Gradle écrits en Kotlin utilisent l'extension de nom de fichier .gradle.kts.

Convertir la syntaxe

Il existe des différences générales de syntaxe entre Groovy et Kotlin. Vous devez donc appliquer ces modifications à vos scripts de compilation.

Ajouter des parenthèses aux appels de méthode

Groovy vous permet d'omettre les parenthèses dans les appels de méthode, tandis que Kotlin les exige. Pour migrer votre configuration, ajoutez des parenthèses à ces types d'appels de méthode. Ce code montre comment configurer un paramètre en Groovy :

compileSdkVersion 30

Voici le même code écrit en Kotlin :

compileSdkVersion(30)

Ajouter = aux appels d'attribution

Le DSL Groovy vous permet d'omettre l'opérateur d'affectation = lors de l'attribution de propriétés, alors que Kotlin l'exige. Ce code montre comment attribuer des propriétés en Groovy :

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

Ce code montre comment attribuer des propriétés en Kotlin :

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

Convertir les chaînes

Voici les différences de chaîne entre Groovy et Kotlin :

  • Guillemets doubles pour les chaînes : alors que Groovy permet de définir des chaînes à l'aide de guillemets simples, Kotlin nécessite des guillemets doubles.

  • Interpolation de chaîne sur les expressions en pointillés : en Groovy, vous pouvez simplement utiliser le préfixe $ pour les interpolations de chaîne sur les expressions en pointillés, mais Kotlin nécessite d'encapsuler ces expressions avec des accolades. Par exemple, en Groovy, vous pouvez utiliser $project.rootDir comme indiqué dans l'extrait suivant :

        myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"

    En langage Kotlin, cependant, le code précédent appelle toString() sur project, et non sur project.rootDir. Pour obtenir la valeur du répertoire racine, encapsulez l'expression ${project.rootDir} avec des accolades :

        myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"

    Pour en savoir plus, consultez la section Modèles de chaîne dans la documentation Kotlin.

Renommer les extensions de fichier

Ajoutez .kts à chaque fichier de compilation lorsque vous migrez son contenu. Par exemple, sélectionnez un fichier de compilation, comme le fichier settings.gradle. Renommez le fichier settings.gradle.kts et convertissez son contenu en Kotlin. Assurez-vous que la compilation du projet se poursuit après la migration de chaque fichier de compilation.

Migrez d'abord vos fichiers les plus petits, gagnez en expérience, puis attelez-vous aux fichiers de plus grande envergure. Vous pouvez utiliser une combinaison de fichiers de compilation Kotlin et Groovy dans un projet. Vous n'avez donc pas besoin de précipiter la migration.

Remplacez def par val ou var.

Remplacez def par val ou var, ce qui est la façon dont les variables sont définies en Kotlin. Voici une déclaration de variable en Groovy :

def building64Bit = false

Voici le même code écrit en Kotlin :

val building64Bit = false

Ajouter le préfixe is aux propriétés booléennes

Groovy utilise une logique de déduction des propriétés basée sur les noms des propriétés. Pour une propriété booléenne foo, ses méthodes déduites peuvent être getFoo, setFoo ou isFoo. Une fois convertis en Kotlin, ces noms de propriété doivent être remplacés par les méthodes déduites qui ne sont pas compatibles avec Kotlin. Par exemple, pour les éléments booléens DSL buildTypes, vous devez leur ajouter le préfixe is. Ce code montre comment définir des propriétés booléennes en Groovy :

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            ...
        }
        debug {
            debuggable true
            ...
        }
    ...

Voici le même code en Kotlin. Notez que les propriétés sont précédées par is.

android {
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
            isShrinkResources = true
            ...
        }
        getByName("debug") {
            isDebuggable = true
            ...
        }
    ...

Convertir les listes et les cartes

Les listes et les cartes Groovy sont définies à l'aide d'une syntaxe différente à celle de Kotlin. Groovy utilise [], tandis que Kotlin appelle explicitement les méthodes de création de collections à l'aide de listOf ou de mapOf. Veillez à remplacer [] par listOf ou mapOf lors de la migration.

Voici comment définir une liste en Groovy par rapport à Kotlin :

jvmOptions += ["-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError</code>"]

Voici le même code écrit en Kotlin :

jvmOptions += listOf("-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError")

Voici comment définir une carte en Groovy par rapport à Kotlin :

def myMap = [key1: 'value1', key2: 'value2']

Voici le même code écrit en Kotlin :

val myMap = mapOf("key1" to "value1", "key2" to "value2")

Configurer les types de compilation

Dans le langage DSL Kotlin, seuls les types de version "release" et "debug" sont disponibles implicitement. Tous les autres types de compilation personnalisés doivent être créés manuellement.

En Groovy, vous pouvez utiliser "release", "debug" et d'autres types de compilation sans avoir à les créer au préalable. L'extrait de code suivant montre une configuration avec les types de compilation debug, release et benchmark en Groovy.

buildTypes {
 debug {
   ...
 }
 release {
   ...
 }
 benchmark {
   ...
 }
}

Pour créer la configuration équivalente en Kotlin, vous devez créer explicitement le type de compilation benchmark.

buildTypes {
 debug {
   ...
 }

 release {
   ...
 }
 register("benchmark") {
    ...
 }
}

Migrer du buildscript vers le bloc "plugins"

Si votre build utilise le bloc buildscript {} pour ajouter des plug-ins au projet, vous devez le refactoriser pour utiliser le bloc plugins {} à la place. Le bloc plugins {} facilite l'application des plug-ins et fonctionne bien avec les catalogues de versions.

De plus, lorsque vous utilisez le bloc plugins {} dans vos fichiers de compilation, Android Studio prend en compte le contexte même en cas d'échec de la compilation. Ce contexte permet de corriger vos fichiers DSL Kotlin, car il permet à l'IDE Studio d'effectuer la saisie semi-automatique du code et de fournir d'autres suggestions utiles.

Trouver les ID des plug-ins

Alors que le bloc buildscript {} ajoute les plug-ins au classpath de compilation à l'aide des coordonnées Maven du plug-in, par exemple com.android.tools.build:gradle:7.4.0, le bloc plugins {} utilise plutôt les ID de plug-in.

Pour la plupart des plug-ins, l'ID du plug-in est la chaîne utilisée lorsque vous les appliquez à l'aide de apply plugin. Par exemple, les ID de plug-in suivants font partie du plug-in Android Gradle:

  • com.android.application
  • com.android.library
  • com.android.lint
  • com.android.test

Vous trouverez la liste complète des plug-ins dans le dépôt Maven de Google.

Les plug-ins Kotlin peuvent être référencés par plusieurs ID de plug-in. Nous vous recommandons d'utiliser l'ID de plug-in avec espace de noms et de refactoriser le raccourci en ID de plug-in avec espace de noms en fonction du tableau suivant :

ID de plug-in abrégés ID de plug-in avec espace de noms
kotlin org.jetbrains.kotlin.jvm
kotlin-android org.jetbrains.kotlin.android
kotlin-kapt org.jetbrains.kotlin.kapt
kotlin-parcelize org.jetbrains.kotlin.plugin.parcelize

Vous pouvez également rechercher des plug-ins sur le portail de plug-ins Gradle, le dépôt central Maven et le dépôt Maven de Google. Pour en savoir plus sur le fonctionnement des ID de plug-in, consultez Développer des plug-ins Gradle personnalisés.

Effectuer la refactorisation

Une fois que vous connaissez les ID des plug-ins que vous utilisez, procédez comme suit:

  1. Si vous avez toujours des dépôts pour les plug-ins déclarés dans le bloc buildscript {}, déplacez-les plutôt vers le fichier settings.gradle.

  2. Ajoutez les plug-ins au bloc plugins {} dans le fichier build.gradle de premier niveau. Vous devez spécifier l'ID et la version du plug-in ici. Si le plug-in n'a pas besoin d'être appliqué au projet racine, utilisez apply false.

  3. Supprimez les entrées classpath du fichier build.gradle.kts de premier niveau.

  4. Appliquez les plug-ins en les ajoutant au bloc plugins {} dans le fichier build.gradle au niveau du module. Vous n'avez besoin de spécifier que l'ID du plug-in ici, car la version est héritée du projet racine.

  5. Supprimez l'appel apply plugin du plug-in du fichier build.gradle au niveau du module.

Par exemple, cette configuration utilise le bloc buildscript {} :

// Top-level build.gradle file
buildscript {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:7.4.0")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0")
        ...
    }
}

// Module-level build.gradle file
apply(plugin: "com.android.application")
apply(plugin: "kotlin-android")

Voici une configuration équivalente à l'aide du bloc plugins {}:

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.4.0' apply false
   id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   id 'org.jetbrains.kotlin.android'
   ...
}

// settings.gradle
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

Convertir le bloc "plugins"

L'application de plug-ins à partir du bloc plugins {} est similaire en Groovy et en Kotlin. Le code suivant montre comment appliquer des plug-ins en Groovy lorsque vous utilisez des catalogues de versions :

// Top-level build.gradle file
plugins {
   alias libs.plugins.android.application apply false
   ...
}

// Module-level build.gradle file
plugins {
   alias libs.plugins.android.application
   ...
}

Le code suivant montre comment faire la même chose en Kotlin :

// Top-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application) apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application)
   ...
}

Le code suivant montre comment appliquer des plug-ins en Groovy lorsque vous n'utilisez pas de catalogues de versions:

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.3.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   ...
}

Le code suivant montre comment faire la même chose en Kotlin :

// Top-level build.gradle.kts file
plugins {
   id("com.android.application") version "7.3.0" apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   id("com.android.application")
   ...
}

Pour en savoir plus sur le bloc plugins {}, consultez la section Appliquer des plug-ins dans la documentation Gradle.

Divers

Pour obtenir des exemples de code Kotlin pour d'autres fonctionnalités, consultez les pages de documentation suivantes :

Problèmes connus

À l'heure actuelle, un problème connu est que la vitesse de compilation peut être plus lente avec Kotlin qu'avec Groovy.

Signaler des problèmes

Pour découvrir comment nous fournir les informations dont nous avons besoin pour catégoriser votre problème, consultez Informations supplémentaires pour les bugs dans Gradle et les outils de compilation. Signalez ensuite un bug à l'aide de l'outil public de suivi des problèmes de Google.

Autres ressources

Pour obtenir un exemple pratique de fichiers de compilation Gradle écrits avec Kotlin, consultez l'application exemple Now In Android sur GitHub.