빌드 종속 항목 추가

Android 스튜디오의 Gradle 빌드 시스템을 사용하면 외부 바이너리 또는 다른 라이브러리 모듈을 빌드에 종속 항목으로 포함할 수 있습니다. 종속 항목은 컴퓨터 또는 원격 저장소에 위치할 수 있으며 종속 항목에서 선언하는 전이 종속 항목도 자동으로 포함됩니다. 이 페이지에서는 Android Gradle 플러그인 (AGP)과 관련된 동작 및 구성에 관한 세부정보를 포함하여 Android 프로젝트에서 종속 항목을 사용하는 방법을 설명합니다. Gradle 종속 항목에 관한 자세한 개념 가이드는 Gradle 종속 항목 관리 가이드를 참고하세요. 그러나 Android 프로젝트에서는 이 페이지에 정의된 종속 항목 구성만 사용해야 합니다.

주의: 종속 항목을 지정할 때는 'com.android.tools.build:gradle:3.+'와 같은 동적 버전 번호를 사용하면 안 됩니다. 이 기능을 사용하면 예상치 못한 버전 업데이트가 발생할 수 있고 버전 차이를 해결하기 어려울 수 있으며 성능이 저하될 수 있습니다.

라이브러리 또는 플러그인 종속 항목 추가

빌드 종속 항목을 추가하고 관리하는 가장 좋은 방법은 새 프로젝트에서 기본적으로 사용하는 버전 카탈로그를 사용하는 것입니다. 이 섹션에서는 Android 프로젝트에 사용되는 가장 일반적인 구성 유형을 설명합니다. 자세한 옵션은 Gradle 문서를 참고하세요. 버전 카탈로그를 사용하는 앱의 예는 Now in Android를 참고하세요. 버전 카탈로그 없이 이미 빌드 종속 항목이 설정되어 있고 다중 모듈 프로젝트가 있는 경우 이전하는 것이 좋습니다.

네이티브 종속 항목 추가 및 관리에 관한 안내는 네이티브 종속 항목을 참고하세요.

다음 예에서는 원격 바이너리 종속 항목 (Jetpack Macrobenchmark 라이브러리), 로컬 라이브러리 모듈 종속 항목 (myLibrary), 플러그인 종속 항목 (Android Gradle 플러그인)을 프로젝트에 추가합니다. 다음은 이러한 종속 항목을 프로젝트에 추가하는 일반적인 단계입니다.

참고: 설정 파일에서 버전 카탈로그를 선언할 수도 있지만, Android 스튜디오의 코드 추천 및 강조 표시를 더 효과적으로 지원하려면 별도의 toml 파일을 사용하는 것이 좋습니다.

1. 버전 카탈로그 파일의 [versions] 섹션에 원하는 종속 항목 버전의 별칭인 libs.versions.toml를 추가합니다 (프로젝트 뷰의 gradle 디렉터리 또는 Android 뷰의 Gradle 스크립트 아래).

   [versions]
   agp = "8.3.0"
   androidx-macro-benchmark = "1.2.2"
   my-library = "1.4"
   
   [libraries]
   ...
   
   [plugins]
   ...
   

   별칭에는 대시 또는 밑줄을 포함할 수 있습니다. 이러한 별칭은 빌드 스크립트에서 참조할 수 있는 중첩 값을 생성합니다. 참조는 카탈로그 이름(libs.versions.toml의 libs 부분)으로 시작합니다. 단일 버전 카탈로그를 사용하는 경우 기본값 'libs'를 유지하는 것이 좋습니다.

2. libs.versions.toml 파일의 [libraries] (원격 바이너리 또는 로컬 라이브러리 모듈의 경우) 또는 [plugins] (플러그인의 경우) 섹션에 종속 항목의 별칭을 추가합니다.

   [versions]
   ...
   
   [libraries]
   androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
   my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }
   
   [plugins]
   androidApplication = { id = "com.android.application", version.ref = "agp" }
   

   일부 라이브러리는 라이브러리 패밀리와 버전을 그룹화하는 게시된 재료명세서 (BOM)에서 사용할 수 있습니다. 버전 카탈로그 및 빌드 파일에 BOM을 포함하고 BOM이 이러한 버전을 자동으로 관리하도록 할 수 있습니다. 자세한 내용은 재료명세서 사용을 참고하세요.

3. 종속 항목이 필요한 모듈의 빌드 스크립트에 종속 항목 별칭 참조를 추가합니다. 빌드 스크립트에서 별칭을 참조할 때 별칭의 하이픈과 대시를 점으로 변환합니다. 모듈 수준 빌드 스크립트는 다음과 같습니다.

   Kotlin

   plugins {
     alias(libs.plugins.androidApplication)
   }
   
   dependencies {
     implementation(libs.androidx.benchmark.macro)
     implementation(libs.my.library)
   }

   Groovy

   plugins {
     alias 'libs.plugins.androidApplication'
   }
   
   dependencies {
     implementation libs.androidx.benchmark.macro
     implementation libs.my.library
   }

   플러그인 참조에는 카탈로그 이름 뒤에 plugins가 포함되고 버전 참조에는 카탈로그 이름 뒤에 versions가 포함됩니다. 버전 참조는 흔하지 않습니다. 버전 참조의 예는 동일한 버전 번호의 종속 항목을 참고하세요. 라이브러리 참조에는 libraries 한정자가 포함되지 않으므로 라이브러리 별칭의 시작 부분에 versions 또는 plugins를 사용할 수 없습니다.

종속성 구성

dependencies 블록 내에서 위 implementation과 같은 여러 종속 항목 구성 중 하나를 사용하여 라이브러리 종속 항목을 선언할 수 있습니다. 각 종속 항목 구성은 Gradle에 종속 항목 사용 방법에 관한 다양한 안내를 제공합니다. 다음 표에서는 Android 프로젝트의 종속 항목에 사용할 수 있는 각 구성을 설명합니다.

구성	동작
implementation	Gradle이 컴파일 클래스 경로에 종속 항목을 추가하고 빌드 출력에 종속 항목을 패키징합니다. 모듈이 implementation 종속 항목을 구성하면 모듈이 컴파일 시간에 종속 항목을 다른 모듈에 누출하기를 바라지 않는다는 것을 Gradle에 알려주는 것입니다. 즉, 종속 항목은 현재 모듈에 종속된 다른 모듈에 제공되지 않습니다. api 대신 이 종속 항목 구성을 사용하면 빌드 시스템에서 다시 컴파일해야 하는 모듈 수가 줄어들기 때문에 빌드 시간이 크게 개선될 수 있습니다. 예를 들어 implementation 종속 항목이 API를 변경하면 Gradle은 이 종속 항목과 이에 직접적으로 종속된 모듈만 다시 컴파일합니다. 대부분의 앱과 테스트 모듈은 이 구성을 사용해야 합니다.
api	Gradle은 컴파일 클래스 경로와 빌드 출력에 종속 항목을 추가합니다. 모듈에 api 종속 항목이 포함되면 모듈이 다른 모듈로 종속 항목을 이전하여 다른 모듈에서 런타임과 컴파일 시간에 사용할 수 있도록 한다는 것을 Gradle에 알려주는 것입니다. 이 구성은 주의해서 사용해야 하며 다른 업스트림 소비자에게 전이하여 내보내야 하는 종속 항목과만 사용해야 합니다. api 종속 항목이 외부 API를 변경하면 Gradle은 컴파일 시 해당 종속 항목에 액세스할 권한이 있는 모든 모듈을 다시 컴파일합니다. api 종속 항목이 많으면 빌드 시간이 크게 증가할 수 있습니다. 종속 항목의 API를 별도의 모듈에 노출하지 않으려면 라이브러리 모듈에서 implementation 종속 항목을 대신 사용해야 합니다.
compileOnly	Gradle은 컴파일 클래스 경로에만 종속 항목을 추가합니다(즉 빌드 출력에는 추가되지 않음). 이는 Android 모듈을 만들고 있으며 컴파일하는 동안 종속 항목이 필요한 경우 유용하지만 런타임에 이를 표시하는 것은 선택사항입니다. 예를 들어 컴파일 시간 주석만 포함된 라이브러리에 종속되는 경우(일반적으로 코드를 생성하는 데 사용되지만 빌드 출력에 포함되지 않는 경우가 많음) 해당 라이브러리를 compileOnly로 표시할 수 있습니다. 이 구성을 사용하는 경우 라이브러리 모듈에 런타임 조건을 포함하여 종속 항목을 사용할 수 있는지 확인한 다음 종속 항목이 제공되지 않는 경우에도 작동할 수 있도록 동작을 적절하게 변경해야 합니다. 이렇게 하면 중요하지 않은 임시 종속 항목을 추가하지 않으므로 최종 앱의 크기를 줄일 수 있습니다. 참고: compileOnly 구성은 Android 보관 파일 (AAR) 종속 항목과 함께 사용할 수 없습니다.
runtimeOnly	Gradle은 런타임 동안 사용하기 위해 빌드 출력에만 종속 항목을 추가합니다. 즉, 컴파일 클래스 경로에는 추가되지 않습니다. 이는 Android에서는 거의 사용되지 않지만 로깅 구현을 제공하기 위해 서버 애플리케이션에서 일반적으로 사용됩니다. 예를 들어 라이브러리는 구현이 포함되지 않은 로깅 API를 사용할 수 있습니다. 이 라이브러리의 소비자는 이를 implementation 종속 항목으로 추가하고 실제 로깅 구현에서 사용할 runtimeOnly 종속 항목을 포함할 수 있습니다.
ksp kapt annotationProcessor	이러한 구성은 코드가 컴파일되기 전에 코드의 주석 및 기타 기호를 처리하는 라이브러리를 제공합니다. 일반적으로 코드의 유효성을 검사하거나 추가 코드를 생성하여 작성해야 하는 코드의 양을 줄입니다. 이러한 종속 항목을 추가하려면 ksp, kapt 또는 annotationProcessor 구성을 사용하여 주석 프로세서 클래스 경로에 추가해야 합니다. 이러한 구성을 사용하면 컴파일 클래스 경로를 주석 프로세서 클래스 경로에서 분리하여 빌드 성능을 개선할 수 있습니다. Gradle은 컴파일 클래스 경로에서 주석 프로세서를 찾으면 컴파일 회피를 비활성화하며 이는 빌드 시간에 부정적인 영향을 미칩니다 (Gradle 5.0 이상에서는 컴파일 클래스 경로에서 발견된 주석 프로세서를 무시합니다). JAR 파일에 다음 파일이 포함되어 있으면 Android Gradle 플러그인은 종속 항목이 주석 프로세서라고 가정합니다. META-INF/services/javax.annotation.processing.Processor 플러그인이 컴파일 클래스 경로에 있는 주석 프로세서를 감지하면 빌드 오류가 발생합니다. ksp는 Kotlin 기호 프로세서이며 Kotlin 컴파일러에서 실행됩니다. kapt 및 apt는 Kotlin 또는 Java 컴파일러가 실행되기 전에 주석을 처리하는 별도의 도구입니다. 사용할 구성을 결정할 때는 다음 사항을 고려하세요. 프로세서를 Kotlin 기호 프로세서로 사용할 수 있는 경우 ksp 종속 항목으로 사용합니다. Kotlin 기호 프로세서 사용에 관한 자세한 내용은 kapt에서 KSP로 이전을 참고하세요. 프로세서를 Kotlin 기호 프로세서로 사용할 수 없는 경우: 프로젝트에 Kotlin 소스가 포함되어 있지만 Java 소스도 포함할 수 있는 경우 kapt를 사용하여 포함합니다. 프로젝트에서 Java 소스만 사용하는 경우 annotationProcessor를 사용하여 포함합니다. 주석 프로세서 사용에 관한 자세한 내용은 주석 프로세서 추가를 참고하세요.
lintChecks	이 구성을 사용하여 Gradle이 Android 앱 프로젝트를 빌드할 때 실행할 린트 검사가 포함된 라이브러리를 포함합니다. lint.jar 파일이 포함된 AAR은 해당 lint.jar 파일에 정의된 검사를 자동으로 실행합니다. 명시적 lintChecks 종속 항목을 추가할 필요가 없습니다. 이렇게 하면 단일 종속 항목에서 라이브러리와 연결된 린트 검사를 정의할 수 있으므로 소비자가 라이브러리를 사용할 때 검사가 실행됩니다.
lintPublish	Gradle에서 lint.jar 파일로 컴파일하고 AAR에 패키징할 린트 검사를 포함하려면 Android 라이브러리 프로젝트에서 이 구성을 사용하세요. 이렇게 하면 AAR을 사용하는 프로젝트에서 이 린트 검사도 적용합니다. 이전에 lintChecks 종속 항목 구성을 사용하여 게시된 AAR에 린트 검사를 포함한 경우 이 종속 항목을 이전하여 대신 lintPublish 구성을 사용해야 합니다. Kotlin dependencies { // Executes lint checks from the ":checks" project at build time. lintChecks(project(":checks")) // Compiles lint checks from the ":checks-to-publish" into a // lint.jar file and publishes it to your Android library. lintPublish(project(":checks-to-publish")) } Groovy dependencies { // Executes lint checks from the ':checks' project at build time. lintChecks project(':checks') // Compiles lint checks from the ':checks-to-publish' into a // lint.jar file and publishes it to your Android library. lintPublish project(':checks-to-publish') }

특정 빌드 변형의 종속 항목 구성

위의 모든 구성은 모든 빌드 변형에 종속 항목을 적용합니다. 대신 특정 빌드 변형 소스 세트나 테스트 소스 세트에 관해서만 종속 항목을 선언하려면 구성 이름을 대문자로 지정하고 이름 앞에 빌드 변형이나 테스트 소스 세트의 이름을 접두사로 붙여야 합니다.

예를 들어 implementation 구성을 사용하여 'free' 제품 버전에만 원격 바이너리 종속 항목을 추가하려면 다음을 사용합니다.

Kotlin

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

Groovy

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

그러나 제품 버전과 빌드 유형이 결합된 변형에 종속 항목을 추가하려면 구성 이름을 초기화해야 합니다.

Kotlin

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

Groovy

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

로컬 테스트와 계측 테스트에 implementation 종속 항목을 추가하는 방법은 다음과 같습니다.

Kotlin

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
}

Groovy

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
}

그러나 일부 구성은 이 상황에 맞지 않습니다. 예를 들어 다른 모듈은 androidTest에 종속될 수 없으므로 androidTestApi 구성을 사용하면 다음과 같은 경고가 표시됩니다.

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

종속 항목 순서

종속 항목을 나열한 순서는 각각의 우선순위를 나타냅니다. 첫 번째 라이브러리는 두 번째 라이브러리보다 우선순위가 높고 두 번째는 세 번째보다 높습니다. 이 순서는 라이브러리에서 앱으로 리소스가 병합되거나 매니페스트 요소가 병합되는 경우 중요합니다.

예를 들어 프로젝트에 다음과 같이 선언되었다고 가정합니다.

• LIB_A와 LIB_B에 순서대로 종속 항목 있음
• 그다음 LIB_A가 LIB_C와 LIB_D에 순서대로 종속됨
• 그다음 LIB_B도 LIB_C에 종속됨

그러면 고정 종속 항목 순서는 다음과 같습니다.

1. LIB_A
2. LIB_D
3. LIB_B
4. LIB_C

이에 따라 LIB_A와 LIB_B 모두 LIB_C를 재정의할 수 있으며 LIB_A(LIB_D에 종속됨)는 LIB_B보다 우선순위가 높기 때문에 LIB_D는 여전히 LIB_B보다 우선순위가 높게 됩니다.

다양한 프로젝트 소스/종속 항목의 매니페스트를 병합하는 방법은 여러 매니페스트 파일 병합에서 자세히 알아보세요.

Play Console의 종속 항목 정보

앱을 빌드할 때 AGP에는 앱에 컴파일되는 라이브러리 종속 항목을 설명하는 메타데이터가 포함됩니다. 앱을 업로드할 때 Play Console은 이 메타데이터를 검사하여 앱에서 사용하는 SDK 및 종속 항목의 알려진 문제에 관한 알림을 제공하고 경우에 따라 이러한 문제를 해결하기 위한 조치 가능한 의견을 제공합니다.

데이터는 압축되고 Google Play 서명 키에 의해 암호화되며 출시 앱의 서명 블록에 저장됩니다. 안전하고 긍정적인 사용자 환경을 위해 이 종속 항목 파일을 보관하는 것이 좋습니다. 모듈의 build.gradle.kts 파일에 다음 dependenciesInfo 블록을 포함하여 선택 해제할 수 있습니다.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

정책 및 종속 항목 관련 잠재적 문제에 관한 자세한 내용은 앱에서 서드 파티 SDK 사용하기에 관한 지원 페이지를 참고하세요.

SDK 통계

Android 스튜디오는 다음 문제가 적용되는 경우 Google Play SDK 색인의 공개 SDK에 대한 버전 카탈로그 파일 및 Project Structure Dialog에 린트 경고를 표시합니다.

• SDK가 작성자에 의해 오래된 것으로 표시됩니다.
• SDK가 Play 정책을 위반합니다.

경고는 이러한 종속 항목을 업데이트해야 한다는 신호입니다. 오래된 버전을 사용하면 향후 Google Play Console에 게시하지 못할 수 있기 때문입니다.

버전 카탈로그 없이 빌드 종속 항목 추가

버전 카탈로그를 사용하여 종속 항목을 추가하고 관리하는 것이 좋지만 간단한 프로젝트에는 필요하지 않을 수 있습니다. 다음은 버전 카탈로그를 사용하지 않는 빌드 파일의 예입니다.

Kotlin

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

Groovy

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

이 빌드 파일은 'com.example.android' 네임스페이스 그룹 내의 'app-magic' 라이브러리의 버전 12.3에 관한 종속 항목을 선언합니다. 원격 바이너리 종속 항목 선언은 다음의 축약형입니다.

Kotlin

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

Groovy

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

빌드 파일은 'mylibrary'라는 Android 라이브러리 모듈에 대한 종속 항목도 선언합니다. 이 이름은 settings.gradle.kts 파일의 include:로 정의한 라이브러리 이름과 일치해야 합니다. 앱을 빌드할 때 빌드 시스템은 라이브러리 모듈을 컴파일하고 컴파일된 콘텐츠를 앱에 패키징합니다.

빌드 파일은 Android Gradle 플러그인(com.application.android)에 대한 종속 항목도 선언합니다. 동일한 플러그인을 사용하는 모듈이 여러 개인 경우 모든 모듈의 빌드 클래스 경로에 플러그인 버전이 하나만 있을 수 있습니다. 각 모듈 빌드 스크립트에서 버전을 지정하는 대신 루트 빌드 스크립트에 버전과 함께 플러그인 종속 항목을 포함하고 적용하지 않도록 표시해야 합니다. apply false를 추가하면 Gradle에 플러그인 버전을 기록하되 루트 빌드에서는 사용하지 않도록 지시합니다. 일반적으로 루트 빌드 스크립트는 이 plugins 블록을 제외하고 비어 있습니다.

Kotlin

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

Groovy

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

모듈 단일 프로젝트의 경우 모듈 수준 빌드 스크립트에서 버전을 명시적으로 지정하고 프로젝트 수준 빌드 스크립트를 비워 둘 수 있습니다.

Kotlin

plugins {
    id("com.android.application") version "8.3.0"
}

Groovy

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}