Gradle 빌드 시스템 기초 - 안드로이드 종속성 관리 완벽 가이드

안드로이드 앱을 개발할 때 Gradle은 필수 도구입니다. 라이브러리를 추가하고, 빌드 설정을 관리하며, APK나 AAB 파일을 생성하는 모든 과정이 Gradle을 통해 이루어집니다. 하지만 초보 개발자에게 Gradle은 복잡하게 느껴질 수 있습니다. 이 글에서는 Gradle의 기본 개념부터 종속성 관리, 최신 버전 활용법까지 차근차근 안내합니다.

Gradle이란 무엇인가

Gradle은 안드로이드 앱의 빌드 자동화 도구입니다. 소스 코드를 컴파일하고, 리소스를 묶고, 라이브러리를 연결하여 최종 실행 파일(APK/AAB)을 만드는 모든 과정을 자동으로 처리합니다. Groovy나 Kotlin DSL로 작성된 빌드 스크립트를 읽어 빌드를 수행합니다.

Gradle의 핵심은 종속성 관리입니다. 앱에서 사용하는 외부 라이브러리(예: Retrofit, Glide, Firebase 등)를 자동으로 다운로드하고, 버전을 관리하며, 충돌을 해결합니다. 개발자는 build.gradle 파일에 필요한 라이브러리만 선언하면, Gradle이 알아서 다운로드하고 프로젝트에 포함시킵니다.

2025년 6월 기준, 최신 Android Gradle Plugin(AGP) 버전은 8.11.0이며, Gradle 8.13 이상을 요구합니다. JDK 17, SDK Build Tools 35.0.0, NDK 27.0.12077973 등 최신 도구와의 호환성이 강화되었습니다. 최대 API 수준 36을 지원하여, 최신 안드로이드 OS에서도 문제없이 빌드할 수 있습니다.

build.gradle 파일 구조 이해하기

안드로이드 프로젝트에는 두 개의 build.gradle 파일이 있습니다. 프로젝트 레벨 build.gradle은 프로젝트 전체에 적용되는 설정을 담고, 모듈 레벨 build.gradle(앱 모듈)은 앱 빌드에 필요한 구체적인 설정을 담고 있습니다.

프로젝트 레벨 build.gradle에는 AGP 버전을 지정하는 classpath가 있습니다. 이 버전이 Gradle 버전과 맞아야 빌드가 정상적으로 진행됩니다. gradle-wrapper.properties 파일에서 Gradle 버전을 확인하고, AGP와 호환되는지 체크해야 합니다.

모듈 레벨 build.gradle은 더 자주 수정하는 파일입니다. 여기서 compileSdk, minSdk, targetSdk를 설정하고, 라이브러리 종속성을 추가하며, buildTypes(Debug/Release)를 구성합니다. dependencies 블록에서 implementation, api, compileOnly 등의 키워드로 라이브러리를 추가합니다.

주요 설정 항목:

• compileSdk: 컴파일에 사용할 안드로이드 SDK 버전 (최신 버전 권장)
• minSdk: 앱이 지원하는 최소 안드로이드 버전 (API 21 이상 권장)
• targetSdk: 앱이 대상으로 하는 안드로이드 버전 (최신 버전 권장)
• versionCode/versionName: 앱 버전 정보

compileSdk는 가능한 최신 버전을 사용하는 것이 좋습니다. 최신 API와 기능을 사용할 수 있고, 보안 업데이트도 빠르게 반영됩니다. minSdk는 지원하고 싶은 사용자 범위에 따라 조정하되, API 21(Android 5.0) 이상을 권장합니다.

종속성 추가 및 관리 방법

라이브러리를 추가하려면 build.gradle의 dependencies 블록에 implementation 키워드로 선언합니다. 예를 들어 Retrofit 라이브러리를 추가하려면 다음과 같이 작성합니다.

dependencies {
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
}

종속성 키워드 종류:

• implementation: 일반적으로 사용하는 종속성, 외부에 노출되지 않음
• api: 라이브러리를 다른 모듈에서도 사용할 수 있도록 노출
• compileOnly: 컴파일 시에만 필요, 런타임에는 포함 안 됨
• runtimeOnly: 런타임에만 필요, 컴파일 시에는 포함 안 됨

implementation을 가장 많이 사용합니다. 라이브러리를 앱 내부에서만 사용하고, 다른 모듈에 노출할 필요가 없기 때문입니다. api는 라이브러리 모듈을 개발할 때 주로 사용하며, 일반 앱 개발에서는 거의 쓰지 않습니다.

종속성을 추가한 후에는 “Sync Now” 버튼을 눌러 Gradle을 동기화해야 합니다. Gradle이 라이브러리를 다운로드하고 프로젝트에 연결합니다. 동기화가 실패하면 오류 메시지를 확인하여 버전 충돌이나 네트워크 문제를 해결해야 합니다.

Version Catalogs로 중앙 집중 관리

Gradle 7.4부터는 Version Catalogs 기능을 공식 지원합니다. 다중 모듈 프로젝트에서 라이브러리 버전을 한 곳에서 관리할 수 있어 매우 편리합니다. gradle/libs.versions.toml 파일을 생성하여 모든 라이브러리 버전을 정의하고, build.gradle에서 참조합니다.

[versions]
compose = "1.7.0"
retrofit = "2.9.0"

[libraries]
androidx-compose-ui = { module = "androidx.compose.ui:ui", version.ref = "compose" }
squareup-retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }

[plugins]
android-application = { id = "com.android.application", version = "8.11.0" }

build.gradle에서는 다음과 같이 참조합니다.

dependencies {
    implementation(libs.androidx.compose.ui)
    implementation(libs.squareup.retrofit)
}

Version Catalogs를 사용하면 버전 관리가 쉬워지고, 여러 모듈에서 같은 버전을 사용하도록 강제할 수 있습니다. 라이브러리 업데이트 시 toml 파일만 수정하면 모든 모듈에 적용됩니다. 대규모 프로젝트에서는 필수적인 기능입니다.

Firebase BoM으로 버전 일괄 관리

Firebase를 사용한다면 BoM(Bill of Materials)을 활용하세요. BoM을 추가하면 여러 Firebase 라이브러리의 버전을 자동으로 맞춰줍니다. 각 라이브러리마다 버전을 지정할 필요가 없어 편리합니다.

dependencies {
    // Firebase BoM
    implementation platform('com.google.firebase:firebase-bom:32.7.0')

    // 버전 지정 없이 추가
    implementation 'com.google.firebase:firebase-analytics'
    implementation 'com.google.firebase:firebase-auth'
    implementation 'com.google.firebase:firebase-firestore'
}

BoM 버전만 최신으로 유지하면, 포함된 모든 Firebase 라이브러리가 호환되는 버전으로 자동 설정됩니다. 버전 충돌 걱정 없이 Firebase 기능을 안전하게 사용할 수 있습니다. 2025년 10월 기준 최신 BoM 버전은 32.7.0 정도이며, Firebase 공식 문서에서 최신 버전을 확인할 수 있습니다.

종속성 충돌 해결 방법

여러 라이브러리를 사용하다 보면 종속성 충돌이 발생할 수 있습니다. 서로 다른 라이브러리가 같은 라이브러리의 다른 버전을 요구할 때 충돌이 일어납니다. Gradle은 기본적으로 가장 높은 버전을 선택하지만, 때로는 수동으로 버전을 지정해야 합니다.

충돌을 확인하려면 ./gradlew app:dependencies 명령을 실행하세요. 실제 사용 중인 라이브러리 트리가 출력되며, 어떤 라이브러리가 어떤 버전을 사용하는지 확인할 수 있습니다. 충돌이 발견되면 build.gradle에서 특정 버전을 강제하거나, exclude 키워드로 불필요한 종속성을 제외합니다.

dependencies {
    implementation('com.example:library:1.0') {
        exclude group: 'com.conflict', module: 'module-name'
    }

    // 특정 버전 강제
    implementation 'com.conflict:module-name:2.0'
}

직접 종속 항목은 전이 종속 항목을 재정의할 수 있습니다. 즉, build.gradle에 명시적으로 선언한 라이브러리 버전이 우선순위가 높습니다. 이 특성을 활용하여 충돌을 해결할 수 있습니다.

자주 묻는 질문 (FAQ)