Zum Android-KMP-Plug-in migrieren

Bisher war die einzige Möglichkeit, Android in ein KMP-Projekt einzubinden, die Verwendung des regulären Gradle-Plug-ins für die Android-Bibliothek: com.android.library. Dieser Ansatz wird jedoch jetzt zugunsten des speziellen com.android.kotlin.multiplatform.library-Plug-ins, auch Android-KMP-Plug-in genannt, eingestellt. In diesem Leitfaden wird beschrieben, wie Sie zum neuen Plug-in migrieren.

Wichtige Funktionen und Unterschiede

Das Android-KMP-Plug-in (com.android.kotlin.multiplatform.library) ist speziell für KMP-Projekte konzipiert und unterscheidet sich in mehreren wichtigen Aspekten vom herkömmlichen com.android.library-Plug-in:

  • Architektur mit einer einzelnen Variante:Das Plug-in arbeitet mit einer einzelnen Variante und optimiert den Build-Prozess, da die Unterstützung für Produktvarianten und Build-Typen entfernt wird, die in Standard-Android-Bibliotheksprojekten häufig vorkommen. Dadurch wird die Konfiguration vereinfacht und die Build-Leistung für KMP-Android-Bibliotheken verbessert.
  • Für KMP optimiert:Das Plug-in wurde speziell für Kotlin-Multiplattform-Bibliotheken entwickelt und konzentriert sich auf gemeinsamen Kotlin-Code und Interoperabilität. Daher werden Android-spezifische native Builds, AIDL (Android Interface Definition Language) und RenderScript nicht unterstützt, da sie in einem KMP-Kontext für freigegebenen Code in der Regel nicht relevant sind.
  • Standardmäßig deaktivierte Tests:Um die Build-Geschwindigkeit in einer mehrplattformfähigen Umgebung weiter zu verbessern, sind Tests standardmäßig deaktiviert. Sie können Tests explizit aktivieren, wenn dies für Ihr Projekt erforderlich ist. Dies gilt sowohl für Tests auf dem Host (Unit-Tests) als auch für Tests auf dem Gerät (Instrumentierungstests).
  • Keine Android-Erweiterung auf oberster Ebene:Das Plug-in erstellt keine android-Erweiterung auf oberster Ebene in Ihren Gradle-Build-Dateien. Die Konfiguration wird mit einem androidLibrary-Block in der Kotlin Multiplatform DSL verwaltet, um eine einheitliche KMP-Projektstruktur beizubehalten.
  • Java-Kompilierung aktivieren:Die Java-Kompilierung ist standardmäßig nicht aktiviert. Wenn für Ihre KMP-Bibliothek Java-basierter Code kompiliert werden muss, müssen Sie die Funktion explizit aktivieren. Verwenden Sie dazu die withJava() API im androidLibrary-Konfigurationsblock Ihres kotlin-Blocks. So können Sie den Kompilierungsprozess genauer steuern und die Build-Zeiten verbessern, wenn die Kompilierung von Java-basiertem Code nicht erforderlich ist.

Vorteile der Migration

Das Android-KMP-Plug-in bietet folgende Vorteile für KMP-Projekte:

  • Verbesserte Buildleistung und -Stabilität:Das Android-KMP-Plug-in wurde für optimierte Buildgeschwindigkeiten und eine verbesserte Stabilität in KMP-Projekten entwickelt. Die optimierte Architektur und der Fokus auf KMP-Workflows tragen zu einem effizienteren und zuverlässigeren Build-Prozess bei.
  • Verbesserte IDE-Integration:Das Plug-in bietet eine bessere Integration in Android Studio und andere Kotlin-IDEs. Dies führt zu einer besseren Codevervollständigung, Navigation, Fehlerbehebung und Entwicklerfreundlichkeit bei der Arbeit mit KMP-Android-Bibliotheken.
  • Vereinfachte Projektkonfiguration:Durch das Entfernen von Android-spezifischen Komplexitäten wie Varianten vereinfacht das Android-KMP-Plug-in die Konfiguration für KMP-Projekte. Das führt zu übersichtlicheren, wartbareren Build-Dateien und einer kürzeren Lernkurve für Entwickler, die neu in der KMP-Android-Entwicklung sind. Bei der Integration von Android in ein KMP-Projekt mit dem com.android.library-Plug-in führte die Interaktion zwischen dem Android Gradle-Plug-in und dem Kotlin Gradle-Plug-in in der mehrplattformfähigen Struktur manchmal zu irreführenden Namen von Quellsätzen. Angenommen, die Quellgruppe zur Konfiguration von Android-Instrumentierungstests hat den Namen androidAndroidTest. Diese Namenskonvention war für Entwickler, die mit standardmäßigen KMP-Projektstrukturen vertraut sind, weniger intuitiv.
  • Offizielle und empfohlene Lösung:Das com.android.kotlin.multiplatform.library-Plug-in ist der offizielle Ersatz für die bisherige Methode, KMP-Bibliotheken mit dem com.android.library-Plug-in Android-Ziele hinzuzufügen. Die weitere Verwendung des com.android.library-Plug-ins für KMP wird von JetBrains nicht mehr unterstützt und es erhält keine zukünftigen Updates und Verbesserungen mehr.

Android-KMP-Plug-in auf ein Projekt anwenden

Es gibt zwei Möglichkeiten, das Android-KMP-Plug-in auf Ihr Projekt anzuwenden: * Bei vorhandenen KMP-Bibliotheksmodulen bearbeiten Sie Ihre Gradle-Dateien manuell. * Für neue KMP-Bibliotheksmodule erstellen Sie das neue Modul direkt über die Android Studio-Benutzeroberfläche.

Plug-in auf ein vorhandenes Modul anwenden

So wenden Sie das Android-KMP-Plug-in auf ein vorhandenes KMP-Bibliotheksmodul an:

  1. Öffnen Sie die TOML-Datei des Versionskatalogs und fügen Sie dem Abschnitt plugins den folgenden Code hinzu:

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

    Ersetzen Sie KOTLIN_PLUGIN_VERSION und ANDROID_KMP_PLUGIN_VERSION durch die tatsächlich verwendeten Versionen.

  2. Öffnen Sie die Datei build.gradle.kts (Kotlin) oder build.gradle (Groovy) im Stammverzeichnis Ihres KMP-Bibliotheksmoduls.

  3. Wenden Sie das Plug-in oben in der Datei innerhalb des plugins-Blocks an:

    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. Konfigurieren Sie den Kotlin Multiplatform-Block (kotlin), um das Android-Ziel zu definieren. Geben Sie im Block kotlin das Android-Ziel mit androidLibrary an:

    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. Nachdem Sie das Plug-in angewendet und den kotlin-Block konfiguriert haben, synchronisieren Sie Ihr Gradle-Projekt, um die Änderungen anzuwenden.

Neues Modul mit dem Plug-in erstellen

Sie können auch direkt in Android Studio ein neues Kotlin-Multiplatform-Bibliotheksmodul erstellen. Dadurch werden die erforderlichen Plug-ins automatisch angewendet, einschließlich des Android-KMP-Plug-ins. Weitere Informationen zum Erstellen eines neuen KMP-Bibliotheksmoduls mit Android Studio finden Sie unter Kotlin Multiplatform einem vorhandenen Projekt hinzufügen.

Weitere Informationen zum gesamten Multiplattform-System und zu erweiterten Konfigurationen finden Sie in der offiziellen Kotlin Multiplatform-Dokumentation.