Migrer vers le plug-in Android-KMP

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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 conçu spécifiquement 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. Les fichiers de compilation sont ainsi plus clairs et plus faciles à gérer, et la courbe d'apprentissage est réduite 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 proposera plus de mises à jour ni d'améliorations à l'avenir.

Appliquer le plug-in Android-KMP à un projet

Il existe deux principales façons 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 d'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. Déclarez les plug-ins dans le catalogue de versions. Ouvrez le fichier TOML du catalogue de versions (généralement gradle/libs.versions.toml) et ajoutez les définitions de plug-in à 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. Appliquez les déclarations de plug-in dans le fichier de compilation racine. Ouvrez le fichier build.gradle.kts (Kotlin) ou build.gradle (Groovy) situé dans le répertoire racine de votre projet. Ajoutez les alias de plug-in au bloc plugins à l'aide de apply false. Les alias de plug-in sont ainsi disponibles pour tous les sous-projets sans appliquer la logique du plug-in au projet racine lui-même.

   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
   }

3. Appliquez le plug-in dans le fichier de compilation du module de bibliothèque KMP. Ouvrez le fichier build.gradle.kts (Kotlin) ou build.gradle (Groovy) dans votre module de bibliothèque KMP. Appliquez le plug-in en haut de votre fichier dans le bloc plugins:

   Kotlin

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

   Groovy

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

4. Configurez la cible KMP Android. Configurez le bloc Kotlin multiplateforme (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. Appliquez les modifications. 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.