Android Gradle 플러그인 출시 노트

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

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

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

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

• 빌드 구성
• Android Gradle 플러그인 DSL 참조
• Gradle DSL 참조
• Gradle 성능 사용자 가이드

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

Android Gradle 플러그인 업데이트

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

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

plugins {
    id("com.android.application") version "8.1.0" apply false
    id("com.android.library") version "8.1.0" apply false
    id("org.jetbrains.kotlin.android") version "1.5.31" apply false
}

plugins {
    id 'com.android.application' version '8.1.0' apply false
    id 'com.android.library' version '8.1.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.5.31' apply false
}

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

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

Gradle 업데이트

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

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

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

gradle wrapper --gradle-version 8.1

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

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

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

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

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

Android API 수준 도구 최소 버전

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

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

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

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

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

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

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

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

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

8.1.0 (2023년 7월)

Android Gradle 플러그인 8.1.0은 다양한 새 기능과 개선사항이 포함된 메이저 버전입니다.

호환성

빌드 구성의 기본값인 Kotlin DSL

새 프로젝트는 이제 빌드 구성에 Kotlin DSL (build.gradle.kts)을 기본적으로 사용합니다. 이는 문법 강조표시, 코드 완성, 선언 탐색 기능을 갖춘 Groovy DSL(build.gradle)보다 더 나은 편집 환경을 제공합니다. 빌드 구성에 AGP 8.1과 Kotlin DSL을 사용하는 경우 최상의 환경을 위해 Gradle 8.1을 사용해야 합니다. 자세한 내용은 Kotlin DSL 이전 가이드를 참고하세요.

앱별 언어 자동 지원

Android 스튜디오 Giraffe Canary 7 및 AGP 8.1.0-alpha07부터 앱이 앱별 언어 설정을 자동으로 지원하도록 구성할 수 있습니다. Android Gradle 플러그인은 프로젝트 리소스를 기반으로 LocaleConfig 파일을 생성하고 최종 매니페스트 파일에 그 참조를 추가하므로 더 이상 수동으로 이 작업을 할 필요가 없습니다. AGP는 앱 모듈의 res 폴더에 있는 리소스와 모든 라이브러리 모듈 종속 항목을 사용하여 LocaleConfig 파일에 포함할 언어를 결정합니다.

자동 앱별 언어 기능은 Android 13(API 수준 33) 및 이후 버전을 실행하는 앱을 지원합니다. 이 기능을 사용하려면 compileSdkVersion을 33 이상으로 설정해야 합니다. 이전 버전의 Android에서 앱별 언어 설정을 구성하려면 API와 인앱 언어 선택 도구를 사용해야 합니다.

앱별 자동 언어 지원을 사용 설정하려면 기본 언어를 지정합니다.

1. 앱 모듈의 res 폴더에서 resources.properties라는 새 파일을 만듭니다.

2. resources.properties 파일에서 unqualifiedResLocale 라벨로 기본 언어를 설정합니다. 언어 이름을 만들려면 언어 코드를 스크립트(선택사항)와 지역 코드(선택사항)와 결합하고 각각 대시로 구분합니다.

   • 언어: 두 글자 또는 세 글자로 된 ISO 639-1 코드를 사용합니다.
   • 스크립트 (선택사항): ISO 15924 코드를 사용합니다.
   • 지역 (선택사항): 두 글자로 된 ISO 3166-1-alpha-2 코드나 3자리의 UN_M.49 코드를 사용합니다.

   예를 들어 기본 언어가 미국 영어인 경우:

       unqualifiedResLocale=en-US
       

AGP는 res 폴더의 values-* 디렉터리를 사용하여 이 기본 언어와 개발자가 지정한 모든 대체 언어를 자동 생성된 LocaleConfig 파일에 추가합니다.

앱별 언어 자동 지원은 기본적으로 사용 중지되어 있습니다. 이 기능을 사용 설정하려면 모듈 수준 build.gradle.kts 파일 (Groovy를 사용하는 경우 build.gradle 파일)의 androidResources {} 블록에서 generateLocaleConfig 설정을 사용합니다.

android {
  androidResources {
    generateLocaleConfig = true
  }
}

android {
  androidResources {
    generateLocaleConfig true
  }
}

Android 린트에 JVM 17을 타겟팅하는 바이트 코드가 포함됨

AGP 8.1.0-alpha04부터 Android 린트에 JVM 17을 타겟팅하는 바이트 코드가 포함됩니다. 맞춤 린트 검사를 작성하는 경우 JDK 17 이상으로 컴파일하고 Kotlin 컴파일러 옵션에서 jvmTarget = '17'을 지정해야 합니다.

린트 도구에 관한 자세한 내용은 린트 검사로 코드 개선을 참고하세요.

네이티브 라이브러리 압축 설정이 DSL로 이동됨

AGP 8.1.0-alpha10부터 매니페스트 대신 DSL을 사용하여 네이티브 라이브러리 압축을 구성하지 않으면 경고가 표시됩니다. 다음 가이드에서는 DSL을 사용하도록 구성을 업데이트하는 방법을 설명합니다. 업데이트하는 데 도움이 필요하면 AGP 업그레이드 어시스턴트(도구 > AGP 업그레이드 어시스턴트)를 사용하세요.

압축되지 않은 네이티브 라이브러리를 사용하려면 매니페스트에서 android::extractNativeLibs 속성을 삭제하고 다음 코드를 모듈 수준 build.gradle.kts 파일 (Groovy를 사용하는 경우 build.gradle 파일)에 추가합니다.

android {
  packagingOptions {
    jniLibs {
      useLegacyPackaging = false
    }
  }
}

android {
  packagingOptions {
    jniLibs {
      useLegacyPackaging false
    }
  }
}

실험용 빌드 플래그

이는 AGP 8.1에서 사용할 수 있는 빌드를 구성하기 위한 실험용 플래그입니다.