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

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

Die Verwendung des Plug-ins com.android.library für die KMP-Entwicklung hängt von Android Gradle-Plug-in-APIs ab, die veraltet sind 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 Hä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 Migration Guide.

Wenn Sie Hilfe bei der Migration zu AGP 9.0 oder höher benötigen, können Sie den Agent-Skill verwenden, der von JetBrains für KMP-Apps erstellt wurde. 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-Plug-in com.android.library:

• Architektur mit einer einzigen Variante:Das Plug-in verwendet eine einzige Variante und unterstützt keine Produktvarianten und Build-Typen mehr. Dadurch wird die Konfiguration vereinfacht und die Build-Leistung verbessert.

• Für KMP optimiert:Das Plug-in wurde für KMP-Bibliotheken entwickelt und konzentriert sich auf gemeinsamen Kotlin-Code und Interoperabilität. Es unterstützt keine Android-spezifischen nativen Builds, AIDL und RenderScript.

• Tests standardmäßig deaktiviert: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 erfolgt mit einem android-Block in der Gradle-KMP-DSL, wodurch eine einheitliche KMP-Projektstruktur beibehalten wird. Es gibt keinen android-Erweiterungsblock auf oberster Ebene.

• Aktivierung der Java-Kompilierung erforderlich:Die Java-Kompilierung ist standardmäßig deaktiviert. Verwenden Sie withJava() im android-Block, 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 folgende 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:Es bietet eine bessere Codevervollständigung, Navigation, Fehlerbehebung und insgesamt eine bessere Entwicklererfahrung bei der Arbeit mit KMP-Android-Bibliotheken.

• Vereinfachte Projektkonfiguration:Das Plug-in vereinfacht die Konfiguration für KMP-Projekte, indem Android-spezifische Komplexitäten wie Build-Varianten entfernt werden. Dies führt zu übersichtlicheren und besser wartbaren Build-Dateien. Bisher konnte die Verwendung des Plug-ins com.android.library in KMP-Projekten zu verwirrenden Source-Set-Namen führen, z. B. androidAndroidTest. Diese Benennungskonvention 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 Plug-in com.android.library fehlen im Plug-in com.android.kotlin.multiplatform.library 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, wodurch die Konfiguration vereinfacht und die Build-Leistung verbessert wird.

  Wenn Sie Build-Varianten benötigen, empfehlen wir, ein separates eigenständiges Android-Bibliotheksmodul mit dem Plug-in com.android.library 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 Ansichtbindung

  Dies sind Android-spezifische UI-Framework-Funktionen, die eng mit dem Android-Ansichtssystem und XML-Layouts verknüpft sind. Im neuen Android-KMP-Bibliotheks-Plug-in empfehlen wir, die UI mit einem plattformübergreifenden Framework wie Compose Multiplatform zu verarbeiten. Datenbindung und Ansichtbindung gelten als Implementierungsdetails einer endgültigen Android-App und nicht als freigebare Bibliothek.

• Unterstützung für native Builds

  Das neue Plug-in konzentriert sich auf die Erstellung einer Standard-AAR-Datei für das Android-Ziel. Die Integration von nativem Code in Kotlin Multiplatform wird direkt von den eigenen nativen Zielen von KMP (z. B. androidNativeArm64 und androidNativeX86) und den C-Interop-Funktionen verarbeitet. Wenn Sie nativen C/C++-Code einfügen müssen, sollten Sie ihn als Teil eines gemeinsamen oder nativen Quellsatzes definieren und die C-Interop im kotlin-Block konfigurieren, anstatt den Android-spezifischen externalNativeBuild-Mechanismus zu verwenden.

  Wenn Sie alternativ Unterstützung für native Builds über externalNativeBuild benötigen, empfehlen wir, ein separates eigenständiges com.android.library-Modul zu erstellen, in dem 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 zum 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 Unterstützung für Build-Typen und Produktvarianten bietet, ist diese Funktion nicht implementiert. Alternativ empfehlen wir, das Plug-in BuildKonfig oder ähnliche Community-Lösungen zu verwenden, um Metadaten für alle Ziele zu generieren.

Vorbereitung

Damit Sie das Plug-in com.android.kotlin.multiplatform.library verwenden können, muss Ihr Projekt mit den folgenden Mindestversionen oder höher 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 (in der Regel 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.2.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. Plug-in-Deklaration in der Build-Datei des Stammverzeichnisses anwenden Öffnen Sie die Datei build.gradle.kts im Stammverzeichnis Ihres Projekts. Fügen Sie die Plug-in-Aliasse mit apply false zum Block plugins hinzu. Dadurch sind die Plug-in-Aliasse für alle Unterprojekte verfügbar, ohne dass die Plug-in-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. Plug-in in der Build-Datei eines KMP-Bibliotheksmoduls anwenden Ö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.

Von Legacy-Plug-in migrieren

In dieser Anleitung wird beschrieben, wie Sie vom Legacy-Plug-in com.android.library zum Plug-in com.android.kotlin.multiplatform.library migrieren.

1. Quellen verschieben

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

2. Abhängigkeiten deklarieren

Eine häufige Aufgabe ist das Deklarieren von Abhängigkeiten für Android-spezifische Quellsätze. Mit dem neuen Plug-in müssen diese explizit im Block sourceSets platziert werden, anders als beim zuvor verwendeten allgemeinen Block dependencies.

// 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")
        }
    }
}

// build.gradle.kts

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

// 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")
}

3. Android-Ressourcen aktivieren

Die Unterstützung für Android-Ressourcen (res-Ordner) ist im neuen Plug-in standardmäßig nicht aktiviert, um die Build-Leistung zu optimieren. Sie müssen sie aktivieren, um sie zu verwenden. Diese Änderung trägt dazu bei, dass Projekte, für die keine Android-spezifischen Ressourcen erforderlich sind, nicht durch den damit verbundenen Build-Aufwand belastet werden.

// build.gradle.kts

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

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

// 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

4. Host- und Gerätetests konfigurieren

Eine wichtige Änderung im neuen Plug-in ist, dass Android-Host-seitige (Unit-) und geräteseitige (Instrumentierungs-)Tests standardmäßig deaktiviert sind. Sie müssen die Testquellsätze und ‑konfigurationen explizit aktivieren, während sie mit dem alten Plug-in automatisch erstellt wurden.

Dieses Aktivierungsmodell trägt dazu bei, dass Ihr Projekt schlank bleibt und nur die Build-Logik und Quellsätze enthält, die Sie aktiv verwenden.

// 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

// 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

5. 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. Auch die Methode zum Festlegen der JVM-Zielversion des Java- und Kotlin-Compilers ändert sich.

// 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

// build.gradle.kts

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

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

6. Mit Build-Varianten über androidComponents interagieren

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

Daher sind Eigenschaften im Zusammenhang mit Build-Typen und Produktvarianten nicht mehr für das Variantenobjekt verfügbar.

// build.gradle.kts

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

// build.gradle.kts

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

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

Ihre KMP-Bibliothek erzeugt eine einzige Variante für Android. Möglicherweise sind Sie jedoch von einer Standard-Android-Bibliothek (com.android.library) abhängig, die mehrere Varianten hat (z.B. free/paid-Produktvarianten). Es ist häufig erforderlich, zu steuern, wie Ihr Projekt eine Variante aus dieser Abhängigkeit auswählt.

// 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"))
      }
    }
  }
}

8. Abhängigkeiten für die Compose-Vorschau

Normalerweise möchten wir, dass bestimmte Bibliotheken auf unsere lokale Entwicklungsumgebung beschränkt sind, damit interne Tools nicht in das endgültige veröffentlichte Artefakt gelangen. Das ist mit dem neuen KMP-Android-Plug-in eine Herausforderung, da es die Architektur mit Build-Typen entfernt, die verwendet wurde, um Entwicklungsabhängigkeiten vom Release-Code zu trennen.

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

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

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

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

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

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

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

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

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

    kotlinOptions {
        jvmTarget = "11"
    }
}

10. Consumer-Keep-Regeln 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 im neuen Plug-in explizit aktivieren. Bisher wurden Consumer-Keep-Regeln standardmäßig veröffentlicht, wenn sie angegeben wurden.

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

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

11. Bibliothek in Maven veröffentlichen

Wenn Sie Ihre KMP-Bibliothek in Maven veröffentlichen möchten, damit sie von anderen Projekten verwendet werden kann, unterscheidet sich der Prozess je nachdem, ob Sie das neue Android-KMP-Plug-in oder das Legacy-Plug-in verwenden.

Plug-in-API-Referenz

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

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant

Bekannte Probleme im Android-KMP-Bibliotheks-Plug-in

Die folgenden bekannten Probleme können auftreten, wenn Sie das neue Plug-in com.android.kotlin.multiplatform.library anwenden:

• Compose-Vorschau schlägt bei Verwendung des neuen Android-KMP-Plug-ins fehl

  • Behoben in Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 und Android Gradle Plugin 9.0.0-alpha13

• NullPointerException in Compose Multiplatform-Vorschauen mit dem Plug-in com.android.kotlin.multiplatform.library

  • Behoben in Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 und Android Gradle Plugin 9.0.0-alpha13

• KMP speichert die gemeinsame Auflösung von Kompilierungsabhängigkeiten im Konfigurationscache, was zu einem Fehler bei der Deserialisierung führt (nur Android)

  • Behoben in Kotlin Gradle Plugin 2.3.0-Beta2

• Instrumentiertes sourceSetTree für das androidLibrary-Ziel unterstützen

  • Behoben in Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 und Android Gradle Plugin 9.0.0-alpha13