Using Gradle

Editar Página

Para construir um projeto Kotlin com Gradle, você deve aplicar o plugin Kotlin Gradle ao seu projeto e configurar as dependências.

Plugin e versões

Aplique o plugin Kotlin Gradle usando os plugins Gradle DSL.

O plugin Kotlin Gradle 1.4.30 funciona com o Gradle 5.4 e posteriores. O kotlin-multiplatform plugin requer Gradle 6.0 ou posterior.

plugins { id 'org.jetbrains.kotlin.<...>' version '1.4.30'}

plugins { kotlin("<...>") version "1.4.30"}

O espaço reservado <...> deve ser substituído por um dos nomes dos plugins que podem ser encontrados em outras seções.

Apontando para múltiplas plataformas

Projetos voltados para múltiplas plataformas, chamados projetos multiplataforma, requerem o plugin kotlin-multiplatform. Saiba mais sobre o plugin.

>

O plugin funciona com o Gradle 6.0 ou superior.

>

plugins { id 'org.jetbrains.kotlin.multiplatform' version '1.4.30'}

>

plugins { kotlin("multiplatform") version "1.4.30"}

Apontando o JVM

>

Para apontar o JVM, aplique o plugin Kotlin JVM.

plugins { id "org.jetbrains.kotlin.jvm" version "1.4.30"}

plugins { kotlin("jvm") version "1.4.30"}

O version deve ser literal neste bloco, e não pode ser aplicado a partir de outro build script.

Alternativamente, você pode usar o mais antigo apply plugin approach:

apply plugin: 'kotlin'

Não é recomendado que você aplique plugins Kotlin com apply no Gradle Kotlin DSL – veja porque.

Kotlin e fontes Java

Fontes Kotlin podem ser armazenados com fontes Java na mesma pasta, ou colocados em pastas diferentes. A convenção padrão é usar pastas diferentes:

project - src - main (root) - kotlin - java

A propriedade correspondente sourceSets deve ser atualizada se não usar a convenção padrão:

sourceSets { main.kotlin.srcDirs += 'src/main/myKotlin' main.java.srcDirs += 'src/main/myJava'}

sourceSets.main { java.srcDirs("src/main/myJava", "src/main/myKotlin")}

Auto JavaScript

>

Quando o alvo for apenas JavaScript, use o plugin kotlin-js. Saiba mais

>

plugins { id 'org.jetbrains.kotlin.js' version '1.4.30'}

plugins { kotlin("js") version "1.4.30"}

>

Kotlin e fontes Java

>

Este plugin só funciona para ficheiros Kotlin por isso é recomendado que mantenha os ficheiros Kotlin e Java separadamente (no caso do projecto conter ficheiros Java). Se você não armazená-los separadamente , especifique a pasta de fontes no bloco sourceSets

kotlin { sourceSets { main.kotlin.srcDirs += 'src/main/myKotlin' }}

kotlin { sourceSets.apply { kotlin.srcDir("src/main/myKotlin") }}

Atenção do Android

É recomendável que você use o Android Studio para criar aplicativos Android. Saiba como usar o plugin Android Gradle.

Configurando dependências

Para adicionar uma dependência em uma biblioteca, defina a dependência do tipo necessário (por exemplo, implementation) no bloco dependencies do conjunto de fontes DSL.

kotlin { sourceSets { commonMain { dependencies { implementation 'com.example:my-library:1.0' } } }}

kotlin { sourceSets { val commonMain by getting { dependencies { implementation("com.example:my-library:1.0") } } }}

Alternativamente, você pode definir dependências no nível superior.

Tipos de dependência

Selecione o tipo de dependência com base nas suas necessidades.

Tipo	Descrição	Quando usar
api	Utilizado tanto durante a compilação como em tempo de execução e é exportado para os consumidores da biblioteca.	Se qualquer tipo de dependência for utilizado na API pública do módulo atual, utilize uma dependência api.
implementation	Usado durante a compilação e em tempo de execução do módulo atual, mas não é exposto para compilação de outros módulos, dependendo daquele com a dependência `implementação’.	Usado para dependências necessárias para a lógica interna de um módulo. Se um módulo é uma aplicação endpoint que não é publicada, use implementation dependências em vez de api dependências.
compileOnly	Usado para compilação do módulo atual e não está disponível em tempo de execução nem durante a compilação de outros módulos.	Usado para APIs que tenham uma implementação de terceiros disponível em tempo de execução.
runtimeOnly	Disponível em tempo de execução mas não é visível durante a compilação de qualquer módulo.

Dependência da biblioteca padrão

Uma dependência de uma biblioteca padrão (stdlib) em cada conjunto de fontes é adicionada automaticamente. A versão da biblioteca padrão é a mesma que a versão do plugin Kotlin Gradle.

Para conjuntos de fontes específicos da plataforma, a variante correspondente da biblioteca específica da plataforma é usada, enquanto uma biblioteca padrão comum é adicionada ao resto. O plugin Kotlin Gradle irá selecionar a biblioteca padrão JVM apropriada dependendo da opção kotlinOptions.jvmTarget do compilador do seu script de construção Gradle.

Se você declarar explicitamente uma dependência de biblioteca padrão (por exemplo, se você precisar de uma versão diferente), o plugin Kotlin Gradle não irá substituí-la ou adicionar uma segunda biblioteca padrão.

Se você não precisar de nenhuma biblioteca padrão, você pode adicionar o sinalizador de opção de exclusão a gradle.properties:

kotlin.stdlib.default.dependency=false

Definir dependências em bibliotecas de teste

A API kotlin.test está disponível para testar diferentes projetos do Kotlin.

Adicionar as dependências correspondentes nas bibliotecas de testes:

• Para commonTest, adicione as dependências kotlin-test-common e kotlin-test-annotations-common.
• Para alvos JVM, use kotlin-test-junit ou kotlin-test-testng para a implementação do asserter correspondente e mapeamento de anotações.
• Para alvos Kotlin/JS, adicione kotlin-test-js como dependência de teste.

Kotlin/Native targets não requerem dependências de teste adicionais, e as implementações kotlin.test API são incorporadas.

Pode usar o estenógrafo para uma dependência em um módulo Kotlin, por exemplo, kotlin(“test”) para “org.jetbrains.kotlin:kotlin-test”.

Definir uma dependência em uma biblioteca de kotlinx

Se você usar uma biblioteca de kotlinx e precisar de uma dependência específica de plataforma, você pode usar variantes de bibliotecas com sufixos como -jvm ou -js, por exemplo, kotlinx-coroutines-core-jvm. Você também pode usar o nome do artefato base da biblioteca – kotlinx-coroutines-core.

kotlin { sourceSets { jvmMain { dependencies { implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.4.2' } } }}

Se você usar uma biblioteca multiplataforma e precisar depender do código compartilhado, defina a dependência apenas uma vez no conjunto de códigos fonte compartilhados. Use o nome do artefato base da biblioteca, como kotlinx-coroutines-core ou ktor-client-core.

kotlin { sourceSets { commonMain { dependencies { implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.2' } } }}

Definir dependências no nível superior

Alternativamente, você pode especificar as dependências no nível superior com os nomes de configuração seguindo o padrão <sourceSetName><DependencyType>. Isso é útil para algumas dependências integradas ao Gradle, como gradleApi(), localGroovy(), ou gradleTestKit(), que não estão disponíveis nos conjuntos de origem da dependência DSL.

dependencies { commonMainImplementation 'com.example:my-library:1.0'}

dependencies { "commonMainImplementation"("com.example:my-library:1.0")}

Processamento de anotações

Kotlin suporta processamento de anotações através da ferramenta de processamento de anotações Kotlin kapt.

Compilação incremental

O plugin Kotlin Gradle suporta compilação incremental. A compilação incremental acompanha as alterações dos arquivos fonte entre os builds, assim apenas arquivos afetados por estas alterações seriam compilados.

A compilação incremental é suportada para os projetos Kotlin/JVM e Kotlin/JS e é habilitada por padrão desde Kotlin 1.1.1.

Existem várias maneiras de desabilitar a configuração:

• Adicionar a seguinte linha ao arquivo gradle.properties ou local.properties:
  • kotlin.incremental=false para Kotlin/JVM
  • kotlin.incremental.js=false para projetos Kotlin/JS

• Como parâmetro da linha de comando, use -Pkotlin.incremental=false ou -Pkotlin.incremental.js=false.

  Note que neste caso o parâmetro deve ser adicionado a cada build subsequente, e qualquer build com compilação incremental desabilitada invalida os caches incrementais.

Note que o primeiro build não é incremental em nenhum caso.

Suporte de cache de compilação Grade

O plugin Kotlin suporta cache de compilação Grade que armazena as saídas de compilação para reutilização em compilações futuras.

Para desativar o cache para todas as tarefas Kotlin, defina o flag de propriedade do sistema kotlin.caching.enabled para false (execute a compilação com o argumento -Dkotlin.caching.enabled=false).

Se você usar kapt, note que as tarefas de processamento de anotações kapt não estão em cache por padrão. Entretanto, você pode habilitar o cache para elas manualmente.

Suporte de cache de configuração Gradle

O cache de configuração está disponível no Gradle 6.5 e mais tarde como um recurso experimental.Você pode verificar a página de lançamentos do Gradle para ver se ele foi promovido para estável.

O plugin Kotlin suporta o cache de configuração Gradle,que acelera o processo de compilação reutilizando os resultados da fase de configuração.

Veja a documentação Gradle para aprender como habilitar o cache de configuração. Uma vez ativado o recurso de cache de configuração, o plugin Kotlin Gradle iniciará usando-o.

Opções do compilador

Para especificar opções adicionais de compilação, use a propriedade kotlinOptions de uma tarefa de compilação do Kotlin.

Quando se tem como alvo o JVM, as tarefas são chamadas de compileKotlin para código de produção e compileTestKotlin para código de teste. As tarefas para conjuntos de fontes personalizados são chamadas de acordo com o compile<Name>Kotlin pattern.

Os nomes das tarefas nos Projetos Android contêm os nomes das variantes de compilação e seguem o pattern compile<BuildVariant>Kotlin, por exemplo, compileDebugKotlin, compileReleaseUnitTestKotlin.

Ao apontar para JavaScript, as tarefas são chamadas de compileKotlinJs e compileTestKotlinJs respectivamente, e compile<Name>KotlinJs para conjuntos de fontes personalizados.

Para configurar uma única tarefa, use o seu nome. Exemplos:

compileKotlin { kotlinOptions.suppressWarnings = true}//orcompileKotlin { kotlinOptions { suppressWarnings = true }}

Note que com Gradle Kotlin DSL, você deve obter a tarefa do projeto tasks primeiro.

Utilizar os tipos Kotlin2JsCompile e KotlinCompileCommon para os alvos JS e Common, de acordo.

Também é possível configurar todas as tarefas de compilação do Kotlin no projeto:

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { kotlinOptions { /*...*/ }}

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach { kotlinOptions { /*...*/ }}

A lista completa de opções para as tarefas Gradle é a seguinte:

Tribuições comuns para a JVM, JS, e JS DCE

>

>

>

>

>

>

>

>

>

>

>

>

>

Nome	Descrição	Valores possíveis	Valor por defeito
>allWarningsAsErrors>	Relatar um erro se houver avisos		falso
>suppressWarnings>	Não gerar avisos		falso
verbose	>Enable verbose logging output		falso
freeCompilerArgs>	>Uma lista de argumentos adicionais do compilador		>

Tributos comuns para JVM e JS

Tributos específico para JVM

Nome	Descrição	Valores possíveis	Valor por defeito
javaParameters	Gerar metadados para Java 1.8 reflexão sobre os parâmetros do método		>falso
jdkHome>	>Incluir um JDK personalizado do local especificado para o classpath em vez do padrão JAVA_HOME
>jvmTarget	Versão alvo do bytecode JVM gerado	“1.6”, “1.8”, “9”, “10”, “11”, “12”, “13”, “14”, “15”	“1.6”
noJdk	Não incluir automaticamente o tempo de execução Java no classpath			>falso
noReflect	Não incluir automaticamente a reflexão de Kotlin no classpath		verdadeira
noStdlib		Não incluir automaticamente o reflexo Kotlin/JVM stdlib e Kotlin na classpath		verdadeira
useIR	Utilizar o backend IR		falso

Atributos específicos para o JS

>

>

>

>

>

>

>

Nome	Descrição	Valores possíveis	Valor por defeito
friendModulesDisabled	Exportação de declaração interna desactivada		falso
>main	Definir se a função main deve ser chamada aquando da execução	“chamada”, “noCall”	“call”
metaInfo	Gerar .meta.js e arquivos .kjsm com metadados. Use para criar uma biblioteca	>	>verdadeiro
moduleKind>	> O tipo de módulo JS gerado pelo compilador	“umd”, “commonjs”, “amd”, “plain”	“umd”
noStdlib	Não incluir automaticamente o Kotlin/JS stdlib padrão em dependências de compilação		verdadeira
outputFile	>Destino *.arquivo js para o resultado da compilação		“<buildDir>/js/packages/<project.name>/kotlin/<project.name>.js”
sourceMap	Gerar mapa de origem		>verdadeiro
sourceMapEmbedSources	Embutir arquivos de origem no mapa de origem	“nunca”, “sempre”, “inlining”
sourceMapPrefix	>Adicionar o prefixo especificado a caminhos no mapa de origem
target	Gerar ficheiros JS para versão ECMA específica	“v5”	“v5”
typedArrays	Translate primitive arrays to JS typed arrays		true

Gerar documentação

Gerar documentação para projetos Kotlin, usa o Dokka;por favor consulte o Dokka README para instruções de configuração. O Dokka suporta projetos em vários formatos, incluindo JavaDoc.

OSGi

Para suporte a OSGi veja a página Kotlin OSGi.

Usando Gradle Kotlin DSL

Ao usar Gradle Kotlin DSL, aplique os plugins Kotlin usando o bloco plugins { ... }. Se você aplicá-los com apply { plugin(...) }, você pode encontrar referências não resolvidas para as extensões geradas pelo Gradle Kotlin DSL. Para resolver isso, você pode comentar as utilizações erradas, executar a tarefa Gradle kotlinDslAccessorsSnapshot, depois descomentar as utilizações e executar novamente a compilação ou reimportar o projeto para o IDE.

.