Build Type — o que é, configuração debug e release no Gradle

O que é Build Type?

Build Type é um elemento da configuração do Gradle em projetos Android que descreve os parâmetros de compilação e empacotamento do aplicativo. Cada Build Type é um conjunto nomeado de opções: debuggable (ativar depuração), minificationEnabled (ativar compressão de código), shrinkResources (ativar compressão de recursos), proguardFiles (arquivos de regras ProGuard), signingConfig (certificado de assinatura) e outros. Os Build Types são declarados no bloco android.buildTypes do arquivo build.gradle do módulo app.

A principal função do Build Type é separar o development workflow (compilação rápida, registros detalhados, depuração) do production release (código otimizado, tamanho mínimo, segurança). A compilação debug deve compilar em segundos e fornecer o máximo de informações ao desenvolvedor. A compilação release deve ser o mais rápida e compacta possível para os usuários. Build Type é uma configuração de infraestrutura, não relacionada à funcionalidade do aplicativo.

O Android Gradle Plugin cria automaticamente um source set para cada Build Type — o diretório src/<buildType>/ (por exemplo, src/debug/, src/release/). Os recursos, código e arquivos de manifesto colocados neste source set são aplicados apenas a esse tipo de compilação. Por exemplo, em src/debug/ pode ser colocado um AndroidManifest.xml com permissão de instalação via ADB, e em src/release/ sem ela. O source set do Build Type tem prioridade sobre o source set do Product Flavor.

Build Type vs Product Flavor

A diferença principal: Build Type responde à pergunta "como compilar?", enquanto Product Flavor responde a "o que compilar?". Build Type pode ser debug, release, staging. Product Flavor pode ser free, paid, enterprise. Build Type não altera a funcionalidade do aplicativo (não adiciona nem remove telas), Product Flavor altera. Build Type pode desativar o depurador e ativar a ofuscação, Product Flavor pode alterar o applicationId e os recursos. Ambos trabalham juntos: cada Build Type é combinado com cada Product Flavor para formar um Build Variant.

Build Types padrão: debug e release

Debug é o Build Type padrão criado pelo AGP. Ele tem debuggable=true, permitindo conectar o depurador, visualizar logs Log.d e usar o profiler do Android Studio. A minification está desativada, portanto a compilação é rápida. Em uma compilação debug, o applicationId recebe o sufixo ".debug" (se não sobrescrito), permitindo instalar a versão debug junto com a versão release no mesmo dispositivo. A compilação debug é assinada com um certificado do debug.keystore, que é criado automaticamente pelo Android SDK.

Release é o Build Type para publicar o aplicativo. debuggable=false, minificationEnabled=true (padrão), shrinkResources=true. O desenvolvedor deve especificar um signingConfig com um certificado de produção; caso contrário, a compilação não será considerada release. A compilação release utiliza ProGuard ou R8 para ofuscação, otimização e compressão de código. O Android Studio não pode conectar o depurador a uma compilação release (se debuggable=false). Todas as chamadas Log.d e Log.v são removidas do código durante a minification se as regras ProGuard apropriadas forem configuradas.

Importante: compilações debug não testam o comportamento de release. A minification pode alterar o comportamento do código — reflection, serialização, Gson/SQLite e outras bibliotecas frequentemente exigem regras ProGuard. Portanto, sempre compile e teste uma compilação release antes de publicar. O Google Play Console e o Firebase Test Lab permitem enviar compilações release para testes automatizados em dispositivos reais antes da publicação.

android {
    buildTypes {
        debug {
            debuggable true
            minification false
            signingConfig signingConfigs.debug
            versionNameSuffix "-debug"
        }

        release {
            debuggable false
            minification true
            shrinkResources true
            proguardFiles "proguard-rules.pro"
            signingConfig signingConfigs.release
            ndk { abiFilters "arm64-v8a", "x86_64" }
        }
    }
}

Criação de Build Types personalizados

Herança via initWith

Além de debug e release, podem ser criados Build Types personalizados — por exemplo staging (ambiente intermediário) ou benchmark (para testes de desempenho). Um Build Type personalizado é declarado no bloco buildTypes da mesma forma que debug e release. O nome pode ser qualquer um, mas é recomendável usar nomes semanticamente claros em inglês. Para staging, geralmente define-se debuggable=true (para diagnosticar problemas no ambiente staging) e minification=true (para testar a ofuscação antes da produção).

Um Build Type personalizado obtém automaticamente um source set correspondente (src/staging/) e gera tarefas como assembleStaging. O AGP não impõe limites no número de tipos personalizados, mas cada novo tipo multiplica o número de Build Variants. O limite prático é de 4 a 5 Build Types: debug, staging, benchmark, release e possivelmente debugMinified (debug com minification ativada para testar regras ProGuard).

Para um Build Type personalizado, você pode herdar debuggable de debug usando initWith. A palavra-chave initWith copia todos os parâmetros do Build Type especificado, após o que podem ser sobrescritos. Isso é conveniente para criar staging baseado em debug: initWith debug + ativar adicionalmente minification. Sem initWith, você teria que listar manualmente todos os parâmetros do tipo base.

android {
    buildTypes {
        staging {
            initWith debug
            minification true
            shrinkResources true
            proguardFiles "staging-proguard-rules.pro"
            versionNameSuffix "-staging"
        }

        benchmark {
            initWith release
            signingConfig signingConfigs.debug
            matchingFallbacks = ["release"]
        }
    }
}

// matchingFallbacks — para bibliotecas que não têm um tipo benchmark
// se a biblioteca só tem release — o AGP usa esse

Configuração de assinatura para diferentes tipos de compilação

SigningConfig determina qual certificado é usado para assinar o APK ou AAB. O Android exige que todos os aplicativos instaláveis sejam assinados — sem isso, o sistema não permitirá a instalação. Para compilações debug, o AGP usa debug.keystore — um certificado pré-instalado com uma senha conhecida gerado pelo Android SDK Tools. Para compilações release, você deve criar seu próprio certificado através do Android Studio (Build → Generate Signed Bundle/APK) ou via linha de comando keytool.

O armazenamento de chaves de assinatura é um aspecto crítico de segurança. Recomenda-se não armazenar chaves release no repositório de código fonte. Em vez disso, use um arquivo keystore.properties (adicionado ao .gitignore), variáveis de ambiente de CI/CD ou o armazenamento criptografado do Android Studio. Em CI/CD (GitHub Actions, GitLab CI), as chaves de assinatura são armazenadas em secrets e passadas ao build.gradle através de propriedades do sistema. Exemplo: storePassword = System.getenv("KEYSTORE_PASSWORD").

Cada Build Type pode referenciar seu próprio signingConfig. Para release — um certificado de produção, para debug — debug.keystore, para staging — um certificado de staging separado. A configuração de assinatura afeta diretamente a capacidade de instalar o aplicativo: se você assinar debug com debug.keystore e staging com uma chave de produção, o staging não pode ser instalado sobre a versão debug devido à incompatibilidade de assinaturas. O applicationId também deve diferir — use applicationIdSuffix para isso.

android {
    signingConfigs {
        debug {
            storeFile file("debug.keystore")
            storePassword "android"
            keyAlias "androiddebugkey"
            keyPassword "android"
        }
        release {
            storeFile file("release-key.jks")
            storePassword System.getenv("KEYSTORE_PASS")
            keyAlias "my-key"
            keyPassword System.getenv("KEY_PASS")
        }
    }

    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

Minification, ProGuard e R8

Resource Shrinking

Minification é o processo de remover código não utilizado e renomear classes, métodos e campos para nomes curtos. O AGP realiza a minification com ProGuard (legado) ou R8 (recomendado, integrado ao AGP desde a versão 3.4). O R8 realiza quatro operações: shrinking (remoção de classes não utilizadas), optimization (simplificação de código), obfuscation (renomeação) e preverify (adição de informações de compatibilidade). O resultado é um APK menor e mais difícil de descompilar.

As regras de minification são definidas em arquivos de regras ProGuard — arquivos de texto com sintaxe como -keep, -dontwarn, -keepclassmembers. Sem regras, o R8 removerá ou renomeará classes usadas através de reflection (Gson, Retrofit, Room, serialização Kotlin). O modelo de projeto do Android Studio cria um arquivo proguard-rules.pro onde as regras para bibliotecas específicas são adicionadas. As bibliotecas também podem conter regras integradas — elas são incluídas automaticamente do jar/aar.

Shrink resources (shrinkResources=true) remove recursos não utilizados do APK. O R8 primeiro determina quais recursos não são usados no código (verifica R.java e referências do manifesto) e depois os remove da compilação final. Para recursos usados através de getIdentifier() ou por bibliotecas de terceiros, você precisa adicionar tools:keep="@layout/my_layout" nos recursos. Combinado com minification, o resource shrinking pode reduzir o tamanho do APK em 40-60%.

# proguard-rules.pro — regras obrigatórias
# Gson: manter classes para serialização
-keepclassmembers class com.example.** {
    <fields>;
}

# Retrofit: manter interfaces de API
-keep,allowobfuscation interface com.example.api.*

# Room: manter DAO e Entity
-keep class * extends androidx.room.RoomDatabase
-keep @interface androidx.room.** { *; }

# Kotlin Coroutines: evitar remoção de Continuation
-keepnames class kotlinx.coroutines.internal.*

# OkHttp: preservar o service loader
-keep class okhttp3.** { *; }

BuildConfigField e recursos para Build Type

BuildConfig é uma classe Java/Kotlin gerada automaticamente que contém constantes definidas em defaultConfig, productFlavors e buildTypes. Através de buildConfigField podem ser adicionados campos personalizados: buildConfigField "String", "API_URL", '"https://api.example.com"'. Um BuildConfigField declarado em buildType está disponível em todas as variantes desse tipo. Os valores em buildType sobrescrevem os valores de productFlavor, que por sua vez sobrescrevem defaultConfig.

Para compilações debug, é conveniente definir API_URL para localhost ou um servidor staging, e para release — para produção. BuildConfig.FLAVOR e BuildConfig.BUILD_TYPE também são gerados automaticamente e contêm o nome do flavor e do build type atuais. No código, pode-se usar: if (BuildConfig.DEBUG) { /* logs */ } — a constante DEBUG é verdadeira apenas para o build type debug. BuildConfig.DEBUG é um campo padrão que o AGP adiciona a cada BuildConfig.

Os recursos para Build Type são definidos através do source set src/<buildType>/res/. Por exemplo, src/debug/res/values/strings.xml pode conter a string "Server: Dev", enquanto src/release/res/ pode conter "Server: Prod". Os recursos do manifesto também são sobrescritos através do source set: src/debug/AndroidManifest.xml pode incluir <uses-permission android:name="android.permission.INTERNET" /> apenas para compilações debug. Isso é mais limpo do que verificar BuildConfig no código e funciona até para atributos que não podem ser definidos programaticamente (como networkSecurityConfig).

// src/debug/kotlin/.../DebugConfig.kt
object DebugConfig {
    val apiUrl = "http://localhost:8080/api"
    val enableLogging = true
    val enableCrashReporting = false
}

// src/release/kotlin/.../ReleaseConfig.kt
object ReleaseConfig {
    val apiUrl = "https://api.production.com/v2"
    val enableLogging = false
    val enableCrashReporting = true
}

// Uso: a classe principal carrega Config via reflection
fun getConfig(): AppConfig = when (BuildConfig.BUILD_TYPE) {
    "debug" -> DebugConfig
    else -> ReleaseConfig
}