settings.gradle: o que é, inclusão de módulos e pluginManagement

O que é settings.gradle?

settings.gradle (ou settings.gradle.kts para Kotlin DSL) é um arquivo que o Gradle executa durante a fase de Initialization. Ele define a hierarquia do projeto, inclui módulos e configura repositórios para plugins e dependências. Sem settings.gradle, o Gradle não sabe quais módulos compilar nem quais plugins estão disponíveis. Em um projeto de módulo único, settings.gradle pode estar ausente — o Gradle usa valores padrão, mas é obrigatório para projetos multimódulo.

O arquivo settings.gradle está localizado na raiz do projeto, junto com o build.gradle raiz. Uma estrutura típica de raiz do projeto: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle é executado antes do build.gradle — durante a fase de Initialization, o Gradle constrói a árvore do projeto (Project na API do Gradle). Após a Initialization, começa a Configuration — a execução do build.gradle de cada módulo.

Historicamente, settings.gradle apareceu no Gradle 0.7 (2010) e inicialmente continha apenas diretivas include. Com a evolução do Gradle, foram adicionados pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) e versionCatalogs (Gradle 7.4). O settings.gradle moderno é um arquivo de configuração poderoso que centraliza o gerenciamento de plugins, repositórios e versões para todo o projeto. O Google reforça essas capacidades no Android Gradle Plugin a partir do AGP 8.0.

settings.gradle vs build.gradle

settings.gradle gerencia a estrutura do projeto e as configurações globais (plugins, repositórios). build.gradle gerencia a compilação (dependências, configurações do Android, tarefas). settings.gradle é executado primeiro e tem acesso à API Settings. build.gradle é executado depois e tem acesso à API Project. Nenhuma configuração em nível de módulo (bloco android, dependencies) pode estar em settings.gradle — isso seria um erro.

Inclusão de módulos via include

A diretiva include é o núcleo do settings.gradle. Ela informa ao Gradle quais módulos devem participar da compilação. O argumento do include é uma string com o caminho do módulo: include(":app") inclui um módulo na raiz, include(":core:network") inclui um módulo no subdiretório core/network/. Os dois pontos no início indicam que o caminho é relativo à raiz do projeto. Após o include, o Gradle encontra automaticamente o build.gradle no diretório especificado e adiciona o módulo à árvore do projeto.

Cada include cria um Project na API do Gradle com o nome igual à string do include. O nome do projeto é usado em implementation(project(":module")) nos build.gradle de outros módulos. Se um módulo não estiver incluído via include, referenciá-lo a partir de outro módulo causará um erro “Project not found”. O Android Studio também usa settings.gradle para exibir os módulos no painel Project — módulos sem include não são visíveis na árvore de arquivos.

O include suporta included builds e composite builds via includeBuild("../library-project"). Isso permite incluir projetos Gradle completos como módulos externos. Os included builds são úteis para desenvolver bibliotecas em paralelo com o aplicativo: as alterações na biblioteca são imediatamente visíveis no aplicativo sem necessidade de publicar em um repositório Maven. Em uma compilação de produção, includeBuild é substituído por uma dependência Maven normal.

// settings.gradle.kts — estrutura típica
rootProject.name = "MyApp"

// Módulos do aplicativo
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Inclusão de uma biblioteca externa (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Bloco de gerenciamento de plugins

Estratégia de resolução

pluginManagement é um bloco no settings.gradle que determina de onde carregar os plugins do Gradle. Apareceu no Gradle 6.8 para gerenciamento centralizado de plugins antes de sua aplicação. Dentro do pluginManagement estão: repositories (lista de repositórios para encontrar plugins), resolutionStrategy (regras de resolução de versões) e plugins (declaração explícita de versões de plugins). Se pluginManagement não estiver definido, o Gradle usa os repositórios do build.gradle — mas os plugins são procurados somente após serem declarados, o que leva a erros se um plugin não for encontrado.

Em projetos Android, pluginManagement é obrigatório se forem usados Version Catalogs ou Convention Plugins. Sem pluginManagement, o Gradle não consegue encontrar o plugin com.android.application ao aplicá-lo no build.gradle.kts. Uma configuração típica: repositories contém google() (plugins Android), mavenCentral() (plugins de terceiros) e gradlePluginPortal() (plugins oficiais do Gradle).

pluginManagement também suporta plugins — declarar plugins com versões que são então aplicadas no build.gradle sem especificar a versão. Isso centraliza as versões dos plugins: se 10 módulos aplicam kotlin-android, a versão é especificada uma vez no pluginManagement. Importante: pluginManagement.plugins é apenas uma declaração. O plugin em si é aplicado no build.gradle via plugins { id("org.jetbrains.kotlin.android") }.

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        maven { url = "https://jitpack.io" }
    }

    // Versões de plugins — centralizadas
    plugins {
        id("com.android.application") version "8.7.0"
        id("com.android.library") version "8.7.0"
        id("org.jetbrains.kotlin.android") version "2.0.21"
        id("com.google.devtools.ksp") version "2.0.21-1.0.25"
    }

    resolutionStrategy {
        // Versão forçada de plugin para todos os módulos
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Aplicação de plugins — apply false (não aplicar à raiz)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Gerenciamento de resolução de dependências

Modos do repositoriesMode

dependencyResolutionManagement é um bloco no settings.gradle que gerencia centralizadamente os repositórios para todos os módulos. Apareceu no Gradle 7.0 como alternativa a declarar repositories em cada build.gradle. Dentro do bloco são definidos repositoriesMode (modo: PREFER_PROJECT, PREFER_SETTINGS ou FAIL_ON_PROJECT_REPOS) e repositories (lista de repositórios). Se repositoriesMode = PREFER_SETTINGS, os repositories dos módulos são ignorados — apenas a lista centralizada é usada.

repositoriesMode pode assumir três valores. PREFER_SETTINGS — os repositórios do build.gradle são ignorados, apenas os do settings.gradle são usados. PREFER_PROJECT — os repositórios do build.gradle têm prioridade sobre os do settings.gradle. FAIL_ON_PROJECT_REPOS — se um módulo declarar seus próprios repositórios, o Gradle lança um erro. Para novos projetos, recomenda-se PREFER_SETTINGS — garante que todos os módulos usem os mesmos repositórios e elimina a duplicação.

repositoriesMode = FAIL_ON_PROJECT_REPOS é especialmente útil em equipes: se um desenvolvedor adicionar um repositório a apenas um módulo e os outros não o virem, surge o problema “works on my machine”. FAIL_ON_PROJECT_REPOS força todos os repositórios a serem declarados centralizadamente no settings.gradle, evitando tais situações. O Google recomenda FAIL_ON_PROJECT_REPOS para todos os projetos Android a partir do AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — todos os repositórios apenas aqui
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

    repositories {
        google()
        mavenCentral()
        maven { url = "https://jitpack.io" }

        // Repositório Maven privado
        maven {
            url = "https://maven.pkg.github.com/company/internal-lib"
            credentials {
                username = providers.gradleProperty("gpr.user")
                    .getOrNull() ?: System.getenv("GPR_USER") ?: ""
                password = providers.gradleProperty("gpr.key")
                    .getOrNull() ?: System.getenv("GPR_KEY") ?: ""
            }
        }
    }
}

// No build.gradle do módulo, repositories não são mais necessários!
// Todos os repositórios centralizados no settings.gradle

Catálogos de versão no settings.gradle

Version Catalogs é uma forma centralizada de gerenciar versões de dependências através de um arquivo TOML. A partir do Gradle 7.4, os Catálogos de Versão são o mecanismo recomendado para todos os projetos Android. O arquivo gradle/libs.versions.toml contém três seções: [versions] (versões), [libraries] (dependências), [plugins] (plugins). No settings.gradle, o Catálogo de Versão é conectado via @Suppress("UnstableApiUsage") e enableFeaturePreview("VERSION_CATALOGS") (em versões antigas do Gradle).

Após conectar o Catálogo de Versão, as dependências dos módulos no build.gradle são especificadas via libs: implementation(libs.retrofit). O IDE fornece autocompletar para libs. O catálogo gera automaticamente accessors type-safe: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles são grupos de dependências que podem ser incluídos com uma única linha. Os Catálogos de Versão também suportam herança — vários arquivos TOML podem ser conectados.

Vantagens dos Catálogos de Versão: local único para versões (não é necessário procurar em todos os build.gradle); acesso type-safe (um erro no nome do libs é detectado na compilação, não em tempo de execução); atualizações automáticas (Dependabot e Renovate suportam TOML); compatibilidade com Convention Plugins. O Google Firebase e o AndroidX distribuem seus próprios catálogos TOML. Para migrar para Catálogos de Versão, existem plugins que transferem automaticamente as versões do build.gradle para TOML.

# gradle/libs.versions.toml
[versions]
agp = "8.7.0"
kotlin = "2.0.21"
composeBom = "2024.12.01"
retrofit = "2.11.0"
coroutines = "1.9.0"

[libraries]
retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
retrofit-gson = { module = "com.squareup.retrofit2:converter-gson", version.ref = "retrofit" }
kotlin-coroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
compose-bom = { module = "androidx.compose:compose-bom", version.ref = "composeBom" }
compose-ui = { module = "androidx.compose.ui:ui" }

[bundles]
compose = ["compose-ui", "compose-material3"]

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

Configurações avançadas: includeBuild e recursos incipientes

includeBuild é uma diretiva para criar um composite build: incluir um projeto Gradle externo como parte da compilação atual. Diferente de include (que inclui um módulo), includeBuild inclui um projeto completo com seu próprio settings.gradle, módulos e plugins. Os composite builds são usados para: desenvolver bibliotecas (analítica, rede) em paralelo com o aplicativo; incluir Convention Plugins de um repositório separado; integrar módulos build-logic.

Recursos incipientes (Incubating Features) são opções experimentais do Gradle que são ativadas via enableFeaturePreview("FEATURE_NAME"). No AGP 8.7+, estão disponíveis: TYPESAFE_PROJECT_ACCESSORS (acesso type-safe a projetos em um projeto multimódulo: em vez de project(":core:network"), pode-se escrever projects.core.network), STABLE_CONFIGURATION_CACHE (cache de configuração estável), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (transformação de artefatos). Recursos incipientes podem ser ativados em produção, mas a API pode mudar em versões futuras.

Gradle Enterprise e Build Scan também são configurados via settings.gradle: plugins { id("com.gradle.enterprise") } com um bloco gradleEnterprise. Build Scan é um serviço em nuvem que mostra informações detalhadas sobre cada compilação: tempo de execução de cada tarefa, cache, erros. Ativar o Build Scan ajuda a diagnosticar problemas de velocidade de compilação. Build Scan é gratuito para projetos de código aberto.

// Recursos incipientes
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
enableFeaturePreview("STABLE_CONFIGURATION_CACHE")

// Gradle Enterprise / Build Scan
plugins {
    id("com.gradle.enterprise") version "3.18"
}

gradleEnterprise {
    buildScan {
        termsOfServiceUrl = "https://gradle.com/terms-of-service"
        termsOfServiceAgree = "yes"
        publishAlwaysIf(true)
    }
}

// Uso de type-safe project accessors no build.gradle
// Em vez de: implementation(project(":core:network"))
// Pode-se: implementation(projects.core.network)