빌드 종속 항목 추가

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

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

빌드 종속 항목을 추가하고 관리하는 가장 좋은 방법은 버전 카탈로그를 사용하는 것입니다. 메서드를 제공합니다. 이 섹션에서는 Android 프로젝트에 사용되는 구성 유형 자세한 내용은 Gradle 문서 추가 옵션을 확인하세요 버전 카탈로그를 사용하는 앱의 예는 다음을 참고하세요. Now in Android 빌드 종속 항목을 이미 설정한 경우 버전 카탈로그가 없고 다중 모듈 프로젝트가 있다면 이전 중 하나에 해당할 수 있습니다.

네이티브 종속 항목 추가 및 관리 (일반적이지 않음)에 관한 안내는 다음을 참고하세요. 네이티브 종속 항목.

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

  1. 원하는 종속 항목 버전의 별칭을 버전 카탈로그 파일의 [versions] 섹션 libs.versions.toml (gradle 디렉터리 아래 Android 뷰의 Project 뷰 또는 Gradle Scripts:

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

[libraries]
...

[plugins]
...

    별칭에는 대시 또는 밑줄이 포함될 수 있습니다. 이러한 별칭은 중첩된 값을 생성합니다. 빌드 스크립트에서 참조할 수 있습니다. 참조는 카탈로그, libs.versions.toml의 libs 부분입니다. 날짜 사용하는 경우 기본 값을 유지하는 것이 좋습니다. "libs."

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

    [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을 버전 카탈로그와 빌드 파일을 관리하고, 해당 버전을 자동으로 관리하도록 할 수 있습니다. 자세한 내용은 자세한 내용은 재료명세서 사용을 참조하세요.

  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이 주석 프로세서가 추가되면 애플리케이션이 <ph type="x-smartling-placeholder"></ph> 빌드 시간에 부정적인 영향을 미치는 컴파일 방지 (Gradle 5.0 이상은 컴파일에서 발견된 주석 프로세서를 무시합니다. 클래스 경로).

JAR 파일에 다음 파일이 포함되어 있으면 Android Gradle 플러그인은 종속 항목이 주석 프로세서라고 가정합니다.

META-INF/services/javax.annotation.processing.Processor

플러그인이 컴파일 클래스 경로에 있는 주석 프로세서를 감지하면 빌드 오류가 발생합니다.

ksp는 Kotlin 기호 프로세서로, Kotlin 컴파일러입니다.

kapt와 apt는 Google Cloud로 프로세스 주석을 추가해야 합니다.

사용할 구성을 결정할 때는 있습니다.

  • 프로세서를 Kotlin 기호 프로세서로 사용할 수 있는 경우 다음을 사용합니다. ksp 종속 항목으로 제공됩니다. kapt에서 ksp로 이전을 참조하세요. 을 참조하세요.
  • 프로세서를 Kotlin 기호 프로세서로 사용할 수 없는 경우 다음을 실행합니다. <ph type="x-smartling-placeholder">
      </ph>
    • 프로젝트에 Kotlin 소스가 포함되어 있지만 Java 소스 포함) kapt 사용 포함할 수 있습니다.
    • 프로젝트에서 Java 소스만 사용하는 경우 annotationProcessor하여 포함시킵니다.

주석 프로세서 사용에 관한 자세한 내용은 주석 프로세서를 추가합니다.
lintChecks

이 구성을 사용하여 린트가 포함된 라이브러리를 포함하세요. Android 앱을 빌드할 때 Gradle이 실행하기를 원하는 검사 살펴보겠습니다

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

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

위의 모든 구성은 종속 항목을 모든 빌드 변형에 적용합니다. 만약 대신 특정 빌드에 대해서만 종속 항목을 선언하려고 함 변형 소스 세트 또는 테스트 소스 설정하는 경우 구성을 대문자로 표시해야 합니다. 이름을 지정하고 빌드 변형 또는 테스트 소스 세트의 이름을 접두사로 붙입니다.

예를 들어 원격 바이너리 종속 항목을 'free' 제품 implementation 구성을 사용하여 버전을 빌드하려는 경우 다음을 사용합니다.

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.5.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.5.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 서명 키로 암호화되어 서명 블록을 두는 것입니다. 이 종속 항목은 유지하는 것이 좋습니다. 파일을 만들어 주세요. 다음을 포함하여 선택 해제할 수 있습니다. 팔로잉 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 스튜디오의 버전 카탈로그 파일 및 Project 공개 SDK의 구조 대화상자 Google Play SDK 색인(다음 문제가 적용되는 경우)

  • 작성자가 SDK를 오래된 버전으로 표시했습니다.
  • SDK가 Play 정책을 위반합니다.

경고는 이러한 종속 항목을 업데이트해야 한다는 신호입니다. 오래된 버전을 사용하면 Google Play에 게시하지 못할 수 있습니다. 살펴보겠습니다

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

버전 카탈로그를 사용하여 종속 항목을 추가하고 관리하는 것이 좋지만, 프로젝트에는 필요하지 않을 수 있습니다 다음은 버전 카탈로그:

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

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

Kotlin

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

Groovy

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

빌드 파일은 또한 Android 라이브러리 모듈에 대한 종속 항목을 선언합니다. "mylibrary"; 이 이름은 include:로 정의된 라이브러리 이름과 settings.gradle.kts 파일을 다운로드합니다. 앱을 빌드할 때 빌드 시스템은 라이브러리 모듈을 컴파일하고 그 결과로 컴파일된 콘텐츠를 있습니다.

빌드 파일은 Android Gradle 플러그인의 종속 항목도 선언합니다. (com.application.android) 동일한 API를 사용하는 모듈이 여러 개 있는 경우 빌드 클래스 경로에 단일 버전의 플러그인만 있을 수 있음 확인할 수 있습니다 각 모듈에서 버전을 지정하는 대신 빌드 스크립트의 경우 루트 빌드 스크립트에 플러그인 종속 항목을 포함해야 합니다. 적용하지 않도록 지정합니다 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'
}