O Plug-in do Android para Gradle 4.0 adicionou suporte ao uso de Kotlin no build do Gradle configuração para substituir o Groovy, a linguagem de programação usada tradicionalmente em arquivos de configuração do Gradle.
O Kotlin tem preferência sobre o Groovy para escrever scripts do Gradle porque ele é mais legível e oferece melhor verificação de tempo de compilação e suporte ao ambiente de desenvolvimento integrado.
Embora o Kotlin ofereça uma integração melhor com o código do Android Studio, editor quando comparado ao Groovy, os builds que usam Kotlin tendem a ser mais lentos do que cria usando o Groovy, então considere o desempenho ao decidir migram.
Esta página fornece informações básicas sobre como converter o código do seu app Android Arquivos de build do Gradle do Groovy para o Kotlin. Para uma migração mais abrangente consulte a documentação documentação oficial.
Cronograma
No Android Studio Giraffe e versões mais recentes, os novos projetos usam a DSL do Kotlin.
(build.gradle.kts
) por padrão para a configuração do build. Isso oferece uma abordagem
de edição do que a DSL do Groovy (build.gradle
) com sintaxe
destaque, preenchimento de código e navegação para declarações. Para saber mais,
consulte
Gradle Kotlin DSL Primer (link em inglês).
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 do Kotlin" são usados alternadamente. Da mesma forma, "Groovy" e "Groovy DSL" são usados alternadamente.
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
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
A DSL do Groovy permite omitir o operador de atribuição =
quando
atribuindo propriedades, enquanto o Kotlin exige isso. 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()
emproject
, não emproject.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
. Renomear o arquivo como
settings.gradle.kts
e converta o conteúdo do arquivo 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. Você pode tem uma mistura de arquivos de build do Kotlin e do Groovy em um projeto, então reserve um tempo para fazer a mudança 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 em 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 usa o
buildscript {}
para adicionar plug-ins ao projeto, você deve refatorar para usar o
plugins {}
bloco de anúncios. O bloco plugins {}
facilita a aplicação de plug-ins e
funciona bem com
catálogos de versões.
Além disso, ao usar 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
realizar o preenchimento de código e fornecer outras sugestões úteis.
Encontrar os IDs dos plug-ins
Já o bloco buildscript {}
adiciona os plug-ins ao caminho de classe do 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 do plug-in é a string usada quando você os aplica usando
apply plugin
: Por exemplo, os IDs de plug-in a seguir fazem parte de
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 na Repositório Maven do Google.
Os plug-ins do Kotlin podem ser referenciados por vários IDs de plug-in. Recomendamos o uso do o ID do plug-in com namespace e refatorar de abreviação para ID de plug-in com namespace tabela a seguir:
IDs de plug-ins abreviados | IDs de plug-ins 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 |
Você também pode pesquisar plug-ins na Portal do plug-in do Gradle, o Repositório Central do Maven e o Repositório Maven do Google. Lida Como desenvolver plug-ins personalizados do Gradle para saber mais sobre como funcionam os IDs de plug-ins.
Executar a refatoração
Assim que você souber os IDs dos plug-ins que usa, execute as seguintes etapas:
Se você ainda tiver repositórios para plug-ins declarados no
buildscript {}
bloqueie-os, mova-os parasettings.gradle
.Adicione os plug-ins ao bloco
plugins {}
no nível superior arquivobuild.gradle
. Você precisa especificar o ID versão do plug-in aqui. Se o plug-in não precisar ser aplicada ao projeto raiz, useapply false
.Remova as entradas
classpath
do arquivobuild.gradle.kts
de nível superior.Aplique os plug-ins adicionando-os ao bloco
plugins {}
na arquivobuild.gradle
de nível de módulo. Você só precisa especificar o nome aqui porque a versão é herdada do projeto raiz.Remova a chamada
apply plugin
para o plug-in do nível do módulo. arquivobuild.gradle
.
Por exemplo, essa 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 estiver usando
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 está. usando 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 mais detalhes sobre o bloco plugins {}
, consulte Aplicando
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.
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 ver um exemplo funcional de arquivos de build do Gradle programados com Kotlin, consulte a App de exemplo Now in Android (link em inglês) no GitHub.