Android Gradle 플러그인 미리보기 출시 노트

이 페이지에는 Android Gradle 플러그인 (AGP)의 미리보기 버전 출시 노트가 포함되어 있습니다.

Android Gradle 플러그인 9.0

Android Gradle 플러그인 9.0은 AGP의 새로운 주요 버전으로, API 및 동작 변경사항이 적용됩니다.

Android Gradle 플러그인 9.0.0-beta04로 업데이트하려면 Android 스튜디오 Otter 3 Feature Drop | 2025.2.3에서 Android Gradle 플러그인 업그레이드 어시스턴트를 사용하세요.

AGP 업그레이드 어시스턴트는 적절한 경우 프로젝트를 업그레이드할 때 기존 동작을 유지하여 AGP 9.0의 새로운 기본값을 모두 채택할 준비가 되지 않았더라도 AGP 9.0을 사용하도록 프로젝트를 업그레이드할 수 있습니다.

호환성

Android Gradle 플러그인 9.0.0-beta04에서 지원하는 최대 Android API 수준은 API 수준 36입니다.

Android Gradle 플러그인 9.0.0-beta04에는 Gradle 9.0.0이 필요합니다.

이제 android DSL 클래스는 새로운 공개 인터페이스만 구현합니다.

지난 몇 년 동안 Google은 공개 API를 더 잘 제어하기 위해 DSL 및 API용 새 인터페이스를 도입했습니다. AGP 버전 7.x 및 8.x에서는 인터페이스 작업이 진행됨에 따라 호환성을 유지하기 위해 새로운 공개 인터페이스도 구현하는 이전 DSL 유형 (예: BaseExtension)을 계속 사용했습니다.

AGP 9.0은 새로운 DSL 인터페이스만 사용하며 구현이 완전히 숨겨진 새로운 유형으로 변경되었습니다. 또한 지원 중단된 이전 변형 API에 대한 액세스도 삭제됩니다.

AGP 9.0으로 업데이트하려면 다음을 수행해야 할 수 있습니다.

• 프로젝트가 내장 Kotlin과 호환되는지 확인: org.jetbrains.kotlin.android 플러그인은 새 DSL과 호환되지 않습니다.

• KMP 프로젝트를 KMP용 Android Gradle 라이브러리 플러그인으로 전환: com.android.library 및 com.android.application 플러그인과 동일한 Gradle 하위 프로젝트에서 org.jetbrains.kotlin.multiplatform 플러그인을 사용하는 것은 새 DSL과 호환되지 않습니다.

• 빌드 파일 업데이트: 인터페이스 변경은 DSL을 최대한 유사하게 유지하기 위한 것이지만 약간의 변경사항이 있을 수 있습니다.

• 새 DSL 및 API를 참조하도록 맞춤 빌드 로직을 업데이트합니다. 내부 DSL에 대한 참조를 공개 DSL 인터페이스로 바꿉니다. 대부분의 경우 일대일 대체가 됩니다. applicationVariants 및 유사한 API의 사용을 새 androidComponents API로 대체합니다. androidComponents API는 플러그인이 더 오래 호환되도록 더 안정적으로 설계되어 있으므로 이 방법이 더 복잡할 수 있습니다. 예는 Gradle 레시피를 참고하세요.

• 서드 파티 플러그인 업데이트: 일부 서드 파티 플러그인은 더 이상 노출되지 않는 인터페이스나 API를 계속 사용할 수 있습니다. AGP 9.0과 호환되는 플러그인 버전으로 이전하세요.

새 DSL 인터페이스로 전환하면 다음과 같은 다양한 지원 중단된 API를 사용하는 플러그인과 Gradle 빌드 스크립트가 방지됩니다.

androidComponents {
    onVariants() { variant ->
        variant.signingConfig
            .enableV1Signing.set(false)
    }
}

androidComponents {
    beforeVariants(
        selector()
            .withBuildType("debug")
            .withFlavor("color", "blue")
    ) { variantBuilder ->
        variantBuilder.enable = false
    }
  }

AGP 9.0으로 업데이트한 후 다음 오류 메시지가 표시되면 프로젝트에서 여전히 일부 이전 유형을 참조하고 있는 것입니다.

java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated
cannot be cast to class com.android.build.gradle.BaseExtension

호환되지 않는 서드 파티 플러그인으로 인해 차단된 경우 선택 해제하고 DSL의 이전 구현과 이전 변형 API를 다시 가져올 수 있습니다. 이 작업을 하는 동안 새 인터페이스도 사용할 수 있으며 자체 빌드 로직을 새 API로 업데이트할 수도 있습니다. 선택 해제하려면 gradle.properties 파일에 다음 줄을 포함하세요.

android.newDsl=false

AGP 9.0으로 업그레이드하기 전에 새 API로 업그레이드할 수도 있습니다. 새 인터페이스는 여러 AGP 버전에 존재해 왔으므로 새 인터페이스와 이전 인터페이스를 혼합할 수 있습니다. AGP API 참조 문서에는 각 AGP 버전의 API 노출 영역과 각 클래스, 메서드, 필드가 추가된 시기가 표시됩니다.

9.0 알파 단계에서 Google은 플러그인 작성자에게 연락하여 새로운 모드와 완전히 호환되는 플러그인을 적용하고 출시하도록 지원하고, Android 스튜디오의 AGP 업그레이드 어시스턴트를 개선하여 이전 과정을 안내할 예정입니다.

새 DSL 또는 Variant API에 기능이 누락된 경우 최대한 빨리 문제를 신고하세요.

Kotlin 내장

Android Gradle 플러그인 9.0에서는 Kotlin 지원이 내장되어 있으며 기본적으로 사용 설정됩니다. 즉, Kotlin 소스 파일을 컴파일하기 위해 더 이상 빌드 파일에 org.jetbrains.kotlin.android (또는 kotlin-android) 플러그인을 적용하지 않아도 됩니다. 이렇게 하면 AGP와의 Kotlin 통합이 간소화되고, 지원 중단된 API의 사용이 방지되며, 경우에 따라 성능이 개선됩니다.

따라서 프로젝트를 AGP 9.0으로 업그레이드할 때는 내장 Kotlin으로 이전하거나 선택 해제해야 합니다.

Kotlin 소스가 없는 Gradle 하위 프로젝트의 경우 기본 제공 Kotlin 지원을 선택적으로 사용 중지할 수도 있습니다.

Kotlin Gradle 플러그인에 대한 런타임 종속 항목

내장 Kotlin 지원을 제공하기 위해 Android Gradle 플러그인 9.0에는 이제 Kotlin Gradle 플러그인 (KGP) 2.2.10에 대한 런타임 종속성이 있습니다. 즉, 더 이상 KGP 버전을 선언할 필요가 없으며 2.2.10보다 낮은 KGP 버전을 사용하는 경우 Gradle이 KGP 버전을 2.2.10으로 자동 업그레이드합니다. 마찬가지로 KSP 버전이 2.2.10-2.0.2보다 낮은 경우 AGP는 KGP 버전에 맞게 2.2.10-2.0.2로 업그레이드합니다.

상위 KGP 버전으로 업그레이드

더 높은 버전의 KGP 또는 KSP를 사용하려면 최상위 수준 빌드 파일에 다음을 추가하세요.

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:KGP_VERSION")

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin:KSP_VERSION")
    }
}

하위 KGP 버전으로 다운그레이드

내장 Kotlin을 선택 해제한 경우에만 KGP 버전을 다운그레이드할 수 있습니다. AGP 9.0에서는 기본적으로 내장 Kotlin이 사용 설정되며 내장 Kotlin에는 KGP 2.2.10 이상이 필요하기 때문입니다.

더 낮은 버전의 KGP 또는 KSP를 사용하려면 엄격한 버전 선언을 사용하여 최상위 빌드 파일에서 해당 버전을 선언하세요.

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("KGP_VERSION") }
        }

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

다운그레이드할 수 있는 최소 KGP 버전은 2.0.0입니다.

테스트 픽스처를 위한 IDE 지원

AGP 9.0에서는 테스트 고정 장치에 대한 Android 스튜디오 IDE 지원이 완전히 제공됩니다.

융합 라이브러리 플러그인

융합 라이브러리 플러그인 (미리보기)을 사용하면 여러 라이브러리를 단일 Android 라이브러리 AAR로 게시할 수 있습니다. 이렇게 하면 사용자가 게시된 아티팩트를 더 쉽게 사용할 수 있습니다.

시작에 관한 자세한 내용은 융합 라이브러리로 여러 Android 라이브러리를 하나로 게시를 참고하세요.

동작 변경사항

Android Gradle 플러그인 9.0에는 다음과 같은 새로운 동작이 있습니다.

AGP 9.0에는 다음 Gradle 속성의 기본값에 대한 업데이트가 포함되어 있습니다. 이렇게 하면 업그레이드 시 AGP 8.13 동작을 유지할 수 있습니다.

android {
  defaultConfig {
    testInstrumentationRunner = "..."
  }
}

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

삭제된 기능

Android Gradle 플러그인 9.0에서는 다음 기능이 삭제됩니다.

• 삽입된 Wear OS 앱 지원
  AGP 9.0에서는 Wear OS 앱 삽입 지원이 삭제됩니다. 이는 더 이상 Play에서 지원되지 않습니다. 여기에는 wearApp 구성과 AndroidSourceSet.wearAppConfigurationName DSL이 삭제됩니다. Wear OS에 앱을 게시하는 방법은 Wear OS에 배포를 참고하세요.
• androidDependencies 및 sourceSets 보고 작업
• 밀도 분할 APK 지원
  AGP 9.0에서는 화면 밀도에 기반한 분할 APK 생성 지원이 삭제됩니다. 기능과 관련 API가 삭제되었습니다. AGP 9.0 이상을 사용하여 화면 밀도에 따라 APK를 분할하려면 App Bundle을 사용하세요.

DSL 변경

Android Gradle 플러그인 9.0에는 다음과 같은 주요 DSL 변경사항이 있습니다.

• CommonExtension의 매개변수화가 삭제되었습니다.

  이 변경사항은 향후 소스 수준의 호환성 중단을 방지하기 위한 소스 수준의 호환성 중단일 뿐이지만 블록 메서드를 CommonExtension에서 ApplicationExtension, LibraryExtension, DynamicFeatureExtension, TestExtension로 이동해야 한다는 의미도 있습니다.

  프로젝트를 AGP 9.0으로 업그레이드할 때 이러한 매개변수나 블록 메서드를 사용하는 Gradle 플러그인 코드를 리팩터링하세요. 예를 들어 다음 플러그인은 유형 매개변수를 삭제하고 삭제된 블록 메서드를 사용하지 않도록 업데이트됩니다.

  AGP 8.13

  val commonExtension: CommonExtension<*, *, *, *, *, *> =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig {
          minSdk {
              version = release(28)
          }
      }
  }
  

  AGP 9.0

  val commonExtension: CommonExtension =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig.apply {
          minSdk {
              version = release(28)
          }
      }
  }
  

  일정 범위의 AGP 버전을 타겟팅하는 플러그인의 경우 게터를 직접 사용하면 AGP 버전 9.0 미만과 바이너리 호환됩니다.

DSL 삭제됨

Android Gradle 플러그인 9.0에서 다음이 삭제됩니다.

• AndroidSourceSet.jni은 작동하지 않았기 때문입니다.

• AndroidSourceSet.wearAppConfigurationName은 삭제된 삽입된 Wear OS 앱 지원과 관련이 있습니다.

• BuildType.isRenderscriptDebuggable은 작동하지 않았기 때문입니다.

• DependencyVariantSelection. DependencySelection로 대체되며, kotlin.android.localDependencySelection로 노출됩니다.

• Installation.installOptions(String). Installation.installOptions의 변경 가능한 속성으로 대체됩니다.

• 실험적이지만 안정화되지 않은 PostProcessing 블록입니다.

• ProductFlavor.setDimension: dimension 속성으로 대체됨

• LanguageSplitOptions는 지원 중단된 Google Play 인스턴트에만 유용했습니다.

• DensitySplit: 이 기능은 더 이상 지원되지 않습니다. App Bundle을 사용해야 합니다.

삭제된 API

Android Gradle 플러그인 9.0에서 다음이 삭제됩니다.

• AndroidComponentsExtension.finalizeDSl. finalizeDsl로 대체되었습니다.

• Component.transformClassesWith. Instrumentation.transformClassesWith로 대체되었습니다.

• Component.setAsmFramesComputationMode. Instrumentation.setAsmFramesComputationMode로 대체되었습니다.

• ComponentBuilder.enabled. ComponentBuilder.enable로 대체되었습니다.

• DependenciesInfoBuilder.includedInApk. includeInApk로 대체됩니다.

• DependenciesInfoBuilder.includedInBundle. includeInBundle로 대체됩니다.

• GeneratesApk.targetSdkVersion. targetSdk으로 대체됩니다.

• Variant.minSdkVersion. minSdk으로 대체됩니다.

• Variant.maxSdkVersion. maxSdk으로 대체됩니다.

• Variant.targetSdkVersion. targetSdk으로 대체됩니다.

• com.android.test 플러그인에는 적용되지 않았기 때문입니다.Variant.unitTest unitTest은 HasUnitTest을 확장하는 VariantBuilder 하위 유형에서 사용할 수 있습니다.

• VariantBuilder.targetSdk 및 targetSdkPreview는 라이브러리에서 의미가 없으므로 삭제했습니다. 대신 GeneratesApkBuilder.targetSdk 또는 GeneratesApkBuilder.targetSdkPreview을 사용하세요.

• com.android.test 플러그인에는 적용되지 않았기 때문입니다.VariantBuilder.enableUnitTest enableUnitTest은 HasUnitTestBuilder을 확장하는 VariantBuilder 하위 유형에서 사용할 수 있습니다.

• HasUnitTestBuilder을 확장하는 VariantBuilder 하위 유형에서 더 일관된 이름의 enableUnitTest을 사용하는 대신 VariantBuilder.unitTestEnabled이 삭제됩니다.

• VariantOutput.enable. enabled으로 대체됩니다.

• 지원 중단되고 사용 중지된 FeaturePlugin 및 FeatureExtension

• 지원 중단되고 사용 중지된 BaseExtension.registerTransform API. AGP 4.2 이하에서 실행을 타겟팅하는 동안 최신 AGP 버전을 기준으로 컴파일할 수 있도록만 유지되었습니다.

삭제된 Gradle 속성

다음 Gradle 속성은 기본적으로 사용 설정된 기능을 전역적으로 사용 중지하는 방법으로 처음 추가되었습니다.

이러한 기능은 AGP 8.0 이하에서 기본적으로 사용 중지되었습니다. 더 효율적인 빌드를 위해 이러한 기능을 사용하는 하위 프로젝트에서만 사용 설정하세요.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

강제 적용된 Gradle 속성

다음 Gradle 속성을 설정하면 AGP 9.0에서 오류가 발생합니다.

Android Gradle 플러그인 업그레이드 어시스턴트는 이러한 속성을 사용하는 프로젝트를 AGP 9.0으로 업그레이드하지 않습니다.

해결된 문제

Android Gradle 플러그인 9.0.0-beta04

Android Gradle 플러그인 9.0.0-beta03

Android Gradle 플러그인 9.0.0-beta02

Android Gradle 플러그인 9.0.0-beta01

Android Gradle 플러그인 9.0.0-alpha14

Android Gradle 플러그인 9.0.0-alpha13

Android Gradle 플러그인 9.0.0-alpha12

Android Gradle 플러그인 9.0.0-alpha11

Android Gradle 플러그인 9.0.0-alpha10

Android Gradle 플러그인 9.0.0-alpha09

Android Gradle 플러그인 9.0.0-alpha08

Android Gradle 플러그인 9.0.0-alpha07

Android Gradle 플러그인 9.0.0-alpha06

Android Gradle 플러그인 9.0.0-alpha05

Android Gradle 플러그인 9.0.0-alpha04

Android Gradle 플러그인 9.0.0-alpha03

Android Gradle 플러그인 9.0.0-alpha02

Android Gradle 플러그인 9.0.0-alpha01