build.gradle: Android에서 구문과 구성 완벽 가이드

build.gradle이란?

build.gradle은 Groovy(.gradle 확장자) 또는 Kotlin(.gradle.kts) 언어로 작성된 빌드 스크립트로, Android 애플리케이션 컴파일의 모든 측면을 관리합니다. Gradle은 Google이 2013년 Android 표준으로 채택한 자동 빌드 시스템입니다. build.gradle은 다음을 설명합니다: 적용된 플러그인(Android, Kotlin, 라이브러리), 연결된 의존성, 사용된 SDK 버전, 애플리케이션 서명 방법 및 게시 위치.

빌드 프로세스는 세 단계로 구성됩니다: Initialization(모듈 검색), Configuration(build.gradle 스크립트 실행), Execution(작업 실행). build.gradle은 Gradle이 작업 그래프를 생성하는 Configuration 단계에서 실행됩니다. 이 시점에서 Build Variants가 결정되고, 의존성이 계산되며, 작업이 구성됩니다. 중요한 점: build.gradle은 단순한 구성이 아닌 코드입니다. 조건문, 루프, 메서드 호출 및 외부 스크립트를 사용할 수 있습니다.

Gradle 파일은 모듈 루트(app/build.gradle)와 프로젝트 루트(build.gradle)에 저장됩니다. 또한 Gradle은 apply from — 외부 Gradle 스크립트 포함을 지원합니다. 이를 통해 반복적인 로직을 공유 설정 파일로 추출할 수 있습니다. Convention Plugins(AGP 7+)의 등장으로 apply from은 더 이상 사용되지 않습니다. Convention Plugins은 모듈 간 구성 재사용을 위한 타입 안전하고 구성 가능한 방법을 제공합니다.

build.gradle의 진화

2013년 이후 build.gradle 구문은 동적 구성의 Groovy에서 컴파일 타임 검사의 Kotlin DSL로 크게 변화했습니다. AGP는 버전 1.0에서 8.7(2025)로 발전했습니다. 주요 이정표: AGP 3.0(Java 8 desugar, 새로운 variant API), AGP 4.0(view binding, Java 11), AGP 7.0(기본 Kotlin DSL, Java 11 최소), AGP 8.0(비전이적 R 클래스, Kotlin의 빌드 구성), AGP 8.7(kapt 대신 KSP, 빠른 구성).

Project-level 및 Module-level build.gradle

Project-level build.gradle(루트)은 모든 모듈에 공통적인 플러그인, 저장소 및 구성을 정의합니다. 주요 블록: plugins(Gradle 플러그인 선언), repositories(의존성 소스: mavenCentral, google, jitpack). 루트 build.gradle에는 일반적으로 android 블록이 없습니다 — 모듈에 나타납니다. Project-level은 모든 하위 프로젝트의 공통 구성을 위한 subprojects 블록도 포함할 수 있지만 Convention Plugins이 더 좋습니다.

Module-level build.gradle(예: app/build.gradle)은 특정 모듈을 설명합니다. 모듈이 애플리케이션인 경우 com.android.application 플러그인을 적용합니다. 라이브러리인 경우 com.android.library를 적용합니다. Module-level에는 android 블록(compileSdk, defaultConfig, buildTypes, productFlavors), dependencies 블록(모듈 의존성) 및 선택적으로 테스트 및 패키징 구성 블록이 포함됩니다. Module-level은 project-level 다음에 실행되며 공통 설정을 재정의할 수 있습니다.

AGP 8.0부터 루트 build.gradle은 중앙 집중식 의존성 버전 관리를 위해 version catalogs(libs.versions.toml)을 사용할 수 있습니다. version catalog는 gradle/ 디렉토리의 파일로, 버전, 라이브러리 및 플러그인을 포함합니다. build.gradle에서 의존성은 libs를 통해 연결됩니다: implementation(libs.retrofit). version catalogs은 새 프로젝트에 필수이며 세 개 이상의 모듈이 있는 모든 프로젝트에 권장됩니다.

// settings.gradle.kts — 프로젝트 루트
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는 Gradle의 원래 구문이었던 동적 JVM 언어입니다. Groovy 스크립트(.gradle)는 동적 타이핑을 사용합니다: 타입을 생략하거나, 따옴표가 있거나 없는 문자열을 사용하거나, 컴파일 타임에 존재하지 않는 메서드를 호출할 수 있습니다. Groovy의 유연성은 또한 단점입니다: 스크립트가 실행될 때까지 IDE가 구문과 타입을 확인할 수 없어 잘못된 매개변수 이름이나 타입으로 인한 런타임 오류가 발생합니다.

Kotlin DSL(.gradle.kts)은 Kotlin의 정적 타이핑을 사용합니다. IDE가 타입을 확인하고, 자동 완성을 통해 사용 가능한 매개변수를 제안하며, 편집 중에 오류를 강조 표시합니다. Kotlin DSL은 Configuration 단계에서 더 느립니다(.kts 파일을 바이트코드로 컴파일하기 때문에). 하지만 Google은 지속적으로 성능을 개선합니다: AGP 8.5+는 Gradle Configuration Cache와 Caching Kotlin DSL compilation을 사용하여 차이를 1~2초로 줄입니다.

Google은 모든 새 프로젝트에 Kotlin DSL을 권장하고 기존 프로젝트의 점진적 마이그레이션을 권장합니다. Groovy에서 Kotlin DSL로의 마이그레이션은 간단합니다: 따옴표가 괄호로 대체되고, 타입이 추가되며, 연산자가 함수로 변환됩니다. 대부분의 라이브러리는 문서에 Kotlin DSL 예제를 제공합니다. 복잡한 경우(Custom Plugin, Task Graph) Kotlin DSL은 타입 안전한 API를 제공하고 Groovy에서 런타임에만 발견되는 오류를 방지합니다. Version catalogs(libs.versions.toml)은 두 구문 모두에서 동일하게 작동합니다.

android 블록: 애플리케이션 구성

compileSdk, minSdk 및 targetSdk

android 블록은 module-level build.gradle의 핵심 요소입니다. 내부에는 namespace(R 및 BuildConfig용), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle이 구성됩니다. android 블록의 모든 매개변수는 Android 모듈에만 적용됩니다. 모듈이 라이브러리인 경우 application 대신 라이브러리 플러그인이 사용되며 android 블록에 applicationId가 없습니다.

compileSdk는 코드를 컴파일하는 데 사용되는 SDK 버전입니다. 최신 Android API(작성 시점 기준 35)여야 합니다. minSdk는 지원되는 최소 API 버전입니다. targetSdk는 애플리케이션이 대상으로 하는 버전입니다(이 버전의 동작 변경 사항이 적용됨). compileSdk와 targetSdk의 차이: compileSdk는 사용 가능한 API를 결정하고, targetSdk는 런타임 동작을 결정합니다. 권장: compileSdk = 최신, targetSdk = 최신 - 1(새로운 변경 사항 적응 테스트용).

compileOptions은 Java 호환성을 설정합니다: sourceCompatibility와 targetCompatibility. AGP 8+는 컴파일에 Java 17+가 필요합니다. packaging은 라이브러리에서 파일 포함을 관리합니다: META-INF 충돌 해결을 위한 exclude, merge, pickFirst. buildFeatures는 ViewBinding, DataBinding, Compose를 활성화/비활성화합니다. aaptOptions은 리소스 처리를 구성합니다: ignoreAssetsPattern, cruncherEnabled. android 블록의 각 요소는 빌드의 특정 측면을 최적화합니다.

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
    }
}

의존성 관리

BOM(Bill of Materials)

build.gradle의 의존성은 프로젝트에 연결된 라이브러리와 모듈입니다. dependencies 블록은 android 블록과 같은 수준에 있습니다. Gradle은 여러 구성을 지원합니다: implementation(라이브러리가 이 모듈에서 사용 가능, 전이적이지 않음), api(라이브러리가 종속 모듈에 전이적으로 사용 가능), compileOnly(컴파일 전용, APK에 포함되지 않음), runtimeOnly(런타임 전용), annotationProcessor / ksp(어노테이션 프로세서), testImplementation(테스트 전용), androidTestImplementation(계측 테스트 전용).

AGP 8.0부터 비전이적 R 클래스 — 각 라이브러리가 자체 R 클래스를 가지며 리소스 충돌을 방지합니다. dependencies 블록에서 올바른 구성을 사용하는 것이 중요합니다: implementation은 전이적 의존성을 노출하지 않아 빌드를 가속화합니다. api는 이를 노출합니다 — 라이브러리가 다른 라이브러리의 타입을 내보낼 때 사용됩니다(예: Retrofit이 공개 API에서 OkHttp 타입을 사용).

버전 관리를 위해 BOM(Bill of Materials) 사용을 권장합니다 — 호환 가능한 라이브러리 버전을 정의하는 빌드 파일입니다. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). BOM을 연결하면 버전 없이 라이브러리 이름만 지정할 수 있습니다 — BOM이 자동으로 호환 버전을 선택합니다. 이는 다른 라이브러리의 전이적 의존성 간 충돌을 제거합니다. BOM은 Firebase, Compose, Kotlin, Ktor, AndroidX에 사용 가능합니다.

dependencies {
    // BOM — 버전 관리
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX 및 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 (BOM 버전)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // 테스트
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

멀티 모듈 프로젝트의 build.gradle

멀티 모듈 프로젝트에서 각 모듈은 자체 build.gradle을 가집니다. 한 모듈을 다른 모듈에 연결하려면 implementation(project(":module-name")) 구문을 사용합니다. Gradle은 구성이 변경되면 모듈을 자동으로 다시 빌드합니다. 멀티 모듈 아키텍처는 빌드 시간을 개선하고(증분 빌드, 병렬 처리) 기능 모듈, 코어 모듈 및 라이브러리 간의 책임을 분리합니다.

멀티 모듈 프로젝트의 주요 문제는 구성 중복입니다. 10개의 모듈이 동일한 minSdk, compileSdk 및 Compose 의존성을 가지고 있다면 다른 build.gradle 파일에 10개의 복사본이 있습니다. 해결책은 Convention Plugins(이전 buildSrc)입니다. Convention Plugin은 Kotlin으로 작성된 Gradle 플러그인으로 모듈에 적용됩니다: plugins { id("myapp.android.library") }. 플러그인은 공통 구성을 포함하며 변경 사항이 즉시 모든 모듈에 적용됩니다.

Convention Plugins을 구성하려면 프로젝트 루트에 build-logic/ 디렉토리를 사용합니다. settings.gradle에 includeBuild와 Kotlin 플러그인이 포함됩니다. Convention Plugins은 프로젝트 간 재사용을 위해 maven 저장소에 게시할 수 있습니다. Google은 멀티 모듈 프로젝트의 표준으로 Convention Plugins을 권장하며 subprojects { }와 apply from을 대체합니다. Convention Plugins으로 전환하면 모듈의 build.gradle이 10~15줄로 줄어듭니다.

// 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 — Convention Plugin 이후
plugins {
    id("myapp.android.library")
}

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