빌드 종속 항목 추가

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

종속 항목 유형

프로젝트에 종속 항목을 추가하려면 모듈 build.gradle 파일의 dependencies 블록에 implementation과 같은 종속 항목 구성을 지정합니다.

예를 들어 앱 모듈의 다음 build.gradle 파일에는 세 가지 종속 항목 유형이 포함되어 있습니다.

plugins {
  id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a local library module
    implementation project(':mylibrary')

    // Dependency on local binaries
    implementation fileTree(dir: 'libs', include: ['*.jar'])

    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
}

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

android { ... }

dependencies {
    // Dependency on a local library module
    implementation(project(":mylibrary"))

    // Dependency on local binaries
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar"))))

    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
}

이러한 각 유형은 다음과 같이 서로 다른 라이브러리 종속 항목을 요청합니다.

로컬 라이브러리 모듈 종속 항목

Groovy

implementation project(':mylibrary')

Kotlin

implementation(project(":mylibrary"))

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

로컬 바이너리 종속 항목

Groovy

  implementation fileTree(dir: 'libs', include: ['*.jar'])
  

Kotlin

  implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar"))))
  

Gradle은 build.gradle 파일에 관한 경로를 읽기 때문에 프로젝트의 module_name/libs/ 디렉터리 내의 JAR 파일 종속성을 선언합니다.

또는 다음과 같이 개별 파일을 지정할 수도 있습니다.

Groovy

  implementation files('libs/foo.jar', 'libs/bar.jar')
  

Kotlin

  implementation(files("libs/foo.jar", "libs/bar.jar"))
  

원격 바이너리 종속 항목

Groovy

  implementation 'com.example.android:app-magic:12.3'
  

Kotlin

  implementation("com.example.android:app-magic:12.3")
  

위의 내용을 길게 풀면 다음과 같습니다.

Groovy

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

Kotlin

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

'com.example.android' 네임스페이스 그룹 안에 있는 'app-magic' 라이브러리의 버전 12.3에 관한 종속 항목을 선언합니다.

참고: 이와 같은 원격 종속 항목을 사용하려면 Gradle이 라이브러리를 찾아야 하는 적절한 원격 저장소를 선언해야 합니다. 라이브러리가 아직 로컬에 존재하지 않는 경우 Gradle은 빌드에서 라이브러리가 필요할 때(예: Sync Project with Gradle Files 를 클릭할 때 또는 빌드를 실행할 때) 원격 사이트에서 가져옵니다.

컴파일 시간에 AGP 종속 항목을 사용하는 경우 이를 명시적인 종속 항목으로 추가해야 합니다. AGP가 내부적으로 api/implementation 구성을 사용하므로 컴파일 클래스 경로에서 일부 아티팩트가 삭제되고 컴파일 클래스 경로가 변경될 수 있습니다.

네이티브 종속 항목

Android Gradle 플러그인 4.0부터는 이 페이지에서 설명하는 방식으로 네이티브 종속 항목을 가져올 수도 있습니다.

네이티브 라이브러리를 노출하는 AAR에 따라 externalNativeBuild에서 사용하는 빌드 시스템에서 자동으로 사용할 수 있게 됩니다. 코드에서 라이브러리에 액세스하려면 네이티브 빌드 스크립트에서 라이브러리에 연결해야 합니다. 이 페이지에서 네이티브 종속 항목 사용을 참고하세요.

종속 항목 구성

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

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

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

예를 들어 'free' 제품 버전에만 implementation 종속 항목을 추가하는 방법은(원격 바이너리 종속 항목 사용) 다음과 같습니다.

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

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

그러나 제품 버전 및 빌드 유형이 결합된 변형에 종속 항목을 추가하려면 configurations 블록에서 구성 이름을 초기화해야 합니다. 다음 샘플에서는 'freeDebug' 빌드 변형에 runtimeOnly 종속 항목을 추가합니다(로컬 바이너리 종속 항목 사용).

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

dependencies {
    freeDebugRuntimeOnly fileTree(dir: 'libs', include: ['*.jar'])
}

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

dependencies {
    freeDebugRuntimeOnly(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar"))))
}

로컬 테스트와 계측 테스트에 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.5.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.5.1")
}

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

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

주석 프로세서 추가

컴파일 클래스 경로에 주석 프로세서를 추가하면 다음과 유사한 오류 메시지가 표시됩니다.

Error: Annotation processors must be explicitly declared now.

이 오류를 해결하려면 아래와 같이 annotationProcessor를 사용하여 종속 항목을 구성하고 프로젝트에 주석 프로세서를 추가하세요.

dependencies {
    // Adds libraries defining annotations to only the compile classpath.
    compileOnly 'com.google.dagger:dagger:version-number'
    // Adds the annotation processor dependency to the annotation processor classpath.
    annotationProcessor 'com.google.dagger:dagger-compiler:version-number'
}

dependencies {
    // Adds libraries defining annotations to only the compile classpath.
    compileOnly("com.google.dagger:dagger:version-number")
    // Adds the annotation processor dependency to the annotation processor classpath.
    annotationProcessor("com.google.dagger:dagger-compiler:version-number")
}

참고:Gradle용 Android 플러그인 3.0.0 이상에서는 더 이상 android-apt 플러그인이 지원되지 않습니다.

주석 프로세서에 인수 전달

주석 프로세서에 인수를 전달해야 하는 경우 모듈의 빌드 구성에서 AnnotationProcessorOptions 블록을 사용하여 전달하면 됩니다. 예를 들어 프리미티브 데이터 유형을 키-값 쌍으로 전달하려면 아래와 같이 argument 속성을 사용하면 됩니다.

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                argument 'key1', 'value1'
                argument 'key2', 'value2'
            }
        }
    }
}

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                arguments += mapOf("key1" to "value1",
                                   "key2" to "value2")
            }
        }
    }
}

그러나 Android Gradle 플러그인 3.2.0 이상을 사용하는 경우 Gradle의 CommandLineArgumentProvider 인터페이스를 사용하여 파일이나 디렉터리를 나타내는 프로세서 인수를 전달해야 합니다.

CommandLineArgumentProvider를 사용하면 개발자 또는 주석 프로세서 작성자가 각 인수에 증분 빌드 속성 유형 주석을 적용하여 증분 및 캐시된 클린 빌드의 정확성과 성능을 개선할 수 있습니다.

예를 들어 아래의 클래스에는 CommandLineArgumentProvider를 구현하고 프로세서의 각 인수에 주석을 추가합니다. 또한 이 샘플은 Groovy 언어 구문을 사용하며 모듈의 build.gradle 파일에 직접 포함됩니다.

class MyArgsProvider implements CommandLineArgumentProvider {

    // Annotates each directory as either an input or output for the
    // annotation processor.
    @InputFiles
    // Using this annotation helps Gradle determine which part of the file path
    // should be considered during up-to-date checks.
    @PathSensitive(PathSensitivity.RELATIVE)
    FileCollection inputDir

    @OutputDirectory
    File outputDir

    // The class constructor sets the paths for the input and output directories.
    MyArgsProvider(FileCollection input, File output) {
        inputDir = input
        outputDir = output
    }

    // Specifies each directory as a command line argument for the processor.
    // The Android plugin uses this method to pass the arguments to the
    // annotation processor.
    @Override
    Iterable<String> asArguments() {
        // Use the form '-Akey[=value]' to pass your options to the Java compiler.
        ["-AinputDir=${inputDir.singleFile.absolutePath}",
         "-AoutputDir=${outputDir.absolutePath}"]
    }
}

android {...}

class MyArgsProvider(
    // Annotates each directory as either an input or output for the
    // annotation processor.
    @get:InputFiles
    // Using this annotation helps Gradle determine which part of the file path
    // should be considered during up-to-date checks.
    @get:PathSensitive(PathSensitivity.RELATIVE)
    val inputDir: FileCollection,

    @get:OutputDirectory
    val outputDir: File
) : CommandLineArgumentProvider {
    // Specifies each directory as a command line argument for the processor.
    // The Android plugin uses this method to pass the arguments to the
    // annotation processor.

    override fun asArguments(): Iterable<String> {
        // Use the form '-Akey[=value]' to pass your options to the Java compiler.
        return listOf("-AinputDir=${inputDir.singleFile.absolutePath}",
                      "-AoutputDir=${outputDir.absolutePath}")
    }
}

android {...}

CommandLineArgumentProvider를 구현하는 클래스를 정의한 후에는 아래와 같이 annotationProcessorOptions.compilerArgumentProvider 메서드를 사용하여 인스턴스를 만들고 Android 플러그인에 전달해야 합니다.

// This is in your module's build.gradle file.
android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                // Creates a new MyArgsProvider object, specifies the input and
                // output paths for the constructor, and passes the object
                // to the Android plugin.
                compilerArgumentProvider new MyArgsProvider(files("input/path"),
                                         new File("output/path"))
            }
        }
    }
}

// This is in your module's build.gradle file.
android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                // Creates a new MyArgsProvider object, specifies the input and
                // output paths for the constructor, and passes the object
                // to the Android plugin.
                compilerArgumentProvider(MyArgsProvider(files("input/path"),
                                                          file("output/path")))
            }
        }
    }
}

CommandLineArgumentProvider 구현을 통해 빌드 성능을 개선하는 방법에 관한 자세한 내용은 자바 프로젝트 캐싱을 참고하세요.

주석 프로세서 오류 검사 중지

불필요한 주석 프로세서가 포함된 종속 항목이 컴파일 클래스 경로에 있는 경우 다음을 build.gradle 파일에 추가하여 오류 검사를 중지할 수 있습니다. 컴파일 클래스 경로에 주석 프로세서를 추가해도 프로세서 클래스 경로에는 추가되지 않습니다.

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                includeCompileClasspath false
            }
        }
    }
}

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                argument("includeCompileClasspath", "false")
            }
        }
    }
}

Kotlin과 kapt를 사용하는 경우:

android {
    ...
    defaultConfig {
        ...
        kapt {
            includeCompileClasspath false
        }
    }
}

android {
    ...
    defaultConfig {
        ...
        kapt {
            includeCompileClasspath = false
        }
    }
}

프로젝트의 주석 프로세서를 프로세서 클래스 경로로 이전한 후 문제가 발생하면 includeCompileClasspath를 true로 설정하여 컴파일 클래스 경로의 주석 프로세서를 허용할 수 있습니다. 그러나 이 속성을 true로 설정하는 것은 권장되지 않으며 이렇게 하는 옵션은 향후 Android 플러그인 업데이트에서 삭제될 예정입니다.

전이 종속 항목 제외

앱의 범위가 커짐에 따라 앱에 직접 종속 항목과 전이 종속 항목(앱에 가져온 라이브러리가 종속된 라이브러리)을 비롯한 다수의 종속 항목이 포함될 수 있습니다. 더는 필요하지 않은 전이 종속 항목을 제외하려면 다음과 같이 exclude 키워드를 사용하면 됩니다.

dependencies {
    implementation('some-library') {
        exclude group: 'com.example.imgtools', module: 'native'
    }
}

dependencies {
    implementation("some-library") {
        exclude(group = "com.example.imgtools", module = "native")
    }
}

테스트 구성에서 전이 종속 항목 제외

테스트에서 특정 전이 종속 항목을 제외해야 하는 경우 위에 표시된 코드 샘플이 예상한 대로 작동하지 않을 수 있습니다. 테스트 구성(예: androidTestImplementation)이 모듈의 implementation 구성을 확장하기 때문입니다. 즉 Gradle이 구성을 확인할 때 항상 implementation 종속 항목이 포함됩니다.

따라서 테스트에서 전이 종속 항목을 제외하려면 아래와 같이 실행 시에 제외해야 합니다.

android.testVariants.all { variant ->
    variant.getCompileConfiguration().exclude group: 'com.jakewharton.threetenabp', module: 'threetenabp'
    variant.getRuntimeConfiguration().exclude group: 'com.jakewharton.threetenabp', module: 'threetenabp'
}

android.testVariants.all {
    compileConfiguration.exclude(group = "com.jakewharton.threetenabp", module = "threetenabp")
    runtimeConfiguration.exclude(group = "com.jakewharton.threetenabp", module = "threetenabp")
}

참고: 전이 종속 항목 제외 섹션의 원본 코드 샘플과 같이 종속 항목 블록에서 exclude 키워드를 사용하여 테스트 구성에서만 사용하고 다른 구성에는 포함되지 않는 전이 종속 항목을 생략할 수 있습니다.

Wear OS 앱 종속 항목 구성

Wear OS 모듈의 종속 항목 구성은 다른 모듈의 종속 항목을 구성하는 것과 비슷합니다. 즉, Wear OS 모듈은 implementation 및 compileOnly와 같이 동일한 종속 항목 구성을 사용합니다.

Wear 모듈은 변형 인식 종속 항목 관리도 지원합니다. 결과적으로 기본 앱 모듈이 Wear 모듈에 종속된 경우 기본 모듈의 각 변형에서 Wear 모듈의 매칭 변형을 사용합니다.

원격 저장소

종속 항목이 로컬 라이브러리나 파일 트리가 아닌 경우 Gradle은 settings.gradle 파일의 dependencyResolutionManagement { repositories {...} } 블록에서 지정된 온라인 저장소에서 파일을 찾습니다. 각 저장소를 나열하는 순서에 따라 Gradle이 각 프로젝트 종속 항목의 저장소를 검색하는 순서가 결정됩니다. 예를 들어 종속 항목을 저장소 A와 B에서 다운로드할 수 있고 A를 먼저 나열한 경우 Gradle은 저장소 A에서 종속 항목을 다운로드합니다.

기본적으로 새 Android 스튜디오 프로젝트에서 아래와 같이 Google Maven 저장소를 지정하고 Maven 중앙 저장소를 프로젝트의 settings.gradle 파일의 저장소 위치로 지정합니다.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

로컬 저장소에서 항목을 가져오려면 mavenLocal()을 사용합니다.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        mavenLocal()
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        mavenLocal()
    }
}

또는 다음과 같이 특정 Maven이나 Ivy 저장소를 선언할 수 있습니다.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven {
            url 'https://repo.example.com/maven2'
        }
        maven {
            url 'file://local/repo/'
        }
        ivy {
            url 'https://repo.example.com/ivy'
        }
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven(url = "https://repo.example.com/maven2")
        maven(url = "file://local/repo/")
        ivy(url = "https://repo.example.com/ivy")
    }
}

자세한 내용은 Gradle 저장소 가이드를 참고하세요.

Google Maven 저장소

다음 Android 라이브러리의 가장 최근 버전은 Google Maven 저장소에서 찾을 수 있습니다.

• AndroidX 라이브러리
• 아키텍처 구성요소 라이브러리
• 제약 조건 레이아웃 라이브러리
• AndroidX 테스트
• 데이터 바인딩 라이브러리
• Android 인스턴트 앱 라이브러리
• Wear OS
• Google Play 서비스
• Google Play 결제 라이브러리
• Firebase

Google Maven 저장소 색인에서 사용할 수 있는 모든 아티팩트를 볼 수 있습니다(프로그래매틱 액세스는 아래를 참조).

이러한 라이브러리 중 하나를 빌드에 추가하려면 최상위 수준 build.gradle 파일에 Google Maven 저장소를 포함하세요.

dependencyResolutionManagement {

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()

        // If you're using a version of Gradle lower than 4.1, you must instead use:
        // maven {
        //     url 'https://maven.google.com'
        // }
        // An alternative URL is 'https://dl.google.com/dl/android/maven2/'.
    }
}

dependencyResolutionManagement {

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()

        // If you're using a version of Gradle lower than 4.1, you must instead use:
        // maven {
        //     url = "https://maven.google.com"
        // }
        // An alternative URL is "https://dl.google.com/dl/android/maven2/".
    }
}

그런 다음 원하는 라이브러리를 모듈의 dependencies 블록에 추가합니다. 예를 들어 appcompat 라이브러리는 다음과 같습니다.

dependencies {
    implementation 'androidx.appcompat:appcompat:1.6.1'
}

dependencies {
    implementation("com.android.support:appcompat-v7:28.0.0")
}

그러나 위 라이브러리의 이전 버전을 사용하려고 하고 종속 항목에 오류가 발생하면 그 버전은 Maven 저장소에서 사용할 수 없으며 대신 오프라인 저장소에서 라이브러리를 가져와야 합니다.

프로그래매틱 액세스

Google Maven 아티팩트에 프로그래매틱 방식으로 액세스하려면 maven.google.com/master-index.xml에서 아티팩트 그룹의 XML 목록을 가져옵니다. 그러면 다음 경로에 모든 그룹의 라이브러리 이름과 버전이 표시됩니다.

maven.google.com/group_path/group-index.xml

예를 들어 android.arch.lifecycle 그룹의 라이브러리는 maven.google.com/android/arch/lifecycle/group-index.xml에 나열됩니다.

또한 다음 경로에서 POM 및 JAR 파일을 다운로드할 수 있습니다.

maven.google.com/group_path/library/version/library-version.ext

예: maven.google.com/android/arch/lifecycle/compiler/1.0.0/compiler-1. 0.0.pom.

SDK 관리자의 오프라인 저장소

Google Maven 저장소에 없는 라이브러리(주로 이전 버전의 라이브러리)의 경우 SDK Manager에서 오프라인 Google 저장소 패키지를 다운로드해야 합니다.

그런 다음 평소와 같이 이러한 라이브러리를 dependencies 블록에 추가할 수 있습니다.

오프라인 라이브러리는 android_sdk/extras/에 저장됩니다.

Android Gradle 플러그인의 네이티브 종속 항목

AAR 라이브러리에는 Android Gradle 플러그인이 사용할 수 있는 네이티브 종속 항목이 포함될 수 있습니다. AGP는 네이티브 라이브러리를 소비자에게 노출하는 AAR을 생성할 수도 있습니다.

네이티브 종속 항목 사용

Android Gradle 플러그인 4.0부터는 C/C++ 종속 항목을 build.gradle 파일에 연결된 AAR에서 가져올 수 있습니다. Gradle은 이 기능을 네이티브 빌드 시스템에 자동으로 제공하지만 가져온 라이브러리와 헤더를 사용하도록 빌드 시스템을 구성해야 합니다. C/C++ 종속 항목은 AAR로 배포되므로 일반 AAR에 관한 다음 링크가 도움이 될 수 있습니다.

• 일반 AAR을 위한 Android 라이브러리 만들기 문서 및 프로젝트에 라이브러리를 통합하는 방법(로컬 C/C++ 종속 항목으로 AAR을 사용하려는 경우)
• build.gradle 파일에 종속 항목을 추가하는 방법에 관한 빌드 종속 항목 추가(특히 원격 종속 항목인 경우)

이 문서에서는 네이티브 빌드 시스템을 구성하는 방법에 중점을 두며, 프로젝트의 Gradle 빌드 환경에 C/C++ 종속 항목 AAR을 이미 추가했다고 가정합니다.

AAR의 네이티브 종속 항목

Gradle 모듈의 AAR 종속 항목은 애플리케이션에서 사용할 네이티브 라이브러리를 노출할 수 있습니다. AAR 내의 prefab 디렉터리는 Prefab 패키지를 포함하며 이 패키지에는 네이티브 종속 항목의 헤더와 라이브러리가 포함됩니다.

각 종속 항목은 하나 이상의 모듈로 구성된 Prefab 패키지를 최대 한 개까지 노출할 수 있습니다. Prefab 모듈은 단일 라이브러리로서 공유, 정적 또는 헤더 전용 라이브러리일 수 있습니다.

라이브러리를 사용하려면 패키지 및 모듈 이름을 알아야 합니다. 규칙에 따라 패키지 이름은 Maven 아티팩트 이름과 일치하고 모듈 이름은 C/C++ 라이브러리 이름과 일치하지만 반드시 그래야 하는 것은 아닙니다. 종속 항목의 문서를 참고하여 사용하는 이름이 무엇인지 확인합니다.

빌드 시스템 구성

Android Gradle 플러그인 4.0 Android Gradle 플러그인 4.1 이상

Android Gradle 모듈에 prefab 기능이 사용 설정되어 있어야 합니다.

이렇게 하려면 모듈의 build.gradle 파일에 있는 android 블록에 다음을 추가합니다.

buildFeatures {
  prefab true
}

buildFeatures {
  prefab = true
}

필요한 경우 프로젝트의 gradle.properties 파일에서 버전을 구성합니다.

android.prefabVersion=2.0.0

일반적으로 선택한 AGP 기본 버전이 필요에 적합합니다. 해결해야 하는 버그가 있거나 원하는 새 기능이 있는 경우에만 다른 버전을 선택해야 합니다.

CMake ndk-build

AAR에서 가져온 종속 항목은 CMAKE_FIND_ROOT_PATH를 통해 CMake에 노출됩니다. 이 값은 CMake 호출 시 Gradle에 의해 자동으로 설정되므로, 빌드가 이 변수를 수정하는 경우 변수에 할당하지 말고 추가해야 합니다.

각 종속 항목은 config-file 패키지를 빌드에 노출합니다. 이 패키지는 find_package 명령어를 사용하여 가져옵니다. 이 명령어는 지정된 패키지 이름 및 버전과 일치하는 config-file 패키지를 검색하여 정의하는 타겟을 빌드에서 사용되도록 노출합니다. 예를 들어 애플리케이션에서 libapp.so를 정의하고 cURL을 사용한다면 CMakeLists.txt에는 다음이 포함되어야 합니다.

add_library(app SHARED app.cpp)

# Add these two lines.
find_package(curl REQUIRED CONFIG)
target_link_libraries(app curl::curl)

이제 app.cpp가 #include "curl/curl.h"할 수 있으며 libapp.so는 빌드할 때 자동으로 libcurl.so에 연결되고 libcurl.so는 앱에 포함됩니다.

AAR로 네이티브 라이브러리 게시

네이티브 AAR을 만드는 기능은 AGP 4.1에서 처음 추가되었습니다.

네이티브 라이브러리를 내보내려면 라이브러리 프로젝트 build.gradle 파일의 android 블록에 다음을 추가하세요.

buildFeatures {
    prefabPublishing true
}

prefab {
    mylibrary {
      headers "src/main/cpp/mylibrary/include"
    }

    myotherlibrary {
        headers "src/main/cpp/myotherlibrary/include"
    }
}

buildFeatures {
    prefabPublishing = true
}

prefab {
    create("mylibrary") {
      headers = "src/main/cpp/mylibrary/include"
    }

    create("myotherlibrary") {
        headers = "src/main/cpp/myotherlibrary/include"
    }
}

이 예에서 ndk-build 또는 CMake 외부 네이티브 빌드의 mylibrary 및 myotherlibrary 라이브러리는 빌드에서 생성된 AAR에 패키징되며 각각은 지정된 디렉터리의 헤더를 종속 디렉터리로 내보냅니다.

종속 항목 순서

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

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

• 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보다 우선순위가 높게 됩니다.

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

모듈 종속 항목 보기

일부 직접 종속 항목은 자체 종속 항목을 가질 수도 있습니다. 이런 종속 항목을 전이 종속 항목이라고 합니다. 각 전이 종속 항목은 수동으로 선언하지 않아도 Gradle에서 자동으로 수집하여 추가합니다. Gradle용 Android 플러그인에서 주어진 모듈을 위해 Gradle이 해결하는 종속 항목 목록을 표시합니다.

각 모듈의 보고서에서는 또한 빌드 변형, 테스트 소스 세트 및 클래스 경로를 기반으로 종속 항목을 그룹화합니다. 다음은 디버그 빌드 변형의 앱 모듈 런타임 클래스 경로 및 계측 테스트 소스 세트의 컴파일 클래스 경로를 위한 샘플 보고서입니다.

debugRuntimeClasspath - Dependencies for runtime/packaging
+--- :mylibrary (variant: debug)
+--- com.google.android.material:material:1.0.0@aar
+--- androidx.appcompat:appcompat:1.0.2@aar
+--- androidx.constraintlayout:constraintlayout:1.1.3@aar
+--- androidx.fragment:fragment:1.0.0@aar
+--- androidx.vectordrawable:vectordrawable-animated:1.0.0@aar
+--- androidx.recyclerview:recyclerview:1.0.0@aar
+--- androidx.legacy:legacy-support-core-ui:1.0.0@aar
...

debugAndroidTest
debugAndroidTestCompileClasspath - Dependencies for compilation
+--- androidx.test.ext:junit:1.1.0@aar
+--- androidx.test.espresso:espresso-core:3.1.1@aar
+--- androidx.test:runner:1.1.1@aar
+--- junit:junit:4.12@jar
...

이 작업을 실행하려면 다음 절차를 따르세요.

1. View > Tool Windows > Gradle을 선택하거나 도구 창 모음에서 Gradle 을 클릭합니다.
2. AppName > Tasks > android를 펼치고 androidDependencies를 더블클릭합니다. Gradle에서 작업을 실행하면 Run 창이 열리고 출력 내용이 표시됩니다.

Gradle의 종속 항목 관리에 관한 자세한 내용은 Gradle 사용자 가이드의 종속 항목 관리 기본 사항을 참조하세요.

종속 항목 해결 오류 수정

앱 프로젝트에 여러 종속 항목을 추가할 때 직접 종속 항목과 전이 종속 항목이 서로 충돌할 수 있습니다. Android Gradle 플러그인에서는 이러한 충돌을 적절히 해결하려고 하지만 일부 충돌은 컴파일 시간 또는 런타임 오류로 이어질 수 있습니다.

어느 종속 항목이 오류의 원인인지 조사하려면 앱 종속 항목 트리를 검사하고 2회 이상 나타나거나 충돌 버전이 있는 종속 항목을 찾습니다.

중복 종속 항목을 쉽게 찾을 수 없으면 다음과 같이 Android 스튜디오의 UI를 사용하여 중복 클래스가 포함된 종속 항목을 검색합니다.

1. 메뉴 바에서 Navigate > Class를 선택합니다.
2. 팝업 검색 대화상자에서 Include non-project items 옆에 있는 체크박스가 선택되어 있는지 확인합니다.
3. 빌드 오류에 표시된 클래스의 이름을 입력합니다.
4. 클래스가 포함된 종속 항목의 결과를 검사합니다.

다음 섹션에서는 발생할 수 있는 종속 항목 해결 오류의 여러 유형과 해결 방법을 설명합니다.

중복 클래스 오류 수정

한 클래스가 런타임 클래스 경로에 두 번 이상 표시되면 다음과 유사한 오류가 발생합니다.

Program type already present com.example.MyClass

이 오류는 일반적으로 다음과 같은 경우에 발생합니다.

• 바이너리 종속 항목에 앱에 직접 종속 항목으로 포함된 라이브러리가 포함되어 있습니다. 예를 들어 앱에서 라이브러리 A와 라이브러리 B에 직접 종속 항목을 선언하지만 라이브러리 A의 바이너리에 이미 라이브러리 B가 포함되어 있습니다.
  • 이 문제를 해결하려면 라이브러리 B를 직접 종속 항목에서 삭제합니다.
• 앱의 동일한 라이브러리에 로컬 바이너리 종속 항목과 원격 바이너리 종속 항목이 있습니다.
  • 이 문제를 해결하려면 바이너리 종속 항목 중 하나를 삭제합니다.

클래스 경로 간 충돌 수정

Gradle이 컴파일 클래스 경로를 해결할 때 먼저 런타임 클래스 경로를 해결하고 그 결과를 사용하여 컴파일 클래스 경로에 추가해야 하는 종속 항목의 버전을 결정합니다. 즉 런타임 클래스 경로에서 다운스트림 클래스 경로의 동일한 종속 항목에 필요한 버전 번호를 결정합니다.

또한 앱의 런타임 클래스 경로에서 Gradle이 앱 테스트 APK의 런타임 클래스 경로에서 종속 항목을 매칭하는 데 필요한 버전 번호를 결정합니다. 그림 1에 클래스 경로의 계층 구조가 설명되어 있습니다.

그림 1. 여러 클래스 경로에 표시되는 종속 항목의 버전 번호는 이 계층 구조에 따라 매칭해야 합니다.

예를 들어 앱에서 implementation 종속 항목 구성을 사용하여 종속 항목의 한 버전을 포함하고 라이브러리 모듈에서는 runtimeOnly 구성을 사용하여 종속 항목의 다른 버전을 포함할 때 여러 클래스 경로에 동일한 종속 항목의 다른 버전이 표시되는 경우 충돌이 발생할 수 있습니다.

런타임 및 컴파일 시간 클래스 경로의 종속 항목을 해결할 때 Android Gradle 플러그인 3.3.0 이상에서는 특정 다운스트림 버전의 충돌을 자동으로 수정하려고 합니다. 예를 들어 런타임 클래스 경로에 라이브러리 A 버전 2.0이 포함되고 컴파일 클래스 경로에 라이브러리 A 버전 1.0이 포함된 경우 플러그인에서 오류를 방지하기 위해 컴파일 클래스 경로의 종속 항목을 라이브러리 A 버전 2.0으로 자동 업데이트합니다.

그러나 런타임 클래스 경로에 라이브러리 버전 1.0이 포함되고 컴파일 클래스 경로에 라이브러리 A 버전 2.0이 포함된 경우에는 플러그인에서 컴파일 클래스 경로의 종속 항목을 라이브러리 A 버전 1.0으로 다운그레이드하지 않으며 다음과 유사한 오류가 계속 발생합니다.

Conflict with dependency 'com.example.library:some-lib:2.0' in project 'my-library'.
Resolved versions for runtime classpath (1.0) and compile classpath (2.0) differ.

이 문제를 해결하려면 다음 중 한 가지를 따르세요.

• 원하는 종속 항목을 라이브러리 모듈에 api 종속 항목으로 포함합니다. 즉 라이브러리 모듈에서만 이 종속 항목을 선언하지만 앱 모듈에서도 라이브러리 모듈의 API에 액세스할 수 있게 됩니다.
• 또는 두 모듈에 모두 종속 항목을 선언할 수 있지만 각 모듈에서 동일한 버전의 종속 항목을 사용하는지 확인해야 합니다. 프로젝트 전체에서 각 종속 항목의 버전을 일관되게 유지하려면 프로젝트 범위 속성을 구성해 보세요.

맞춤 빌드 로직 적용

이 섹션에서는 Android Gradle 플러그인을 확장하거나 플러그인을 작성할 때 유용한 고급 주제에 관해 설명합니다.

변형 종속 항목을 맞춤 로직에 게시

라이브러리에 다른 프로젝트 또는 하위 프로젝트에서 사용하려는 기능이 포함되어 있을 수 있습니다. 라이브러리 게시는 라이브러리를 사용자에게 제공하는 과정입니다. 라이브러리에서 사용자가 컴파일 및 런타임 시 액세스할 수 있는 종속 항목을 관리할 수 있습니다.

아래에 설명한 대로 사용자가 라이브러리를 이용하기 위해 사용해야 하는 각 클래스 경로의 전이 종속 항목이 포함된 두 개의 별도 구성이 있습니다.

• variant_nameApiElements: 이 구성에는 사용자가 컴파일 시에 이용 가능한 전이 종속 항목이 포함됩니다.
• variant_nameRuntimeElements: 이 구성에는 사용자가 런타임에 이용 가능한 전이 종속 항목이 포함됩니다.

여러 구성 간의 관계에 관한 자세한 내용은 자바 라이브러리 플러그인 구성을 참고하세요.

맞춤 종속 항목 해결 전략

한 프로젝트에 동일한 라이브러리의 두 버전에 관한 종속 항목이 포함될 수 있으며 이 때문에 종속 항목 충돌이 발생할 수 있습니다. 예를 들어 프로젝트가 모듈 A의 버전 1과 모듈 B의 버전 2에 종속되고 모듈 A가 모듈 B의 버전 3에 전이 종속된 경우 종속 항목 충돌이 발생합니다.

이 충돌을 해결하기 위해 Android Gradle 플러그인에서는 다음과 같은 종속 항목 해결 전략을 사용합니다. 즉 플러그인에서 종속 항목 그래프에 동일한 모듈의 여러 버전이 있음을 감지하면 기본적으로 버전 번호가 가장 높은 버전을 선택합니다.

그러나 이 전략이 항상 의도한 대로 작동하는 것은 아닙니다. 종속 항목 해결 전략을 맞춤설정하려면 다음 구성을 사용하여 작업에 필요한 변형의 특정 종속 항목을 해결해야 합니다.

• variant_nameCompileClasspath: 이 구성에는 주어진 변형의 컴파일 클래스 경로에 맞는 해결 전략이 포함되어 있습니다.
• variant_nameRuntimeClasspath: 이 구성에는 주어진 변형의 런타임 클래스 경로에 맞는 해결 전략이 포함되어 있습니다.

Android Gradle 플러그인에는 각 변형의 구성 객체에 액세스하는 데 사용할 수 있는 getter가 포함되어 있습니다. 따라서 아래 예와 같이 변형 API를 사용하여 종속 항목 해결을 쿼리할 수 있습니다.

android {
    applicationVariants.all { variant ->
        // Return compile configuration objects of a variant.
        variant.getCompileConfiguration().resolutionStrategy {
        // Use Gradle's ResolutionStrategy API
        // to customize how this variant resolves dependencies.
            ...
        }
        // Return runtime configuration objects of a variant.
        variant.getRuntimeConfiguration().resolutionStrategy {
            ...
        }
        // Return annotation processor configuration of a variant.
        variant.getAnnotationProcessorConfiguration().resolutionStrategy {
            ...
        }
    }
}

android {
    applicationVariants.all {
        // Return compile configuration objects of a variant.
        compileConfiguration.resolutionStrategy {
        // Use Gradle's ResolutionStrategy API
        // to customize how this variant resolves dependencies.
            ...
        }
        // Return runtime configuration objects of a variant.
        runtimeConfiguration.resolutionStrategy {
            ...
        }
        // Return annotation processor configuration of a variant.
        annotationProcessorConfiguration.resolutionStrategy {
            ...
        }
    }
}

Play Console의 종속 항목 정보

AGP 4.0.0 이상을 사용하여 앱을 빌드할 때 플러그인에는 앱에 컴파일되는 라이브러리 종속 항목을 설명하는 메타데이터가 포함되어 있습니다. 앱을 업로드할 때 Play Console은 이 메타데이터를 검사하여 SDK 및 앱에서 사용하는 종송 항목에 관해 알려진 문제 관련 알림을제공하고, 일부 경우 문제 해결을 위한 실행 가능한 피드백도 제공합니다.

데이터는 압축되고 Google Play 서명 키에 의해 암호화되며 출시 앱의 서명 블록에 저장됩니다. 안전하고 긍정적인 사용자 환경을 위해 이 종속 항목 파일을 보관하는 것이 좋습니다. 이 정보를 공유하지 않으려면 모듈의 build.gradle 파일에 다음 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의 린트 경고를 build.gradle 파일 및 Project Structure Dialog에 표시합니다. 이는 이러한 종속 항목을 업데이트하라는 신호입니다. 오래된 버전을 사용하면 향후 Google Play Console에 게시하지 못할 수 있기 때문입니다.