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>)와 최신 Variant API (androidComponents {})를 사용하여 완전히 지연된 빌드 모델로 전환하면 속성과 작업 연결이 활성 빌드 실행 그래프에 필요한 경우에만 주문형으로 지연 계산됩니다.

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

핵심 아키텍처 차이점

기존 BaseVariant API (applicationVariants.all {})는 적극적이고 작업 중심적이었습니다. 이를 통해 개발자는 구성 단계에서 Gradle 작업과 내부 구성에 직접 액세스할 수 있었으며, 이는 본질적으로 최신 Gradle 성능 기능을 중단합니다.

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

삭제 및 교체되는 항목

기존 DSL 및 이전 변형 API에 사용된 모든 이전 인터페이스와 클래스가 삭제됩니다. 빌드 스크립트와 맞춤 플러그인을 준비하려면 다음 지원 종료 API와 플래그에서 이전하세요.

삭제된 API 또는 기능 교체 또는 조치 필요
직접 작업 액세스:
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 아티팩트 API: 동작을 변경하기 위해 작업을 가져오는 대신 variant.artifacts를 사용하여 작업 간에 전달되는 실제 파일 (아티팩트)을 추가, 수정 또는 대체합니다.
적극적인 소스 등록:
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
 소스 API: variant.sources.java.addGeneratedSourceDirectory(...)를 사용하여 맞춤 작업의 출력 디렉터리를 연결합니다.
클래스 경로 / 구성 액세스:
  • getCompileConfiguration()
  • getCompileClasspath()
 Instrumentation API: 바이트 코드(클래스 경로 액세스의 가장 일반적인 사용 사례)를 수정하거나 검사하려면 AsmClassVisitorFactory를 사용하여 variant.instrumentation.transformClassesWith(...)를 사용합니다.
즉시 속성 변경:
  • 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
        }
    }
}

After: Modern Variant 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 출시에서 실행하는 동안 gradle.properties가 선택 해제를 사용 중지하고 다음 엄격한 동작 플래그를 설정하는지 확인하여 AGP 10.0 동작을 명시적으로 적용할 수 있습니다.

# 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부터 개별 모듈을 선택적으로 선택 해제할 수 있습니다. 프로젝트 경로를 지정하는 gradle.properties에 android.newDsl.optOut를 추가합니다.

# 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

모듈별 선택적 내장 Kotlin 사용 중지

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

android {
    enableKotlin = false
}

의견 및 버그 신고 워크플로

새 Variant API가 필요한 사용 사례를 지원하는지 확인하고자 합니다. 새 변형 API가 사용 사례를 수용할 수 없는 이전 API에서 마이그레이션하는 데 문제가 있는 경우 다음 단계에 따라 의견을 제공하세요.

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

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

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

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

AGP 9.0 (2026년 1월)

새 변형 API가 안정적으로 실행되고 이전 API는 지원 중단됨

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

새 DSL 인터페이스가 안정화되고 이전 인터페이스는 지원 중단됨

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

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

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