Migrar a configuração do build do Groovy para o Kotlin

O Plug-in do Android para Gradle 4.0 adicionou suporte ao uso do Kotlin na configuração do build do Gradle como uma substituição para o Groovy, a linguagem de programação tradicionalmente usada em arquivos de configuração do Gradle.

O Kotlin é preferido ao Groovy para programar scripts do Gradle porque é mais legível e oferece melhores opções de verificação do tempo de compilação e suporte ao ambiente de desenvolvimento integrado.

Embora o Kotlin ofereça melhor integração no editor de código do Android Studio em comparação com o Groovy, os builds que usam o Kotlin tendem a ser mais lentos do que os que usam o Groovy. Portanto, considere o desempenho do build ao decidir migrar ou não.

Esta página oferece informações básicas sobre a conversão dos arquivos de build do Gradle do seu app Android do Groovy para o Kotlin. Para conferir um guia de migração mais abrangente, consulte a documentação oficial (link em inglês) do Gradle.

Cronograma

Observação: o Kotlin é a linguagem padrão para a configuração do build a partir do Android Studio Giraffe. Se você estiver usando o AGP 8.1 e a DSL do Kotlin para a configuração do build, use o Gradle 8.1 para ter a melhor experiência.

A partir do Android Studio Giraffe, os novos projetos usam a DSL do Kotlin (build.gradle.kts) por padrão para a configuração do build. Isso oferece uma experiência de edição melhor do que a DSL do Groovy (build.gradle) com destaque de sintaxe, preenchimento de código e navegação para declarações. Para saber mais, consulte o Gradle Kotlin DSL Primer.

Termos comuns

DSL de Kotlin: refere-se principalmente à DSL de Kotlin do Plug-in do Android para Gradle ou, às vezes, à DSL de Kotlin do Gradle (links em inglês).

Neste guia de migração, "Kotlin" e "DSL de Kotlin" são usados como sinônimos. Da mesma forma, "Groovy" e "DSL do Groovy" são usados de forma intercambiável.

Nomear arquivos de script

Os nomes das extensões dos arquivos de script são baseados na linguagem em que o arquivo de build está programado:

• Os arquivos de build do Gradle programados no Groovy usam a extensão de nome de arquivo .gradle.
• Os arquivos de build do Gradle programados em Kotlin usam a extensão de nome de arquivo .gradle.kts.

Converter a sintaxe

Há algumas diferenças gerais na sintaxe entre o Groovy e o Kotlin. Por isso, é necessário aplicar essas mudanças a todos os scripts de build.

Adicionar parênteses a chamadas de método

Dica: como primeira etapa, mesmo antes de mudar as extensões de arquivo, adicione parênteses ao código do Groovy. Isso facilita a conversão para Kotlin.

O Groovy permite omitir parênteses em chamadas de método, enquanto o Kotlin os exige. Para migrar a configuração, adicione parênteses a esses tipos de chamadas de método. Este código mostra como definir uma configuração no Groovy:

compileSdkVersion 30

Este é o mesmo código programado em Kotlin:

compileSdkVersion(30)

Adicionar = a chamadas de atribuição

Dica: antes de mudar as extensões de arquivo, adicione = ao código do Groovy. Isso facilita a conversão para Kotlin.

A DSL do Groovy permite omitir o operador de atribuição = ao atribuir propriedades, enquanto o Kotlin o exige. Este código mostra como atribuir propriedades no Groovy:

java {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
}

Este código mostra como atribuir propriedades no Kotlin:

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

Converter strings

Confira as diferenças de string entre o Groovy e o Kotlin:

• Aspas duplas para strings: embora o Groovy permita que strings sejam definidas usando aspas simples, o Kotlin exige aspas duplas.

• Interpolação de strings em expressões pontilhadas: no Groovy, use apenas o prefixo $ para interpolações de strings em expressões com pontos. Porém, o Kotlin exige que você coloque as expressões pontilhadas entre chaves. Por exemplo, no Groovy, é possível usar $project.rootDir, conforme mostrado no snippet a seguir:

      myRootDirectory = "$project.rootDir/tools/proguard-rules-debug.pro"
      

  No entanto, em Kotlin, o código anterior chama toString() em project, não em project.rootDir. Para receber o valor do diretório raiz, coloque a expressão ${project.rootDir} entre chaves:

      myRootDirectory = "${project.rootDir}/tools/proguard-rules-debug.pro"
      

  Para saber mais, consulte Modelos de string na documentação do Kotlin (em inglês).

Renomear extensões de arquivo

Anexe .kts a cada arquivo de build durante a migração do conteúdo. Por exemplo, selecione um arquivo de build, como o settings.gradle. Renomeie o arquivo como settings.gradle.kts e converta o conteúdo para Kotlin. Confira se o projeto ainda é compilado depois da migração de cada arquivo de build.

Migre seus arquivos menores primeiro, adquira experiência e depois continue. É possível ter uma mistura de arquivos de build Kotlin e Groovy em um projeto. Portanto, leve o tempo que precisar para fazer isso com cuidado.

Substituir def por val ou var

Substitua def por val ou var, que é a maneira de definir variáveis no Kotlin. Esta é uma declaração de variável no Groovy:

def building64Bit = false

Este é o mesmo código programado em Kotlin:

val building64Bit = false

Prefixar propriedades booleanas com is

O Groovy usa a lógica de dedução da propriedade com base nos nomes das propriedades. Para uma propriedade booleana foo, os métodos delimitados podem ser getFoo, setFoo ou isFoo. Assim, uma vez convertido em Kotlin, você precisará mudar os nomes das propriedades para os métodos deduzidos que não têm suporte do Kotlin. Por exemplo, para elementos booleanos DSL buildTypes, é necessário prefixá-los com is. Este código mostra como definir propriedades booleanas no Groovy:

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            ...
        }
        debug {
            debuggable true
            ...
        }
    ...

O código abaixo é o mesmo no Kotlin. As propriedades têm o prefixo is.

android {
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
            isShrinkResources = true
            ...
        }
        getByName("debug") {
            isDebuggable = true
            ...
        }
    ...

Converter listas e mapas

Listas e mapas no Groovy e no Kotlin são definidos usando sintaxes diferentes. O Groovy usa [], enquanto o Kotlin chama métodos de criação de coleção explicitamente usando listOf ou mapOf. Não se esqueça de substituir [] por listOf ou mapOf ao migrar.

Confira como definir uma lista no Groovy em comparação com o Kotlin:

jvmOptions += ["-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError</code>"]

Este é o mesmo código programado em Kotlin:

jvmOptions += listOf("-Xms4000m", "-Xmx4000m", "-XX:+HeapDumpOnOutOfMemoryError")

Confira como definir um mapa no Groovy em comparação com o Kotlin:

def myMap = [key1: 'value1', key2: 'value2']

Este é o mesmo código programado em Kotlin:

val myMap = mapOf("key1" to "value1", "key2" to "value2")

Configurar tipos de build

Na DSL do Kotlin, apenas os tipos de build de depuração e de lançamento estão disponíveis implicitamente. Todos os outros tipos de build personalizados precisam ser criados manualmente.

No Groovy, é possível usar a depuração, a versão e determinados outros tipos de build sem criá-los antes. O snippet de código a seguir mostra uma configuração com os tipos de build debug, release e benchmark no Groovy.

buildTypes {
 debug {
   ...
 }
 release {
   ...
 }
 benchmark {
   ...
 }
}

Para criar a configuração equivalente no Kotlin, é preciso criar explicitamente o tipo de build benchmark.

buildTypes {
 debug {
   ...
 }

 release {
   ...
 }
 register("benchmark") {
    ...
 }
}

Migrar do buildscript para o bloco de plug-ins

Se o build usar o bloco buildscript {} para adicionar plug-ins ao projeto, reformule para usar o bloco plugins {}. O bloco plugins {} facilita a aplicação de plug-ins e funciona bem com catálogos de versões.

Além disso, quando você usa o bloco plugins {} nos arquivos de build, o Android Studio reconhece o contexto, mesmo quando o build falha. Esse contexto ajuda a fazer correções nos arquivos DSL do Kotlin, porque permite que o ambiente de desenvolvimento integrado do Studio realize o preenchimento de código e forneça outras sugestões úteis.

Encontrar os IDs dos plug-ins

Enquanto o bloco buildscript {} adiciona os plug-ins ao caminho de classe de build usando as coordenadas do Maven do plug-in, por exemplo, com.android.tools.build:gradle:7.4.0, o bloco plugins {} usa os IDs do plug-in.

Para a maioria dos plug-ins, o ID é a string usada quando você os aplica usando apply plugin. Por exemplo, os IDs de plug-in a seguir fazem parte do Plug-in do Android para Gradle:

• com.android.application
• com.android.library
• com.android.lint
• com.android.test

Você pode encontrar a lista completa de plug-ins no repositório Maven do Google.

Os plug-ins Kotlin podem ser referenciados por vários IDs de plug-in. Recomendamos usar o ID do plug-in com namespace e refatorar da abreviação para o ID do plug-in com namespace usando a tabela a seguir:

IDs de plug-in abreviados	IDs de plug-in com namespace
kotlin	org.jetbrains.kotlin.jvm
kotlin-android	org.jetbrains.kotlin.android
kotlin-kapt	org.jetbrains.kotlin.kapt
kotlin-parcelize	org.jetbrains.kotlin.plugin.parcelize

Também é possível pesquisar plug-ins no portal de plug-ins do Gradle, no repositório central do Maven e no repositório do Google Maven. Leia Como desenvolver plug-ins personalizados do Gradle para saber mais sobre como os IDs de plug-in funcionam.

Fazer a refatoração

Depois de saber os IDs dos plug-ins que você usa, siga estas etapas:

1. Se você ainda tiver repositórios para plug-ins declarados no bloco buildscript {}, mova-os para o arquivo settings.gradle.

2. Adicione os plug-ins ao bloco plugins {} no arquivo build.gradle de nível superior. É necessário especificar o ID e a versão do plug-in aqui. Se o plug-in não precisar ser aplicado ao projeto raiz, use apply false.

3. Remova as entradas classpath do arquivo build.gradle.kts de nível superior.

4. Aplique os plug-ins adicionando-os ao bloco plugins {} no arquivo build.gradle do módulo. Você só precisa especificar o ID do plug-in aqui porque a versão é herdada do projeto raiz.

5. Remova a chamada apply plugin do plug-in do arquivo build.gradle no nível do módulo.

Por exemplo, esta configuração usa o bloco buildscript {}:

// Top-level build.gradle file
buildscript {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:7.4.0")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0")
        ...
    }
}

// Module-level build.gradle file
apply(plugin: "com.android.application")
apply(plugin: "kotlin-android")

Esta é uma configuração equivalente usando o bloco plugins {}:

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.4.0' apply false
   id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   id 'org.jetbrains.kotlin.android'
   ...
}

// settings.gradle
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

Converter o bloco de plug-ins

A aplicação de plug-ins do bloco plugins {} é semelhante no Groovy e no Kotlin. O código a seguir mostra como aplicar plug-ins no Groovy quando você usa catálogos de versões:

// Top-level build.gradle file
plugins {
   alias libs.plugins.android.application apply false
   ...
}

// Module-level build.gradle file
plugins {
   alias libs.plugins.android.application
   ...
}

O código abaixo mostra como fazer o mesmo no Kotlin:

// Top-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application) apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   alias(libs.plugins.android.application)
   ...
}

O código a seguir mostra como aplicar plug-ins no Groovy quando você não usa catálogos de versões:

// Top-level build.gradle file
plugins {
   id 'com.android.application' version '7.3.0' apply false
   ...
}

// Module-level build.gradle file
plugins {
   id 'com.android.application'
   ...
}

O código abaixo mostra como fazer o mesmo no Kotlin:

// Top-level build.gradle.kts file
plugins {
   id("com.android.application") version "7.3.0" apply false
   ...
}

// Module-level build.gradle.kts file
plugins {
   id("com.android.application")
   ...
}

Para conferir mais detalhes sobre o bloco plugins {}, consulte Como aplicar plug-ins na documentação do Gradle.

Diversos

Para amostras de código Kotlin para outras funcionalidades, consulte as páginas de documentação abaixo:

• Se você tiver uma configuração do ProGuard, consulte Ativar redução, ofuscação e otimização.
• Se você tiver um bloco signingConfig {}, consulte Remover informações de assinatura dos arquivos de compilação.
• Se você usar propriedades de todo o projeto, consulte Configurar propriedades para todo o projeto.

Cuidado: embora o Gradle permita definir propriedades de todo o projeto no nível do módulo, evite fazer isso. Essa ação vincula os módulos que compartilham as propriedades. A vinculação de módulos dificulta a exportação posterior de um módulo como projeto independente e impede que o Gradle use a execução paralela de projetos para agilizar os builds que têm vários módulos.

Problemas conhecidos

No momento, um problema conhecido é que a velocidade de build pode ser mais lenta com o Kotlin do que com o Groovy.

Como informar problemas

Para conferir instruções sobre como fornecer as informações necessárias para fazer a triagem do problema, consulte Detalhes de ferramentas de build e bugs do Gradle. Em seguida, registre um bug usando o Issue Tracker público do Google.

Mais recursos

Para consultar um exemplo prático de arquivos de build do Gradle programados com Kotlin, consulte o app de exemplo Agora no Android no GitHub.