settings.gradle: 개요, 모듈 include 및 pluginManagement

settings.gradle이란?

settings.gradle(Kotlin DSL의 경우 settings.gradle.kts)은 Gradle이 Initialization 단계에서 실행하는 파일입니다. 프로젝트 계층 구조를 정의하고, 모듈을 포함하며, 플러그인 및 종속성의 리포지토리를 구성합니다. settings.gradle이 없으면 Gradle은 어떤 모듈을 빌드해야 하고 어떤 플러그인을 사용할 수 있는지 알 수 없습니다. 단일 모듈 프로젝트에서는 settings.gradle이 없어도 되지만, 멀티모듈 프로젝트에서는 필수입니다.

settings.gradle 파일은 프로젝트 루트에 있으며 루트 build.gradle과 함께 위치합니다. 일반적인 루트 프로젝트 구조: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle은 build.gradle보다 먼저 실행됩니다. Initialization 단계에서 Gradle은 프로젝트 트리(Gradle API의 Project)를 구축합니다. Initialization이 완료되면 Configuration이 시작되어 각 모듈의 build.gradle이 실행됩니다.

역사적으로 settings.gradle은 Gradle 0.7(2010)에서 등장했으며 처음에는 include 디렉티브만 포함했습니다. Gradle의 발전에 따라 pluginManagement(Gradle 6.8), dependencyResolutionManagement(Gradle 7.0), versionCatalogs(Gradle 7.4)가 추가되었습니다. 최신 settings.gradle은 프로젝트 전체의 플러그인, 리포지토리 및 버전 관리를 중앙 집중화하는 강력한 구성 파일입니다. Google은 AGP 8.0부터 Android Gradle Plugin에서 이러한 기능을 필수로 지정하고 있습니다.

settings.gradle vs build.gradle

settings.gradle은 프로젝트 구조와 전역 설정(플러그인, 리포지토리)을 관리합니다. build.gradle은 빌드(종속성, Android 구성, 태스크)를 관리합니다. settings.gradle이 먼저 실행되며 Settings API에 접근할 수 있습니다. build.gradle은 이후에 실행되며 Project API에 접근할 수 있습니다. 모듈 수준 구성(android 블록, dependencies)은 settings.gradle에 있을 수 없습니다.

include를 통한 모듈 포함

include 디렉티브는 settings.gradle의 핵심입니다. 어떤 모듈이 빌드에 참여해야 하는지 Gradle에 알려줍니다. include의 인자는 모듈 경로가 포함된 문자열입니다. include(":app")은 루트 수준의 모듈을 포함하고, include(":core:network")는 core/network/ 하위 디렉터리의 모듈을 포함합니다. 시작 부분의 콜론은 경로가 프로젝트 루트를 기준으로 함을 나타냅니다. include 이후 Gradle은 지정된 디렉터리에서 build.gradle을 자동으로 찾아 모듈을 프로젝트 트리에 추가합니다.

각 include는 include 문자열과 동일한 이름의 Project를 Gradle API에 생성합니다. 프로젝트 이름은 다른 모듈의 build.gradle 파일에서 implementation(project(":module"))에 사용됩니다. include를 통해 포함되지 않은 모듈을 참조하면 “Project not found” 오류가 발생합니다. Android Studio IDE도 Project 패널에 모듈을 표시하기 위해 settings.gradle을 사용합니다. include되지 않은 모듈은 파일 트리에 표시되지 않습니다.

include는 includeBuild("../library-project")를 통해 included builds와 composite builds를 지원합니다. 이를 통해 전체 Gradle 프로젝트를 외부 모듈로 포함할 수 있습니다. Included builds는 애플리케이션과 병렬로 라이브러리를 개발할 때 유용합니다. 라이브러리의 변경 사항은 Maven 리포지토리에 게시하지 않고도 애플리케이션에 즉시 반영됩니다. 프로덕션 빌드에서는 includeBuild가 일반 Maven 종속성으로 대체됩니다.

// settings.gradle.kts — 일반적인 구조
rootProject.name = "MyApp"

// 애플리케이션 모듈
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// 외부 라이브러리 포함(composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

플러그인 관리 블록

해결 전략

pluginManagement은 Gradle 플러그인을 로드할 위치를 결정하는 settings.gradle의 블록입니다. Gradle 6.8에서 플러그인을 적용하기 전에 중앙 집중식으로 관리하기 위해 도입되었습니다. pluginManagement 내부에는 repositories(플러그인 검색 리포지토리 목록), resolutionStrategy(버전 해결 규칙), plugins(명시적 플러그인 버전 선언)가 있습니다. pluginManagement가 정의되지 않으면 Gradle은 build.gradle의 리포지토리를 사용하지만, 플러그인은 선언된 후에만 검색되므로 플러그인을 찾을 수 없으면 오류가 발생합니다.

Android 프로젝트에서 Version Catalogs나 Convention Plugins을 사용하는 경우 pluginManagement가 필수입니다. pluginManagement가 없으면 Gradle은 build.gradle.kts에 적용할 때 com.android.application 플러그인을 찾을 수 없습니다. 일반적인 구성: repositories에는 google()(Android 플러그인), mavenCentral()(서드파티 플러그인), gradlePluginPortal()(공식 Gradle 플러그인)이 포함됩니다.

pluginManagement는 plugins도 지원합니다. 버전과 함께 플러그인을 선언하고 나중에 build.gradle에서 버전을 지정하지 않고 적용할 수 있습니다. 이렇게 하면 플러그인 버전이 중앙 집중화됩니다. 10개의 모듈이 kotlin-android를 적용하는 경우 버전은 pluginManagement에서 한 번만 지정됩니다. 중요: pluginManagement.plugins는 단순한 선언입니다. 플러그인 자체는 build.gradle에서 plugins { id("org.jetbrains.kotlin.android") }를 통해 적용됩니다.

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

    // 플러그인 버전 — 중앙 집중식
    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 {
        // 모든 모듈에 대한 강제 플러그인 버전
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // 플러그인 적용 — apply false(루트에 적용하지 않음)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

종속성 해결 관리

repositoriesMode 모드

dependencyResolutionManagement는 모든 모듈의 리포지토리를 중앙에서 관리하는 settings.gradle의 블록입니다. Gradle 7.0에서 각 build.gradle에 repositories를 선언하는 대안으로 도입되었습니다. 블록 내부에는 repositoriesMode(모드: PREFER_PROJECT, PREFER_SETTINGS 또는 FAIL_ON_PROJECT_REPOS)와 repositories(리포지토리 목록)가 설정됩니다. repositoriesMode = PREFER_SETTINGS인 경우 모듈 수준의 repositories는 무시되고 중앙 집중식 목록만 사용됩니다.

repositoriesMode는 세 가지 값을 가질 수 있습니다. PREFER_SETTINGS — build.gradle의 리포지토리가 무시되고 settings.gradle의 리포지토리만 사용됩니다. PREFER_PROJECT — build.gradle 리포지토리가 settings.gradle보다 우선합니다. FAIL_ON_PROJECT_REPOS — 모듈이 자체 리포지토리를 선언하면 Gradle이 오류를 발생시킵니다. 새 프로젝트의 경우 PREFER_SETTINGS가 권장됩니다. 모든 모듈이 동일한 리포지토리를 사용하도록 보장하고 중복을 제거합니다.

repositoriesMode = FAIL_ON_PROJECT_REPOS는 특히 팀에서 유용합니다. 개발자가 하나의 모듈에만 리포지토리를 추가하고 다른 모듈에서는 볼 수 없는 경우 “works on my machine” 문제가 발생합니다. FAIL_ON_PROJECT_REPOS는 모든 리포지토리를 settings.gradle에서 중앙 집중식으로 선언하도록 강제하여 이러한 상황을 방지합니다. Google은 AGP 8.0부터 모든 Android 프로젝트에 FAIL_ON_PROJECT_REPOS를 권장합니다.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — 모든 리포지토리는 여기만
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

        // 비공개 Maven 리포지토리
        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") ?: ""
            }
        }
    }
}

// build.gradle 모듈에 repositories가 더 이상 필요하지 않습니다!
// 모든 리포지토리가 settings.gradle에 중앙 집중화됨

settings.gradle의 버전 카탈로그

Version Catalogs는 TOML 파일을 통해 종속성 버전을 중앙 집중식으로 관리하는 방법입니다. Gradle 7.4부터 버전 카탈로그는 모든 Android 프로젝트에 권장되는 메커니즘입니다. gradle/libs.versions.toml 파일에는 세 개의 섹션이 있습니다: [versions](버전), [libraries](종속성), [plugins](플러그인). settings.gradle에서 버전 카탈로그는 @Suppress("UnstableApiUsage")와 enableFeaturePreview("VERSION_CATALOGS")(이전 Gradle 버전)를 통해 연결됩니다.

버전 카탈로그를 연결한 후 build.gradle의 모듈 종속성은 libs를 통해 지정됩니다: implementation(libs.retrofit). IDE는 libs에 대한 자동 완성을 제공합니다. 카탈로그는 자동으로 타입 세이프 접근자를 생성합니다: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles는 한 줄로 포함할 수 있는 종속성 그룹입니다. 버전 카탈로그는 상속도 지원하며 여러 TOML 파일을 연결할 수 있습니다.

버전 카탈로그의 장점: 버전의 단일 위치(모든 build.gradle 파일을 검색할 필요 없음); 타입 세이프 접근(libs 이름의 오타는 컴파일 타임에 발견, 런타임 아님); 자동 업데이트(Dependabot과 Renovate가 TOML 지원); Convention Plugins과의 호환성. Google Firebase와 AndroidX는 자체 TOML 카탈로그를 배포합니다. Version Catalogs로 마이그레이션하기 위해 build.gradle에서 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" }

고급 설정: includeBuild 및 실험적 기능

includeBuild는 복합 빌드를 생성하기 위한 디렉티브입니다. 현재 빌드의 일부로 외부 Gradle 프로젝트를 포함합니다. include(모듈 포함)와 달리 includeBuild는 자체 settings.gradle, 모듈 및 플러그인이 있는 전체 프로젝트를 포함합니다. 복합 빌드는 다음과 같은 경우에 사용됩니다: 애플리케이션과 병렬로 라이브러리(분석, 네트워킹) 개발; 별도 리포지토리에서 Convention Plugins 포함; build-logic 모듈 통합.

실험적 기능(Incubating Features)은 enableFeaturePreview("FEATURE_NAME")을 통해 활성화되는 Gradle의 실험적 옵션입니다. AGP 8.7+에서 사용 가능한 기능: TYPESAFE_PROJECT_ACCESSORS(멀티모듈 프로젝트에서 타입 세이프 프로젝트 접근: project(":core:network") 대신 projects.core.network 작성 가능), STABLE_CONFIGURATION_CACHE(안정적인 구성 캐싱), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST(아티팩트 변환). 실험적 기능은 프로덕션에서 활성화할 수 있지만 API는 향후 버전에서 변경될 수 있습니다.

Gradle Enterprise와 Build Scan도 settings.gradle을 통해 구성됩니다: plugins { id("com.gradle.enterprise") }와 gradleEnterprise 블록. Build Scan은 각 빌드에 대한 자세한 정보(각 태스크의 실행 시간, 캐싱, 오류)를 표시하는 클라우드 서비스입니다. Build Scan을 활성화하면 빌드 속도 문제를 진단하는 데 도움이 됩니다. Build Scan은 오픈 소스 프로젝트의 경우 무료입니다.

// 실험적 기능
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)
    }
}

// build.gradle에서 타입 세이프 프로젝트 접근자 사용
// 대신: implementation(project(":core:network"))
// 가능: implementation(projects.core.network)