내장 Kotlin으로 이전

Android Gradle 플러그인 9.0에서는 내장 Kotlin 지원이 도입되고 기본적으로 사용 설정됩니다. 즉, Kotlin 소스 파일을 컴파일하기 위해 빌드 파일에 org.jetbrains.kotlin.android (또는 kotlin-android) 플러그인을 더 이상 적용하지 않아도 됩니다. Kotlin이 내장되어 있어 빌드 파일이 더 간단해지고 AGP와 kotlin-android 플러그인 간의 호환성 문제를 방지할 수 있습니다.

기본 제공 Kotlin 사용 설정

Kotlin 지원이 내장되려면 AGP 9.0 이상이 필요합니다. AGP 9.0에서는 AGP를 적용하는 모든 모듈에 내장 Kotlin이 이미 사용 설정되어 있으므로 사용 설정하기 위해 별도로 조치를 취할 필요가 없습니다. 하지만 이전에 gradle.properties 파일에서 android.builtInKotlin=false를 설정하여 내장 Kotlin을 선택 해제한 경우 해당 설정을 삭제하거나 android.builtInKotlin=true를 설정하여 사용 설정해야 합니다.

내장 Kotlin을 사용하려면 프로젝트를 일부 변경해야 하므로 내장 Kotlin을 사용 설정한 후 다음 단계에 따라 프로젝트를 이전하세요.

이전 단계

이전 AGP 버전에서 AGP 9.0으로 프로젝트를 업그레이드하거나 내장 Kotlin을 수동으로 사용 설정한 후 다음과 같은 오류 메시지가 표시될 수 있습니다.

Failed to apply plugin 'org.jetbrains.kotlin.android'.
> Cannot add extension with name 'kotlin', as there is an extension already registered with that name.

...또는

Failed to apply plugin 'com.jetbrains.kotlin.android'
> The 'org.jetbrains.kotlin.android' plugin is no longer required for Kotlin support since AGP 9.0.

기본 제공 Kotlin을 사용하려면 프로젝트를 일부 변경해야 하기 때문입니다. 이 오류를 해결하려면 다음 단계를 수행하세요.

  1. kotlin-android 플러그인 삭제
  2. 필요한 경우 kotlin-kapt 플러그인 마이그레이션
  3. 필요한 경우 kotlinOptions{} 블록 마이그레이션

1. kotlin-android 플러그인 삭제

org.jetbrains.kotlin.android (또는 kotlin-android) 플러그인을 적용하는 모듈 수준 빌드 파일에서 플러그인을 삭제합니다. 삭제할 정확한 코드는 버전 카탈로그를 사용하여 플러그인을 선언하는지 여부에 따라 다릅니다.

버전 카탈로그 사용

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.kotlin.android)
}

버전 카탈로그 없음

Kotlin

// Module-level build file
plugins {
    id("org.jetbrains.kotlin.android")
}

Groovy

// Module-level build file
plugins {
    id 'org.jetbrains.kotlin.android'
}

그런 다음 최상위 빌드 파일에서 플러그인을 삭제합니다.

버전 카탈로그 사용

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.kotlin.android) apply false
}

버전 카탈로그 없음

Kotlin

// Top-level build file
plugins {
    id("org.jetbrains.kotlin.android") version "KOTLIN_VERSION" apply false
}

Groovy

// Top-level build file
plugins {
    id 'org.jetbrains.kotlin.android' version 'KOTLIN_VERSION' apply false
}

버전 카탈로그를 사용하는 경우 버전 카탈로그 TOML 파일 (일반적으로 gradle/libs.versions.toml)에서도 플러그인 정의를 삭제합니다.

[plugins]
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "KOTLIN_VERSION" }

2. 필요한 경우 kotlin-kapt 플러그인 이전

빌드 파일에서 org.jetbrains.kotlin.kapt (또는 kotlin-kapt)를 사용하는 경우 이 플러그인은 내장 Kotlin과 호환되지 않습니다. 이 플러그인을 현재 Android Gradle 플러그인과 동일한 버전을 사용하는 com.android.legacy-kapt 플러그인으로 바꿔야 합니다.

예를 들어 버전 카탈로그를 사용하는 경우 다음과 같이 버전 카탈로그 TOML 파일을 업데이트합니다.

[plugins]
android-application = { id = "com.android.application", version.ref = "AGP_VERSION" }

# Add the following plugin definition
legacy-kapt = { id = "com.android.legacy-kapt", version.ref = "AGP_VERSION" }

# Remove the following plugin definition
kotlin-kapt = { id = "org.jetbrains.kotlin.kapt", version.ref = "KOTLIN_VERSION" }

그런 다음 빌드 파일을 업데이트합니다.

Kotlin

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Groovy

// Top-level build file
plugins {
    alias(libs.plugins.legacy.kapt) apply false
    alias(libs.plugins.kotlin.kapt) apply false
}

Kotlin

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

Groovy

// Module-level build file
plugins {
    alias(libs.plugins.legacy.kapt)
    alias(libs.plugins.kotlin.kapt)
}

3. 필요한 경우 kotlinOptions{} 블록 마이그레이션

android.kotlinOptions{} DSL을 사용하는 경우 kotlin.compilerOptions{} DSL로 마이그레이션해야 합니다.

예를 들어 다음 코드를 업데이트합니다.

Kotlin

android {
    kotlinOptions {
        languageVersion = "2.0"
        jvmTarget = "11"
    }
}

Groovy

android {
    kotlinOptions {
        languageVersion = "2.0"
        jvmTarget = "11"
    }
}

...새 DSL로 이전합니다.

Kotlin

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

Groovy

kotlin {
    compilerOptions {
        languageVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0
        // Optional: Set jvmTarget
        // jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11
    }
}

문제 신고

이전 단계를 완료한 후 문제가 발생하면 문제 #438678642 설명의 알려진 문제를 확인하고 필요한 경우 의견을 보내 주세요.

기본 제공 Kotlin 선택 해제

기본 제공 Kotlin을 사용하도록 프로젝트를 이전할 수 없는 경우 gradle.properties 파일에서 android.builtInKotlin = false를 설정하여 기본 제공 Kotlin을 일시적으로 사용 중지하세요. 이렇게 하면 AGP 10.0 이전의 향후 AGP 9.x 버전에서 내장 Kotlin을 사용 중지할 수 없으므로 내장 Kotlin으로 이전하라는 경고가 빌드에 표시됩니다.

모듈별 이전

android.builtInKotlin Gradle 속성을 사용하면 AGP를 적용하는 모든 모듈에 내장 Kotlin을 사용 설정하거나 사용 중지할 수 있습니다.

모든 모듈을 한 번에 이전하기가 어렵다면 모듈을 하나씩 이전하면 됩니다.

  1. gradle.properties 파일에서 android.builtInKotlin = false를 설정하여 모든 모듈의 내장 Kotlin을 사용 중지합니다.

  2. 현재 Android Gradle 플러그인과 동일한 버전을 사용하여 내장 Kotlin을 사용 설정하려는 모듈에 com.android.experimental.built-in-kotlin 플러그인을 적용합니다.

  3. 이전 이전 단계를 실행하여 이 모듈을 내장 Kotlin으로 이전합니다.

  4. 모든 모듈을 이전한 후 gradle.properties에서 android.builtInKotlin = false 설정을 삭제하고 빌드 파일에서 com.android.experimental.built-in-kotlin 플러그인을 삭제합니다.