Android Gradle 플러그인 8.9 출시 노트

JCenter 저장소는 2021년 3월 31일 읽기 전용으로 변경되었습니다. 자세한 내용은 JCenter 서비스 업데이트를 참고하세요.

Android 스튜디오 빌드 시스템은 Gradle을 기반으로 하며 Android Gradle 플러그인에는 Android 앱을 빌드하는 데 사용하는 몇 가지 추가 기능이 있습니다. Android Gradle 플러그인(AGP)은 일반적으로 Android 스튜디오와 완전히 동기화되어 업데이트되지만, 나머지 Gradle 시스템과 함께 Android 스튜디오로부터 독립적으로 실행되고 별도로 업데이트될 수도 있습니다.

이 페이지에서는 Gradle 도구를 업데이트하는 방법과 최근 업데이트 내용을 설명합니다. 이전 Android Gradle 플러그인 버전의 출시 노트는 이전 출시 노트를 참고하세요.

이 버전의 Android Gradle 플러그인에서 수정된 사항을 확인하려면 해결된 문제를 참고하세요.

Android Gradle 플러그인의 예정된 브레이킹 체인지를 개략적으로 알아보려면 Android Gradle 플러그인 로드맵을 참고하세요.

Gradle을 사용하여 Android 빌드를 구성하는 방법에 관한 자세한 내용은 다음 페이지를 참고하세요.

Gradle 빌드 시스템에 관한 자세한 내용은 Gradle 사용자 가이드를 참고하세요.

Android Gradle 플러그인 업데이트

Android 스튜디오를 업데이트하면 Android Gradle 플러그인을 사용 가능한 최신 버전으로 자동 업데이트하라는 메시지가 표시될 수 있습니다. 업데이트를 수락하거나 프로젝트의 빌드 요구사항에 따라 버전을 수동으로 지정할 수 있습니다.

Android 스튜디오의 File > Project Structure > Project 메뉴 또는 최상위 build.gradle.kts 파일에서 플러그인 버전을 지정할 수 있습니다. 플러그인 버전은 Android 스튜디오 프로젝트에 빌드된 모든 모듈에 적용됩니다. 다음 예는 build.gradle.kts 파일에서 플러그인을 버전 8.9.0으로 설정합니다.

KotlinGroovy
plugins {
    id("com.android.application") version "8.9.0" apply false
    id("com.android.library") version "8.9.0" apply false
    id("org.jetbrains.kotlin.android") version "2.1.10" apply false
}
plugins {
    id 'com.android.application' version '8.9.0' apply false
    id 'com.android.library' version '8.9.0' apply false
    id 'org.jetbrains.kotlin.android' version '2.1.10' apply false
}

주의: 버전 번호에 동적 종속 항목을 사용해서는 안 됩니다(예: 'com.android.tools.build:gradle:8.9.+'). 이 기능을 사용하면 예상치 못한 버전 업데이트가 발생할 수 있고 버전 차이를 해결하기 어려울 수 있습니다.

지정된 플러그인 버전을 다운로드하지 않은 경우, 다음에 프로젝트를 빌드할 때 또는 Android 스튜디오 메뉴 바에서 File > Sync Project with Gradle Files를 클릭하면 Gradle에서 지정된 버전의 플러그인을 다운로드합니다.

Gradle 업데이트

Android 스튜디오를 업데이트하면 Gradle 또한 사용 가능한 최신 버전으로 업데이트하라는 메시지가 표시될 수 있습니다. 업데이트를 수락하거나 프로젝트의 빌드 요구사항에 따라 버전을 수동으로 지정할 수 있습니다.

다음 표는 각 버전의 Android Gradle 플러그인에 필요한 Gradle 버전을 보여줍니다. 최상의 성능을 위해서는 Gradle과 플러그인을 가능한 최신 버전으로 사용해야 합니다.

플러그인 버전필요한 최소 Gradle 버전
8.98.11.1
8.88.10.2
8.78.9
8.68.7
8.58.7
8.48.6
8.38.4
8.28.2
8.18.0
8.08.0
7.47.5
플러그인 버전필요한 Gradle 버전
7.37.4
7.27.3.3
7.17.2
7.07.0
4.2.0+6.7.1
4.1.0+6.5+
4.0.0+6.1.1+
3.6.0~3.6.45.6.4+
3.5.0~3.5.45.4.1+
3.4.0~3.4.35.1.1+
3.3.0~3.3.34.10.1+
3.2.0~3.2.14.6+
3.1.0+4.4+
3.0.0+4.1+
2.3.0+3.3+
2.1.3~2.2.32.14.1~3.5
2.0.0~2.1.22.10~2.13
1.5.02.2.1~2.13
1.2.0~1.3.12.2.1~2.9
1.0.0~1.1.32.2.1~2.3

Android 스튜디오의 File > Project Structure > Project 메뉴에서 Gradle 버전을 지정하거나 명령줄을 사용하여 Gradle 버전을 업데이트할 수 있습니다. 선호되는 방법은 Gradle Wrapper 명령줄 도구를 사용하여 gradlew 스크립트를 업데이트하는 것입니다. 다음 예는 Gradle 래퍼를 사용하여 Gradle 버전을 8.9로 설정합니다. Gradle과 Gradle Wrapper 자체를 모두 업그레이드하려면 이 명령어를 두 번 실행해야 합니다(자세한 내용은 Gradle Wrapper 업그레이드 참고).

gradle wrapper --gradle-version 8.9

그러나 AGP를 업데이트했는데 더 이상 현재 Gradle 버전과 호환되지 않는 등의 일부 경우에는 실패할 수 있습니다. 이 경우 gradle/wrapper/gradle-wrapper.properties 파일에서 Gradle 배포 참조를 수정해야 합니다. 다음 예는 gradle-wrapper.properties 파일에서 Gradle 버전을 8.9로 설정합니다.

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.9-bin.zip
...

Android Gradle 플러그인과 Android 스튜디오 호환성

Android 스튜디오 빌드 시스템은 Gradle을 기반으로 하며 Android Gradle 플러그인(AGP)에는 Android 앱을 빌드하는 데 사용하는 몇 가지 추가 기능이 있습니다. 다음 표에는 각 버전의 Android 스튜디오에 필요한 AGP 버전이 나열되어 있습니다.

Android 스튜디오 버전 필요한 AGP 버전
Meerkat | 2024.3.1 3.2~8.9
Ladybug 기능 출시 | 2024.2.2 3.2~8.8
Ladybug | 2024.2.1 3.2~8.7
Koala 기능 출시 | 2024.1.2 3.2~8.6
Koala | 2024.1.1 3.2~8.5
Jellyfish | 2023.3.1 3.2~8.4
Iguana | 2023.2.1 3.2~8.3
Hedgehog | 2023.1.1 3.2-8.2
Giraffe | 2022.3.1 3.2~8.1
Flamingo | 2022.2.1 3.2~8.0
Android 스튜디오 버전 필요한 AGP 버전
Electric Eel | 2022.1.1 3.2~7.4
Dolphin | 2021.3.1 3.2~7.3
Chipmunk | 2021.2.1 3.2~7.2
Bumblebee | 2021.1.1 3.2~7.1
Arctic Fox | 2020.3.1 3.1~7.0

Android Gradle 플러그인의 새로운 기능에 관한 정보는 Android Gradle 플러그인 출시 노트를 참고하세요.

Android API 수준 도구 최소 버전

특정 API 수준을 지원하는 최소 버전의 Android 스튜디오와 AGP가 있습니다. 프로젝트의 targetSdk 또는 compileSdk에 필요한 버전보다 낮은 버전의 Android 스튜디오 또는 AGP를 사용하면 예기치 않은 문제가 발생할 수 있습니다. Android OS의 미리보기 버전을 타겟팅하는 프로젝트에서 작업하려면 Android 스튜디오와 AGP의 최신 미리보기 버전을 사용하는 것이 좋습니다. 안정화 버전과 함께 Android 스튜디오의 미리보기 버전을 설치할 수 있습니다.

Android 스튜디오 및 AGP의 최소 버전은 다음과 같습니다.

API 수준 Android 스튜디오 최소 버전 AGP 최소 버전
바클라바 미리보기 Meerkat | 2024.3.1 8.9.0
35 Koala 기능 출시 | 2024.2.1 8.6.0
34 Hedgehog | 2023.1.1 8.1.1
33 Flamingo | 2022.2.1 7.2

버전 관리 변경사항(2020년 11월)

기본 Gradle 빌드 도구와 더 일치하도록 Android Gradle 플러그인(AGP)의 버전 번호 체계가 업데이트되었습니다.

주요 변경사항은 다음과 같습니다.

  • 이제 AGP는 시맨틱 버전 관리를 사용하고, 메이저 버전에는 브레이킹 체인지가 타겟팅됩니다.

  • Gradle 메이저 버전에 맞춘 AGP 메이저 버전이 매년 1회 출시될 예정입니다.

  • AGP 4.2 이후 출시되는 버전은 7.0이며 Gradle 버전 7.x로 업그레이드해야 합니다. AGP의 모든 메이저 버전에는 기본 Gradle 도구의 메이저 버전 업그레이드가 필요합니다.

  • API는 1년 정도 미리 지원 중단될 예정이며 이를 대체하는 기능이 곧바로 제공됩니다. 지원 중단된 API는 약 1년 후, 다음 주요 업데이트 동안 삭제됩니다.

호환성

Android Gradle 플러그인 8.9에서 지원하는 최대 API 수준은 API 수준 35입니다. 다음은 기타 호환성 정보입니다.

최소 버전 기본 버전 참고
Gradle 8.11.1 8.11.1 자세한 내용은 Gradle 업데이트하기를 참고하세요.
SDK 빌드 도구 35.0.0 35.0.0 SDK 빌드 도구를 설치 또는 구성합니다.
NDK 해당 사항 없음 27.0.12077973 다른 버전의 NDK를 설치 또는 구성합니다.
JDK 17 17 자세한 내용은 JDK 버전 설정을 참고하세요.

해결된 문제

Android Gradle 플러그인 8.9.0

해결된 문제
Android Gradle 플러그인
디스크 공간이 부족하여 GMD 설정 작업이 실패할 때 조치 가능한 오류 메시지 제공
com.android.settings 플러그인이 targetSdk를 인식하지 않음
유용하지 않은 오류 'compileSdkVersion이 지정되지 않았습니다. build.gradle에 추가하세요.'
빌드 메뉴에 '빌드 정리'가 없음
AGP의 내장 Kotlin 지원이 Kotlin stdlib 종속 항목을 자동으로 추가하도록 허용할 수 있습니다.
기본 제공 Kotlin 지원을 처리하도록 shouldConfigureKotlinPlatformAttribute 업데이트
`checkTestedAppObfuscationRelease`의 오류 메시지에 Kotlin Gradle 문법을 제공합니다.
해결되지 않은 종속 항목을 개선할 수 있는 경우 융합 라이브러리 오류
gradle.properties의 시스템 속성이 별도의 프로세스에서 R8 Gradle 작업자에게 전달되지 않음
BuiltArtifact.outputFile을 파일 유형으로 만들기
융합 라이브러리에 네임스페이스를 제공하지 않으면 올바른 오류 메시지가 표시되지 않음
AGP 7.1.0-alpha08의 린트 옵션이 stdout을 허용하지 않음
Android Gradle 플러그인: 변형이 소스 세트 이름을 노출해야 함
구성 캐시가 TERM 환경 변수 설정에 취약함
통계가 사용 설정된 경우 AndroidComponentsExtension.addSourceSetConfigurations가 손상됨
초기화 스크립트 'C:\Users\mypc\AppData\Local\Temp\ijresolvers2.gradle'의 162번째 줄
통계가 사용 설정된 경우 AndroidComponentsExtension.addSourceSetConfigurations가 손상됨
Dexer(D8)
java.lang.VerifyError: 인증 도구에서 클래스를 거부함: [0x430] copy1 v2<-v264 type=Undefined cat=3
린트
린트 Gradle 검사로 린트가 비정상 종료됨
린트 스택 트레이스에 예외 메시지 없이 InstantiationException으로 린트가 실패함
android.permission.SCHEDULE_EXACT_ALARM이 시스템 앱에만 부여된다는 거짓양성 린트 검사
StringFormatInvalid 검사를 Compose stringResource 메서드에 적용해야 함
RequiresFeature 주석이 Kotlin 파일에 작동하지 않음
kotlin android.os.Handler removeCallbacks Runnable
shift를 사용하여 상수를 사용하는 대신 정의에 WrongConstant 린트가 표시됨
WrongConstant 린트가 두 번 표시됨
지원되지 않는 Java nio API가 포함된 API 26 미만의 런타임 예외 (린트 오류 없음)
린트가 테스트의 비공개 도우미 메서드에서도 RequiresApi 사용을 방지함
Android 스튜디오에서 .hasRoute(Route::class)를 사용할 때 K2 모드에서 RestrictedApi 경고가 발생함
린트가 테스트의 @RequiresExtension을 SDK 확장 프로그램을 지원하지 않는 @SdkSuppress로 대체하도록 제안함
맞춤 패딩이 필요한 하위 RelativeLayout을 래핑하기 위해 fitSystemWindows와 함께 사용된 FrameLayout이 있으면 린트에서 불필요한 중첩 레이아웃을 잘못 보고합니다.
CoarseFineLocation 린트 규칙이 maxSdkVersion 속성을 고려하지 않음
린트 8.7.3에서 AppLinkSplitToWebAndCustom이 UnknownIssue임
'\\'에서 린트 검사 StringEscapeDetector 비정상 종료
봉인된 인터페이스의 `@Parcelize` 주석에 관한 잘못된 린트 경고
AS 2024.3.1.4가 Kotlin 텍스트를 수정할 때 간헐적으로 중단됩니다.
린트 통합
앱 번들을 빌드할 때 lintVitalRelease가 자동으로 실행되지 않음
축소기(R8)
AGP 8.8로 업그레이드한 후 Gson proguard가 제대로 작동하지 않음
java.lang.VerifyError: 인증 도구에서 클래스를 거부함
AGP 8.10.0-alpha04에 포함된 R8으로 축소하면 Leanback이 비정상 종료됨