빌드 종속 항목 추가

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

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

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

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

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

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 프로젝트의 종속 항목에 사용할 수 있는 각 구성을 설명합니다.

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

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' 제품 버전에만 원격 바이너리 종속 항목을 추가하려면 다음을 사용합니다.

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

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

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

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

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

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

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

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

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

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에 게시하지 못할 수 있기 때문입니다.

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

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

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

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에 관한 종속 항목을 선언합니다. 원격 바이너리 종속 항목 선언은 다음의 축약형입니다.

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

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 블록을 제외하고 비어 있습니다.

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

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

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

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

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