Configurare il plug-in Android Gradle Library per KMP

Il plug-in Gradle com.android.kotlin.multiplatform.library è lo strumento ufficialmente supportato per aggiungere un target Android a un modulo della libreria Kotlin Multiplatform (KMP). Semplifica la configurazione del progetto, migliora le prestazioni della build e offre una migliore integrazione con Android Studio.

L'utilizzo del plug-in com.android.library per lo sviluppo KMP dipende dalle API del plug-in Android per Gradle deprecate e che richiedono l'attivazione nel plug-in Android per Gradle 9.0 e versioni successive (quarto trimestre del 2025). Queste API dovrebbero essere rimosse nel plug-in Android per Gradle 10.0 (seconda metà del 2026).

Per applicare questo plug-in, consulta la sezione Applica il plug-in Android-KMP. Se devi eseguire la migrazione dalle API legacy, consulta la guida alla migrazione.

Funzionalità e differenze principali

Il plug-in Android-KMP è progettato appositamente per i progetti KMP e si differenzia dal plug-in com.android.library standard per diversi aspetti chiave:

• Architettura a variante singola: il plug-in utilizza una singola variante, rimuovendo il supporto per le versioni prodotto e i tipi di compilazione, il che semplifica la configurazione e migliora le prestazioni della build.

• Ottimizzazione per KMP: il plug-in è progettato per le librerie KMP, con una particolare attenzione al codice Kotlin condiviso e all'interoperabilità, omettendo il supporto per build native specifiche per Android, AIDL e RenderScript.

• Test disattivati per impostazione predefinita: sia i test delle unità sia quelli del dispositivo (instrumentazione) sono disattivati per impostazione predefinita per migliorare la velocità della build. Puoi attivarli se necessario.

• Nessuna estensione Android di primo livello: la configurazione viene gestita con un blocco androidLibrary all'interno di Gradle KMP DSL, mantenendo una struttura di progetto KMP coerente. Non è presente alcun blocco dell'estensione android di primo livello.

• Compilazione Java con attivazione esplicita: la compilazione Java è disattivata per impostazione predefinita. Utilizza withJava() nel blocco androidLibrary per abilitarla. In questo modo i tempi di compilazione migliorano quando non è necessaria la compilazione Java.

Vantaggi del plug-in della libreria Android-KMP

Il plug-in Android-KMP offre i seguenti vantaggi per i progetti KMP:

• Prestazioni e stabilità della build migliorate: è progettato per ottimizzare la velocità della build e migliorare la stabilità all'interno dei progetti KMP. L'attenzione ai flussi di lavoro KMP contribuisce a un processo di compilazione più efficiente e affidabile.

• Integrazione IDE avanzata: offre completamento del codice, navigazione, debug ed esperienza complessiva per gli sviluppatori migliori quando lavora con le librerie KMP Android.

• Configurazione semplificata del progetto: il plug-in semplifica la configurazione per i progetti KMP rimuovendo le complessità specifiche di Android, come le varianti di compilazione. In questo modo, i file della build saranno più puliti e più facili da gestire. In precedenza, l'utilizzo del plug-in com.android.library nel progetto KMP poteva creare nomi di set di risorse poco chiari, ad esempio androidAndroidTest. Questa convenzione di denominazione era meno intuitiva per gli sviluppatori che conoscono le strutture standard dei progetti KMP.

Soluzioni alternative per le funzionalità non supportate

Rispetto all'integrazione di KMP con il plug-in com.android.library, alcune funzionalità non sono presenti nel plug-in com.android.kotlin.multiplatform.library. Ecco le soluzioni alternative per le funzionalità non supportate:

• Varianti di build

  I tipi di build e le varianti di prodotto non sono supportati. Questo perché il nuovo plugin utilizza un'architettura a variante singola, che semplifica la configurazione e migliora le prestazioni di build.

  Se hai bisogno di varianti di build, ti consigliamo di creare un modulo di libreria Android autonomo separato utilizzando il plug-in com.android.library, configurare i tipi di build e le varianti di prodotto all'interno di questo modulo e poi utilizzarlo come dipendenza di progetto standard dal set di origine androidMain della libreria Kotlin Multiplatform. Per maggiori dettagli, vedi Creare una libreria Android e Configurare le varianti di build.

• Associazione di dati e associazione di visualizzazioni

  Si tratta di funzionalità del framework UI specifiche per Android strettamente accoppiate al sistema di visualizzazione Android e ai layout XML. Nel nuovo plug-in della libreria Android-KMP ti consigliamo di gestire la UI utilizzando un framework multipiattaforma come Compose Multiplatform. L'associazione di dati e l'associazione di visualizzazioni sono considerati dettagli dell'implementazione di un'app per Android finale, non una libreria condivisibile.

• Supporto nativo per la build

  Il nuovo plug-in si concentra sulla produzione di un AAR standard per il target Android. L'integrazione del codice nativo in Kotlin Multiplatform viene gestita direttamente dai target nativi di KMP (ad esempio androidNativeArm64 e androidNativeX86) e dalle sue funzionalità di interoperabilità C. Se devi includere codice C/C++ nativo, devi definirlo come parte di un set di risorse comune o nativo e configurare l'interoperabilità C all'interno del blocco kotlin, anziché utilizzare il meccanismo externalNativeBuild specifico per Android.

  In alternativa, se hai bisogno del supporto per le build native tramite externalNativeBuild, ti consigliamo di creare un modulo com.android.library autonomo separato in cui puoi integrare il codice nativo e utilizzare questa libreria autonoma dal set di origine androidMain del progetto della libreria Kotlin Multiplatform. Per maggiori dettagli, consulta Creare una libreria Android e Aggiungere codice C e C++ al progetto.

• Classe BuildConfig

  La funzionalità BuildConfig è più utile in ambienti multivariante. Poiché il nuovo plug-in della libreria Kotlin Multiplatform è indipendente dalla variante e non supporta i tipi di compilazione e le versioni prodotto, questa funzionalità non è implementata. In alternativa, consigliamo di utilizzare il plug-in BuildKonfig o soluzioni simili della community per generare metadati per tutti i target.

Prerequisiti

Per utilizzare il plug-in com.android.kotlin.multiplatform.library, il progetto deve essere configurato con le seguenti versioni minime o successive:

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

Applica il plug-in Android-KMP a un modulo esistente

Per applicare il plug-in Android-KMP a un modulo di libreria KMP esistente, segui questi passaggi:

1. Dichiara i plug-in nel catalogo delle versioni. Apri il file TOML del catalogo delle versioni (di solito gradle/libs.versions.toml) e aggiungi la sezione delle definizioni dei plug-in:

   # To check the version number of the latest Kotlin release, go to
   # https://kotlinlang.org/docs/releases.html
   
   [versions]
   androidGradlePlugin = "9.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. Applica la dichiarazione del plug-in nel file della build principale. Apri il file build.gradle.kts che si trova nella directory root del progetto. Aggiungi gli alias del plug-in al blocco plugins utilizzando apply false. In questo modo, gli alias del plug-in sono disponibili per tutti i progetti secondari senza applicare la logica del plug-in al progetto principale stesso.

   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. Applica il plug-in in un file della build del modulo della libreria KMP. Apri il file build.gradle.kts nel modulo della libreria KMP e applica il plug-in all'inizio del file all'interno del blocco 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. Configura la destinazione KMP Android. Configura il blocco Kotlin Multiplatform (kotlin) per definire la destinazione Android. All'interno del blocco kotlin, specifica la destinazione Android utilizzando 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. Applica le modifiche. Dopo aver applicato il plug-in e configurato il blocco kotlin, sincronizza il progetto Gradle per applicare le modifiche.

Esegui la migrazione dal plug-in legacy

Questa guida ti aiuta a eseguire la migrazione dal plug-in com.android.library legacy al plug-in com.android.kotlin.multiplatform.library.

1. Dichiarazione delle dipendenze

La dichiarazione delle dipendenze per i set di risorse specifici per Android è un'attività comune. Il nuovo plug-in richiede che questi elementi vengano inseriti esplicitamente all'interno del blocco sourceSets, a differenza del blocco dependencies generale utilizzato in precedenza.

// 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. Attiva le risorse Android

Il supporto per le risorse Android (cartelle res) non è attivato per impostazione predefinita nel nuovo plug-in per ottimizzare le prestazioni della build. Per utilizzarle, devi attivare l'opzione. Questa modifica contribuisce a garantire che i progetti che non richiedono risorse specifiche per Android non siano appesantiti dall'overhead della build associato.

// 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. Configurazione dei test di host e dispositivo

Una modifica significativa introdotta nel nuovo plug-in è che i test lato host (unità) e lato dispositivo (instrumentati) di Android sono disattivati per impostazione predefinita. Devi attivare esplicitamente la creazione delle configurazioni e dei set di risorse di test, mentre il vecchio plug-in li creava automaticamente.

Questo modello di attivazione contribuisce a verificare che il progetto rimanga snello e includa solo la logica della build e i set di risorse che utilizzi attivamente.

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

4. Abilita la compilazione della risorsa Java

Se la tua libreria KMP deve compilare le risorse Java per il target Android, devi abilitare esplicitamente questa funzionalità con il nuovo plug-in. Tieni presente che questa opzione attiva la compilazione per i file Java che si trovano direttamente all'interno del progetto, non per le sue dipendenze. Cambia anche il metodo per impostare la versione target di JVM del compilatore Java e 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. Interagisci con le varianti di compilazione utilizzando androidComponents

L'estensione androidComponents è ancora disponibile per interagire con gli artefatti della build in modo programmatico. Sebbene gran parte dell'API Variant rimanga invariata, l'interfaccia AndroidKotlinMultiplatformVariant è più limitata perché il plug-in produce una sola variante.

Di conseguenza, le proprietà correlate ai tipi di compilazione e alle versioni prodotto non sono più disponibili nell'oggetto variante.

// build.gradle.kts

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

// build.gradle.kts

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

6. Seleziona le varianti delle dipendenze della libreria Android

La libreria KMP produce una sola variante per Android. Tuttavia, potresti dipendere da una libreria Android standard (com.android.library) che ha più varianti (ad es. versioni prodotto free/paid). Controllare il modo in cui il progetto seleziona una variante da questa dipendenza è un requisito comune.

// 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. Dipendenze di anteprima di Compose

In genere, vogliamo che le librerie specifiche siano limitate al nostro ambiente di sviluppo locale per evitare che gli strumenti interni vengano inclusi nell'artefatto pubblicato finale. Ciò diventa una sfida con il nuovo plug-in KMP per Android, perché rimuove l'architettura del tipo di compilazione utilizzata per separare le dipendenze di sviluppo dal codice di release.

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

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

8. Configura la JVM target per il target KMP Android

Il plug-in KMP Android imposta la JVM target utilizzando androidLibrary.compilerOptions.jvmTarget, che si applica sia a Java sia a Kotlin, semplificando la configurazione rispetto ai blocchi compileOptions e kotlinOptions separati nei progetti Android puri.

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

9. Pubblicare le regole di conservazione per i consumatori

Se la tua libreria KMP deve includere regole di conservazione per i consumatori (ad esempio regole ProGuard per R8), devi attivare esplicitamente la pubblicazione nel nuovo plug-in. In precedenza, le regole di conservazione per i consumatori venivano pubblicate per impostazione predefinita, se specificate.

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

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

Riferimento API plug-in

Il nuovo plug-in ha una superficie API diversa da com.android.library. Per informazioni dettagliate sul nuovo DSL e sulle nuove interfacce, consulta i riferimenti API:

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant

Problemi noti nel plug-in della libreria Android-KMP

Di seguito sono riportati i problemi noti che potrebbero verificarsi quando applichi il nuovo plug-in com.android.kotlin.multiplatform.library:

• L'anteprima di Compose non va a buon fine quando si utilizza il nuovo plug-in android-KMP

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

• NullPointerException nelle anteprime di Compose Multiplatform con il plug-in com.android.kotlin.multiplatform.library

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

• KMP memorizza la risoluzione delle dipendenze di compilazione comuni nella cache di configurazione che genera un errore durante la deserializzazione (solo Android)

  • Corretto in Kotlin Gradle Plugin 2.3.0-Beta2

• Supporto di sourceSetTree strumentato per la destinazione androidLibrary

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