Migrar para o plug-in Android-KMP

Antes, a única maneira de integrar o Android a um projeto do KMP era usar o Plug-in do Gradle da biblioteca Android regular: com.android.library. No entanto, essa abordagem foi descontinuada em favor do plug-in com.android.kotlin.multiplatform.library dedicado, também conhecido como plug-in Android-KMP. Este guia explica como migrar para o novo plug-in.

Principais recursos e diferenças

O plug-in Android-KMP (com.android.kotlin.multiplatform.library) é personalizado específicamente para projetos KMP e difere do plug-in com.android.library tradicional em vários aspectos importantes:

  • Arquitetura de variante única:o plug-in opera com uma única variante, simplificando o processo de build ao remover o suporte para variações de produto e tipos de build comumente encontrados em projetos de biblioteca Android padrão. Isso simplifica a configuração e melhora o desempenho do build para bibliotecas do Android do KMP.
  • Otimizado para KMP:o plug-in foi projetado especificamente para bibliotecas Multiplatform do Kotlin, com foco em código Kotlin compartilhado e interoperabilidade. Consequentemente, ele omite o suporte a builds nativos específicos do Android, AIDL (Android Interface Definition Language) e RenderScript, que normalmente não são relevantes em um contexto de código compartilhado do KMP.
  • Testes desativados por padrão:para melhorar ainda mais a velocidade de build em um ambiente multiplataforma, os testes são desativados por padrão. É possível ativar explicitamente os testes, se necessário para seu projeto. Isso se aplica a testes no host (testes de unidade) e testes no dispositivo (testes de instrumentação).
  • Nenhuma extensão de nível superior do Android:o plug-in não cria uma extensão android de nível superior nos arquivos de build do Gradle. A configuração é processada com um bloco androidLibrary na DSL multiplataforma do Kotlin, mantendo uma estrutura de projeto KMP consistente.
  • Ativar a compilação do Java:a compilação do Java não é ativada por padrão. Se a biblioteca do KMP precisar compilar um código baseado em Java, você precisará ativar explicitamente usando a API withJava() no bloco de configuração androidLibrary no bloco kotlin. Isso permite um controle mais preciso sobre o processo de compilação e pode melhorar os tempos de build quando a compilação de código baseado em Java não é necessária.

Benefícios da migração

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

  • Melhoria na performance e na estabilidade do build:o plug-in Android-KMP foi projetado para otimizar a velocidade de build e melhorar a estabilidade nos projetos do KMP. A arquitetura simplificada e o foco nos fluxos de trabalho do KMP contribuem para um processo de build mais eficiente e confiável.
  • Melhoria na integração do ambiente de desenvolvimento integrado:o plug-in oferece integração superior com o Android Studio e outros ambientes de desenvolvimento integrado do Kotlin. Isso leva a uma melhor conclusão de código, navegação, depuração e experiência geral do desenvolvedor ao trabalhar com bibliotecas do KMP para Android.
  • Configuração simplificada do projeto:ao remover complexidades específicas do Android, como variantes, o plug-in Android-KMP simplifica a configuração para projetos do KMP. Isso resulta em arquivos de build mais limpos e fáceis de manter, além de uma curva de aprendizado reduzida para desenvolvedores que estão começando a usar o desenvolvimento Android com KMP. Anteriormente, ao integrar o Android a um projeto do KMP usando o plug-in com.android.library, a interação entre o plug-in do Android para Gradle e o plug-in do Kotlin para Gradle na estrutura multiplataforma às vezes resultava em nomes de conjuntos de origem enganosos. Por exemplo, o conjunto de origem dedicado à configuração de testes instrumentados do Android foi nomeado androidAndroidTest. Essa convenção de nomenclatura era menos intuitiva para desenvolvedores que já conheciam as estruturas de projeto padrão do KMP.
  • Solução oficial e recomendada:o plug-in com.android.kotlin.multiplatform.library é a substituição oficial do método anterior de adição de destinos do Android a bibliotecas do KMP usando o plug-in com.android.library. O uso contínuo do plug-in com.android.library para KMP não será mais compatível com o JetBrains e não vai se beneficiar de atualizações e melhorias futuras.

Aplicar o plug-in Android-KMP a um projeto

Há duas maneiras principais de aplicar o plug-in do Android-KMP ao seu projeto: * Para módulos de biblioteca KMP existentes, edite os arquivos do Gradle manualmente. * Para novos módulos de biblioteca do KMP, crie o novo módulo diretamente na interface do Android Studio.

Aplicar o plug-in a um módulo

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

  1. Abra o arquivo TOML do catálogo de versões e adicione o seguinte à seção plugins:

    [plugins]
kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform",
version.ref = "KOTLIN_PLUGIN_VERSION" }
android-kotlin-multiplatform-library = { id =
"com.android.kotlin.multiplatform.library", version.ref =
"ANDROID_KMP_PLUGIN_VERSION" }

    Substitua KOTLIN_PLUGIN_VERSION e ANDROID_KMP_PLUGIN_VERSION pelas versões que você está usando.

  2. Abra o arquivo build.gradle.kts (Kotlin) ou build.gradle (Groovy) na raiz do módulo da biblioteca KMP.

  3. Aplique o plug-in na parte de cima do arquivo no bloco plugins:

    Kotlin

    plugins {
   alias(libs.plugins.kotlin.multiplatform) apply false

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library) apply false
}

    Groovy

    plugins {
   alias(libs.plugins.kotlin.multiplatform) apply false

   // Add the following
   alias(libs.plugins.android.kotlin.multiplatform.library) apply false
}

  4. Configure o bloco Kotlin Multiplatform (kotlin) para definir o destino 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"
       }

       compilations.configureEach {
           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"
       }

       compilations.configureEach {
           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. Depois de aplicar o plug-in e configurar o bloco kotlin, sincronize seu projeto do Gradle para aplicar as mudanças.

Criar um novo módulo com o plug-in

Também é possível criar um novo módulo de biblioteca Kotlin Multiplatform diretamente no Android Studio. Isso aplica os plug-ins necessários automaticamente, incluindo o plug-in Android-KMP. Para mais orientações sobre como criar um novo módulo de biblioteca do KMP com o Android Studio, consulte Adicionar o Kotlin Multiplatform a um projeto existente.

Para mais informações sobre o ecossistema multiplataforma geral e configurações mais avançadas, consulte a documentação multiplataforma do Kotlin (link em inglês).