Gradle 프로젝트 구성

Kotlin 프로젝트를 Gradle로 빌드하려면, 빌드 스크립트 파일 build.gradle(.kts)에 Kotlin Gradle 플러그인을 추가하고 프로젝트의 의존성을 구성해야 합니다.

NOTE

빌드 스크립트 내용에 대해 더 알아보려면,

빌드 스크립트 탐색 섹션을 방문하세요.

플러그인 적용

Kotlin Gradle 플러그인을 적용하려면, Gradle 플러그인 DSL의 plugins{} 블록을 사용하세요.

Kotlin

plugins {
    // `<...>`를 대상 환경에 적합한 플러그인 이름으로 바꾸세요.
    kotlin("<...>") version "2.1.21"
    // 예를 들어, 대상 환경이 JVM인 경우:
    // kotlin("jvm") version "2.1.21"
}

Groovy

plugins {
    // `<...>`를 대상 환경에 적합한 플러그인 이름으로 바꾸세요.
    id 'org.jetbrains.kotlin.<...>' version '2.1.21'
    // 예를 들어, 대상 환경이 JVM인 경우: 
    // id 'org.jetbrains.kotlin.jvm' version '2.1.21'
}

NOTE

Kotlin Gradle 플러그인(KGP)과 Kotlin은 동일한 버전 번호를 공유합니다.

프로젝트를 구성할 때, Kotlin Gradle 플러그인(KGP)과 사용 가능한 Gradle 버전 간의 호환성을 확인하세요. 다음 표에는 Gradle 및 Android Gradle 플러그인(AGP)의 최소 및 최대 전체 지원 버전이 나와 있습니다.

KGP 버전	Gradle 최소 및 최대 버전	AGP 최소 및 최대 버전
2.1.20	7.6.3–8.12.1	7.3.1–8.7.2
2.1.0–2.1.10	7.6.3–8.10*	7.3.1–8.7.2
2.0.20–2.0.21	6.8.3–8.8*	7.1.3–8.5
2.0.0	6.8.3–8.5	7.1.3–8.3.1
1.9.20–1.9.25	6.8.3–8.1.1	4.2.2–8.1.0
1.9.0–1.9.10	6.8.3–7.6.0	4.2.2–7.4.0
1.8.20–1.8.22	6.8.3–7.6.0	4.1.3–7.4.0
1.8.0–1.8.11	6.8.3–7.3.3	4.1.3–7.2.1
1.7.20–1.7.22	6.7.1–7.1.1	3.6.4–7.0.4
1.7.0–1.7.10	6.7.1–7.0.2	3.4.3–7.0.2
1.6.20–1.6.21	6.1.1–7.0.2	3.4.3–7.0.2

DANGER

*Kotlin 2.0.20–2.0.21 및 Kotlin 2.1.0–2.1.10은 Gradle 8.6까지 완벽하게 호환됩니다.

Gradle 버전 8.7–8.10도 지원되지만, 한 가지 예외가 있습니다. Kotlin Multiplatform Gradle 플러그인을 사용하는 경우,

JVM 타겟에서 withJava() 함수를 호출하는 멀티플랫폼 프로젝트에서 사용 중단 경고가 표시될 수 있습니다.

자세한 내용은 기본적으로 생성되는 Java 소스 세트를 참조하세요.

최신 릴리스까지 Gradle 및 AGP 버전을 사용할 수도 있지만, 그렇게 할 경우 사용 중단 경고가 발생하거나 일부 새로운 기능이 작동하지 않을 수 있다는 점을 유의하세요.

예를 들어, Kotlin Gradle 플러그인과 kotlin-multiplatform 플러그인 2.1.21은 프로젝트 컴파일을 위해 최소 Gradle 버전 7.6.3을 필요로 합니다.

마찬가지로, 최대 전체 지원 버전은 8.12.1입니다. 이 버전은 사용 중단된 Gradle 메서드 및 속성이 없으며, 모든 현재 Gradle 기능을 지원합니다.

프로젝트 내 Kotlin Gradle 플러그인 데이터

기본적으로 Kotlin Gradle 플러그인은 프로젝트 루트의 .kotlin 디렉토리에 영구적인 프로젝트별 데이터를 저장합니다.

DANGER

.kotlin 디렉토리를 버전 제어에 커밋하지 마세요.

예를 들어, Git을 사용 중이라면 .gitignore 파일에 .kotlin을 추가하세요.

이 동작을 구성하기 위해 프로젝트의 gradle.properties 파일에 추가할 수 있는 속성들이 있습니다.

Gradle 속성	설명
kotlin.project.persistent.dir	프로젝트 수준 데이터가 저장되는 위치를 구성합니다. 기본값: <project-root-directory>/.kotlin
kotlin.project.persistent.dir.gradle.disableWrite	.gradle 디렉토리에 Kotlin 데이터를 쓰는 것을 비활성화할지 여부를 제어합니다(이전 IDEA 버전과의 하위 호환성을 위해). 기본값: false

JVM 타겟팅

JVM을 타겟팅하려면 Kotlin JVM 플러그인을 적용하세요.

Kotlin

plugins {
    kotlin("jvm") version "2.1.21"
}

Groovy

plugins {
    id "org.jetbrains.kotlin.jvm" version "2.1.21"
}

이 블록에서 version은 리터럴이어야 하며, 다른 빌드 스크립트에서 적용할 수 없습니다.

Kotlin 및 Java 소스

Kotlin 소스와 Java 소스는 같은 디렉토리에 저장할 수 있으며, 또는 다른 디렉토리에 배치할 수 있습니다.

기본 규칙은 다른 디렉토리를 사용하는 것입니다.

project
    - src
        - main (root)
            - kotlin
            - java

DANGER

.java 파일은 컴파일되지 않으므로 Java .java 파일을 src/*/kotlin 디렉토리에 저장하지 마세요.

대신 src/main/java를 사용할 수 있습니다.

기본 규칙을 사용하지 않는 경우, 해당 sourceSets 속성은 업데이트되어야 합니다.

Kotlin

sourceSets.main {
    java.srcDirs("src/main/myJava", "src/main/myKotlin")
}

Groovy

sourceSets {
    main.kotlin.srcDirs += 'src/main/myKotlin'
    main.java.srcDirs += 'src/main/myJava'
}

관련 컴파일 작업의 JVM 타겟 호환성 확인

빌드 모듈에서 다음과 같은 관련 컴파일 작업이 있을 수 있습니다.

• compileKotlin 및 compileJava
• compileTestKotlin 및 compileTestJava

NOTE

main 및 test 소스 세트 컴파일 작업은 관련이 없습니다.

이러한 관련 작업에 대해 Kotlin Gradle 플러그인은 JVM 타겟 호환성을 확인합니다. kotlin 확장 또는 작업의 jvmTarget 속성과 java 확장 또는 작업의 targetCompatibility 값이 다르면 JVM 타겟 비호환성이 발생합니다. 예를 들면 다음과 같습니다. compileKotlin 작업의 jvmTarget=1.8이고, compileJava 작업의 targetCompatibility=15입니다(또는 상속받습니다).

gradle.properties 파일에 kotlin.jvm.target.validation.mode 속성을 다음으로 설정하여 전체 프로젝트에 대한 이 확인의 동작을 구성할 수 있습니다.

• error – 플러그인이 빌드를 실패시킵니다; Gradle 8.0+ 프로젝트의 기본값.
• warning – 플러그인이 경고 메시지를 출력합니다; Gradle 8.0 미만 프로젝트의 기본값.
• ignore – 플러그인이 확인을 건너뛰고 메시지를 생성하지 않습니다.

build.gradle(.kts) 파일에서 작업 수준으로도 구성할 수 있습니다.

Kotlin

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>().configureEach {
    jvmTargetValidationMode.set(org.jetbrains.kotlin.gradle.dsl.jvm.JvmTargetValidationMode.WARNING)
}

Groovy

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile.class).configureEach {
    jvmTargetValidationMode = org.jetbrains.kotlin.gradle.dsl.jvm.JvmTargetValidationMode.WARNING
}

JVM 타겟 비호환성을 피하려면, 도구 체인을 구성하거나 JVM 버전을 수동으로 맞추세요.

타겟이 호환되지 않으면 어떤 문제가 발생할 수 있나요?

Kotlin 및 Java 소스 세트에 대한 JVM 타겟을 수동으로 설정하는 두 가지 방법이 있습니다.

• Java 도구 체인을 설정하는 암시적인 방법.
• kotlin 확장 또는 작업의 jvmTarget 속성과 java 확장 또는 작업의 targetCompatibility를 설정하는 명시적인 방법.

다음과 같은 경우 JVM 타겟 비호환성이 발생합니다.

• jvmTarget과 targetCompatibility에 다른 값을 명시적으로 설정한 경우.
• 기본 구성을 사용하고 있으며 JDK가 1.8이 아닌 경우.

빌드 스크립트에 Kotlin JVM 플러그인만 있고 JVM 타겟에 대한 추가 설정이 없는 경우 JVM 타겟의 기본 구성을 고려해 봅시다.

Kotlin

plugins {
    kotlin("jvm") version "2.1.21"
}

Groovy

plugins {
    id "org.jetbrains.kotlin.jvm" version "2.1.21"
}

빌드 스크립트에 jvmTarget 값에 대한 명시적인 정보가 없는 경우, 기본값은 null이며 컴파일러는 이를 기본값 1.8로 변환합니다. targetCompatibility는 현재 Gradle의 JDK 버전과 동일하며, 이는 사용자의 JDK 버전과 같습니다(단, Java 도구 체인 접근 방식을 사용하는 경우는 제외). JDK 버전이 17이라고 가정하면, 게시된 라이브러리 아티팩트는 JDK 17+와 호환된다고 선언하게 되는데, 이는 잘못된 것입니다: org.gradle.jvm.version=17. 이 경우, 바이트코드 버전이 1.8임에도 불구하고 이 라이브러리를 추가하려면 메인 프로젝트에서 Java 17을 사용해야 합니다. 이 문제를 해결하려면 도구 체인을 구성하세요.

Gradle Java 도구 체인 지원

DANGER

Android 사용자 경고. Gradle 도구 체인 지원을 사용하려면 Android Gradle 플러그인(AGP) 버전 8.1.0-alpha09 이상을 사용하세요.

Gradle Java 도구 체인 지원은 AGP 7.4.0부터만 사용 가능합니다.

그럼에도 불구하고, 이 문제로 인해 AGP는 버전 8.1.0-alpha09까지 targetCompatibility를 도구 체인의 JDK와 동일하게 설정하지 않았습니다.

8.1.0-alpha09 미만 버전을 사용하는 경우, compileOptions를 통해 targetCompatibility를 수동으로 구성해야 합니다.

<MAJOR_JDK_VERSION> 플레이스홀더를 사용하려는 JDK 버전으로 바꾸세요.

android {

    compileOptions {

        sourceCompatibility = <MAJOR_JDK_VERSION>

        targetCompatibility = <MAJOR_JDK_VERSION>

    }

}

Gradle 6.7은 Java 도구 체인 지원을 도입했습니다. 이 기능을 사용하면 다음을 수행할 수 있습니다.

• Gradle의 JDK 및 JRE와 다른 JDK 및 JRE를 사용하여 컴파일, 테스트 및 실행 파일을 실행할 수 있습니다.
• 아직 출시되지 않은 언어 버전으로 코드를 컴파일하고 테스트할 수 있습니다.

도구 체인 지원을 통해 Gradle은 로컬 JDK를 자동 감지하고 빌드에 필요한 누락된 JDK를 설치할 수 있습니다. 이제 Gradle 자체는 어떤 JDK에서도 실행될 수 있으며 주요 JDK 버전에 의존하는 작업에 대해 원격 빌드 캐시 기능을 계속 재사용할 수 있습니다.

Kotlin Gradle 플러그인은 Kotlin/JVM 컴파일 작업을 위한 Java 도구 체인을 지원합니다. JS 및 Native 작업은 도구 체인을 사용하지 않습니다. Kotlin 컴파일러는 항상 Gradle 데몬이 실행 중인 JDK에서 실행됩니다. Java 도구 체인은 다음과 같습니다.

• JVM 타겟에 사용 가능한 -jdk-home 옵션을 설정합니다.
• 사용자가 jvmTarget 옵션을 명시적으로 설정하지 않으면 compilerOptions.jvmTarget을 도구 체인의 JDK 버전으로 설정합니다. 사용자가 도구 체인을 구성하지 않으면 jvmTarget 필드는 기본값을 사용합니다. JVM 타겟 호환성에 대해 자세히 알아보세요.
• 모든 Java 컴파일, 테스트 및 javadoc 작업에서 사용될 도구 체인을 설정합니다.
• kapt 워커가 실행되는 JDK에 영향을 줍니다.

도구 체인을 설정하려면 다음 코드를 사용하세요. <MAJOR_JDK_VERSION> 플레이스홀더를 사용하려는 JDK 버전으로 바꾸세요.

Kotlin

kotlin {
    jvmToolchain {
        languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
    }
    // 또는 더 짧게:
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // 예를 들어:
    jvmToolchain(17)
}

Groovy

kotlin {
    jvmToolchain {
        languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
    }
    // 또는 더 짧게:
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // 예를 들어:
    jvmToolchain(17)
}

kotlin 확장을 통해 도구 체인을 설정하면 Java 컴파일 작업의 도구 체인도 업데이트된다는 점에 유의하세요.

java 확장을 통해 도구 체인을 설정할 수 있으며, Kotlin 컴파일 작업이 이를 사용합니다.

Kotlin

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)) 
    }
}

Groovy

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
    }
}

Gradle 8.0.2 이상을 사용하는 경우, 도구 체인 리졸버 플러그인도 추가해야 합니다. 이 유형의 플러그인은 도구 체인을 다운로드할 저장소를 관리합니다. 예를 들어, settings.gradle(.kts)에 다음 플러그인을 추가하세요.

Kotlin

plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version("0.9.0")
}

Groovy

plugins {
    id 'org.gradle.toolchains.foojay-resolver-convention' version '0.9.0'
}

Gradle 사이트에서 foojay-resolver-convention의 버전이 Gradle 버전에 해당하는지 확인하세요.

NOTE

Gradle이 어떤 도구 체인을 사용하는지 이해하려면 로그 레벨 --info로 Gradle 빌드를 실행하고

출력에서 [KOTLIN] Kotlin compilation 'jdkHome' argument:로 시작하는 문자열을 찾으세요.

콜론 뒤의 부분이 도구 체인의 JDK 버전입니다.

특정 작업에 대해 어떤 JDK든 (로컬 JDK 포함) 설정하려면 Task DSL을 사용하세요.

Kotlin 플러그인의 Gradle JVM 도구 체인 지원에 대해 자세히 알아보세요.

Task DSL로 JDK 버전 설정

Task DSL은 UsesKotlinJavaToolchain 인터페이스를 구현하는 모든 작업에 대해 어떤 JDK 버전이든 설정할 수 있도록 합니다. 현재 이러한 작업은 KotlinCompile 및 KaptTask입니다. Gradle이 주요 JDK 버전을 검색하도록 하려면 빌드 스크립트에서 <MAJOR_JDK_VERSION> 플레이스홀더를 바꾸세요.

Kotlin

val service = project.extensions.getByType<JavaToolchainService>()
val customLauncher = service.launcherFor {
    languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
}
project.tasks.withType<UsesKotlinJavaToolchain>().configureEach {
    kotlinJavaToolchain.toolchain.use(customLauncher)
}

Groovy

JavaToolchainService service = project.getExtensions().getByType(JavaToolchainService.class)
Provider<JavaLauncher> customLauncher = service.launcherFor {
    it.languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
}
tasks.withType(UsesKotlinJavaToolchain::class).configureEach { task ->
    task.kotlinJavaToolchain.toolchain.use(customLauncher)
}

또는 로컬 JDK의 경로를 지정하고 <LOCAL_JDK_VERSION> 플레이스홀더를 이 JDK 버전으로 바꿀 수 있습니다.

tasks.withType<UsesKotlinJavaToolchain>().configureEach {
    kotlinJavaToolchain.jdk.use(
        "/path/to/local/jdk", // JDK 경로를 입력하세요.
        JavaVersion.<LOCAL_JDK_VERSION> // 예를 들어, JavaVersion.17
    )
}

컴파일러 작업 연결

한 컴파일이 다른 컴파일의 컴파일된 출력을 사용하도록 관계를 설정하여 컴파일을 _연결_할 수 있습니다. 컴파일을 연결하면 컴파일 사이에 internal 가시성이 설정됩니다.

Kotlin 컴파일러는 각 타겟의 test 및 main 컴파일과 같이 일부 컴파일을 기본적으로 연결합니다. 사용자 정의 컴파일 중 하나가 다른 컴파일에 연결되어 있음을 표현해야 하는 경우, 자체 연결된 컴파일을 생성하세요.

IDE가 소스 세트 간의 가시성을 추론하기 위해 연결된 컴파일을 지원하도록 하려면 build.gradle(.kts)에 다음 코드를 추가하세요.

Kotlin

val integrationTestCompilation = kotlin.target.compilations.create("integrationTest") {
    associateWith(kotlin.target.compilations.getByName("main"))
}

Groovy

integrationTestCompilation {
    kotlin.target.compilations.create("integrationTest") {
        associateWith(kotlin.target.compilations.getByName("main"))
    }
}

여기서 integrationTest 컴파일은 main 컴파일과 연결되어 있으며, 이는 기능 테스트에서 internal 객체에 대한 액세스를 제공합니다.

Java 모듈(JPMS) 활성화 구성

Kotlin Gradle 플러그인이 Java 모듈과 작동하도록 하려면, 빌드 스크립트에 다음 줄을 추가하고 YOUR_MODULE_NAME을 org.company.module과 같이 JPMS 모듈에 대한 참조로 바꾸세요.

Kotlin

// Gradle 버전 7.0 미만을 사용하는 경우 다음 세 줄을 추가하세요.
java {
    modularity.inferModulePath.set(true)
}

tasks.named("compileJava", JavaCompile::class.java) {
    options.compilerArgumentProviders.add(CommandLineArgumentProvider {
        // 컴파일된 Kotlin 클래스를 javac에 제공합니다 – Java/Kotlin 혼합 소스 작동에 필요
        listOf("--patch-module", "YOUR_MODULE_NAME=${sourceSets["main"].output.asPath}")
    })
}

Groovy

// Gradle 버전 7.0 미만을 사용하는 경우 다음 세 줄을 추가하세요.
java {
    modularity.inferModulePath = true
}

tasks.named("compileJava", JavaCompile.class) {
    options.compilerArgumentProviders.add(new CommandLineArgumentProvider() {
        @Override
        Iterable<String> asArguments() {
            // 컴파일된 Kotlin 클래스를 javac에 제공합니다 – Java/Kotlin 혼합 소스 작동에 필요
            return ["--patch-module", "YOUR_MODULE_NAME=${sourceSets["main"].output.asPath}"]
        }
    })
}

NOTE

module-info.java를 평소와 같이 src/main/java 디렉토리에 넣으세요.

모듈의 경우, "package is empty or does not exist" 빌드 실패를 피하려면 Kotlin 파일의 패키지 이름이 module-info.java의 패키지 이름과 같아야 합니다.

자세히 알아보세요:

• Java 모듈 시스템용 모듈 빌드
• Java 모듈 시스템을 사용하는 애플리케이션 빌드
• Kotlin에서 "모듈"의 의미

기타 세부 정보

Kotlin/JVM에 대해 자세히 알아보세요.

컴파일 작업에서 아티팩트 사용 비활성화

일부 드문 시나리오에서 순환 의존성 오류로 인해 빌드 실패를 경험할 수 있습니다. 예를 들어, 여러 컴파일이 있어 한 컴파일이 다른 컴파일의 모든 내부 선언을 볼 수 있고, 생성된 아티팩트가 두 컴파일 작업의 출력에 의존하는 경우:

FAILURE: Build failed with an exception.

What went wrong:
Circular dependency between the following tasks:
:lib:compileKotlinJvm
--- :lib:jvmJar
     \--- :lib:compileKotlinJvm (*)
(*) - details omitted (listed previously)

이 순환 의존성 오류를 해결하기 위해 archivesTaskOutputAsFriendModule이라는 Gradle 속성을 추가했습니다. 이 속성은 컴파일 작업에서 아티팩트 입력의 사용을 제어하며, 그 결과 작업 의존성이 생성되는지 여부를 결정합니다.

기본적으로 이 속성은 작업 의존성을 추적하기 위해 true로 설정됩니다. 순환 의존성 오류가 발생하면, 컴파일 작업에서 아티팩트 사용을 비활성화하여 작업 의존성을 제거하고 순환 의존성 오류를 피할 수 있습니다.

컴파일 작업에서 아티팩트 사용을 비활성화하려면 gradle.properties 파일에 다음을 추가하세요.

kotlin.build.archivesTaskOutputAsFriendModule=false

지연 Kotlin/JVM 작업 생성

Kotlin 1.8.20부터 Kotlin Gradle 플러그인은 모든 작업을 등록하며 드라이 런(dry run) 시에는 구성하지 않습니다.

컴파일 작업 destinationDirectory의 비표준 위치

Kotlin/JVM KotlinJvmCompile/KotlinCompile 작업의 destinationDirectory 위치를 재정의하는 경우, 빌드 스크립트를 업데이트하세요. JAR 파일에서 sourceSets.main.outputs에 sourceSets.main.kotlin.classesDirectories를 명시적으로 추가해야 합니다.

tasks.jar(type: Jar) {
    from sourceSets.main.outputs
    from sourceSets.main.kotlin.classesDirectories
}

여러 플랫폼 타겟팅

여러 플랫폼을 타겟팅하는 프로젝트, 즉 멀티플랫폼 프로젝트는 kotlin-multiplatform 플러그인을 필요로 합니다.

NOTE

kotlin-multiplatform 플러그인은 Gradle 7.6.3 이상에서 작동합니다.

Kotlin

plugins {
    kotlin("multiplatform") version "2.1.21"
}

Groovy

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.1.21'
}

다양한 플랫폼을 위한 Kotlin Multiplatform 및 iOS 및 Android를 위한 Kotlin Multiplatform에 대해 자세히 알아보세요.

Android 타겟팅

Android 애플리케이션을 생성할 때는 Android Studio를 사용하는 것이 좋습니다. Android Gradle 플러그인 사용 방법을 알아보세요.

JavaScript 타겟팅

JavaScript를 타겟팅할 때도 kotlin-multiplatform 플러그인을 사용하세요. Kotlin/JS 프로젝트 설정에 대해 자세히 알아보세요.

Kotlin

plugins {
    kotlin("multiplatform") version "2.1.21"
}

Groovy

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.1.21'
}

JavaScript용 Kotlin 및 Java 소스

이 플러그인은 Kotlin 파일에만 작동하므로, (프로젝트에 Java 파일이 포함된 경우) Kotlin 파일과 Java 파일을 별도로 유지하는 것이 좋습니다. 별도로 저장하지 않는 경우, sourceSets{} 블록에 소스 폴더를 지정하세요.

Kotlin

kotlin {
    sourceSets["main"].apply {
        kotlin.srcDir("src/main/myKotlin")
    }
}

Groovy

kotlin {
    sourceSets {
        main.kotlin.srcDirs += 'src/main/myKotlin'
    }
}

KotlinBasePlugin 인터페이스로 구성 작업 트리거

모든 Kotlin Gradle 플러그인(JVM, JS, 멀티플랫폼, Native 등)이 적용될 때마다 일부 구성 작업을 트리거하려면, 모든 Kotlin 플러그인이 상속하는 KotlinBasePlugin 인터페이스를 사용하세요.

Kotlin

import org.jetbrains.kotlin.gradle.plugin.KotlinBasePlugin

// ...

project.plugins.withType<KotlinBasePlugin>() {
    // 여기에 작업을 구성하세요.
}

Groovy

import org.jetbrains.kotlin.gradle.plugin.KotlinBasePlugin

// ...

project.plugins.withType(KotlinBasePlugin.class) {
    // 여기에 작업을 구성하세요.
}

의존성 구성

라이브러리에 의존성을 추가하려면, 소스 세트 DSL의 dependencies{} 블록에 필요한 유형의 의존성(예: implementation)을 설정하세요.

Kotlin

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.example:my-library:1.0")
        }
    }
}

Groovy

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation 'com.example:my-library:1.0'
            }
        }
    }
}

또는 최상위 수준에서 의존성을 설정할 수 있습니다.

의존성 유형

요구 사항에 따라 의존성 유형을 선택하세요.

유형	설명	사용 시기
api	컴파일 시와 런타임 시 모두 사용되며 라이브러리 사용자에게 내보내집니다.	의존성에서 어떤 유형이든 현재 모듈의 공개 API에서 사용되는 경우, api 의존성을 사용하세요.
implementation	현재 모듈의 컴파일 및 런타임 시 사용되지만, implementation 의존성을 가진 모듈에 의존하는 다른 모듈의 컴파일에는 노출되지 않습니다.	모듈의 내부 로직에 필요한 의존성에 사용합니다. 모듈이 게시되지 않는 엔드포인트 애플리케이션인 경우, api 의존성 대신 implementation 의존성을 사용하세요.
compileOnly	현재 모듈의 컴파일에 사용되며 런타임 시나 다른 모듈의 컴파일 시에는 사용할 수 없습니다.	런타임 시 서드파티 구현이 가능한 API에 사용합니다.
runtimeOnly	런타임 시 사용 가능하지만 어떤 모듈의 컴파일 시에도 보이지 않습니다.

표준 라이브러리 의존성

표준 라이브러리(stdlib)에 대한 의존성은 각 소스 세트에 자동으로 추가됩니다. 사용되는 표준 라이브러리 버전은 Kotlin Gradle 플러그인 버전과 동일합니다.

플랫폼별 소스 세트의 경우, 해당 라이브러리의 플랫폼별 변형이 사용되며, 나머지는 공통 표준 라이브러리가 추가됩니다. Kotlin Gradle 플러그인은 Gradle 빌드 스크립트의 compilerOptions.jvmTarget 컴파일러 옵션에 따라 적절한 JVM 표준 라이브러리를 선택합니다.

표준 라이브러리 의존성을 명시적으로 선언하는 경우(예: 다른 버전이 필요한 경우), Kotlin Gradle 플러그인은 이를 재정의하거나 두 번째 표준 라이브러리를 추가하지 않습니다.

표준 라이브러리가 전혀 필요하지 않다면 gradle.properties 파일에 다음 Gradle 속성을 추가할 수 있습니다.

kotlin.stdlib.default.dependency=false

전이적 의존성의 버전 정렬

Kotlin 표준 라이브러리 버전 1.9.20부터 Gradle은 표준 라이브러리에 포함된 메타데이터를 사용하여 전이적 kotlin-stdlib-jdk7 및 kotlin-stdlib-jdk8 의존성을 자동으로 정렬합니다.

예를 들어, 1.8.0 – 1.9.10 사이의 Kotlin 표준 라이브러리 버전에 대한 의존성 implementation("org.jetbrains.kotlin:kotlin-stdlib:1.8.0")을 추가하면, Kotlin Gradle 플러그인은 전이적 kotlin-stdlib-jdk7 및 kotlin-stdlib-jdk8 의존성에 이 Kotlin 버전을 사용합니다. 이는 다른 표준 라이브러리 버전으로 인한 클래스 중복을 방지합니다. kotlin-stdlib-jdk7 및 kotlin-stdlib-jdk8을 kotlin-stdlib로 병합하는 방법에 대해 자세히 알아보세요. gradle.properties 파일의 kotlin.stdlib.jdk.variants.version.alignment Gradle 속성으로 이 동작을 비활성화할 수 있습니다.

kotlin.stdlib.jdk.variants.version.alignment=false

버전을 정렬하는 다른 방법

• 버전 정렬에 문제가 있는 경우, Kotlin BOM을 통해 모든 버전을 정렬할 수 있습니다. 빌드 스크립트에서 kotlin-bom에 대한 플랫폼 의존성을 선언하세요.

  implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.1.21"))

  implementation platform('org.jetbrains.kotlin:kotlin-bom:2.1.21')

:::

• 표준 라이브러리 버전에 대한 의존성을 추가하지 않았지만, 전이적으로 다른 이전 버전의 Kotlin 표준 라이브러리를 가져오는 두 개의 다른 의존성이 있는 경우, 이 전이적 라이브러리에 대해 명시적으로 2.1.21 버전을 요구할 수 있습니다.

  dependencies {
      constraints {
          add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk7") {
              version {
                  require("2.1.21")
              }
          }
          add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk8") {
              version {
                  require("2.1.21")
              }
          }
      }
  }

  dependencies {
      constraints {
          add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk7") {
              version {
                  require("2.1.21")
              }
          }
          add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk8") {
              version {
                  require("2.1.21")
              }
          }
      }
  }

:::

• Kotlin 표준 라이브러리 버전 2.1.21 (implementation("org.jetbrains.kotlin:kotlin-stdlib:2.1.21"))에 대한 의존성을 추가하고, Kotlin Gradle 플러그인의 이전 버전(1.8.0 이전)을 사용하는 경우, 표준 라이브러리 버전에 맞게 Kotlin Gradle 플러그인을 업데이트하세요.

  plugins {
      // `<...>`를 플러그인 이름으로 바꾸세요.
      kotlin("<...>") version "2.1.21"
  }

  plugins {
      // `<...>`를 플러그인 이름으로 바꾸세요.
      id "org.jetbrains.kotlin.<...>" version "2.1.21"
  }

:::

• 예를 들어, kotlin-stdlib-jdk7/kotlin-stdlib-jdk8의 1.8.0 이전 버전을 사용 중이고 (implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk7:SOME_OLD_KOTLIN_VERSION")), 전이적으로 kotlin-stdlib:1.8+를 가져오는 의존성이 있는 경우, kotlin-stdlib-jdk<7/8>:SOME_OLD_KOTLIN_VERSION를 kotlin-stdlib-jdk*:2.1.21으로 바꾸거나 해당 라이브러리에서 전이적 kotlin-stdlib:1.8+를 제외하세요.

  dependencies {
      implementation("com.example:lib:1.0") {
          exclude(group = "org.jetbrains.kotlin", module = "kotlin-stdlib")
      }
  }

  dependencies {
      implementation("com.example:lib:1.0") {
          exclude group: "org.jetbrains.kotlin", module: "kotlin-stdlib"
      }
  }

:::

테스트 라이브러리에 의존성 설정

kotlin.test API는 모든 지원 플랫폼에서 Kotlin 프로젝트를 테스트하는 데 사용할 수 있습니다. commonTest 소스 세트에 kotlin-test 의존성을 추가하면, Gradle 플러그인이 각 테스트 소스 세트에 해당하는 테스트 의존성을 추론할 수 있습니다.

Kotlin/Native 타겟은 추가 테스트 의존성을 필요로 하지 않으며, kotlin.test API 구현은 내장되어 있습니다.

Kotlin

kotlin {
    sourceSets {
         commonTest.dependencies {
             implementation(kotlin("test")) // 이는 모든 플랫폼 의존성을 자동으로 가져옵니다.
        }
    }
}

Groovy

kotlin {
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test") // 이는 모든 플랫폼 의존성을 자동으로 가져옵니다.
            }
        }
    }
}

NOTE

Kotlin 모듈에 대한 의존성에는 약어를 사용할 수 있습니다. 예를 들어, "org.jetbrains.kotlin:kotlin-test" 대신 kotlin("test")를 사용할 수 있습니다.

kotlin-test 의존성은 어떤 공유 또는 플랫폼별 소스 세트에서도 사용할 수 있습니다.

kotlin-test의 JVM 변형

Kotlin/JVM의 경우, Gradle은 기본적으로 JUnit 4를 사용합니다. 따라서 kotlin("test") 의존성은 JUnit 4용 변형인 kotlin-test-junit으로 해석됩니다.

빌드 스크립트의 테스트 작업에서 useJUnitPlatform() 또는 useTestNG()를 호출하여 JUnit 5 또는 TestNG를 선택할 수 있습니다. 다음 예시는 Kotlin 멀티플랫폼 프로젝트용입니다.

Kotlin

kotlin {
    jvm {
        testRuns["test"].executionTask.configure {
            useJUnitPlatform()
        }
    }
    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test"))
        }
    }
}

Groovy

kotlin {
    jvm {
        testRuns["test"].executionTask.configure {
            useJUnitPlatform()
        }
    }
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test")
            }
        }
    }
}

다음 예시는 JVM 프로젝트용입니다.

Kotlin

dependencies {
    testImplementation(kotlin("test"))
}

tasks {
    test {
        useTestNG()
    }
}

Groovy

dependencies {
    testImplementation 'org.jetbrains.kotlin:kotlin-test'
}

test {
    useTestNG()
}

JVM에서 JUnit을 사용하여 코드 테스트 방법을 알아보세요.

자동 JVM 변형 해결은 때때로 구성에 문제를 일으킬 수 있습니다. 이 경우, 필요한 프레임워크를 명시적으로 지정하고 프로젝트 gradle.properties 파일에 다음 줄을 추가하여 자동 해결을 비활성화할 수 있습니다.

kotlin.test.infer.jvm.variant=false

빌드 스크립트에서 kotlin("test")의 변형을 명시적으로 사용했고 호환성 충돌로 인해 프로젝트 빌드가 작동을 멈춘 경우, 호환성 가이드의 이 문제를 참조하세요.

kotlinx 라이브러리에 의존성 설정

멀티플랫폼 라이브러리를 사용하고 공유 코드에 의존해야 하는 경우, 공유 소스 세트에서 한 번만 의존성을 설정하세요. kotlinx-coroutines-core 또는 ktor-client-core와 같은 라이브러리의 기본 아티팩트 이름을 사용하세요.

Kotlin

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
        }
    }
}

Groovy

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2'
            }
        }
    }
}

플랫폼별 의존성을 위해 kotlinx 라이브러리가 필요한 경우에도, 해당 플랫폼 소스 세트에서 라이브러리의 기본 아티팩트 이름을 계속 사용할 수 있습니다.

Kotlin

kotlin {
    sourceSets {
        jvmMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
        }
    }
}

Groovy

kotlin {
    sourceSets {
        jvmMain {
            dependencies {
                implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2'
            }
        }
    }
}

최상위 수준에서 의존성 설정

또는 최상위 수준에서 의존성을 지정할 수 있으며, 구성 이름에 대해 <sourceSetName><DependencyType> 패턴을 사용합니다. 이는 소스 세트의 의존성 DSL에서 사용할 수 없는 gradleApi(), localGroovy(), gradleTestKit()와 같은 일부 Gradle 내장 의존성에 유용할 수 있습니다.

Kotlin

dependencies {
    "commonMainImplementation"("com.example:my-library:1.0")
}

Groovy

dependencies {
    commonMainImplementation 'com.example:my-library:1.0'
}

저장소 선언

공개적으로 사용 가능한 저장소를 선언하여 해당 오픈 소스 의존성을 사용할 수 있습니다. repositories{} 블록에서 저장소의 이름을 설정하세요.

Kotlin

repositories {
    mavenCentral()
}

Groovy

repositories {
    mavenCentral()
}

인기 있는 저장소로는 Maven Central과 Google의 Maven 저장소가 있습니다.

DANGER

Maven 프로젝트와도 함께 작업하는 경우, Gradle과 Maven 프로젝트 간에 전환할 때 문제가 발생할 수 있으므로 mavenLocal()을 저장소로 추가하는 것을 피하는 것이 좋습니다. mavenLocal() 저장소를 반드시 추가해야 한다면, repositories{} 블록의 마지막 저장소로 추가하세요. 자세한 내용은 mavenLocal()에 대한 사례를 참조하세요.

둘 이상의 서브 프로젝트에서 동일한 저장소를 선언해야 하는 경우, settings.gradle(.kts) 파일의 dependencyResolutionManagement{} 블록에 저장소를 중앙에서 선언하세요.

Kotlin

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

Groovy

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

서브 프로젝트에 선언된 모든 저장소는 중앙에서 선언된 저장소를 재정의합니다. 이 동작을 제어하는 방법과 사용 가능한 옵션에 대한 자세한 내용은 Gradle 문서를 참조하세요.

다음 단계는?

자세히 알아보세요:

• 컴파일러 옵션 및 전달 방법.
• 점진적 컴파일, 캐시 지원, 빌드 보고서 및 Kotlin 데몬.
• Gradle 기본 사항 및 세부 사항.
• Gradle 플러그인 변형 지원.