Настройка проекта Gradle

Данные плагина Kotlin Gradle в проекте

По умолчанию плагин Kotlin Gradle сохраняет постоянные данные проекта в корневой папке проекта, в каталоге .kotlin.

В файл gradle.properties проекта можно добавить свойства, чтобы настроить это поведение:

Исходный код Kotlin и Java

Исходный код Kotlin и Java можно хранить в одном каталоге или размещать в разных каталогах.

По умолчанию используются разные каталоги:

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

Если вы не используете соглашение по умолчанию, необходимо обновить соответствующее свойство sourceSets:

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

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

Проверка совместимости целевых платформ JVM связанных задач компиляции

В модуле сборки могут быть связанные задачи компиляции, например:

• compileKotlin и compileJava

• compileTestKotlin и compileTestJava

Для таких связанных задач плагин Kotlin Gradle проверяет совместимость целевых платформ JVM. Разные значения атрибута jvmTarget в расширении или задаче kotlin и атрибута targetCompatibility в расширении или задаче java приводят к несовместимости целевых платформ 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):

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

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

Чтобы избежать несовместимости целевых платформ JVM, настройте цепочку инструментов или вручную согласуйте версии JVM.

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

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

Поддержка цепочек инструментов Java в Gradle

В Gradle 6.7 появилась поддержка цепочек инструментов Java. Эта функция позволяет:

• Использовать для компиляции, тестирования и запуска исполняемых файлов JDK и JRE, отличные от используемых Gradle.

• Компилировать и тестировать код с помощью ещё не выпущенной версии языка.

При поддержке цепочек инструментов Gradle может автоматически обнаруживать локальные JDK и устанавливать отсутствующие JDK, необходимые для сборки. Теперь сам Gradle может работать на любой JDK и при этом повторно использовать функцию удалённого кэша сборки для задач, зависящих от основной версии JDK.

Плагин Kotlin Gradle поддерживает цепочки инструментов Java для задач компиляции Kotlin/JVM. Задачи JS и Native не используют цепочки инструментов. Компилятор Kotlin всегда работает на той JDK, на которой запущен демон Gradle. Цепочка инструментов Java:

• Задаёт параметр -jdk-home, доступный для целевых платформ JVM.

• Если пользователь явно не задаёт параметр jvmTarget, устанавливает для compilerOptions.jvmTarget версию JDK из цепочки инструментов. Если пользователь не настраивает цепочку инструментов, для поля jvmTarget используется значение по умолчанию. Подробнее см. в разделе Совместимость целевых платформ JVM.

• Задаёт цепочку инструментов для всех задач компиляции Java, тестирования и javadoc.

• Влияет на JDK, в которой работают рабочие процессы kapt.

Чтобы задать цепочку инструментов, используйте следующий код. Замените заполнитель <MAJOR_JDK_VERSION> на версию JDK, которую хотите использовать:

kotlin {
    jvmToolchain {
        languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
    }
    // Or shorter:
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // For example:
    jvmToolchain(17)
}

kotlin {
    jvmToolchain {
        languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
    }
    // Or shorter:
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // For example:
    jvmToolchain(17)
}

Обратите внимание, что настройка цепочки инструментов через расширение kotlin также обновляет цепочку инструментов для задач компиляции Java.

Цепочку инструментов можно задать через расширение java, после чего задачи компиляции Kotlin будут её использовать:

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

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

Если вы используете Gradle 8.0.2 или выше, необходимо также добавить плагин для разрешения цепочки инструментов. Плагин этого типа управляет выбором репозитория для загрузки цепочки инструментов. Например, добавьте следующий плагин в файл settings.gradle(.kts):

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

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

Убедитесь, что версия foojay-resolver-convention соответствует вашей версии Gradle. Сведения о версиях см. на сайте Gradle.

Чтобы задать любую JDK (в том числе локальную) для конкретной задачи, используйте DSL задач.

Подробнее о поддержке цепочек инструментов JVM в Gradle в плагине Kotlin.

Задание версии JDK с помощью DSL задач

DSL задач позволяет задать любую версию JDK для любой задачи, реализующей интерфейс UsesKotlinJavaToolchain. На данный момент к таким задачам относятся KotlinCompile и KaptTask. Если вы хотите, чтобы Gradle выполнил поиск основной версии JDK, замените заполнитель <MAJOR_JDK_VERSION> в сценарии сборки:

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

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", // Put a path to your JDK
        JavaVersion.<LOCAL_JDK_VERSION> // For example, JavaVersion.17
    )
}

Связывание задач компилятора

Можно связать компиляции, установив между ними такую зависимость, при которой одна компиляция использует результаты компиляции другой. Связывание компиляций обеспечивает между ними видимость internal.

Компилятор Kotlin по умолчанию связывает некоторые компиляции, например компиляции test и main каждой целевой платформы. Если необходимо указать, что одна из пользовательских компиляций связана с другой, создайте собственную связанную компиляцию.

Чтобы среда IDE поддерживала связанные компиляции при определении видимости между наборами исходного кода, добавьте следующий код в файл build.gradle(.kts):

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

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

В этом примере компиляция integrationTest связана с компиляцией main, что обеспечивает доступ к объектам internal из функциональных тестов.

Настройка с включённой поддержкой модулей Java (JPMS)

Чтобы плагин Kotlin Gradle работал с модулями Java, добавьте следующие строки в сценарий сборки и замените YOUR_MODULE_NAME ссылкой на ваш модуль JPMS, например org.company.module:

tasks.named("compileJava", JavaCompile::class.java) {
    // Provide compiled Kotlin classes to javac – needed for Java/Kotlin mixed sources to work
    val mainOutput: FileCollection = sourceSets["main"].output
    options.compilerArgumentProviders.add(CommandLineArgumentProvider {
        listOf("--patch-module", "YOUR_MODULE_NAME=${mainOutput.asPath}")
    })
}

tasks.named("compileJava", JavaCompile.class) {
    // Provide compiled Kotlin classes to javac – needed for Java/Kotlin mixed sources to work
    FileCollection mainOutput = sourceSets["main"].output
    options.compilerArgumentProviders.add(new CommandLineArgumentProvider() {
        @Override
        Iterable<String> asArguments() {
            return ["--patch-module", "YOUR_MODULE_NAME=${mainOutput.asPath}"]
        }
    })
}

Подробнее:

• Сборка модулей для системы модулей Java

• Создание приложений с использованием системы модулей Java

• Что означает «модуль» в Kotlin

Другие сведения

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)

kotlin.build.archivesTaskOutputAsFriendModule=false

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

Настройка целевой платформы JavaScript

Используйте Kotlin/JS, если хотите:

• Совместно использовать бизнес-логику с кодовой базой JavaScript/TypeScript

• Создавать на Kotlin веб-приложения, код которых нельзя совместно использовать

Дополнительную информацию см. в разделе Веб-разработка.

При настройке целевой платформы JavaScript используйте плагин kotlin-multiplatform:

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

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

Настройте целевую платформу JavaScript, указав, должна ли она работать в браузере или среде Node.js:

kotlin {
    js().browser {  // or js().nodejs
        /* ... */
    }
}

Настройка целевой платформы WebAssembly

Используйте Kotlin/Wasm, если хотите совместно использовать логику и пользовательский интерфейс на нескольких платформах. Дополнительную информацию см. в разделе Веб-разработка.

Как и в случае с JavaScript, при настройке целевой платформы WebAssembly (Wasm) используйте плагин kotlin-multiplatform:

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

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

В зависимости от ваших требований можно настроить целевую платформу:

• wasmJs: для запуска в браузерах или Node.js

• wasmWasi: для запуска в средах Wasm с поддержкой WASI (WebAssembly System Interface), таких как Wasmtime, WasmEdge и других.

Настройте целевую платформу wasmJs для веб-браузеров или Node.js:

kotlin {
    wasmJs {
        browser { // or nodejs
            /* ... */
        }
    }
}

Для сред WASI настройте целевую платформу wasmWasi с Node.js или Wasmtime:

kotlin {
    wasmWasi {
        nodejs { // or wasmtime
            /* ... */
        }
    }
}

Исходный код Kotlin и Java для целевой веб-платформы

KGP работает только с файлами Kotlin, поэтому рекомендуется хранить файлы Kotlin и Java отдельно (если проект содержит файлы Java). Если они хранятся вместе, укажите папку с исходным кодом в блоке sourceSets{}:

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

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

Настройка зависимостей на верхнем уровне

В мультиплатформенных проектах можно настраивать общие зависимости с помощью блока dependencies {} верхнего уровня. Объявленные здесь зависимости действуют так, как если бы они были добавлены в наборы исходного кода commonMain или commonTest.

Чтобы использовать блок dependencies {} верхнего уровня, разрешите его использование, добавив аннотацию @OptIn(ExperimentalKotlinGradlePluginApi::class) перед блоком:

kotlin {
    @OptIn(ExperimentalKotlinGradlePluginApi::class)
    dependencies {
        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")
    }
}

kotlin {
    dependencies {
        implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0'
    }
}

Добавьте зависимости для конкретной платформы в блок sourceSets {} соответствующей целевой платформы.

Оставить отзыв об этой функции можно в YouTrack.

Типы зависимостей

Выберите тип зависимости в соответствии с вашими требованиями.

Зависимость от стандартной библиотеки

Зависимость от стандартной библиотеки (stdlib) автоматически добавляется в каждый набор исходного кода. Используется та же версия стандартной библиотеки, что и версия плагина Kotlin Gradle.

Для наборов исходного кода конкретных платформ используется соответствующий вариант библиотеки для этой платформы, а для остальных добавляется общая стандартная библиотека. Плагин Kotlin Gradle выбирает подходящую стандартную библиотеку JVM в зависимости от параметра compilerOptions.jvmTarget компилятора в сценарии сборки Gradle.

Если вы явно объявите зависимость от стандартной библиотеки (например, если вам нужна другая версия), плагин Kotlin Gradle не переопределит ее и не добавит вторую стандартную библиотеку.

Если стандартная библиотека вам не нужна, добавьте в файл gradle.properties следующее свойство Gradle:

kotlin.stdlib.default.dependency=false

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

Добавление зависимостей от библиотек для тестирования

API kotlin.test доступен для тестирования проектов Kotlin на всех поддерживаемых платформах. Добавьте зависимость kotlin-test в набор исходного кода commonTest, чтобы плагин Gradle мог определить соответствующие зависимости для тестов в каждом наборе исходного кода.

Целевые платформы Kotlin/Native не требуют дополнительных зависимостей для тестирования: реализации API kotlin.test встроены.

kotlin {
    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test")) // This brings all the platform dependencies automatically
        }
    }
}

kotlin {
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test") // This brings all the platform dependencies automatically
            }
        }
    }
}

Зависимость kotlin-test также можно использовать в любом общем наборе исходного кода или наборе для конкретной платформы.

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

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

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

tasks {
    test {
        useTestNG()
    }
}

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

test {
    useTestNG()
}

kotlin.test.infer.jvm.variant=false

Добавление зависимости от библиотеки kotlinx

Если вы используете мультиплатформенную библиотеку и вам нужна зависимость от общего кода, укажите ее только один раз в общем наборе исходного кода. Используйте базовое имя артефакта библиотеки, например kotlinx-coroutines-core или ktor-client-core:

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

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

Если библиотека kotlinx нужна как зависимость для конкретной платформы, в соответствующем наборе исходного кода платформы также можно использовать базовое имя артефакта библиотеки:

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

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