Configurar o plug-in de biblioteca do Android Gradle para KMP

O plug-in do Gradle com.android.kotlin.multiplatform.library é a ferramenta oficialmente compatível para adicionar um destino Android a um módulo de biblioteca do Kotlin Multiplatform (KMP). Ele simplifica a configuração do projeto, melhora a performance do build e oferece uma integração melhor com o Android Studio.

O uso do plug-in com.android.library para desenvolvimento de KMP depende de APIs do Plug-in do Android para Gradle que estão descontinuadas e exigem ativação no Plug-in do Android para Gradle 9.0 e versões mais recentes (4º trimestre de 2025). Essas APIs serão removidas no Plug-in do Android para Gradle 10.0 (segundo semestre de 2026).

Observação: não há uma substituição direta para configurar um módulo Kotlin Multiplatform usando o plug-in com.android.application. Para migrar, extraia seu aplicativo Android para um módulo separado do Gradle.

Para aplicar esse plug-in, consulte a seção Aplicar o plug-in Android-KMP. Se precisar migrar das APIs legadas, consulte o guia de migração.

Cuidado: há alguns problemas conhecidos com o novo plug-in.

Principais recursos e diferenças

O plug-in Android-KMP é feito especificamente para projetos KMP e difere do plug-in com.android.library padrão em vários aspectos principais:

• Arquitetura de variante única:o plug-in usa uma única variante, removendo o suporte para variações de produto e tipos de build, o que simplifica a configuração e melhora o desempenho do build.

• Otimizado para KMP:o plug-in foi projetado para bibliotecas KMP, com foco em código Kotlin compartilhado e interoperabilidade, sem suporte para AIDL, RenderScript e builds nativos específicos do Android.

• Testes desativados por padrão:os testes de unidade e de dispositivo (instrumentação) são desativados por padrão para aumentar a velocidade do build. É possível ativá-los se necessário.

• Nenhuma extensão do Android de nível superior:a configuração é processada com um bloco androidLibrary na DSL KMP do Gradle, mantendo uma estrutura de projeto KMP consistente. Não há um bloqueio de extensão de nível superior android.

• Ativar a compilação Java:a compilação Java fica desativada por padrão. Use withJava() no bloco androidLibrary para ativar. Isso melhora os tempos de build quando a compilação Java não é necessária.

Benefícios do plug-in da biblioteca Android-KMP

O plug-in Android-KMP oferece os seguintes benefícios para projetos KMP:

• Melhoria na performance e estabilidade do build:projetado para otimizar as velocidades de build e melhorar a estabilidade em projetos KMP. O foco nos fluxos de trabalho do KMP contribui para um processo de build mais eficiente e confiável.

• Integração aprimorada do ambiente de desenvolvimento integrado:oferece melhor preenchimento de código, navegação, depuração e experiência geral do desenvolvedor ao trabalhar com bibliotecas KMP Android.

• Configuração simplificada do projeto:o plug-in simplifica a configuração para projetos KMP removendo complexidades específicas do Android, como variantes de build. Isso resulta em arquivos de build mais limpos e fáceis de manter. Antes, usar o plug-in com.android.library em um projeto KMP podia criar nomes de conjunto de origem confusos, como androidAndroidTest. Essa convenção de nomenclatura era menos intuitiva para desenvolvedores familiarizados com estruturas de projetos KMP padrão.

Problemas conhecidos no plug-in da biblioteca Android-KMP

Estes são os problemas conhecidos que podem ocorrer ao aplicar o novo plug-in com.android.kotlin.multiplatform.library:

• A prévia do Compose falha ao usar o novo plug-in android-KMP

• NullPointerException em prévias do Compose Multiplatform com o plug-in com.android.kotlin.multiplatform.library

• O KMP armazena a resolução de dependência de compilação comum no cache de configuração, o que causa um erro ao desserializar (apenas Android).

• Suporte a sourceSetTree instrumentado para destino androidLibrary

Pré-requisitos

Para usar o plug-in com.android.kotlin.multiplatform.library, seu projeto precisa ser configurado com as seguintes versões mínimas ou mais recentes:

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

Aplicar o plug-in Android-KMP a um módulo atual

Para aplicar o plug-in Android-KMP a um módulo de biblioteca KMP atual, siga estas etapas:

1. Declarar plug-ins no catálogo de versões. Abra o arquivo TOML do catálogo de versões (geralmente gradle/libs.versions.toml) e adicione a seção de definições de plug-in:

   # 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. Aplique a declaração do plug-in no arquivo de build raiz. Abra o arquivo build.gradle.kts localizado no diretório raiz do projeto. Adicione os aliases do plug-in ao bloco plugins usando apply false. Isso disponibiliza os aliases do plug-in para todos os subprojetos sem aplicar a lógica do plug-in ao projeto raiz.

   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. Aplique o plug-in em um arquivo de build do módulo de biblioteca KMP. Abra o arquivo build.gradle.kts no módulo da biblioteca KMP e aplique o plug-in na parte de cima do arquivo dentro do bloco 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. Configure o destino do KMP do Android. Configure o bloco Kotlin Multiplatform (kotlin) para definir a plataforma de destino do Android. No bloco kotlin, especifique o destino do Android usando 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. Aplicar mudanças. Depois de aplicar o plug-in e configurar o bloco kotlin, sincronize seu projeto do Gradle para aplicar as mudanças.

Migrar do plug-in legado

Este guia ajuda você a migrar do plug-in com.android.library legado para o plug-in com.android.kotlin.multiplatform.library.

Observação: desde a versão 2.2.0-Beta2 do plug-in do Kotlin para Gradle e a versão 8.12.0-alpha04 do plug-in do Android para Gradle, existe um novo bloco de configuração chamado android{} ao lado do androidLibrary{}. O bloco androidLibrary{} foi descontinuado e será removido em uma versão futura do AGP. Migre para o bloco android{} .

1. Como declarar dependências

Uma tarefa comum é declarar dependências para conjuntos de origem específicos do Android. O novo plug-in exige que eles sejam colocados explicitamente no bloco sourceSets, ao contrário do bloco dependencies geral usado anteriormente.

Android-KMP

O novo plug-in promove uma estrutura mais limpa agrupando as dependências do Android no conjunto de origem androidMain. Além do conjunto de origem principal, há dois conjuntos de origem de teste, que são criados sob demanda: androidDeviceTest e androidHostTest. Consulte Configurar testes de host e dispositivo para mais informações.

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

Os conjuntos de origem têm compilações correspondentes do Kotlin chamadas main, deviceTest e hostTest. Os conjuntos e as compilações de origem podem ser configurados no script de build da seguinte maneira:

// build.gradle.kts

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

Plug-in legado

Com o plug-in antigo, era possível declarar dependências específicas do Android no bloco de dependências de nível superior, o que às vezes podia ser confuso em um módulo multiplataforma.

// 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. Como ativar recursos do Android

O suporte para recursos do Android (pastas res) não é ativado por padrão no novo plug-in para otimizar o desempenho do build. É necessário ativar esse recurso para usar. Essa mudança ajuda a garantir que projetos que não exigem recursos específicos do Android não sejam afetados pela sobrecarga de build associada.

Observação: isso está relacionado apenas a recursos específicos do Android. Não é necessário ativar isso se você estiver usando Recursos multiplataforma do Compose.

Android-KMP

É preciso ativar explicitamente o processamento de recursos do Android. Os recursos precisam ser colocados em src/androidMain/res.

// build.gradle.kts

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

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

Plug-in legado

O processamento de recursos era ativado por padrão. Você pode adicionar imediatamente um diretório res em src/main e começar a adicionar elementos drawable, valores etc. em 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. Como configurar testes de host e dispositivo

Uma mudança significativa no novo plug-in é que os testes do lado do host (unidade) e do dispositivo (instrumentados) do Android são desativados por padrão. É necessário ativar explicitamente a criação dos conjuntos de origem e configurações de teste, enquanto o plug-in antigo os criava automaticamente.

Esse modelo de inclusão ajuda a verificar se o projeto permanece enxuto e inclui apenas a lógica de build e os conjuntos de origem que você usa ativamente.

Android-KMP

No novo plug-in, ative e configure os testes dentro do bloco kotlin.androidLibrary. Isso torna a configuração mais explícita e evita a criação de componentes de teste não utilizados. O conjunto de origem test se torna androidHostTest, e androidTest se torna androidDeviceTest.

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

Plug-in legado

Com o plug-in com.android.library, os conjuntos de origem test e androidTest foram criados por padrão. Você configuraria o comportamento deles dentro do bloco android, geralmente usando a DSL testOptions.

// 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. Ativar a compilação de origem Java

Se a biblioteca KMP precisar compilar fontes Java para a plataforma Android, você precisará ativar explicitamente essa funcionalidade com o novo plug-in. Isso ativa a compilação de arquivos Java localizados diretamente no projeto, não nas dependências dele. O método para definir a versão de destino da JVM do compilador Java e Kotlin também muda.

Android-KMP

Você precisa ativar a compilação Java chamando withJava(). O destino da JVM agora é configurado diretamente no bloco kotlin { androidLibrary {} } para uma configuração mais unificada. A definição de jvmTarget aqui se aplica à compilação em Kotlin e Java para o destino Android.

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

Plug-in legado

A compilação Java era ativada por padrão. O destino da JVM para fontes Java e Kotlin foi definido no bloco "android" usando "compileOptions".

// build.gradle.kts

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

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

5. Interagir com variantes de build usando androidComponents

A extensão androidComponents ainda está disponível para interagir com artefatos de build de forma programática. Embora grande parte da API Variant permaneça a mesma, a nova interface AndroidKotlinMultiplatformVariant é mais limitada porque o plug-in produz apenas uma variante.

Consequentemente, as propriedades relacionadas a tipos de build e variações de produto não estão mais disponíveis no objeto de variante.

Android-KMP

O bloco onVariants agora itera em uma única variante. Você ainda pode acessar propriedades comuns, como name e artifacts, mas não as específicas do tipo de build.

// build.gradle.kts

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

Plug-in legado

Com várias variantes, você pode acessar propriedades específicas do tipo de build para configurar tarefas.

// build.gradle.kts

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

6. Selecionar variantes de dependências de biblioteca do Android

Sua biblioteca KMP produz uma única variante para Android. No entanto, talvez você dependa de uma biblioteca padrão do Android (com.android.library) que tenha várias variantes (por exemplo, free/paid variações de produtos). Controlar como seu projeto seleciona uma variante dessa dependência é um requisito comum.

Android-KMP

O novo plug-in centraliza e esclarece essa lógica no bloco kotlin.androidLibrary.localDependencySelection. Isso deixa muito mais claro quais variantes de dependências externas serão selecionadas para sua biblioteca KMP de variante única.

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

Plug-in legado

Você configurou estratégias de seleção de dependências nos blocos buildTypes and productFlavors. Isso geralmente envolvia o uso de missingDimensionStrategy para fornecer uma variação padrão para uma dimensão que a biblioteca não tinha ou matchingFallbacks em uma variação específica para definir uma ordem de pesquisa.

Consulte Resolver erros de correspondência para mais informações sobre o uso da API.

7. Dependências da visualização do Compose

Normalmente, queremos ter bibliotecas específicas no escopo do nosso ambiente de desenvolvimento local para evitar que ferramentas internas vazem para o artefato publicado final. Isso se torna um desafio com o novo plug-in do Android KMP porque ele remove a arquitetura de tipo de build usada para separar o desenvolvimento de dependências do código de lançamento.

Android-KMP

Para adicionar uma dependência apenas para desenvolvimento e testes locais, adicione a dependência diretamente à configuração do caminho de classe de execução (no bloco dependencies de nível superior) da compilação principal do Android. Isso ajuda a garantir que a dependência esteja disponível no momento da execução (por exemplo, para ferramentas como Compose Preview), mas não faz parte do classpath de compilação ou da API publicada da sua biblioteca.

Prévia: essa solução alternativa só está disponível no Plug-in do Android para Gradle versão 9.0.0-beta01 e mais recentes.

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

Plug-in legado

Projetos do Kotlin Multiplatform que usam o plug-in com.android.library para a plataforma Android precisam usar a configuração debugImplementation, que limita a dependência ao tipo de build de depuração e impede que ela seja incluída na variante de lançamento da biblioteca usada pelos consumidores.

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

8. Configurar o destino da JVM para o destino do Android da KMP

O plug-in do Android KMP define a meta da JVM usando androidLibrary.compilerOptions.jvmTarget, que se aplica a Java e Kotlin, simplificando a configuração em comparação com os blocos separados compileOptions e kotlinOptions em projetos Android puros.

Android-KMP

Ao trabalhar com um projeto Kotlin Multiplatform (KMP) que inclui um destino Android, você tem várias maneiras de configurar a versão de destino da JVM para os compiladores Kotlin e Java. Entender o escopo e a hierarquia dessas configurações é fundamental para gerenciar a compatibilidade de bytecode do projeto.

Confira as três principais maneiras de definir o destino da JVM, ordenadas da menor para a maior precedência. Os valores de destino da JVM que têm maior precedência se aplicam a um subconjunto menor dos destinos configurados e substituem os valores de menor precedência. Isso significa que você pode definir diferentes versões da JVM para diferentes destinos e compilações dentro dos destinos no seu projeto.

Como usar o conjunto de ferramentas do Kotlin (menor precedência)

A maneira mais geral de definir o destino da JVM é especificar a cadeia de ferramentas no bloco kotlin do arquivo build.gradle.kts. Essa abordagem define o destino para tarefas de compilação do Kotlin e do Java em todos os destinos baseados na JVM no seu projeto, incluindo o Android.

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

Essa configuração faz com que kotlinc e javac tenham como destino a JVM 21. É uma ótima maneira de estabelecer um valor de referência consistente para todo o projeto.

Como usar opções de compilador no nível de destino do Android (precedência média)

Você pode especificar o destino da JVM especificamente para o destino do KMP do Android no bloco android. Essa configuração substitui a configuração jvmToolchain em todo o projeto e se aplica a todas as compilações do Android.

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

Nesse caso, mesmo que um jvmToolchain seja definido para uma versão diferente, o código Kotlin e Java do destino do Android será compilado para segmentar a JVM 11.

Usar opções de compilador no nível da compilação (maior precedência)

Para ter o controle mais granular, é possível configurar opções de compilador por compilação (por exemplo, apenas em androidMain ou androidHostTest). Isso é útil se uma compilação específica precisar segmentar uma versão diferente da JVM. Essa configuração substitui a cadeia de ferramentas do Kotlin e as opções de nível de destino do Android.

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

Essa configuração ajuda a garantir que todas as compilações no destino do Android usem a JVM 11, oferecendo controle refinado.

Plug-in legado

Em um projeto KMP que usa o plug-in padrão da biblioteca Android (com.android.library), a configuração é um pouco diferente de quando você usa o plug-in Android KMP (mas conceitualmente semelhante).

Como usar o conjunto de ferramentas do Kotlin

O método kotlin.jvmToolchain() funciona de maneira idêntica, definindo sourceCompatibility e targetCompatibility para Java e jvmTarget para Kotlin. Recomendamos usar essa abordagem.

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

compileOptions e kotlinOptions

Se você não usa a cadeia de ferramentas do Kotlin, precisa configurar os destinos da JVM usando blocos separados para Java e Kotlin.

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

    kotlinOptions {
        jvmTarget = "11"
    }
}

Referência da API do plug-in

O novo plug-in tem uma plataforma de API diferente de com.android.library. Para informações detalhadas sobre a nova DSL e as interfaces, consulte as referências da API:

• KotlinMultiplatformAndroidLibraryExtension
• KotlinMultiplatformAndroidLibraryTarget
• KotlinMultiplatformAndroidDeviceTest
• KotlinMultiplatformAndroidHostTest
• KotlinMultiplatformAndroidVariant