Konfigurowanie wtyczki Android Gradle Library Plugin dla KMP

Wtyczka Gradle com.android.kotlin.multiplatform.library to oficjalnie obsługiwane narzędzie do dodawania platformy Android do modułu biblioteki Kotlin Multiplatform (KMP). Upraszcza konfigurację projektu, zwiększa wydajność kompilacji i zapewnia lepszą integrację z Androidem Studio.

Korzystanie z com.android.library wtyczki do tworzenia aplikacji na wiele platform zależy od interfejsów API wtyczki Androida do obsługi Gradle, które są wycofane i wymagają zgody użytkownika w wtyczce Androida do obsługi Gradle w wersji 9.0 i nowszych (IV kwartał 2025 r.). Te interfejsy API zostaną usunięte w wtyczce Androida do obsługi Gradle w wersji 10.0 (w drugiej połowie 2026 r.).

Aby zastosować tę wtyczkę, zapoznaj się z sekcją Stosowanie wtyczki Android-KMP. Jeśli musisz przeprowadzić migrację ze starszych interfejsów API, zapoznaj się z przewodnikiem po migracji.

Najważniejsze funkcje i różnice

Wtyczka Android-KMP jest przeznaczona specjalnie do projektów KMP i różni się od standardowej wtyczki com.android.library w kilku kluczowych aspektach:

• Architektura pojedynczego wariantu: wtyczka używa pojedynczego wariantu, co eliminuje obsługę wersji produktu i typów kompilacji, upraszcza konfigurację i zwiększa wydajność kompilacji.

• Zoptymalizowana pod kątem KMP: wtyczka jest przeznaczona do bibliotek KMP i skupia się na udostępnianiu kodu Kotlin oraz interoperacyjności, pomijając obsługę natywnych kompilacji specyficznych dla Androida, AIDL i RenderScript.

• Testy domyślnie wyłączone: zarówno testy jednostkowe, jak i testy na urządzeniu (instrumentacyjne) są domyślnie wyłączone, aby zwiększyć szybkość kompilacji. W razie potrzeby możesz je włączyć.

• Brak rozszerzenia Androida najwyższego poziomu: konfiguracja jest obsługiwana za pomocą bloku androidLibrary w języku DSL Gradle KMP, co zapewnia spójną strukturę projektu KMP. Nie ma bloku rozszerzenia android najwyższego poziomu.

• Kompilacja Javy z wyrażeniem zgody: kompilacja Javy jest domyślnie wyłączona. Użyj withJava() w bloku androidLibrary, aby włączyć tę funkcję. Skraca to czas kompilacji, gdy kompilacja w Javie nie jest potrzebna.

Zalety wtyczki biblioteki Android-KMP

Wtyczka Android-KMP zapewnia te korzyści w przypadku projektów KMP:

• Lepsza wydajność i stabilność kompilacji: zaprojektowano ją z myślą o optymalizacji szybkości kompilacji i zwiększeniu stabilności w projektach KMP. Skupienie się na przepływach pracy KMP przyczynia się do bardziej wydajnego i niezawodnego procesu kompilacji.

• Ulepszona integracja z IDE: zapewnia lepsze uzupełnianie kodu, nawigację, debugowanie i ogólne wrażenia deweloperskie podczas pracy z bibliotekami KMP na Androida.

• Uproszczona konfiguracja projektu: wtyczka upraszcza konfigurację projektów KMP, usuwając złożoności związane z Androidem, takie jak warianty kompilacji. Dzięki temu pliki kompilacji są bardziej przejrzyste i łatwiejsze w utrzymaniu. Wcześniej używanie wtyczki com.android.library w projekcie KMP mogło powodować tworzenie mylących nazw zestawów źródeł, np. androidAndroidTest. Ta konwencja nazewnictwa była mniej intuicyjna dla programistów znających standardowe struktury projektów KMP.

Wymagania wstępne

Aby używać wtyczki com.android.kotlin.multiplatform.library, projekt musi być skonfigurowany z tymi minimalnymi wersjami lub nowszymi:

• Wtyczka Androida do obsługi Gradle (AGP): 8.10.0
• Wtyczka Kotlin Gradle Plugin (KGP): 2.0.0

Stosowanie wtyczki Android-KMP do istniejącego modułu

Aby zastosować wtyczkę Android-KMP do istniejącego modułu biblioteki KMP, wykonaj te czynności:

1. Zadeklaruj wtyczki w katalogu wersji. Otwórz plik TOML katalogu wersji (zwykle gradle/libs.versions.toml) i dodaj sekcję definicji wtyczek:

   # To check the version number of the latest Kotlin release, go to
   # https://kotlinlang.org/docs/releases.html
   
   [versions]
   androidGradlePlugin = "8.13.2"
   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. Zastosuj deklarację wtyczki w głównym pliku kompilacji. Otwórz plik build.gradle.kts znajdujący się w katalogu głównym projektu. Dodaj aliasy wtyczek do bloku plugins za pomocą apply false. Dzięki temu aliasy wtyczek są dostępne we wszystkich podprojektach bez stosowania logiki wtyczki do samego projektu głównego.

   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. Zastosuj wtyczkę w pliku kompilacji modułu biblioteki KMP. Otwórz plik build.gradle.kts w module biblioteki KMP i zastosuj wtyczkę u góry pliku w bloku plugins:

   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. Skonfiguruj platformę docelową KMP na Androida. Skonfiguruj blok Kotlin Multiplatform (kotlin), aby zdefiniować platformę docelową Androida. W bloku kotlin określ docelową platformę Androida za pomocą tego kodu: androidLibrary

   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. Zastosuj zmiany. Po zastosowaniu wtyczki i skonfigurowaniu bloku kotlin zsynchronizuj projekt Gradle, aby zastosować zmiany.

Migracja ze starszej wtyczki

Ten przewodnik pomoże Ci przeprowadzić migrację ze starszej wtyczki com.android.library do wtyczki com.android.kotlin.multiplatform.library.

1. Deklarowanie zależności

Częstym zadaniem jest deklarowanie zależności dla zestawów źródeł specyficznych dla Androida. Nowa wtyczka wymaga, aby były one wyraźnie umieszczone w bloku sourceSets, w przeciwieństwie do ogólnego bloku dependencies używanego wcześniej.

// 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. Włączanie zasobów Androida

Obsługa zasobów Androida (foldery res) nie jest domyślnie włączona w nowej wtyczce, aby zoptymalizować wydajność kompilacji. Aby z nich korzystać, musisz wyrazić na to zgodę. Ta zmiana pomaga zapewnić, że projekty, które nie wymagają zasobów specyficznych dla Androida, nie będą obciążone związanym z tym narzutem na kompilację.

// 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. Konfigurowanie testów hosta i urządzenia

Istotną zmianą w nowej wtyczce jest to, że testy po stronie hosta (jednostkowe) i po stronie urządzenia (instrumentalne) na Androidzie są domyślnie wyłączone. Aby utworzyć zestawy i konfiguracje źródeł testowych, musisz wyraźnie wyrazić na to zgodę. Stara wtyczka tworzyła je automatycznie.

Ten model oparty na zgodzie użytkownika pomaga sprawdzić, czy projekt jest uproszczony i zawiera tylko logikę kompilacji oraz zestawy źródeł, których aktywnie używasz.

// 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. Włączanie kompilacji kodu źródłowego w Javie

Jeśli biblioteka KMP musi kompilować źródła Java na potrzeby platformy Android, musisz wyraźnie włączyć tę funkcję za pomocą nowego wtyczki. Pamiętaj, że ta opcja umożliwia kompilację plików Java znajdujących się bezpośrednio w projekcie, a nie w jego zależnościach. Zmienia się też metoda ustawiania wersji JVM kompilatora Java i Kotlin.

// 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. Interakcja z wariantami kompilacji za pomocą androidComponents

Rozszerzenie androidComponents jest nadal dostępne do programowego korzystania z artefaktów kompilacji. Chociaż większość interfejsu Variant API pozostaje bez zmian, nowy interfejs AndroidKotlinMultiplatformVariant jest bardziej ograniczony, ponieważ wtyczka generuje tylko jeden wariant.

W związku z tym właściwości związane z typami kompilacji i wersjami produktu nie są już dostępne w obiekcie wariantu.

// build.gradle.kts

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

// build.gradle.kts

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

6. Wybieranie wariantów zależności biblioteki Androida

Biblioteka KMP generuje jeden wariant na Androida. Możesz jednak korzystać ze standardowej biblioteki Androida (com.android.library), która ma wiele wariantów (np. free/paid warianty usługi). Kontrolowanie sposobu, w jaki projekt wybiera wariant z tej zależności, jest powszechnym wymaganiem.

// 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. Zależności podglądu w widoku tworzenia

Zwykle chcemy, aby określone biblioteki były ograniczone do naszego lokalnego środowiska programistycznego, aby zapobiec przedostawaniu się narzędzi wewnętrznych do ostatecznego opublikowanego artefaktu. W przypadku nowej wtyczki KMP Android jest to problematyczne, ponieważ usuwa ona architekturę typu kompilacji używaną do oddzielania zależności deweloperskich od kodu wersji.

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

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

8. Konfigurowanie platformy docelowej JVM dla platformy docelowej KMP Android

Wtyczka KMP Androida ustawia docelową platformę JVM za pomocą parametru androidLibrary.compilerOptions.jvmTarget, który ma zastosowanie zarówno do Javy, jak i do Kotlina, co upraszcza konfigurację w porównaniu z osobnymi blokami compileOptions i kotlinOptions w projektach czysto androidowych.

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

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

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

Dokumentacja API wtyczek

Nowa wtyczka ma inny interfejs API niż com.android.library. Szczegółowe informacje o nowym języku DSL i interfejsach znajdziesz w dokumentacji interfejsu API:

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant

Znane problemy we wtyczce biblioteki Android-KMP

Oto znane problemy, które mogą wystąpić po zastosowaniu nowego wtyczki com.android.kotlin.multiplatform.library:

• Podgląd kompozycji nie działa podczas korzystania z nowej wtyczki android-KMP

  • Poprawiono w wersjach Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 i Android Gradle Plugin 9.0.0-alpha13

• NullPointerException w podglądach Compose Multiplatform z wtyczką com.android.kotlin.multiplatform.library

  • Poprawiono w wersjach Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 i Android Gradle Plugin 9.0.0-alpha13

• KMP przechowuje w pamięci podręcznej konfiguracji wspólne rozwiązanie zależności kompilacji, co prowadzi do błędu podczas deserializacji (tylko Android)

  • Poprawiono w wersji Kotlin Gradle Plugin 2.3.0-Beta2

• Obsługa instrumentowanego elementu sourceSetTree w przypadku elementu docelowego androidLibrary

  • Poprawiono w wersjach Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 i Android Gradle Plugin 9.0.0-alpha13

Nieobsługiwane funkcje

W porównaniu z integracją KMP z wtyczką com.android.library we wtyczce com.android.kotlin.multiplatform.library brakuje tych funkcji:

• Wiązanie danych i wiązanie widoków

  Są to funkcje platformy interfejsu Androida ściśle powiązane z systemem widoków Androida i układami XML. W nowej wtyczce biblioteki Android-KMP zalecamy obsługę interfejsu za pomocą platformy wieloplatformowej, takiej jak Compose Multiplatform. Powiązanie danych i powiązanie widoków są uważane za szczegóły implementacji końcowej aplikacji na Androida, a nie za bibliotekę, którą można udostępniać.

• Obsługa kompilacji natywnych

  Nowa wtyczka koncentruje się na tworzeniu standardowego pliku AAR dla platformy Android. Integracja kodu natywnego w Kotlin Multiplatform jest obsługiwana bezpośrednio przez własne natywne platformy docelowe KMP (np. androidNativeArm64 i androidNativeX86) oraz możliwości współdziałania z językiem C. Jeśli musisz uwzględnić kod natywny w języku C/C++, zdefiniuj go w ramach wspólnego lub natywnego zestawu źródeł i skonfiguruj współdziałanie z językiem C w bloku kotlin, zamiast używać mechanizmu externalNativeBuild specyficznego dla Androida.

  Jeśli potrzebujesz obsługi kompilacji natywnych, zalecamy utworzenie osobnego, samodzielnego modułu com.android.library, w którym możesz zintegrować kod natywny i używać samodzielnej biblioteki w projekcie biblioteki Kotlin Multiplatform.

• BuildConfig zajęcia

  Funkcja BuildConfig jest najbardziej przydatna w środowiskach z wieloma wariantami. Nowa wtyczka biblioteki Kotlin Multiplatform nie jest zależna od wariantów i nie obsługuje typów kompilacji ani wersji produktu, więc ta funkcja nie jest zaimplementowana. Zamiast tego zalecamy używanie BuildKonfigwtyczki lub podobnych rozwiązań społecznościowych do generowania metadanych dla wszystkich miejsc docelowych.