Android Gradle 플러그인 DSL/API 이전 일정

Android Gradle 플러그인 (AGP)은 Android 애플리케이션을 지원하는 빌드 시스템으로, 다양한 유형의 소스를 컴파일하고 실제 Android 기기 또는 에뮬레이터에서 실행할 수 있는 애플리케이션에 컴파일된 소스를 연결하는 지원 기능이 있습니다.

다음 섹션에서는 AGP의 DSL 및 API에 예정된 변경사항을 설명합니다. 새 API가 공개 버전에 도입됨에 따라 이전 API는 지원 중단됨으로 표시됩니다. 지원 중단된 API는 다음 공개 버전에서 사용할 수 없게 됩니다. 다음 섹션에서는 각 주요 AGP 출시에 예정된 변경사항에 관한 정보를 제공합니다.

AGP API 지원 중단 또는 삭제에 관한 더 자세한 내용은 AGP API 업데이트를 참고하세요.

참고: 다음 기간은 추정치이며 변경될 수 있습니다.

AGP 10.0 (2026년 말)

Android Gradle 플러그인 10.0 API 변경사항 및 현대화

AGP 10.0은 완전히 지연되고 구성 캐시와 호환되는 빌드 모델로의 전환을 완료합니다. 이 출시에서는 레거시 지연되지 않는 API를 더 안전하고 성능이 우수한 아키텍처로 대체하기 위한 수년간의 노력이 마무리됩니다.

지연 빌드 모델을 사용하는 이유

레거시 지연되지 않는 빌드 모델에서 Gradle은 모든 동기화 또는 빌드 호출 중에 모든 프로젝트 모듈에서 객체를 적극적으로 평가하고, 변형 데이터를 쿼리하고, 태스크를 구성합니다. 이러한 적극적인 평가로 인해 실행되지 않는 변형 및 태스크에서 CPU 시간과 메모리가 낭비되고 복잡한 빌드 스크립트에서 평가 순서 충돌이 발생합니다.

지연 제공자 (Provider<T>) 및 최신 변형 API (androidComponents {})를 사용하여 완전히 지연되는 빌드 모델로 전환하면 속성 및 태스크 연결이 활성 빌드 실행 그래프에 필요한 경우에만 지연 방식으로 계산됩니다.

이 출시에서 삭제되는 레거시 API는 이 최신 아키텍처와 근본적으로 호환되지 않았습니다. 이러한 API를 삭제하면 AGP가 Gradle 구성 캐시 및 프로젝트 격리를 완전히 지원할 수 있으므로 Android 스튜디오에서 빌드 속도와 동기화 시간이 크게 개선됩니다.

핵심 아키텍처 차이점

레거시 BaseVariant API (applicationVariants.all {})는 적극적이고 태스크 중심적이었습니다. 이 API는 구성 단계에서 개발자에게 Gradle 태스크 및 내부 구성에 대한 직접 액세스 권한을 부여하여 최신 Gradle 성능 기능을 근본적으로 손상시킵니다.

새 변형 API (androidComponents {})는 지연되고 아티팩트 중심적입니다. 이 API는 Gradle의 Property API를 광범위하게 사용하고 Task 및 TaskProvider에 대한 모든 참조를 완전히 삭제하므로 기본 태스크 자체가 아닌 입력 및 출력 (Variant.artifacts)과 깔끔하게 상호작용해야 합니다.

삭제되고 대체되는 항목

레거시 DSL 및 이전 변형 API에 사용된 모든 이전 인터페이스와 클래스는 삭제됩니다. 빌드 스크립트와 커스텀 플러그인을 준비하려면 수명이 다한 다음 API 및 플래그에서 이전하세요.

삭제된 API 또는 기능	대체 또는 필요한 작업
직접 태스크 액세스: getJavaCompile() getMergeResourcesProvider() getAssembleProvider()	Artifacts API: 태스크를 가져와 동작을 변경하는 대신 variant.artifacts를 사용하여 태스크 간에 전달되는 실제 파일 (아티팩트)을 추가, 수정 또는 대체합니다.
적극적인 소스 등록: registerJavaGeneratingTask() registerResGeneratingTask()	Sources API: variant.sources.java.addGeneratedSourceDirectory(...)를 사용하여 커스텀 태스크의 출력 디렉터리를 연결합니다.
클래스 경로 / 구성 액세스: getCompileConfiguration() getCompileClasspath()	Instrumentation API: 바이트 코드(클래스 경로 액세스의 가장 일반적인 사용 사례)를 수정하거나 검사하려면 variant.instrumentation.transformClassesWith(...)를 사용하여 AsmClassVisitorFactory를 사용합니다.
적극적인 속성 변경: buildConfigField() resValue()	지연 `MapProperty` 인스턴스: variant.buildConfigFields.put(...) 및 variant.manifestPlaceholders.put(...)을 사용합니다.
선택 해제 플래그: android.newDsl android.builtInKotlin	직접적인 대체가 없습니다. ` gradle.properties`에서 이러한 플래그를 삭제합니다. 최신 DSL 및 기본 제공 Kotlin이 엄격하게 적용됩니다.
레거시 변형 API 확장 프로그램: applicationVariants libraryVariants testVariants unitTestVariants	androidComponents.onVariants()로 대체합니다.
변형 필터링 (variantFilter 블록)	변형 선택기를 사용하여 androidComponents.beforeVariants()로 대체합니다.
SDK 및 NDK 구성요소: sdkDirectory ndkDirectory bootClasspath adbExecutable	`androidComponents.sdkComponents`를 사용하여 SDK 구성요소에 액세스합니다.
테스트 환경: deviceProvider testServer	커스텀 테스트 기기 등록을 Gradle 관리 기기로 이전합니다.
지원 중단된 등록 API: registerArtifactType registerBuildTypeSourceProvider registerProductFlavorSourceProvider registerJavaArtifact registerMultiFlavorSourceProvider wrapJavaSourceSet	직접적인 대체 없이 삭제되었습니다.
Transform API	변환을 Artifacts API 및 AsmClassVisitorFactory로 대체합니다.

모든 대체 DSL 및 변형 API (androidComponents {}) 인터페이스와 클래스에 액세스하려면 커스텀 Gradle 플러그인 또는 빌드 로직을 개발할 때 항상 gradle-api 아티팩트를 사용하세요.

이전 단계

AGP 10.0으로 원활하고 예측 가능하게 업그레이드하려면 다음 이전 관행을 따르세요.

1. AGP 업그레이드 어시스턴트 실행: 10.0으로 직접 업그레이드하기 전에 Android 스튜디오 (Tools > AGP Upgrade Assistant)에서 공식 AGP 업그레이드 어시스턴트를 실행합니다. 이 어시스턴트는 여러 일반적인 DSL 및 빌드 스크립트 이전을 자동화하고 기존 빌드 동작을 유지하는 데 도움이 됩니다.
2. Android 스튜디오에서 에이전트 모드 기술 사용: AI 업그레이드 기술 (예: Android 기술 저장소에서 사용할 수 있는 AGP 업그레이드 기술)을 활용하여 Android 스튜디오 내에서 복잡한 빌드 로직과 DSL 이전을 자동화하고 간소화합니다.
3. 먼저 AGP 9.x에서 지원 중단 경고 수정: 프로젝트를 최신 AGP 9.x 출시로 업그레이드하고 기존의 모든 지원 중단 경고를 해결합니다. 프로젝트가 9.x에서 경고 없이 android.newDsl=false 또는 android.builtInKotlin=false에 의존하지 않고 작동하면 10.0으로 원활하게 전환할 수 있습니다.
4. 서드 파티 Gradle 플러그인 감사: 서드 파티 플러그인이 AGP 10.0 호환 버전으로 업그레이드되었는지 확인합니다. 여전히 레거시 확장 프로그램 유형에 의존하는 플러그인은 ClassCastException: ... cannot be cast to class BaseExtension과 같은 빌드 실패를 일으킵니다.
5. 공식 이전 레시피 사용: 복잡한 실제 이전 예시와 나란히 비교하려면 공식 gradle-recipes GitHub 저장소를 참고하세요.

다음은 레거시 변형을 적극적으로 쿼리하는 것에서 androidComponents {}를 사용하여 변형을 지연 방식으로 구성하는 것으로 이전하는 방법을 보여주는 이전 후 비교입니다.

이전: 레거시 변형 API (AGP 10.0에서 삭제됨)

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

이후: 최신 변형 API (androidComponents {})

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

AGP 9.x에서 AGP 10.0 동작을 테스트하는 방법

AGP 10.0 출시를 기다리지 않고도 빌드 동작을 테스트하고 호환성을 검증할 수 있습니다. AGP 9.x 출시에서 실행하는 동안 선택 해제를 사용 중지하고 다음 엄격한 동작 플래그를 설정하여 AGP 10.0 동작을 명시적으로 적용할 수 있습니다.gradle.properties

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

android.newDsl=true 및 android.builtInKotlin=true를 적용하면 커스텀 빌드 로직과 서드 파티 플러그인이 AGP 10.0의 엄격한 API 요구사항과 완전히 호환되는지 확인할 수 있습니다.

이전 중 선택적 하위 프로젝트 선택 해제

최신 동작을 테스트하기 위해 프로젝트 전체에서 android.newDsl=true를 전역적으로 사용 설정하되 특정 하위 프로젝트를 이전하는 데 시간이 더 필요한 경우 AGP 9.4.0-alpha04부터 개별 모듈을 선택적으로 선택 해제할 수 있습니다. 프로젝트 경로를 지정하는 android.newDsl.optOut을 gradle.properties에 추가합니다.

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

참고: 하위 프로젝트 선택 해제 (android.newDsl.optOut)는 AGP 9.x의 임시 이전 지원이며 AGP 10.0에서 android.newDsl과 함께 삭제됩니다.

모듈별 선택적 기본 제공 Kotlin 사용 중지

프로젝트 전체에서 기본 제공 Kotlin을 전역적으로 사용 설정하되(android.builtInKotlin=true) 특정 하위 프로젝트를 kotlin-android에서 이전하는 데 시간이 더 필요한 경우 (또는 Kotlin 코드가 없는 모듈의 경우) 프로젝트 수준이 아닌 DSL 수준에서 이러한 모듈을 구성합니다. 모듈의 빌드 파일 내에서 enableKotlin = false를 설정합니다.

android {
    enableKotlin = false
}

참고: Kotlin이 아닌 하위 프로젝트에서 모듈 수준(enableKotlin = false) 에서 기본 제공 Kotlin을 사용 중지하면 Kotlin 컴파일러 태스크가 삭제되어 빌드 성능이 개선되고 Kotlin 표준 라이브러리에 종속 항목이 추가되지 않습니다.

의견 및 버그 신고 워크플로

새 변형 API가 필요한 사용 사례를 지원하도록 하고자 합니다. 새 변형 API가 사용 사례를 수용할 수 없는 이전 API에서 이전하는 데 장애물이 발생하면 다음 단계에 따라 의견을 제공하세요.

1. 기존 항목 확인: 먼저 AGP 10.0 변형 API 전역 추적 버그를 확인하여 이전 차단기가 이미 알려져 있는지 확인하고 문제를 +1합니다.
2. 누락된 API 신고: 사용 사례가 고유한 경우 Google에서 조사하고 지원할 수 있도록 특정 변형 API 템플릿을 사용하여 새 기능 요청을 제출합니다.

(미정)비공개 내부 AGP 클래스에 대한 액세스 권한이 삭제됨

이제 gradle 아티팩트의 종속 항목이 모든 내부 클래스를 숨기고, 인터페이스와 클래스 에 대한 컴파일 권한만 부여합니다.gradle-api 이는 플러그인 컴파일에 영향을 미칩니다.

내부 클래스에 대한 액세스 권한을 얻기 위해 종속 항목을 수동으로 추가할 수 없습니다.

중요: 내부 AGP 클래스 삭제에 관한 의견을 기다리고 있습니다. 이 추적 문제에 관한 의견을 제출하여 액세스 권한이 필요한 구체적인 예 등 사용 사례에 관한 의견을 보내주세요.

AGP 9.0 (2026년 1월)

새 변형 API가 공개되고 이전 API는 지원 중단됨

4.1 및 4.2에서 인큐베이션된 변형 API가 공개되고 gradle-api 아티팩트에 있습니다. 이전 변형 API에 사용된 이전 인터페이스와 클래스는 이제 지원 중단되며 사용하려면 명시적으로 선택해야 합니다.

새 DSL 인터페이스가 공개되고 이전 API는 지원 중단됨

4.1, 4.2 및 7.0에서 인큐베이션된 DSL 인터페이스가 공개되고 gradle-api 아티팩트에 있습니다. DSL에 사용된 이전 인터페이스와 클래스는 이제 지원 중단되며 사용하려면 명시적으로 선택해야 합니다.

비공개 내부 AGP 클래스에 계속 액세스할 수 있음

빌드 파일 및 플러그인을 컴파일하는 중에도 다른 아티팩트에 있는 AGP의 비공개 내부 클래스에 액세스할 수는 있지만, 이러한 클래스는 언제든지 변경되어 사용 불가할 수 있기 때문에 사용하지 않는 것이 좋습니다.