build.gradle: o que é, sintaxe e configuração no Android

O que é build.gradle?

build.gradle é um script de compilação na linguagem Groovy (extensão .gradle) ou Kotlin (.gradle.kts) que gerencia todos os aspetos da compilação de uma aplicação Android. Gradle é um sistema de compilação automática adotado pelo Google em 2013 como padrão para Android. build.gradle descreve: quais plugins estão aplicados (Android, Kotlin, bibliotecas), quais dependências estão conectadas, quais versões de SDK são usadas, como assinar a aplicação e onde publicar.

O processo de compilação inclui três fases: Initialization (descoberta de módulos), Configuration (execução de scripts build.gradle), Execution (execução de tarefas). build.gradle é executado durante a fase Configuration, quando o Gradle cria o grafo de tarefas. Neste momento, os Build Variants são determinados, as dependências são calculadas e as tarefas são configuradas. Importante: build.gradle é código, não apenas configuração. Nele podem ser usadas condições, loops, chamadas de métodos e scripts externos.

Os ficheiros Gradle são armazenados na raiz do módulo (app/build.gradle) e na raiz do projeto (build.gradle). Além disso, o Gradle suporta apply from — inclusão de scripts Gradle externos. Isso permite extrair lógica repetitiva em ficheiros com configurações partilhadas. Com o advento dos Convention Plugins (AGP 7+), apply from é considerado obsoleto — os Convention Plugins fornecem uma forma type-safe e composável de reutilizar configuração entre módulos.

Evolução do build.gradle

Desde 2013, a sintaxe do build.gradle passou por mudanças significativas: do Groovy com configurações dinâmicas ao Kotlin DSL com verificações em tempo de compilação. O AGP evoluiu da versão 1.0 para 8.7 (2025). Marcos principais: AGP 3.0 (Java 8 desugar, nova variant API), AGP 4.0 (view binding, Java 11), AGP 7.0 (Kotlin DSL por padrão, Java 11 mínimo), AGP 8.0 (classes R não transitivas, build config em Kotlin), AGP 8.7 (KSP em vez de kapt, configuração rápida).

Project-level e Module-level build.gradle

Project-level build.gradle (raiz) define plugins, repositórios e configurações comuns a todos os módulos. Blocos principais: plugins (declarações de plugins Gradle), repositories (fontes de dependências: mavenCentral, google, jitpack). O build.gradle raiz normalmente não tem bloco android — ele aparece nos módulos. O Project-level pode também conter um bloco subprojects para configuração comum de todos os subprojetos, embora os Convention Plugins sejam preferíveis.

Module-level build.gradle (por exemplo, app/build.gradle) descreve um módulo específico. Se o módulo for uma aplicação, aplica o plugin com.android.application. Se for uma biblioteca — com.android.library. O Module-level contém: bloco android (compileSdk, defaultConfig, buildTypes, productFlavors), bloco dependencies (dependências do módulo) e opcionalmente blocos para configuração de testes e empacotamento. O Module-level é executado após o project-level e pode sobrescrever configurações comuns.

A partir do AGP 8.0, o build.gradle raiz pode usar version catalogs (libs.versions.toml) para gestão centralizada de versões de dependências. Um version catalog é um ficheiro no diretório gradle/ que contém versões, bibliotecas e plugins. No build.gradle, as dependências são conectadas através de libs: implementation(libs.retrofit). Os version catalogs são obrigatórios para novos projetos e recomendados para todos os projetos com três ou mais módulos.

// settings.gradle.kts — raiz do projeto
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (project-level)
plugins {
    id("com.android.application") version "8.7.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
}

// app/build.gradle.kts (module-level)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp")
}

android {
    namespace = "com.example.myapp"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 1
        versionName = "1.0.0"
    }
}

Groovy vs Kotlin DSL

Groovy é uma linguagem JVM dinâmica que foi a sintaxe original do Gradle. Os scripts Groovy (.gradle) usam tipagem dinâmica: podem-se omitir tipos, usar strings com ou sem aspas, chamar métodos que não existem em tempo de compilação. A flexibilidade do Groovy é também o seu defeito: o IDE não pode verificar sintaxe e tipos até o script ser executado, levando a erros em tempo de execução devido a nomes de parâmetros ou tipos incorretos.

Kotlin DSL (.gradle.kts) usa a tipagem estática do Kotlin. O IDE verifica tipos, sugere parâmetros disponíveis através de autocompleção e realça erros em tempo de edição. O Kotlin DSL é mais lento durante a fase Configuration (devido à compilação de ficheiros .kts para bytecode), mas o Google melhora continuamente o desempenho: o AGP 8.5+ usa Gradle Configuration Cache e Caching Kotlin DSL compilation, reduzindo a diferença para 1-2 segundos.

O Google recomenda Kotlin DSL para todos os novos projetos e a migração gradual dos existentes. A migração de Groovy para Kotlin DSL é direta: as aspas são substituídas por parênteses, os tipos são adicionados, os operadores são convertidos em funções. A maioria das bibliotecas fornece exemplos de Kotlin DSL na sua documentação. Para casos complexos (Custom Plugin, Task Graph), o Kotlin DSL fornece uma API type-safe e previne erros que no Groovy só são descobertos em tempo de execução. Os version catalogs (libs.versions.toml) funcionam igualmente com ambas as sintaxes.

Bloco android: configuração da aplicação

compileSdk, minSdk e targetSdk

Bloco android é o elemento central do module-level build.gradle. Dentro dele são configurados: namespace (para R e BuildConfig), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Todos os parâmetros do bloco android aplicam-se apenas a módulos Android. Se o módulo for uma biblioteca, usa-se o plugin de biblioteca em vez de application, e applicationId está ausente do bloco android.

compileSdk é a versão do SDK com a qual o código é compilado. Deve ser a última API Android (no momento da escrita — 35). minSdk é a versão mínima de API suportada. targetSdk é a versão que a aplicação alvo (as alterações comportamentais desta versão são aplicadas). A diferença entre compileSdk e targetSdk: compileSdk determina as APIs disponíveis, targetSdk determina o comportamento em tempo de execução. Recomendação: compileSdk = latest, targetSdk = latest - 1 (para testar a adaptação a novas alterações).

compileOptions define a compatibilidade Java: sourceCompatibility e targetCompatibility. O AGP 8+ requer Java 17+ para compilação. packaging gere a inclusão de ficheiros de bibliotecas: exclude, merge, pickFirst para resolver conflitos META-INF. buildFeatures ativa/desativa ViewBinding, DataBinding, Compose. aaptOptions configura o processamento de recursos: ignoreAssetsPattern, cruncherEnabled. Cada elemento do bloco android otimiza um aspeto específico da compilação.

android {
    namespace = "com.example.myapp"
    compileSdk = 35
    buildToolsVersion = "35.0.0"

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 5
        versionName = "2.3.1"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        getByName("debug") { isDebuggable = true }
        getByName("release") {
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
        }
    }

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

    buildFeatures {
        viewBinding = true
        compose = true
    }
}

Gestão de dependências

BOM (Bill of Materials)

Dependências no build.gradle são bibliotecas e módulos conectados ao projeto. O bloco dependencies está ao mesmo nível que o bloco android. O Gradle suporta várias configurações: implementation (a biblioteca está disponível neste módulo, não transitiva), api (a biblioteca está transitivamente disponível para módulos dependentes), compileOnly (apenas para compilação, não incluída no APK), runtimeOnly (apenas em tempo de execução), annotationProcessor / ksp (processadores de anotações), testImplementation (apenas para testes), androidTestImplementation (apenas para testes instrumentados).

A partir do AGP 8.0, Classes R não transitivas — cada biblioteca tem a sua própria classe R, prevenindo conflitos de recursos. No bloco dependencies é importante usar as configurações corretas: implementation não expõe dependências transitivas, acelerando a compilação. api expõe-nas — usado quando uma biblioteca exporta tipos de outra biblioteca (por exemplo, Retrofit usa tipos OkHttp na sua API pública).

Para gestão de versões, recomenda-se usar BOM (Bill of Materials) — um ficheiro de compilação que define versões compatíveis de bibliotecas. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). Após conectar o BOM, pode-se especificar apenas o nome da biblioteca sem versão — o BOM selecionará automaticamente uma versão compatível. Isto elimina conflitos entre dependências transitivas de diferentes bibliotecas. Os BOM estão disponíveis para Firebase, Compose, Kotlin, Ktor, AndroidX.

dependencies {
    // BOM — gestão de versões
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX e Compose
    implementation("androidx.core:core-ktx")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx")
    implementation("androidx.activity:activity-compose")
    implementation("androidx.compose.ui:ui")

    // Network
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")

    // Firebase (versões do BOM)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // Testing
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

build.gradle em projetos multimódulo

Em projetos multimódulo, cada módulo tem o seu próprio build.gradle. Para conectar um módulo a outro, usa-se a sintaxe implementation(project(":module-name")). O Gradle recompila automaticamente o módulo se a sua configuração mudar. A arquitetura multimódulo melhora o tempo de compilação (compilação incremental, paralelismo) e separa responsabilidades entre módulos de funcionalidade, módulos principais e bibliotecas.

O problema principal dos projetos multimódulo é a duplicação de configuração. Se 10 módulos têm o mesmo minSdk, compileSdk e dependências Compose, são 10 cópias em diferentes build.gradle. A solução são os Convention Plugins (anteriormente buildSrc). Um Convention Plugin é um plugin Gradle escrito em Kotlin que é aplicado aos módulos: plugins { id("myapp.android.library") }. O plugin contém configuração comum e as alterações aplicam-se imediatamente a todos os módulos.

Para organizar os Convention Plugins, usa-se o diretório build-logic/ na raiz do projeto. Contém includeBuild no settings.gradle e plugins Kotlin. Os Convention Plugins podem ser publicados num repositório maven para reutilização entre projetos. O Google recomenda Convention Plugins como padrão para projetos multimódulo, substituindo subprojects { } e apply from. A migração para Convention Plugins reduz o build.gradle do módulo para 10-15 linhas.

// build-logic/src/main/kotlin/AndroidLibraryConventionPlugin.kt
class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            with(plugins) {
                apply("com.android.library")
                apply("org.jetbrains.kotlin.android")
            }
            extensions.configure<CommonExtension<*, *, *, *>> {
                compileSdk = 35
                defaultConfig { minSdk = 26 }
                compileOptions {
                    sourceCompatibility = JavaVersion.VERSION_17
                    targetCompatibility = JavaVersion.VERSION_17
                }
            }
        }
    }
}

// module/build.gradle.kts — após Convention Plugin
plugins {
    id("myapp.android.library")
}

dependencies {
    implementation(project(":core:network"))
}