--- title: "Gradle Plugin em Kotlin: O que É e Como Funciona | Kotlin Brasil" url: "https://kotlin.dev.br/glossario/gradle-plugin/" markdown_url: "https://kotlin.dev.br/glossario/gradle-plugin.MD" description: "Aprenda o que são Gradle Plugins no ecossistema Kotlin, como configurar builds e automatizar tarefas de compilação." date: "2025-08-09" author: "Karina Melo" --- # Gradle Plugin em Kotlin: O que É e Como Funciona | Kotlin Brasil Aprenda o que são Gradle Plugins no ecossistema Kotlin, como configurar builds e automatizar tarefas de compilação. ## O que é Gradle Plugin em Kotlin? Um **Gradle Plugin** é um modulo que estende as capacidades do sistema de build **Gradle**, adicionando tarefas, configurações e convenções ao projeto. No ecossistema Kotlin, o plugin mais importante é o **Kotlin Gradle Plugin** (`org.jetbrains.kotlin.jvm`, `org.jetbrains.kotlin.multiplatform`, etc.), que ensina o Gradle a compilar código Kotlin. Alem do plugin oficial do Kotlin, existem dezenas de plugins que automatizam tarefas comuns: serialização, geracaco de código, análise estática, publicacao de bibliotecas é muito mais. ### Aplicando o Kotlin Gradle Plugin A forma moderna de aplicar plugins usa o bloco `plugins` no `build.gradle.kts`: ```kotlin plugins { kotlin("jvm") version "1.9.22" } repositories { mavenCentral() } dependencies { implementation(kotlin("stdlib")) testImplementation(kotlin("test")) } ``` Para projetos Android: ```kotlin plugins { id("com.android.application") kotlin("android") version "1.9.22" } ``` Para projetos multiplataforma: ```kotlin plugins { kotlin("multiplatform") version "1.9.22" } kotlin { jvm() iosArm64() iosSimulatorArm64() sourceSets { commonMain.dependencies { implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3") } } } ``` ### Plugins comuns no ecossistema Kotlin O ecossistema Kotlin tem vários plugins essenciais: ```kotlin plugins { kotlin("jvm") version "1.9.22" kotlin("plugin.serialization") version "1.9.22" // kotlinx.serialization id("com.google.devtools.ksp") version "1.9.22-1.0.17" // KSP id("org.jetbrains.compose") version "1.5.12" // Compose Multiplatform } ``` Cada plugin adiciona funcionalidades específicas: - **kotlin-serialization**: gera código de serialização em tempo de compilação. - **KSP (Kotlin Symbol Processing)**: processa anotações e gera código. - **Compose**: habilita o compilador do Jetpack Compose. ### Criando um Gradle Plugin customizado Você pode criar seus próprios plugins para automatizar tarefas específicas do projeto. A forma mais simples e um plugin no `buildSrc`: ```kotlin // buildSrc/src/main/kotlin/MeuPlugin.kt import org.gradle.api.Plugin import org.gradle.api.Project class MeuPlugin : Plugin { override fun apply(projeto: Project) { projeto.tasks.register("saudacao") { group = "custom" description = "Exibe uma saudacao" doLast { println("Ola do MeuPlugin!") } } } } ``` ```kotlin // buildSrc/build.gradle.kts plugins { `kotlin-dsl` } repositories { mavenCentral() } ``` ```kotlin // build.gradle.kts (no projeto principal) plugins { id("meu-plugin") // Registrado automaticamente pelo buildSrc } ``` ### Plugin com extension (configuração customizada) Plugins mais sofisticados usam extensions para permitir configuração: ```kotlin // Definir a extension open class MinhaConfiguracao { var nomeDoApp: String = "MeuApp" var versao: String = "1.0.0" var habilitarLogs: Boolean = false } class PluginConfiguravelPlugin : Plugin { override fun apply(projeto: Project) { val config = projeto.extensions.create("minhaConfig", MinhaConfiguracao::class.java) projeto.afterEvaluate { projeto.tasks.register("info") { doLast { println("App: ${config.nomeDoApp}") println("Versão: ${config.versao}") println("Logs: ${config.habilitarLogs}") } } } } } ``` Uso no `build.gradle.kts`: ```kotlin minhaConfig { nomeDoApp = "KotlinBrasil" versao = "2.0.0" habilitarLogs = true } ``` ### Convention Plugins Uma prática moderna e criar convention plugins que padronizam configurações em projetos multi-modulo: ```kotlin // build-logic/convention/src/main/kotlin/kotlin-library-convention.gradle.kts plugins { kotlin("jvm") } kotlin { jvmToolchain(17) } tasks.withType { useJUnitPlatform() } dependencies { testImplementation(kotlin("test")) } ``` ```kotlin // Qualquer modulo do projeto plugins { id("kotlin-library-convention") } // Automaticamente herda todas as configurações do convention plugin ``` Isso evita duplicacao de configuração entre modulos e garante consistencia. ### Version Catalogs com plugins O Gradle Version Catalog centraliza versões de dependências e plugins: ```toml # gradle/libs.versions.toml [versions] kotlin = "1.9.22" ksp = "1.9.22-1.0.17" [plugins] kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" } kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" } ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" } ``` ```kotlin // build.gradle.kts plugins { alias(libs.plugins.kotlin.jvm) alias(libs.plugins.kotlin.serialization) } ``` ### Quando usar Gradle Plugins - **Compilação de Kotlin**: o plugin `kotlin-jvm` ou `kotlin-multiplatform` e obrigatório para compilar Kotlin. - **Geracao de código**: plugins como KSP e serialization geram código em tempo de compilação, evitando boilerplate. - **Padronizacao**: convention plugins garantem que todos os modulos de um projeto seguem as mesmas regras. - **Automação**: tarefas repetitivas como publicacao, geracao de documentação e análise de código podem ser automatizadas com plugins. - **Integração**: plugins conectam o build a ferramentas externas como Docker, Kubernetes, AWS. ### Casos de Uso no Mundo Real 1. **configuração padronizada em projetos multi-modulo**: empresas com dezenas de modulos Kotlin usam convention plugins para garantir que todos os modulos compartilhem a mesma versão do JDK, as mesmas regras de compilação e as mesmas dependências de teste. Isso elimina duplicacao de configuração e reduz erros causados por inconsistencias entre modulos. 2. **Geracao automatica de código com KSP**: projetos que usam bibliotecas como Room, Moshi ou Hilt aplicam o plugin KSP para processar anotacoes e gerar código em tempo de compilação. O plugin elimina boilerplate manual e garante que o código gerado esteja sempre sincronizado com as definicoes das anotacoes. 3. **Pipeline de CI/CD com publicacao automatizada**: plugins customizados automatizam o processo de versionamento, geracao de changelogs e publicacao de artefatos no Maven Central ou em repositórios privados. Um único comando `./gradlew publish` executa todo o pipeline configurado pelo plugin. 4. **Analise estática e qualidade de código**: plugins como Detekt e Ktlint sao aplicados para impor regras de estilo e detectar problemas de código em tempo de build. Eles podem ser configurados para falhar o build quando violacoes criticas sao encontradas, garantindo a qualidade do código antes do merge. ### Boas Praticas - Utilize Version Catalogs (`libs.versions.toml`) para centralizar todas as versões de plugins e dependências em um único arquivo. Isso facilita atualizações e garante consistencia entre modulos do projeto. - Crie convention plugins no diretorio `build-logic` para configuracoes reutilizaveis em vez de duplicar blocos de configuração em cada `build.gradle.kts`. Isso segue o princípio DRY e facilita a manutenção. - Verifique a matriz de compatibilidade entre versões do Kotlin Gradle Plugin, KSP e outros plugins antes de atualizar. Incompatibilidades entre versões sao uma das causas mais frequentes de falhas de build. - Habilite o build cache e a compilação incremental do Kotlin para acelerar builds. Configure `kotlin.incremental=true` e `org.gradle.caching=true` no `gradle.properties`. - Prefira a DSL `plugins {}` com type-safe accessors em vez da sintaxe legada `apply plugin`. A DSL moderna oferece autocompletar no IDE, verificação de tipos e melhor legibilidade. ### Perguntas Frequentes **P: Qual a diferenca entre um plugin aplicado com `kotlin("jvm")` e `id("org.jetbrains.kotlin.jvm")`?** R: Sao equivalentes. A função `kotlin("jvm")` e um atalho (sugar syntax) fornecido pelo Gradle que se expande para `id("org.jetbrains.kotlin.jvm")`. Ambas as formas aplicam exatamente o mesmo plugin. A forma curta e mais legivel e preferida pela comunidade. **P: Quando devo criar um plugin customizado em vez de usar scripts de build?** R: Crie um plugin customizado quando a lógica de build precisa ser reutilizada em múltiplos projetos ou modulos, quando a configuração e complexa o suficiente para se beneficiar de testes unitarios, ou quando você quer distribuir a lógica como um artefato independente. Para lógica simples e específica de um projeto, scripts no `buildSrc` ou `build-logic` sao suficientes. **P: O que e buildSrc e como ele se compara a build-logic?** R: O `buildSrc` e um diretorio especial reconhecido automaticamente pelo Gradle, cujo código e compilado antes de qualquer script de build. O `build-logic` (ou `build-conventions`) e um included build configurado manualmente que oferece mais flexibilidade, como a possibilidade de cachear a compilação e evitar invalidacao de todo o build quando o código muda. Projetos modernos preferem `build-logic` com included builds. **P: Como posso depurar problemas causados por plugins do Gradle?** R: Use `./gradlew build --info` ou `--debug` para logs detalhados. O comando `./gradlew buildEnvironment` mostra todos os plugins aplicados e suas versões. Para conflitos de dependência, `./gradlew dependencies` exibe a arvore completa. Tambem e possível executar o build com `--scan` para gerar um relatorio interativo no Gradle Build Scan. ### Erros comuns 1. **Versão incompativel entre plugins**: o Kotlin Gradle Plugin, KSP e outros plugins precisam ter versões compatíveis. Verifique a matriz de compatibilidade antes de atualizar. 2. **Aplicar plugins na ordem errada**: em projetos Android, o plugin Android deve ser aplicado antes do Kotlin. A ordem dos plugins pode afetar o comportamento do build. 3. **Usar `apply` em vez de `plugins`**: a sintaxe antiga `apply plugin: 'kotlin'` ainda funciona, mas a DSL `plugins { }` e type-safe e preferida. 4. **Configurar o plugin fora do bloco correto**: cada plugin tem seu bloco de configuração específico. Configurar no lugar errado causa erros silenciosos ou inesperados. 5. **Nao cachear builds**: o Kotlin Gradle Plugin suporta incremental compilation e build cache. Nao configurar isso pode deixar o build muito mais lento do que necessário. ### Tarefas úteis do Kotlin Gradle Plugin ```bash # Compilar o projeto ./gradlew compileKotlin # Executar testes ./gradlew test # Verificar dependências ./gradlew dependencies # Limpar e reconstruir ./gradlew clean build ``` ### Termos relacionados - **KSP (Kotlin Symbol Processing)**: plugin para processamento de anotações e geracao de código em Kotlin. - **Kotlin Multiplatform**: plugin que habilita compilação para múltiplas plataformas. - **Serialization**: plugin que gera serializadores em tempo de compilação. - **buildSrc**: diretorio especial do Gradle para lógica de build compartilhada. - **Version Catalog**: sistema de gerenciamento centralizado de versões de dependências e plugins. - **Convention Plugin**: plugin que padroniza configurações entre modulos de um projeto. Gradle Plugins são a espinha dorsal do sistema de build no ecossistema Kotlin. Entender como aplica-los, configura-los e, quando necessário, cria-los, e uma habilidade essencial para qualquer desenvolvedor Kotlin que trabalhe em projetos profissionais.