내장 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을 사용 설정하므로 사용 설정하기 위해 아무것도 할 필요가 없습니다. 그러나 이전에 기본 Kotlin을 선택 해제한 경우 android.builtInKotlin=false 파일에서 gradle.properties를 설정하여 해당 설정을 삭제하거나 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. 필요한 경우 android.kotlinOptions{} DSL 이전
  4. 필요한 경우 kotlin.sourceSets{} DSL 이전

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과 호환되지 않습니다. kapt를 사용하는 경우 프로젝트를 KSP로 이전하는 것이 좋습니다.

아직 KSP로 이전할 수 없는 경우 kotlin-kapt 플러그인을 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. 필요한 경우 android.kotlinOptions{} DSL 이전

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
    }
}

4. 필요한 경우 kotlin.sourceSets{} DSL 이전

kotlin-android 플러그인을 사용하면 AGP를 통해 추가 Kotlin 소스 디렉터리를 android.sourceSets{} DSL 또는 kotlin.sourceSets{} DSL을 사용하여 추가할 수 있습니다. android.sourceSets{} DSL을 사용하면 디렉터리를 AndroidSourceSet.kotlin 집합 또는 AndroidSourceSet.java 집합에 추가할 수 있습니다.

기본 Kotlin을 사용하면 지원되는 유일한 옵션은 android.sourceSets{} DSL을 사용하여 디렉터리를 AndroidSourceSet.kotlin 집합에 추가하는 것입니다. 지원되지 않는 옵션을 사용하는 경우 다음과 같이 이전합니다.

Kotlin

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories += "additionalSourceDirectory/kotlin"
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories += "additionalSourceDirectory/kotlin"
}

Groovy

# Adding Kotlin source directories to kotlin.sourceSets is not supported
kotlin.sourceSets.named("main") {
    kotlin.srcDir("additionalSourceDirectory/kotlin")
}

# Adding Kotlin source directories to AndroidSourceSet.java is also not supported
android.sourceSets.named("main") {
    java.directories.add("additionalSourceDirectory/kotlin")
}

# Add Kotlin source directories to AndroidSourceSet.kotlin
android.sourceSets.named("main") {
    kotlin.directories.add("additionalSourceDirectory/kotlin")
}

Kotlin 소스 디렉터리를 특정 변형에 추가하거나 디렉터리가 작업에 의해 생성되는 경우 변형 API에서 addStaticSourceDirectory 또는 addGeneratedSourceDirectory 메서드를 사용할 수 있습니다.

Kotlin

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

Groovy

androidComponents.onVariants { variant ->
    variant.sources.kotlin!!.addStaticSourceDirectory("additionalSourceDirectory/kotlin")
    variant.sources.kotlin!!.addGeneratedSourceDirectory(TASK_PROVIDER, TASK_OUTPUT)
}

문제 신고

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

기본 Kotlin 선택 해제

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

프로젝트를 이전할 준비가 되면 기본 Kotlin을 사용 설정하고 이전 단계를 따르세요.

모듈별 이전

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

모든 모듈을 한 번에 이전하는 것이 어려운 경우 한 번에 하나의 모듈을 이전할 수 있습니다.

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

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

  3. 이전 이전 단계에 따라 이 모듈을 기본 Kotlin으로 이전합니다.

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

기본 Kotlin을 선택적으로 사용 중지하는 옵션

Android Gradle 플러그인 9.0은 적용되는 모든 모듈에 기본 Kotlin을 사용 설정합니다. 대규모 프로젝트에서 Kotlin 소스가 없는 모듈에 기본 Kotlin을 선택적으로 사용 중지하는 것이 좋습니다. 이렇게 하면 빌드 성능 비용이 약간 드는 Kotlin 컴파일 작업과 Kotlin 표준 라이브러리에 대한 자동 종속 항목이 모두 삭제됩니다.

모듈에 기본 Kotlin을 사용 중지하려면 해당 모듈의 빌드 파일에서 enableKotlin = false를 설정합니다.

Kotlin

android {
    enableKotlin = false
}

Groovy

android {
    enableKotlin = false
}