Android 스튜디오의 Gradle 빌드 시스템을 사용하면 외부 바이너리 또는 다른 라이브러리 모듈을 빌드에 종속 항목으로 포함할 수 있습니다. 종속 항목은 컴퓨터 또는 원격 저장소에 위치할 수 있으며 종속 항목에서 선언하는 전이 종속 항목도 자동으로 포함됩니다. 이 페이지에서는 Android Gradle 플러그인 (AGP)과 관련된 동작 및 구성에 관한 세부정보를 포함하여 Android 프로젝트에서 종속 항목을 사용하는 방법을 설명합니다. Gradle 종속 항목에 관한 자세한 개념 가이드는 Gradle 종속 항목 관리 가이드도 참조해야 하지만 Android 프로젝트에서는 이 페이지에서 정의하고 있는 종속 항목 구성만 사용해야 합니다.
라이브러리 또는 플러그인 종속 항목 추가
빌드 종속 항목을 추가하고 관리하는 가장 좋은 방법은 새 프로젝트에서 기본적으로 사용하는 버전 카탈로그를 사용하는 것입니다. 이 섹션에서는 Android 프로젝트에 사용되는 가장 일반적인 구성 유형을 설명합니다. 더 많은 옵션은 Gradle 문서를 참고하세요. 버전 카탈로그를 사용하는 앱의 예는 Now in Android를 참고하세요. 이미 버전 카탈로그 없이 설정된 빌드 종속 항목이 있고 다중 모듈 프로젝트가 있다면 이전하는 것이 좋습니다.
네이티브 종속 항목 추가 및 관리에 관한 안내는 네이티브 종속 항목을 참고하세요.
다음 예에서는 프로젝트에 원격 바이너리 종속 항목 (Jetpack Macrobenchmark 라이브러리), 로컬 라이브러리 모듈 종속 항목 (myLibrary
), 플러그인 종속 항목 (Android Gradle 플러그인)을 추가합니다. 다음은 이러한 종속 항목을 프로젝트에 추가하는 일반적인 단계입니다.
Project 뷰의
gradle
디렉터리 또는 Android 뷰의 Gradle Scripts에서libs.versions.toml
이라는 버전 카탈로그 파일의[versions]
섹션에 원하는 종속 항목의 버전에 대한 별칭을 추가합니다.[versions] agp = "8.3.0" androidx-macro-benchmark = "1.2.2" my-library = "1.4" [libraries] ... [plugins] ...
별칭에는 대시 또는 밑줄이 포함될 수 있습니다. 이러한 별칭은 빌드 스크립트에서 참조할 수 있는 중첩 값을 생성합니다. 참조는 카탈로그 이름, 즉
libs.versions.toml
의libs
부분으로 시작합니다. 단일 버전 카탈로그를 사용하는 경우 기본값 'libs'를 유지하는 것이 좋습니다.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이 이러한 버전을 자동으로 관리하도록 할 수 있습니다. 자세한 내용은 재료명세서 사용을 참고하세요.
종속 항목이 필요한 모듈의 빌드 스크립트에 종속 항목 별칭 참조를 추가합니다. 빌드 스크립트에서 별칭을 참조할 때 별칭의 하이픈과 대시를 점으로 변환합니다. 모듈 수준 빌드 스크립트는 다음과 같습니다.
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 |
Gradle은 컴파일 클래스 경로와 빌드 출력에 종속 항목을 추가합니다. 모듈에 api 종속 항목이 포함되어 있으면 모듈이 다른 모듈로 종속 항목을 전이하여 내보내려 하므로 런타임과 컴파일 시간에 모두 종속 항목을 사용할 수 있음을 Gradle에 알립니다.
이 구성은 주의해서 사용해야 하며 다른 업스트림 소비자에게 전이하여 내보내야 하는 종속 항목에만 사용해야 합니다. |
compileOnly |
Gradle은 컴파일 클래스 경로에만 종속 항목을 추가합니다(즉 빌드 출력에는 추가되지 않음). 이는 Android 모듈을 만들고 있으며 컴파일하는 동안 종속 항목이 필요한 경우 유용하지만 런타임에 이를 표시하는 것은 선택사항입니다. 예를 들어 일반적으로 코드를 생성하는 데 사용되지만 빌드 출력에 포함되지 않는 경우가 많은 컴파일 시간 주석만 포함된 라이브러리에 종속되는 경우 해당 라이브러리를 compileOnly 로 표시할 수 있습니다.
이 구성을 사용하는 경우 라이브러리 모듈에 런타임 조건을 포함하여 종속 항목을 사용할 수 있는지 확인한 다음 종속 항목이 제공되지 않는 경우에도 작동할 수 있도록 동작을 적절하게 변경해야 합니다. 이렇게 하면 중요하지 않은 임시 종속 항목을 추가하지 않으므로 최종 앱의 크기를 줄일 수 있습니다.
참고: Android 보관 파일 (AAR) 종속 항목에는 |
runtimeOnly |
Gradle은 런타임 동안 사용하기 위해 빌드 출력에만 종속 항목을 추가합니다. 즉, 컴파일 클래스 경로에는 추가되지 않습니다.
Android에서는 거의 사용되지 않지만 로깅 구현을 제공하기 위해 서버 애플리케이션에서 일반적으로 사용됩니다. 예를 들어 라이브러리는 구현이 포함되지 않은 로깅 API를 사용할 수 있습니다. 이 라이브러리의 소비자는 라이브러리를 implementation 종속 항목으로 추가하고 사용할 실제 로깅 구현을 위한 runtimeOnly 종속 항목을 포함할 수 있습니다.
|
ksp |
이러한 구성은 코드가 컴파일되기 전에 코드의 주석 및 기타 기호를 처리하는 라이브러리를 제공합니다. 일반적으로 코드의 유효성을 검사하거나 추가 코드를 생성하여 작성해야 하는 코드의 양을 줄입니다. 이러한 종속 항목을 추가하려면 JAR 파일에 다음 파일이 포함되어 있으면 Android Gradle 플러그인은 종속 항목이 주석 프로세서라고 가정합니다.
플러그인이 컴파일 클래스 경로에 있는 주석 프로세서를 감지하면 빌드 오류가 발생합니다.
사용할 구성을 결정할 때는 다음 사항을 고려하세요.
주석 프로세서 사용에 관한 자세한 내용은 주석 프로세서 추가를 참고하세요. |
lintChecks |
Android 앱 프로젝트를 빌드할 때 Gradle이 실행할 린트 검사가 포함된 라이브러리를 포함하려면 이 구성을 사용합니다.
|
lintPublish |
Gradle에서 lint.jar 파일로 컴파일하고 AAR에 패키징할 린트 검사를 포함하려면 Android 라이브러리 프로젝트에서 이 구성을 사용하세요. 이렇게 하면 AAR을 사용하는 프로젝트에서 이 린트 검사도 적용합니다. 이전에 lintChecks 종속 항목 구성을 사용하여 게시된 AAR에 린트 검사를 포함한 경우 이 종속 항목을 이전하여 대신 lintPublish 구성을 사용해야 합니다.
Kotlindependencies { // 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")) } Groovydependencies { // 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
에 종속됨
그러면 고정 종속 항목 순서는 다음과 같습니다.
LIB_A
LIB_D
LIB_B
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 서명 키로 암호화되며 출시 앱의 서명 블록에 저장됩니다. 안전하고 긍정적인 사용자 환경을 위해 이 종속 항목 파일을 보관하는 것이 좋습니다. 다음 dependenciesInfo
블록을 모듈의 build.gradle.kts
파일에 포함하여 선택 해제할 수 있습니다.
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' }