Android Gradle-Bibliotheks-Plug-in für KMP einrichten

Das Gradle-Plug-in com.android.kotlin.multiplatform.library ist das offiziell unterstützte Tool, um einem KMP-Bibliotheksmodul (Kotlin Multiplatform) ein Android-Ziel hinzuzufügen. Es vereinfacht die Projektkonfiguration, verbessert die Build-Leistung und bietet eine bessere Integration in Android Studio.

Die Verwendung des com.android.library-Plug-ins für die KMP-Entwicklung hängt von Android-Gradle-Plug-in-APIs ab, die eingestellt wurden und für die im Android-Gradle-Plug-in 9.0 und höher (4. Quartal 2025) eine Aktivierung erforderlich ist. Diese APIs werden voraussichtlich im Android-Gradle-Plug-in 10.0 (zweite Jahreshälfte 2026) entfernt.

Informationen zum Anwenden dieses Plug-ins finden Sie im Abschnitt Android-KMP-Plug-in anwenden. Wenn Sie von den Legacy-APIs migrieren müssen, lesen Sie die Migrationsanleitung.

Wenn Sie Hilfe bei der Migration zu AGP 9.0 oder höher benötigen, können Sie den von JetBrains für KMP-Apps erstellten Agent-Skill verwenden. Weitere Informationen zur Verwendung von Skills in Android Studio finden Sie unter Agent-Modus mit Skills erweitern. Beachten Sie, dass KI-Ergebnisse nicht vollständig vorhersehbar sind.

Wichtige Funktionen und Unterschiede

Das Android-KMP-Plug-in ist speziell auf KMP-Projekte zugeschnitten und unterscheidet sich in mehreren wichtigen Punkten vom Standard-com.android.library-Plug-in:

  • Architektur mit einer einzelnen Variante: Das Plug-in verwendet eine einzelne Variante. Die Unterstützung für Produktvarianten und Build-Typen wurde entfernt, was die Konfiguration vereinfacht und die Build-Leistung verbessert.

  • Optimiert für KMP:Das Plug-in ist für KMP-Bibliotheken konzipiert und konzentriert sich auf freigegebenen Kotlin-Code und Interoperabilität. Die Unterstützung für Android-spezifische native Builds, AIDL und RenderScript wurde weggelassen.

  • Standardmäßig deaktivierte Tests: Sowohl Unit- als auch Gerätetests (Instrumentierungstests) sind standardmäßig deaktiviert, um die Build-Geschwindigkeit zu erhöhen. Sie können sie bei Bedarf aktivieren.

  • Keine Android-Erweiterung auf oberster Ebene:Die Konfiguration wird mit einem android-Block innerhalb der Gradle-KMP-DSL verarbeitet, wodurch eine einheitliche KMP-Projektstruktur beibehalten wird. Es gibt keinen android-Erweiterungsblock auf oberster Ebene.

  • Java-Kompilierung aktivieren: Die Java-Kompilierung ist standardmäßig deaktiviert. Verwenden Sie withJava() im Block android, um sie zu aktivieren. Dadurch werden die Build-Zeiten verbessert, wenn keine Java-Kompilierung erforderlich ist.

Vorteile des Android-KMP-Bibliotheks-Plug-ins

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

  • Verbesserte Build-Leistung und ‑Stabilität:Es wurde für optimierte Build-Geschwindigkeiten und verbesserte Stabilität in KMP-Projekten entwickelt. Der Fokus auf KMP-Workflows trägt zu einem effizienteren und zuverlässigeren Build-Prozess bei.

  • Verbesserte IDE-Integration: Sie bietet eine bessere Codevervollständigung, Navigation, Fehlerbehebung und eine insgesamt bessere Entwicklungsumgebung bei der Arbeit mit KMP-Android-Bibliotheken.

  • Vereinfachte Projektkonfiguration: Das Plug-in vereinfacht die Konfiguration für KMP-Projekte, da Android-spezifische Komplexitäten wie Build-Varianten entfernt werden. Das führt zu übersichtlicheren und leichter zu verwaltenden Build-Dateien. Bisher konnte die Verwendung des com.android.library-Plug-ins in einem KMP-Projekt zu verwirrenden Source-Set-Namen wie androidAndroidTest führen. Diese Namenskonvention war für Entwickler, die mit Standard-KMP-Projektstrukturen vertraut sind, weniger intuitiv.

Problemumgehungen für nicht unterstützte Funktionen

Im Vergleich zur KMP-Integration mit dem com.android.library-Plug-in fehlen im com.android.kotlin.multiplatform.library-Plug-in einige Funktionen. Hier sind die Problemumgehungen für die nicht unterstützten Funktionen:

  • Build-Varianten

    Build-Typen und Produktvarianten werden nicht unterstützt. Das liegt daran, dass das neue Plug-in eine Architektur mit einer einzigen Variante verwendet, was die Konfiguration vereinfacht und die Build-Leistung verbessert.

    Wenn Sie Build-Varianten benötigen, empfehlen wir, ein separates eigenständiges Android-Bibliotheksmodul mit dem com.android.library-Plug-in zu erstellen, Build-Typen und Produktvarianten in diesem Modul zu konfigurieren und es dann als Standardprojektabhängigkeit aus dem androidMain-Source-Set Ihrer Kotlin Multiplatform-Bibliothek zu verwenden. Weitere Informationen finden Sie unter Android-Bibliothek erstellen und Build-Varianten konfigurieren.

  • Datenbindung und Ansichtsbindung

    Dies sind Android-spezifische UI-Framework-Funktionen, die eng mit dem Android-View-System und XML-Layouts verknüpft sind. Mit dem neuen Android-KMP-Bibliotheks-Plug-in empfehlen wir, die Benutzeroberfläche mit einem Multiplattform-Framework wie Compose Multiplatform zu verwalten. Datenbindung und Ansichtsbindung gelten als Implementierungsdetails einer endgültigen Android-App, nicht als freigebbare Bibliothek.

  • Unterstützung für native Builds

    Das neue Plug-in konzentriert sich auf die Erstellung eines Standard-AAR für das Android-Ziel. Die Einbindung von nativem Code in Kotlin Multiplatform wird direkt von den nativen Zielen von KMP (z. B. androidNativeArm64 und androidNativeX86) und den C-Interoperabilitätsfunktionen übernommen. Wenn Sie nativen C/C++-Code einbinden müssen, sollten Sie ihn als Teil eines gemeinsamen oder nativen Source-Sets definieren und die C-Interoperabilität im kotlin-Block konfigurieren, anstatt den Android-spezifischen externalNativeBuild-Mechanismus zu verwenden.

    Wenn Sie native Build-Unterstützung über externalNativeBuild benötigen, empfehlen wir, ein separates eigenständiges com.android.library-Modul zu erstellen, in das Sie nativen Code einbinden können, und diese eigenständige Bibliothek aus dem androidMain-Source-Set Ihres Kotlin Multiplatform-Bibliotheksprojekts zu verwenden. Weitere Informationen finden Sie unter Android-Bibliothek erstellen und C- und C++-Code zu Ihrem Projekt hinzufügen.

  • BuildConfig-Klasse

    Die Funktion BuildConfig ist in Umgebungen mit mehreren Varianten am nützlichsten. Da das neue Kotlin Multiplatform-Bibliotheks-Plug-in variantenunabhängig ist und keine Build-Typen und Produktvarianten unterstützt, ist diese Funktion nicht implementiert. Als Alternative empfehlen wir, das BuildKonfig-Plug-in oder ähnliche Community-Lösungen zu verwenden, um Metadaten für alle Ziele zu generieren.

Vorbereitung

Wenn Sie das com.android.kotlin.multiplatform.library-Plug-in verwenden möchten, muss Ihr Projekt mindestens mit den folgenden Versionen konfiguriert sein:

  • Android-Gradle-Plug-in (AGP): 8.10.0
  • Kotlin Gradle-Plug-in (KGP): 2.0.0

Android-KMP-Plug-in auf ein vorhandenes Modul anwenden

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

  1. Plug-ins im Versionskatalog deklarieren Öffnen Sie die TOML-Datei des Versionskatalogs (normalerweise gradle/libs.versions.toml) und fügen Sie den Abschnitt mit den Plug-in-Definitionen hinzu:

    # To check the version number of the latest Kotlin release, go to
# https://kotlinlang.org/docs/releases.html

[versions]
androidGradlePlugin = "9.4.0"
kotlin = "KOTLIN_VERSION"

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

  2. Wenden Sie die Plug-in-Deklaration in der Stamm-Build-Datei an. Öffnen Sie die Datei build.gradle.kts im Stammverzeichnis Ihres Projekts. Fügen Sie die Plug-in-Aliasse mit apply false dem Block plugins hinzu. Dadurch werden die Plugin-Aliasse für alle Unterprojekte verfügbar, ohne dass die Plugin-Logik auf das Stammprojekt selbst angewendet wird.

    Kotlin

    // Root build.gradle.kts file

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

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

    Groovy

    // Root build.gradle file

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

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

  3. Wenden Sie das Plug-in in einer Build-Datei für ein KMP-Bibliotheksmodul an. Öffnen Sie die Datei build.gradle.kts in Ihrem KMP-Bibliotheksmodul und wenden Sie das Plug-in oben in der Datei im Block plugins an:

    Kotlin

    // Module-specific build.gradle.kts file

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

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

    Groovy

    // Module-specific build.gradle file

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

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

  4. Android-KMP-Ziel konfigurieren Konfigurieren Sie den Kotlin Multiplatform-Block (kotlin), um das Android-Ziel zu definieren. Geben Sie im Block kotlin das Android-Ziel mit android an:

    Kotlin

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

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

       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 {
   android {
       namespace = "com.example.kmpfirstlib"
       compileSdk = 33
       minSdk = 24

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

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

Vom Legacy-Plug-in migrieren

In diesem Leitfaden wird die Migration vom Legacy-Plug-in com.android.library zum Plug-in com.android.kotlin.multiplatform.library beschrieben.

1. Quellen verschieben

Mit dem Legacy-Plug-in konnten Sie zusätzlich zu src/androidMain, src/androidHostTest und src/androidDeviceTest die Quellsätze src/main, src/test und src/androidTest verwenden. Das neue Plug-in verwendet nur die letztgenannten Quellverzeichnisse. Sie müssen also Quellen von src/main nach src/androidMain, von src/test nach src/androidHostTest und von src/androidTest nach src/androidDeviceTest verschieben.

2. Benutzerdefinierte Quell- und Ressourcenverzeichnisse konfigurieren

Wenn Sie Quellen oder Ressourcen in nicht standardmäßigen Verzeichnissen haben, haben Sie diese zuvor mit dem Block sourceSets konfiguriert. Verwenden Sie mit dem neuen Plug-in die Erweiterung androidComponents, um der Variante statische Quellverzeichnisse hinzuzufügen.

Beachten Sie, dass die Methode addStaticSourceDirectory mit dem neuen Plug-in das Verzeichnis der vorhandenen Liste von Quellverzeichnissen hinzufügt. Beim Legacy-Plug-in ersetzt die Methode setSrcDirs die Liste, während die Methode srcDir Elemente hinzufügt.

Android-KMP

Verwenden Sie im neuen Plug-in den Block onVariants, um mit den Quellen der Variante zu interagieren.

// build.gradle.kts

androidComponents {
    onVariants { variant ->
        // Add a directory for Kotlin sources
        variant.sources.kotlin?.addStaticSourceDirectory("other/kotlin")

        // Add a directory for Android assets
        variant.sources.assets?.addStaticSourceDirectory("other/assets")
    }
}

Legacy-Plug-in

Mit dem Plug-in com.android.library wurde der Block sourceSets verwendet, um Quellverzeichnisse festzulegen oder hinzuzufügen.

// build.gradle.kts

android {
    sourceSets {
        getByName("main") {
            // Replaces the directory for Kotlin sources.
            kotlin.setSrcDirs(listOf("other/kotlin"))

            // Appends a directory for assets.
            assets.srcDir("other/assets")
        }
    }
}

3. Abhängigkeiten deklarieren

Eine häufige Aufgabe ist das Deklarieren von Abhängigkeiten für Android-spezifische Source-Sets. Das neue Plug-in erfordert, dass diese explizit im sourceSets-Block platziert werden, im Gegensatz zum zuvor verwendeten allgemeinen dependencies-Block.

Android-KMP

Das neue Plug-in sorgt für eine sauberere Struktur, da Android-Abhängigkeiten im Source-Set androidMain gruppiert werden. Zusätzlich zum Haupt-Source-Set gibt es zwei Test-Source-Sets, die bei Bedarf erstellt werden: androidDeviceTest und androidHostTest. Weitere Informationen finden Sie unter Host- und Gerätetests konfigurieren.

// build.gradle.kts

kotlin {
    android {}
    //... other targets

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")
        }

        // Dependencies are now scoped to the specific Android source set
        androidMain.dependencies {
            implementation("androidx.appcompat:appcompat:1.7.0")
            implementation("com.google.android.material:material:1.11.0")
        }
    }
}

Die Source-Sets haben entsprechende Kotlin-Kompilierungen mit den Namen main, deviceTest und hostTest. Die Quellsätze und Kompilierungen können im Build-Skript so konfiguriert werden:

// build.gradle.kts

kotlin {
    android {
        compilations.getByName("deviceTest") {
            kotlinOptions.languageVersion = "2.0"
        }
    }
}

Legacy-Plug-in

Mit dem Legacy-Plug-in konnten Sie Android-spezifische Abhängigkeiten im Abhängigkeitenblock auf oberster Ebene deklarieren, was in einem Multiplattform-Modul manchmal verwirrend sein konnte.

// build.gradle.kts

kotlin {
  androidTarget()
  //... other targets
}

// Dependencies for all source sets were often mixed in one block
dependencies {
  // Common dependencies
  commonMainImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")

  // Android-specific dependencies
  implementation("androidx.appcompat:appcompat:1.7.0")
  implementation("com.google.android.material:material:1.11.0")
}

4. Android-Ressourcen aktivieren

Die Unterstützung für Android-Ressourcen (res-Ordner) ist beim neuen Plug-in nicht standardmäßig aktiviert, um die Build-Leistung zu optimieren. Sie müssen die Einstellung aktivieren, um sie zu nutzen. Durch diese Änderung wird sichergestellt, dass Projekte, die keine Android-spezifischen Ressourcen erfordern, nicht durch den damit verbundenen Build-Overhead belastet werden.

Android-KMP

Sie müssen die Verarbeitung von Android-Ressourcen explizit aktivieren. Die Ressourcen sollten in src/androidMain/res platziert werden.

// build.gradle.kts

kotlin {
  android {
    // ...
    // Enable Android resource processing
    androidResources {
      enable = true
    }
  }
}

// Project Structure
// └── src
//     └── androidMain
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

Legacy-Plug-in

Die Ressourcenverarbeitung war standardmäßig aktiviert. Sie könnten sofort ein res-Verzeichnis in src/main hinzufügen und mit dem Hinzufügen von XML-Drawables, Werten usw. beginnen.

// build.gradle.kts

android {
    namespace = "com.example.library"
    compileSdk = 34
    // No extra configuration was needed to enable resources.
}

// Project Structure
// └── src
//     └── main
//         └── res
//             ├── values
//             │   └── strings.xml
//             └── drawable
//                 └── icon.xml

5. Host- und Gerätetests konfigurieren

Standardmäßig werden durch das neue Plug-in Android-Tests auf Hostseite (Unit-Tests) und auf Geräteseite (instrumentierte Tests) deaktiviert. Sie müssen die Erstellung der Test-Source-Sets und -Konfigurationen explizit aktivieren, während das Legacy-Plug-in sie automatisch erstellt hat.

Dieses Opt-in-Modell sorgt dafür, dass Ihr Projekt schlank bleibt und nur die Build-Logik und Source-Sets enthält, die Sie aktiv verwenden.

Android-KMP

Mit dem neuen Plug-in können Sie Tests im kotlin.android-Block aktivieren und konfigurieren. Dadurch wird die Einrichtung expliziter und es werden keine ungenutzten Testkomponenten erstellt. Das Source-Set androidUnitTest wird zu androidHostTest (das Testverzeichnis ändert sich von src/androidUnitTest zu src/androidHostTest) und androidInstrumentedTest wird zu androidDeviceTest (das Testverzeichnis ändert sich von src/androidInstrumentedTest zu src/androidDeviceTest).

// build.gradle.kts

kotlin {
  android {
    // ...

    // Opt-in to enable and configure host-side (unit) tests
    withHostTest {
      isIncludeAndroidResources = true
    }

    // Opt-in to enable and configure device-side (instrumented) tests
    withDeviceTest {
      instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
      execution = "HOST"
    }
  }
}

// Project Structure (After Opt-in)
// └── src
//     ├── androidHostTest
//     └── androidDeviceTest

Legacy-Plug-in

Mit dem com.android.library-Plug-in werden die Source-Sets androidUnitTest und androidInstrumentedTest standardmäßig erstellt. Sie konfigurieren ihr Verhalten im android-Block, in der Regel mit der testOptions-DSL.

// build.gradle.kts

android {
  defaultConfig {
    // Runner was configured in defaultConfig
    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
  }

  testOptions {
    // Configure unit tests (for the 'test' source set)
    unitTests.isIncludeAndroidResources = true

    // Configure device tests (for the 'androidTest' source set)
    execution = "HOST"
  }
}

// Project Structure (Defaults)
// └── src
//     ├── test
//     └── androidTest

6. Java-Quellkompilierung aktivieren

Wenn Ihre KMP-Bibliothek Java-Quellen für das Android-Ziel kompilieren muss, müssen Sie diese Funktion mit dem neuen Plug-in explizit aktivieren. Beachten Sie, dass dadurch die Kompilierung für Java-Dateien aktiviert wird, die sich direkt in Ihrem Projekt befinden, nicht für die Abhängigkeiten. Die Methode zum Festlegen der JVM-Zielversion des Java- und Kotlin-Compilers ändert sich ebenfalls.

Android-KMP

Sie müssen die Java-Kompilierung aktivieren, indem Sie withJava() aufrufen. Das JVM-Ziel wird jetzt direkt im kotlin { android {} }-Block konfiguriert, um eine einheitlichere Einrichtung zu ermöglichen. Wenn Sie hier jvmTarget festlegen, gilt dies sowohl für die Kotlin- als auch für die Java-Kompilierung für das Android-Ziel.

// build.gradle.kts

kotlin {
  android {
    //  Opt-in to enable Java source compilation
    withJava()
    // Configure the JVM target for both Kotlin and Java sources
    compilerOptions {
      jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8)
    }
  }
  // ...
}

// Project Structure:
// └── src
//     └── androidMain
//         ├── kotlin
//         │   └── com/example/MyKotlinClass.kt
//         └── java
//             └── com.example/MyJavaClass.java

Legacy-Plug-in

Die Java-Kompilierung war standardmäßig aktiviert. Das JVM-Ziel für Java- und Kotlin-Quellen wurde im Android-Block mit compileOptions festgelegt.

// build.gradle.kts

android {
  // ...
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
}

kotlin {
  androidTarget {
    compilations.all {
      kotlinOptions.jvmTarget = "1.8"
    }
  }
}

7. Mit androidComponents mit Build-Varianten interagieren

Die Erweiterung androidComponents ist weiterhin verfügbar, um programmatisch mit Build-Artefakten zu interagieren. Ein Großteil der Variant API bleibt zwar gleich, die neue AndroidKotlinMultiplatformVariant-Schnittstelle ist jedoch eingeschränkter, da das Plug-in nur eine einzige Variante erzeugt.

Daher sind Attribute, die sich auf Build-Typen und Produktvarianten beziehen, nicht mehr im Variantenobjekt verfügbar.

Android-KMP

Der onVariants-Block iteriert jetzt über eine einzelne Variante. Sie können weiterhin auf allgemeine Properties wie name und artifacts zugreifen, aber nicht auf Build-Typ-spezifische Properties.

// build.gradle.kts

androidComponents {
  onVariants { variant ->
      val artifacts = variant.artifacts
  }
}

Legacy-Plug-in

Mit mehreren Varianten können Sie auf Build-Typspezifische Properties zugreifen, um Aufgaben zu konfigurieren.

// build.gradle.kts

androidComponents {
  onVariants(selector().withBuildType("release")) { variant ->
    // ...
  }
}

8. Varianten von Android-Bibliotheksabhängigkeiten auswählen

Ihre KMP-Bibliothek erzeugt eine einzelne Variante für Android. Möglicherweise sind Sie jedoch von einer Android-Standardbibliothek (com.android.library) abhängig, die mehrere Varianten hat (z.B. free/paid Produktvarianten). Eine gängige Anforderung ist, festzulegen, wie Ihr Projekt eine Variante aus dieser Abhängigkeit auswählt.

Android-KMP

Das neue Plug-in zentralisiert und verdeutlicht diese Logik im Block kotlin.android.localDependencySelection. Dadurch wird viel deutlicher, welche Varianten externer Abhängigkeiten für Ihre KMP-Bibliothek mit einer einzelnen Variante ausgewählt werden.

// build.gradle.kts
kotlin {
  android {
    localDependencySelection {
      // For dependencies with multiple build types, select 'debug' first, and 'release' in case 'debug' is missing
      selectBuildTypeFrom.set(listOf("debug", "release"))

      // For dependencies with a 'type' flavor dimension...
      productFlavorDimension("type") {
        // ...select the 'typeone' flavor.
        selectFrom.set(listOf("typeone"))
      }
    }
  }
}

Legacy-Plug-in

Sie haben Strategien zur Auswahl von Abhängigkeiten in den buildTypes and productFlavors-Blöcken konfiguriert. Dazu wurde oft missingDimensionStrategy verwendet, um eine Standardvariante für eine Dimension bereitzustellen, die Ihre Bibliothek nicht hatte, oder matchingFallbacks innerhalb einer bestimmten Variante, um eine Suchreihenfolge zu definieren.

Weitere Informationen zur API-Nutzung finden Sie unter Abgleichsfehler beheben.

9. Abhängigkeiten für die Compose-Vorschau hinzufügen

In der Regel möchten wir bestimmte Bibliotheken auf unsere lokale Entwicklungsumgebung beschränken, um zu verhindern, dass interne Tools in das endgültige veröffentlichte Artefakt gelangen. Das ist mit dem neuen KMP-Android-Plug-in eine Herausforderung, da die Build-Typ-Architektur entfernt wird, die verwendet wird, um Entwicklungsabhängigkeiten vom Release-Code zu trennen.

Android-KMP

Wenn Sie eine Abhängigkeit nur für die lokale Entwicklung und Tests hinzufügen möchten, fügen Sie die Abhängigkeit direkt der Laufzeit-Klassenpfadkonfiguration (im dependencies-Block auf oberster Ebene) der Android-Hauptkompilierung hinzu. So ist die Abhängigkeit zur Laufzeit verfügbar (z. B. für Tools wie Compose Preview), ist aber nicht Teil des Kompilierungs-Klassenpfads oder der veröffentlichten API Ihrer Bibliothek.

// build.gradle.kts
dependencies {
  "androidRuntimeClasspath"(libs.androidx.compose.ui.tooling)
}

Legacy-Plug-in

Kotlin Multiplatform-Projekte, die das com.android.library-Plug-in für das Android-Ziel verwenden, sollten die debugImplementation-Konfiguration verwenden. Dadurch wird die Abhängigkeit auf den Debug-Build-Typ beschränkt und verhindert, dass sie in die Release-Variante der Bibliothek aufgenommen wird, die von den Nutzern verwendet wird.

// build.gradle.kts
dependencies {
  debugImplementation(libs.androidx.compose.ui.tooling)
}

10. JVM-Ziel für das KMP-Android-Ziel konfigurieren

Das KMP-Android-Plug-in legt das JVM-Ziel mit android.compilerOptions.jvmTarget fest, was sowohl für Java als auch für Kotlin gilt. Dadurch wird die Konfiguration im Vergleich zu den separaten compileOptions- und kotlinOptions-Blöcken in reinen Android-Projekten vereinfacht.

Android-KMP

Wenn Sie mit einem Kotlin Multiplatform-Projekt (KMP) arbeiten, das ein Android-Ziel enthält, haben Sie mehrere Möglichkeiten, die JVM-Zielversion für den Kotlin- und den Java-Compiler zu konfigurieren. Es ist wichtig, den Umfang und die Hierarchie dieser Konfigurationen zu verstehen, um die Bytecode-Kompatibilität Ihres Projekts zu verwalten.

Hier sind die drei wichtigsten Möglichkeiten, das JVM-Ziel festzulegen, sortiert von der niedrigsten zur höchsten Priorität. JVM-Zielwerte mit höherer Priorität gelten für eine kleinere Teilmenge Ihrer konfigurierten Ziele und überschreiben Werte mit niedrigerer Priorität. Das bedeutet, dass Sie für verschiedene Ziele und Kompilierungen innerhalb von Zielen in Ihrem Projekt unterschiedliche JVM-Versionen festlegen können.

Kotlin-Toolchain verwenden (niedrigste Priorität)

Die allgemeinste Methode zum Festlegen des JVM-Ziels besteht darin, die Toolchain im Block kotlin Ihrer build.gradle.kts-Datei anzugeben. Bei diesem Ansatz wird das Ziel für Kotlin- und Java-Kompilierungsaufgaben für alle JVM-basierten Ziele in Ihrem Projekt festgelegt, einschließlich Android.

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

Mit dieser Konfiguration werden sowohl kotlinc als auch javac auf JVM 21 ausgerichtet. So können Sie eine einheitliche Grundlage für Ihr gesamtes Projekt schaffen.

Android-Compileroptionen auf Zielebene verwenden (mittlere Priorität)

Sie können das JVM-Ziel speziell für das Android-KMP-Ziel im android-Block angeben. Diese Einstellung überschreibt die projektweite jvmToolchain-Konfiguration und gilt für alle Android-Kompilierungen.

// build.gradle.kts
kotlin {
    android {
        compilerOptions {
            jvmTarget.set(JvmTarget.JVM_11)
        }
    }
}

In diesem Fall wird der Kotlin- und Java-Code des Android-Ziels für die JVM 11 kompiliert, auch wenn ein jvmToolchain auf eine andere Version festgelegt ist.

Compileroptionen auf Kompilierungsebene verwenden (höchste Priorität)

Für eine möglichst detaillierte Steuerung können Sie Compiler-Optionen pro Kompilierung konfigurieren (z. B. nur für androidMain oder androidHostTest). Dies ist nützlich, wenn eine bestimmte Kompilierung auf eine andere JVM-Version abzielen muss. Diese Einstellung überschreibt sowohl die Kotlin-Toolchain als auch die Optionen für die Android-Zielebene.

// build.gradle.kts
kotlin {
    android {
        compilations.all {
            compileTaskProvider.configure {
                compilerOptions.jvmTarget.set(JvmTarget.JVM_11)
            }
        }
    }
}

Diese Konfiguration sorgt dafür, dass alle Kompilierungen innerhalb des Android-Ziels JVM 11 verwenden, und ermöglicht eine detaillierte Steuerung.

Legacy-Plug-in

In einem KMP-Projekt, das das Standard-Android-Bibliotheks-Plug-in (com.android.library) verwendet, unterscheidet sich die Konfiguration geringfügig von der Verwendung des KMP-Android-Plug-ins, ist aber konzeptionell ähnlich.

Kotlin-Toolchain verwenden

Die Methode kotlin.jvmToolchain() funktioniert genauso und legt sourceCompatibility und targetCompatibility für Java und jvmTarget für Kotlin fest. Wir empfehlen, diesen Ansatz zu verwenden.

// build.gradle.kts
kotlin {
    jvmToolchain(21)
}

compileOptions und kotlinOptions

Wenn Sie die Kotlin-Toolchain nicht verwenden, müssen Sie die JVM-Ziele mit separaten Blöcken für Java und Kotlin konfigurieren.

// build.gradle.kts
android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }

    kotlinOptions {
        jvmTarget = "11"
    }
}

11. Regeln für die Aufbewahrung von Nutzerdaten veröffentlichen

Wenn Ihre KMP-Bibliothek Consumer-Keep-Regeln (z. B. ProGuard-Regeln für R8) für ihre Nutzer bereitstellen muss, müssen Sie die Veröffentlichung mit dem neuen Plug-in explizit aktivieren. Bisher wurden von Nutzern festgelegte Behaltensregeln standardmäßig veröffentlicht, sofern sie angegeben wurden.

Android-KMP

Mit dem neuen Plug-in müssen Sie optimization.consumerKeepRules.publish = true festlegen und Regeldateien im Block consumerKeepRules angeben, um Consumer-Keep-Regeln zu veröffentlichen.

// build.gradle.kts
kotlin {
  android {
    optimization {
      consumerKeepRules.apply {
        publish = true
        file("consumer-proguard-rules.pro")
      }
    }
  }
}

Legacy-Plug-in

Bei com.android.library werden alle Regeldateien, die mit consumerProguardFiles in android.defaultConfig angegeben sind, standardmäßig in den Artefakten der Bibliothek veröffentlicht.

// build.gradle.kts
android {
  defaultConfig {
    consumerProguardFiles("consumer-proguard-rules.pro")
  }
}

12. Bibliothek in Maven veröffentlichen

Wenn Sie Ihre KMP-Bibliothek in Maven veröffentlichen möchten, damit sie von anderen Projekten verwendet werden kann, hängt der Vorgang davon ab, ob Sie das neue Android-KMP-Plug-in oder das alte Plug-in verwenden.

Android-KMP

Das com.android.kotlin.multiplatform.library-Plug-in ist in die standardmäßigen Veröffentlichungsmechanismen von Kotlin Multiplatform eingebunden. Über den standardmäßigen Veröffentlichungsprozess für KMP-Bibliotheken hinaus sind keine Android-spezifischen Schritte erforderlich.

Folgen Sie der offiziellen Dokumentation von JetBrains, um Ihre Bibliothek zu veröffentlichen: Veröffentlichung für eine Multiplattform-Bibliothek einrichten.

Legacy-Plug-in

Wenn Sie com.android.library für das Android-Ziel in einem KMP-Projekt verwenden, müssen Sie der Standardanleitung zum Veröffentlichen von Android-Bibliotheken folgen, um das Android-spezifische Artefakt (.aar) vorzubereiten und zu veröffentlichen.

Eine ausführliche Anleitung finden Sie unter Bibliothek für den Release vorbereiten.

Plugin API-Referenz

Das neue Plug-in hat eine andere API-Oberfläche als com.android.library. Detaillierte Informationen zur neuen DSL und zu den neuen Schnittstellen finden Sie in den API-Referenzen:

Bekannte Probleme mit dem Android-KMP-Bibliotheks-Plug-in

Dies sind die bekannten Probleme, die beim Anwenden des neuen com.android.kotlin.multiplatform.library-Plug-ins auftreten können: