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

Das com.android.kotlin.multiplatform.library-Gradle-Plug-in ist das offiziell unterstützte Tool zum Hinzufügen eines Android-Ziels zu einem Bibliotheksmodul für Kotlin Multiplatform (KMP). Sie vereinfacht die Projektkonfiguration, verbessert die Build-Leistung und bietet eine bessere Integration mit 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 sind und für die eine Einwilligung erforderlich ist, wenn das Android-Gradle-Plug-in 9.0 oder höher verwendet wird (4. Quartal 2025). Diese APIs werden voraussichtlich im Android-Gradle-Plug-in 10.0 entfernt (zweite Hälfte des Jahres 2026).

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.

Wichtige Funktionen und Unterschiede

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

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

• Für KMP optimiert:Das Plug-in ist für KMP-Bibliotheken konzipiert und konzentriert sich auf gemeinsamen Kotlin-Code und Interoperabilität. Es bietet keine Unterstützung für Android-spezifische native Builds, AIDL und RenderScript.

• 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 erfolgt mit einem androidLibrary-Block in der Gradle KMP-DSL, wodurch eine konsistente KMP-Projektstruktur beibehalten wird. Es gibt keinen Block für die Erweiterung android auf oberster Ebene.

• Java-Kompilierung mit Opt-in:Die Java-Kompilierung ist standardmäßig deaktiviert. Verwenden Sie withJava() im androidLibrary-Block, um die Funktion zu aktivieren. Dadurch werden die Build-Zeiten verkürzt, 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:Bessere Vervollständigung von Code, Navigation, Fehlerbehebung und allgemeine Entwicklungsumgebung bei der Arbeit mit KMP-Android-Bibliotheken.

• Vereinfachte Projektkonfiguration:Das Plug-in vereinfacht die Konfiguration für KMP-Projekte, indem es Android-spezifische Komplexitäten wie Build-Varianten entfernt. Das führt zu übersichtlicheren und besser wartbaren Build-Dateien. Bisher konnten durch die Verwendung des com.android.library-Plug-ins in KMP-Projekten verwirrende Quellsetnamen wie androidAndroidTest entstehen. Diese Namenskonvention war für Entwickler, die mit den Standardprojektstrukturen von KMP vertraut sind, weniger intuitiv.

Bekannte Probleme im 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:

• Compose-Vorschau schlägt fehl, wenn das neue Android-KMP-Plugin verwendet wird

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

• KMP stores common compilation dependency resolution in Configuration cache leading to error when deserializing (Android only)

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

Voraussetzungen

Damit Sie das com.android.kotlin.multiplatform.library-Plug-in 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 (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 = "8.13.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 Stamm-Build-Datei anwenden Öffnen Sie die Datei build.gradle.kts im Stammverzeichnis Ihres Projekts. Fügen Sie die Plug-in-Aliasse dem plugins-Block mit apply false hinzu. Dadurch sind die Plug-in-Aliase 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. Wenden Sie das Plug-in in der Build-Datei eines KMP-Bibliotheksmoduls 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 androidLibrary an:

   Kotlin

   kotlin {
      androidLibrary {
          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 {
      androidLibrary {
          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 kotlin-Block konfiguriert haben, synchronisieren Sie Ihr Gradle-Projekt, um die Änderungen zu übernehmen.

Vom alten Plug-in migrieren

In diesem Leitfaden erfahren Sie, wie Sie vom alten com.android.library-Plug-in zum com.android.kotlin.multiplatform.library-Plug-in migrieren.

1. Abhängigkeiten deklarieren

Eine häufige Aufgabe ist das Deklarieren von Abhängigkeiten für Android-spezifische Quellsets. Beim neuen Plug‑in müssen diese explizit im sourceSets-Block platziert werden, im Gegensatz zum allgemeinen dependencies-Block, der zuvor verwendet wurde.

// build.gradle.kts

kotlin {
    androidLibrary {}
    //... 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 {
    androidLibrary {
        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")
}

2. Android-Ressourcen aktivieren

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

// build.gradle.kts

kotlin {
  androidLibrary {
    // ...
    // 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

3. Host- und Gerätetests konfigurieren

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

Dieses Opt-in-Modell trägt dazu bei, dass Ihr Projekt schlank bleibt und nur die Build-Logik und Quellsets enthält, die Sie aktiv verwenden.

// build.gradle.kts

kotlin {
  androidLibrary {
    // ...

    // 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 = "ANDROIDX_TEST_ORCHESTRATOR"
    }
  }
}

// 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 = "ANDROIDX_TEST_ORCHESTRATOR"
  }
}

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

4. Java-Quellcode-Kompilierung aktivieren

Wenn für das Android-Ziel Ihrer KMP-Bibliothek Java-Quellen kompiliert werden müssen, müssen Sie diese Funktion mit dem neuen Plug-in explizit aktivieren. Dadurch wird die Kompilierung für Java-Dateien aktiviert, die sich direkt in Ihrem Projekt befinden, nicht für die zugehörigen Abhängigkeiten. Auch die Methode zum Festlegen der JVM-Zielversion des Java- und Kotlin-Compilers ändert sich.

// build.gradle.kts

kotlin {
  androidLibrary {
    //  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"
    }
  }
}

5. Mit Build-Varianten über androidComponents interagieren

Die androidComponents-Erweiterung ist weiterhin verfügbar, um programmgesteuert mit Build-Artefakten zu interagieren. Die Variant API ist größtenteils unverändert, die neue AndroidKotlinMultiplatformVariant-Schnittstelle ist jedoch eingeschränkter, da das Plug-in nur eine Variante erzeugt.

Daher sind Properties, die sich auf Build-Typen und Produktvarianten beziehen, nicht mehr für das Variant-Objekt verfügbar.

// build.gradle.kts

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

// build.gradle.kts

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

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

Ihre KMP-Bibliothek erzeugt eine einzelne Variante für Android. Möglicherweise sind Sie jedoch von einer Standard-Android-Bibliothek (com.android.library) mit mehreren Varianten abhängig, z.B. free/paid Produktvarianten). Es ist häufig erforderlich, zu steuern, wie in Ihrem Projekt eine Variante aus dieser Abhängigkeit ausgewählt wird.

// build.gradle.kts
kotlin {
  androidLibrary {
    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"))
      }
    }
  }
}

7. Abhängigkeiten für die Erstellung der Vorschau

In der Regel möchten wir, dass bestimmte Bibliotheken auf unsere lokale Entwicklungsumgebung beschränkt sind, damit keine internen Tools in das endgültige veröffentlichte Artefakt gelangen. Das neue KMP-Android-Plugin stellt hier eine Herausforderung dar, da es die Build-Typ-Architektur entfernt, die zum Trennen von Entwicklungsabhängigkeiten vom Release-Code verwendet wird.

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

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

Plugin 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