Configura el complemento de biblioteca de Android Gradle para KMP

El complemento de Gradle com.android.kotlin.multiplatform.library es la herramienta compatible oficialmente para agregar un destino de Android a un módulo de biblioteca de Kotlin Multiplatform (KMP) . Simplifica la configuración del proyecto, mejora el rendimiento de la compilación y ofrece una mejor integración con Android Studio.

El uso del complemento com.android.library para el desarrollo de KMP depende de las APIs del complemento de Android para Gradle que dejaron de estar disponibles y requieren la habilitación en el complemento de Android para Gradle 9.0 y versiones posteriores (cuarto trimestre de 2025). Se espera que estas APIs se quiten en el complemento de Android para Gradle 10.0 (segunda mitad de 2026).

Para aplicar este complemento, consulta la sección Aplica el complemento de Android-KMP. Si necesitas migrar desde las APIs heredadas, consulta la Guía de migración.

Para obtener ayuda con la migración de AGP 9.0 y versiones posteriores, puedes usar la habilidad del agente creada por JetBrains para apps de KMP. Para obtener más información sobre el uso de habilidades en Android Studio, consulta Extiende el modo de agente con habilidades. Ten en cuenta que los resultados de la IA no son del todo predecibles.

Funciones y diferencias clave

El complemento de Android-KMP está diseñado específicamente para proyectos de KMP y difiere del complemento com.android.library estándar en varios aspectos clave:

• Arquitectura de una sola variante: El complemento usa una sola variante, lo que quita la compatibilidad con las variantes de productos y los tipos de compilación, lo que simplifica la configuración y mejora el rendimiento de la compilación.

• Optimizado para KMP: El complemento está diseñado para bibliotecas de KMP, se enfoca en el código Kotlin compartido y la interoperabilidad, y omite la compatibilidad con compilaciones nativas específicas de Android, AIDL y RenderScript.

• Pruebas inhabilitadas de forma predeterminada: Las pruebas de unidades y de dispositivos (instrumentación) están inhabilitadas de forma predeterminada para mejorar la velocidad de compilación. Puedes habilitarlas si es necesario.

• Sin extensión de Android de nivel superior: La configuración se controla con un bloque android dentro de la DSL de KMP de Gradle, lo que mantiene una estructura de proyecto de KMP coherente. No hay un bloque de extensión android de nivel superior.

• Compilación de Java habilitada: La compilación de Java está inhabilitada de forma predeterminada. Usa withJava() en el bloque android para habilitarla. Esto mejora los tiempos de compilación cuando no se necesita la compilación de Java.

Beneficios del complemento de biblioteca de Android-KMP

El complemento de Android-KMP proporciona los siguientes beneficios para los proyectos de KMP:

• Rendimiento y estabilidad de compilación mejorados: Está diseñado para optimizar las velocidades de compilación y mejorar la estabilidad dentro de los proyectos de KMP. Su enfoque en los flujos de trabajo de KMP contribuye a un proceso de compilación más eficiente y confiable.

• Integración mejorada del IDE: Proporciona una mejor finalización de código, navegación, depuración y experiencia general del desarrollador cuando se trabaja con bibliotecas de KMP para Android.

• Configuración de proyecto simplificada: El complemento simplifica la configuración de los proyectos de KMP quitando las complejidades específicas de Android, como las variantes de compilación. Esto da como resultado archivos de compilación más limpios y fáciles de mantener. Anteriormente, el uso del complemento com.android.library en el proyecto de KMP podía crear nombres de conjuntos de orígenes confusos, como androidAndroidTest. Esta convención de nombres era menos intuitiva para los desarrolladores familiarizados con las estructuras de proyectos de KMP estándar.

Soluciones alternativas para funciones no compatibles

En comparación con la integración de KMP con el complemento com.android.library, faltan algunas funciones en el complemento com.android.kotlin.multiplatform.library. Estas son las soluciones alternativas para las funciones no compatibles:

• Variantes de compilación

  No se admiten los tipos de compilación ni las variantes de productos. Esto se debe a que el nuevo complemento usa una arquitectura de una sola variante, lo que simplifica la configuración y mejora el rendimiento de la compilación.

  Si necesitas variantes de compilación, te recomendamos que crees un módulo de biblioteca de Android independiente por separado con el complemento com.android.library, configures los tipos de compilación y las variantes de productos dentro de ese módulo y, luego, lo consumas como una dependencia de proyecto estándar del conjunto de orígenes androidMain de tu biblioteca de Kotlin Multiplatform. Para obtener más detalles, consulta Crea una biblioteca de Android y Configura variantes de compilación.

• Vinculación de datos y vinculación de vistas

  Estas son funciones del framework de IU específicas de Android que están estrechamente vinculadas al sistema de vistas de Android y a los diseños XML. En el nuevo complemento de biblioteca de Android-KMP, te recomendamos que controles la IU con un framework multiplataforma como Compose Multiplatform. La vinculación de datos y la vinculación de vistas se consideran detalles de implementación de una app para Android final, no una biblioteca compartible.

• Compatibilidad con compilación nativa

  El nuevo complemento se enfoca en producir un AAR estándar para el destino de Android. La integración de código nativo en Kotlin Multiplatform se controla directamente con los propios destinos nativos de KMP (como androidNativeArm64 y androidNativeX86) y sus capacidades de interoperabilidad de C. Si necesitas incluir código nativo de C/C++, debes definirlo como parte de un conjunto de orígenes común o nativo y configurar la interoperabilidad de C dentro del bloque kotlin, en lugar de usar el mecanismo externalNativeBuild específico de Android.

  Como alternativa, si necesitas compatibilidad con compilación nativa a través de externalNativeBuild, te recomendamos que crees un módulo com.android.library independiente por separado en el que puedas integrar código nativo y consumir esa biblioteca independiente del conjunto de orígenes androidMain del proyecto de biblioteca de Kotlin Multiplatform. Para obtener más detalles, consulta Crea una biblioteca de Android y Agrega código C y C++ a tu proyecto.

• Clase BuildConfig

  La función BuildConfig es más útil en entornos de varias variantes. Dado que el nuevo complemento de biblioteca de Kotlin Multiplatform es independiente de la variante y no admite tipos de compilación ni variantes de productos, esta función no se implementa. Como alternativa, te recomendamos que uses el complemento BuildKonfig o soluciones similares de la comunidad para generar metadatos para todos los destinos.

Requisitos previos

Para usar el complemento com.android.kotlin.multiplatform.library, tu proyecto debe estar configurado con las siguientes versiones mínimas o superiores:

• Complemento de Android para Gradle (AGP): 8.10.0
• Complemento de Gradle para Kotlin (KGP): 2.0.0

Aplica el complemento de Android-KMP a un módulo existente

Para aplicar el complemento de Android-KMP a un módulo de biblioteca de KMP existente, sigue estos pasos:

1. Declara complementos en el catálogo de versiones. Abre el archivo TOML del catálogo de versiones (por lo general, gradle/libs.versions.toml) y agrega la sección de definiciones de complementos:

   # 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. Aplica la declaración del complemento en el archivo de compilación raíz. Abre el archivo build.gradle.kts ubicado en el directorio raíz de tu proyecto. Agrega los alias del complemento al bloque plugins con apply false. Esto hace que los alias del complemento estén disponibles para todos los subproyectos sin aplicar la lógica del complemento al proyecto raíz.

   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. Aplica el complemento en un archivo de compilación de módulo de biblioteca de KMP. Abre el archivo build.gradle.kts en tu módulo de biblioteca de KMP y aplica el complemento en la parte superior del archivo dentro del bloque 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 el destino de KMP para Android. Configura el bloque de Kotlin Multiplatform (kotlin) para definir el destino de Android. Dentro del bloque kotlin, especifica el destino de Android con android:

   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. Aplica los cambios. Después de aplicar el complemento y configurar el bloque kotlin, sincroniza tu proyecto de Gradle para aplicar los cambios.

Migra desde el complemento heredado

Esta guía te ayuda a migrar desde el complemento com.android.library heredado al complemento com.android.kotlin.multiplatform.library.

1. Cómo mover orígenes

El complemento heredado te permitía usar los conjuntos de orígenes src/main, src/test y src/androidTest, además de src/androidMain, src/androidHostTest y src/androidDeviceTest. El nuevo complemento solo usa los últimos directorios de origen, por lo que deberás mover los orígenes de src/main a src/androidMain, de src/test a src/androidHostTest y de src/androidTest a src/androidDeviceTest.

2. Cómo declarar dependencias

Una tarea común es declarar dependencias para los conjuntos de orígenes específicos de Android. El nuevo complemento requiere que estos se coloquen de forma explícita dentro del bloque sourceSets, a diferencia del bloque dependencies general que se usaba anteriormente.

// 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. Cómo habilitar recursos de Android

La compatibilidad con los recursos de Android (carpetas res) no está habilitada de forma predeterminada en el nuevo complemento para optimizar el rendimiento de la compilación. Debes habilitar la opción para usarlos. Este cambio ayuda a garantizar que los proyectos que no requieren recursos específicos de Android no se vean afectados por la sobrecarga de compilación asociada.

// 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. Cómo configurar pruebas de host y dispositivo

Un cambio significativo en el nuevo complemento es que las pruebas de host (unidades) y de dispositivo (instrumentadas) de Android están inhabilitadas de forma predeterminada. Debes habilitar la opción de forma explícita para crear los conjuntos de orígenes y las configuraciones de prueba, mientras que el complemento anterior los creaba automáticamente.

Este modelo de habilitación ayuda a verificar que tu proyecto siga siendo simple y solo incluya la lógica de compilación y los conjuntos de orígenes que usas de forma activa.

// 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. Habilita la compilación de código fuente Java

Si tu biblioteca de KMP necesita compilar orígenes de Java para su destino de Android, debes habilitar de forma explícita esta funcionalidad con el nuevo complemento. Ten en cuenta que esto habilita la compilación para los archivos Java ubicados directamente dentro de tu proyecto, no para sus dependencias. También cambia el método para configurar la versión de destino de JVM del compilador de Java y Kotlin.

// 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. Interactúa con variantes de compilación usando androidComponents

La extensión androidComponents aún está disponible para interactuar con artefactos de compilación de forma programática. Si bien gran parte de la API de Variant sigue siendo la misma, la nueva interfaz AndroidKotlinMultiplatformVariant es más limitada porque el complemento solo produce una sola variante.

En consecuencia, las propiedades relacionadas con los tipos de compilación y las variantes de productos ya no están disponibles en el objeto de variante.

// build.gradle.kts

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

// build.gradle.kts

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

7. Selecciona variantes de dependencias de bibliotecas de Android

Tu biblioteca de KMP produce una sola variante para Android. Sin embargo, es posible que dependas de una biblioteca de Android estándar (com.android.library) que tenga varias variantes (p.ej., variantes de productos free/paid). Controlar cómo tu proyecto selecciona una variante de esa dependencia es un requisito común.

// 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. Dependencias de vista previa de Compose

Por lo general, queremos tener bibliotecas específicas en nuestro entorno de desarrollo local para evitar que las herramientas internas se filtren en el artefacto publicado final. Esto se convierte en un desafío con el nuevo complemento de Android para KMP porque quita la arquitectura de tipo de compilación que se usa para separar las dependencias de desarrollo del código de lanzamiento.

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

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

9. Configura el destino de JVM para el destino de Android de KMP

El complemento para Android de KMP establece el destino de JVM con android.compilerOptions.jvmTarget, que se aplica a Java y Kotlin, lo que simplifica la configuración en comparación con los bloques compileOptions y kotlinOptions separados en proyectos de Android puros.

// 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. Publica reglas de conservación del consumidor

Si tu biblioteca de KMP necesita enviar reglas de conservación del consumidor (como reglas de ProGuard para R8) para sus consumidores, debes habilitar de forma explícita la publicación en el nuevo complemento. Anteriormente, las reglas de conservación del consumidor se publicaban de forma predeterminada si se especificaban.

// 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. Publica tu biblioteca en Maven

Si planeas publicar tu biblioteca de KMP en Maven para que la usen otros proyectos, el proceso difiere según si usas el nuevo complemento de Android-KMP o el complemento heredado.

Referencia de la API del complemento

El nuevo complemento tiene una plataforma de API diferente a com.android.library. Para obtener información detallada sobre la nueva DSL y las interfaces, consulta las referencias de la API:

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant

Problemas conocidos en el complemento de biblioteca de Android-KMP

Estos son los problemas conocidos que pueden ocurrir cuando aplicas el nuevo complemento com.android.kotlin.multiplatform.library:

• Falla la versión previa de Compose cuando se usa el nuevo complemento de Android-KMP

  • Se corrigió en Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 y Android Gradle Plugin 9.0.0-alpha13.

• NullPointerException en las vistas previas de Compose Multiplatform con el complemento com.android.kotlin.multiplatform.library

  • Se corrigió en Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 y Android Gradle Plugin 9.0.0-alpha13.

• KMP almacena la resolución de dependencias de compilación comunes en la caché de configuración, lo que genera un error cuando se deserializa (solo para Android).

  • Se corrigió en Kotlin Gradle Plugin 2.3.0-Beta2.

• Admite sourceSetTree instrumentado para el destino de androidLibrary.

  • Se corrigió en Android Studio Otter 2 Feature Drop | 2025.2.2 Canary 3 y Android Gradle Plugin 9.0.0-alpha13.