Esegui la migrazione al plug-in Android-KMP

In precedenza, l'unico modo per integrare Android in un progetto KMP era utilizzare il plug-in Gradle della raccolta Android normale: com.android.library. Tuttavia, questo approccio è stato ritirato a favore del plug-in com.android.kotlin.multiplatform.library dedicato, noto anche come plug-in Android-KMP. Questa guida spiega come eseguire la migrazione al nuovo plug-in.

Funzionalità e differenze principali

Il plug-in Android-KMP (com.android.kotlin.multiplatform.library) è personalizzato specificamente per i progetti KMP e si differenzia dal plug-in com.android.library tradizionale in diversi aspetti chiave:

  • Architettura a singola variante: il plug-in funziona con una singola variante, semplificando il processo di compilazione rimuovendo il supporto per i gusti dei prodotti e i tipi di compilazione comunemente presenti nei progetti di librerie Android standard. In questo modo, la configurazione viene semplificata e le prestazioni di compilazione delle librerie Android KMP vengono migliorate.
  • Ottimizzato per KMP:il plug-in è progettato specificamente per le librerie Kotlin Multiplatform, incentrato sull'interoperabilità e sul codice Kotlin condiviso. Di conseguenza, omette il supporto per le build native specifiche per Android, AIDL (Android Interface Definition Language) e RenderScript, che in genere non sono pertinenti in un contesto di codice condiviso KMP.
  • Test disattivati per impostazione predefinita:per migliorare ulteriormente la velocità di compilazione in un ambiente multipiattaforma, i test sono disattivati per impostazione predefinita. Puoi attivare esplicitamente i test, se necessario per il tuo progetto. Questo vale sia per i test sull'host (test di unità) sia per i test sul dispositivo (test di strumentazione).
  • Nessuna estensione Android di primo livello: il plug-in non crea un'estensioneandroid di primo livello nei file di compilazione di Gradle. La configurazione viene gestita con un blocco androidLibrary all'interno del DSL multipiattaforma Kotlin, mantenendo una struttura del progetto KMP coerente.
  • Attiva la compilazione Java:la compilazione Java non è attiva per impostazione predefinita. Se la libreria KMP deve compilare codice basato su Java, devi attivarla esplicitamente utilizzando l'API withJava() all'interno del blocco di configurazione androidLibrary nel blocco kotlin. Ciò consente un controllo più granulare sul processo di compilazione e può migliorare i tempi di compilazione quando la compilazione del codice basato su Java non è obbligatoria.

Vantaggi della migrazione

Il plug-in Android-KMP offre i seguenti vantaggi per i progetti KMP:

  • Miglioramento delle prestazioni e della stabilità della compilazione: il plug-in Android-KMP è progettato per velocità di compilazione ottimizzate e stabilità migliorata all'interno dei progetti KMP. La sua architettura semplificata e l'attenzione ai flussi di lavoro KMP contribuiscono a un processo di compilazione più efficiente e affidabile.
  • Integrazione IDE migliorata:il plug-in offre un'integrazione superiore con Android Studio e altri IDE Kotlin. Ciò comporta una migliore compilazione del codice, navigazione, debug ed esperienza complessiva dello sviluppatore quando si utilizzano le librerie Android KMP.
  • Configurazione semplificata del progetto: rimuovendo complessità specifiche di Android come le varianti, il plug-in Android-KMP semplifica la configurazione per i progetti KMP. Il risultato è file di build più puliti e gestibili e una curva di apprendimento ridotta per gli sviluppatori che non hanno esperienza con lo sviluppo Android KMP. In precedenza, quando si integrava Android in un progetto KMP utilizzando il plug-in com.android.library, l'interazione tra il plug-in Android per Gradle e il plug-in Kotlin per Gradle all'interno della struttura multipiattaforma a volte generava nomi ingannevoli degli insiemi di origine. Ad esempio, il set di origine dedicato alla configurazione dei test di Android instrumentati è stato denominato androidAndroidTest. Questa convenzione di denominazione era meno intuitiva per gli sviluppatori familiari alle strutture di progetto KMP standard.
  • Soluzione ufficiale e consigliata: il plug-in com.android.kotlin.multiplatform.library è la sostituzione ufficiale del metodo precedente per l'aggiunta di target Android alle librerie KMP utilizzando il plug-in com.android.library. Il plugin com.android.library per KMP non sarà più supportato da JetBrains e non potrà beneficiare di aggiornamenti e miglioramenti futuri.

Applicare il plug-in Android-KMP a un progetto

Esistono due modi principali per applicare il plug-in Android-KMP al progetto:

Applica il plug-in a un modulo esistente

Per applicare il plug-in Android-KMP a un modulo della libreria KMP esistente:

  1. Dichiarare i plug-in nel catalogo delle versioni. Apri il file TOML del catalogo delle versioni (di solito gradle/libs.versions.toml) e aggiungi le definizioni dei plug-in alla sezione [plugins]. sezione:

    [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" }

    Sostituisci KOTLIN_PLUGIN_VERSION e ANDROID_KMP_PLUGIN_VERSION con le versioni effettive in uso.

  2. Applica le dichiarazioni dei plug-in nel file di compilazione principale. Apri il file build.gradle.kts (Kotlin) o build.gradle (Groovy) nella directory principale del progetto. Aggiungi gli alias del plug-in al blocco plugins utilizzando apply false. In questo modo, gli alias dei plug-in sono disponibili per tutti i sottoprogetti senza applicare la logica del plug-in al progetto principale stesso.

    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. Applica il plug-in nel file di compilazione del modulo della libreria KMP. Apri il file build.gradle.kts (Kotlin) o build.gradle (Groovy) nel modulo della libreria KMP. Applica il plug-in nella parte superiore del file all'interno del blocco 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. Configura il target KMP per Android. Configura il blocco Kotlin Multiplatform (kotlin) per definire il target Android. All'interno del blocco kotlin, specifica il target Android utilizzando 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. Applica le modifiche. Dopo aver applicato il plug-in e configurato il blocco kotlin, sincronizza il progetto Gradle per applicare le modifiche.

Creare un nuovo modulo con il plug-in

Puoi anche creare un nuovo modulo della libreria Kotlin multipiattaforma direttamente in Android Studio. In questo modo vengono applicati automaticamente i plug-in necessari, incluso il plug-in Android-KMP. Per ulteriori indicazioni su come creare un nuovo modulo della libreria KMP con Android Studio, consulta Aggiungere Kotlin Multiplatform a un progetto esistente.

Per ulteriori informazioni sull'ecosistema multipiattaforma complessivo e su configurazioni più avanzate, consulta la documentazione ufficiale di Kotlin Multiplatform.