Migrer vers le plug-in Android-KMP

Auparavant, le seul moyen d'intégrer Android à un projet KMP était d'utiliser le plug-in Gradle de bibliothèque Android standard: com.android.library. Toutefois, cette approche est désormais obsolète et remplacée par le plug-in com.android.kotlin.multiplatform.library dédié, également appelé plug-in Android-KMP. Ce guide explique comment migrer vers le nouveau plug-in.

Principales caractéristiques et différences

Le plug-in Android-KMP (com.android.kotlin.multiplatform.library) est spécialement conçu pour les projets KMP et diffère du plug-in com.android.library traditionnel sur plusieurs points clés:

  • Architecture à variante unique:le plug-in fonctionne avec une seule variante, ce qui simplifie le processus de compilation en supprimant la prise en charge des types de produits et de compilation couramment trouvés dans les projets de bibliothèque Android standards. Cela simplifie la configuration et améliore les performances de compilation pour les bibliothèques Android KMP.
  • Optimisé pour KMP:le plug-in est spécialement conçu pour les bibliothèques Kotlin Multiplatform, en se concentrant sur le code Kotlin partagé et l'interopérabilité. Par conséquent, il n'est pas compatible avec les builds natifs spécifiques à Android, AIDL (Android Interface Definition Language) et RenderScript, qui ne sont généralement pas pertinents dans un contexte de code partagé KMP.
  • Tests désactivés par défaut:pour accélérer davantage la compilation dans un environnement multiplate-forme, les tests sont désactivés par défaut. Vous pouvez activer explicitement les tests si nécessaire pour votre projet. Cela s'applique aux tests sur l'hôte (tests unitaires) et aux tests sur l'appareil (tests d'instrumentation).
  • Aucune extension Android de premier niveau:le plug-in ne crée pas d'extension android de premier niveau dans vos fichiers de compilation Gradle. La configuration est gérée avec un bloc androidLibrary dans le DSL multiplateforme Kotlin, ce qui permet de maintenir une structure de projet KMP cohérente.
  • Compilation Java activable:la compilation Java n'est pas activée par défaut. Si votre bibliothèque KMP doit compiler du code basé sur Java, vous devez l'activer explicitement à l'aide de l'API withJava() dans le bloc de configuration androidLibrary de votre bloc kotlin. Cela permet de mieux contrôler le processus de compilation et peut améliorer les temps de compilation lorsque la compilation du code basé sur Java n'est pas requise.

Avantages de la migration

Le plug-in Android-KMP offre les avantages suivants pour les projets KMP:

  • Amélioration des performances et de la stabilité de la compilation:le plug-in Android-KMP est conçu pour optimiser les vitesses de compilation et améliorer la stabilité dans les projets KMP. Son architecture simplifiée et son accent mis sur les workflows KMP contribuent à un processus de compilation plus efficace et fiable.
  • Intégration améliorée de l'IDE:le plug-in offre une intégration supérieure avec Android Studio et d'autres IDE Kotlin. Cela permet d'améliorer la finalisation du code, la navigation, le débogage et l'expérience globale des développeurs lorsqu'ils travaillent avec les bibliothèques Android KMP.
  • Configuration simplifiée des projets:en supprimant les complexités propres à Android, comme les variantes, le plug-in Android-KMP simplifie la configuration des projets KMP. Cela permet d'obtenir des fichiers de compilation plus clairs et plus faciles à gérer, et de réduire la courbe d'apprentissage pour les développeurs qui débutent le développement Android avec KMP. Auparavant, lorsque vous intégriez Android à un projet KMP à l'aide du plug-in com.android.library, l'interaction entre le plug-in Android Gradle et le plug-in Kotlin Gradle dans la structure multiplateforme entraînait parfois des noms de jeux de sources trompeurs. Par exemple, l'ensemble de sources dédié à la configuration des tests d'instrumentation Android était nommé androidAndroidTest. Cette convention d'attribution de noms était moins intuitive pour les développeurs familiarisés avec les structures de projet KMP standards.
  • Solution officielle et recommandée:le plug-in com.android.kotlin.multiplatform.library remplace officiellement la méthode précédente consistant à ajouter des cibles Android aux bibliothèques KMP à l'aide du plug-in com.android.library. JetBrains ne prendra plus en charge l'utilisation du plug-in com.android.library pour KMP et ne bénéficiera plus des futures mises à jour et améliorations.

Appliquer le plug-in Android-KMP à un projet

Il existe deux façons principales d'appliquer le plug-in Android-KMP à votre projet : * Pour les modules de bibliothèque KMP existants, modifiez vos fichiers Gradle manuellement. * Pour les nouveaux modules de bibliothèque KMP, créez-les directement depuis l'UI Android Studio.

Appliquer le plug-in à un module existant

Pour appliquer le plug-in Android-KMP à un module de bibliothèque KMP existant, procédez comme suit:

  1. Ouvrez votre fichier TOML de catalogue de versions et ajoutez les éléments suivants à la section plugins:

    [plugins]
kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform",
version.ref = "KOTLIN_PLUGIN_VERSION" }
android-kotlin-multiplatform-library = { id =
"com.android.kotlin.multiplatform.library", version.ref =
"ANDROID_KMP_PLUGIN_VERSION" }

    Remplacez KOTLIN_PLUGIN_VERSION et ANDROID_KMP_PLUGIN_VERSION par les versions que vous utilisez.

  2. Ouvrez votre fichier build.gradle.kts (Kotlin) ou build.gradle (Groovy) dans la racine de votre module de bibliothèque KMP.

  3. Appliquez le plug-in en haut de votre fichier dans le bloc plugins:

    Kotlin

    plugins {
   alias(libs.plugins.kotlin.multiplatform) apply false

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library) apply false
}

    Groovy

    plugins {
   alias(libs.plugins.kotlin.multiplatform) apply false

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library) apply false
}

  4. Configurez le bloc Kotlin Multiplatform (kotlin) pour définir la cible Android. Dans le bloc kotlin, spécifiez la cible Android à l'aide de androidLibrary:

    Kotlin

    kotlin {
   androidLibrary {
       namespace = "com.example.kmpfirstlib"
       compileSdk = 33
       minSdk = 24

       withJava() // enable java compilation support
       withHostTestBuilder {}.configure {}
       withDeviceTestBuilder {
           sourceSetTreeName = "test"
       }

       compilations.configureEach {
           compilerOptions.configure {
               jvmTarget.set(
                   org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
               )
           }
       }
   }

   sourceSets {
       androidMain {
           dependencies {
               // Add Android-specific dependencies here
           }
       }
       getByName("androidHostTest") {
           dependencies {
           }
       }

       getByName("androidDeviceTest") {
           dependencies {
           }
       }
   }
   // ... other targets (JVM, iOS, etc.) ...
}

    Groovy

    kotlin {
   androidLibrary {
       namespace = "com.example.kmpfirstlib"
       compileSdk = 33
       minSdk = 24

       withJava() // enable java compilation support
       withHostTestBuilder {}.configure {}
       withDeviceTestBuilder {
           it.sourceSetTreeName = "test"
       }

       compilations.configureEach {
           compilerOptions.options.jvmTarget.set(
               org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
           )
       }
   }

   sourceSets {
       androidMain {
           dependencies {
           }
       }
       androidHostTest {
           dependencies {
           }
       }
       androidDeviceTest {
           dependencies {
           }
       }
   }
   // ... other targets (JVM, iOS, etc.) ...
}

  5. Après avoir appliqué le plug-in et configuré le bloc kotlin, synchronisez votre projet Gradle pour appliquer les modifications.

Créer un module avec le plug-in

Vous pouvez également créer un module de bibliothèque Kotlin Multiplatform directement dans Android Studio. Les plug-ins nécessaires sont alors appliqués automatiquement, y compris le plug-in Android-KMP. Pour en savoir plus sur la création d'un module de bibliothèque KMP avec Android Studio, consultez Ajouter Kotlin Multiplatform à un projet existant.

Pour en savoir plus sur l'écosystème multiplate-forme global et les configurations plus avancées, consultez la documentation officielle sur la multiplate-forme Kotlin.