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

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.

Настройте поведение этой проверки для всего проекта, установив свойство kotlin.jvm.target.validation.mode в файле build.gradle(.kts) в значение:

• 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 "1.9.0"
}

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

Поддержка Gradle Java toolchains

Gradle 6.7 ввёл поддержку Java toolchains. С помощью этой функции вы можете:

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

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

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

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

• Устанавливает -jdk-home опцию, доступную для целей JVM.

• Устанавливает compilerOptions.jvmTarget на версию JDK toolchain, если пользователь не устанавливает jvmTarget опцию явно. Если пользователь не настраивает toolchain, поле jvmTarget использует значение по умолчанию. Подробнее о совместимости целевой JVM.

• Устанавливает toolchain, который будет использоваться для любых задач Java компиляции, тестирования и документации.

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

Используйте следующий код для установки toolchain. Замените заполнитель <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.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
    }
    // Or shorter:
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // For example:
    jvmToolchain(17)
}

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

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

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

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

Если вы используете Gradle 8.0.2 или выше, вам также необходимо добавить плагин разрешения toolchains. Этот тип плагина управляет тем, откуда загружать toolchain.

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

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

Проверьте, что версия foojay-resolver-convention соответствует вашей версии Gradle на сайте Gradle.

Для установки любого JDK (даже локального) для конкретной задачи используйте Task DSL.

Узнайте больше о поддержке Gradle JVM toolchain в плагине Kotlin.

Установка версии JDK с помощью Task DSL

Task 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.set(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.

// Add the following three lines if you use a Gradle version less than 7.0
java {
    modularity.inferModulePath.set(true)
}

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

// Add the following three lines if you use a Gradle version less than 7.0
java {
    modularity.inferModulePath = true
}

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

Узнайте больше о:

• Создании модулей для Java Module System

• Создание приложений с использованием Java Module System

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

Дополнительные сведения

Узнайте больше о Kotlin/JVM.

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

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

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

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

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

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

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

Если вам вообще не нужна стандартная библиотека, вы можете добавить опцию исключения в gradle.properties.

kotlin.stdlib.default.dependency=false

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

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

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

• kotlin-test-common и kotlin-test-annotations-common для общих наборов исходных файлов

• kotlin-test-junit для наборов исходных файлов JVM

• kotlin-test-js для наборов исходных файлов Kotlin/JS

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

kotlin {
    sourceSets {
        val commonTest by getting {
            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 Gradle по умолчанию использует JUnit 4. Поэтому зависимость kotlin("test") разрешается до варианта для JUnit 4, а именно kotlin-test-junit.

Вы можете выбрать JUnit 5 или TestNG, вызвав useJUnitPlatform() или useTestNG() в задаче тестирования вашего скрипта сборки. Следующий пример предназначен для проекта Kotlin Multiplatform:

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

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

Следующий пример предназначен для проекта JVM:

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

tasks {
    test {
        useTestNG()
    }
}

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

test {
    useTestNG()
}

Узнайте, как тестировать код с помощью JUnit на JVM.

Если вам необходимо использовать другой фреймворк тестирования JVM, отключите автоматический выбор фреймворка тестирования, добавив строку kotlin.test.infer.jvm.variant=false в файл gradle.properties проекта. После этого добавьте фреймворк как зависимость Gradle.

Если вы явно использовали вариант kotlin("test") в своём скрипте сборки и сборка проекта перестала работать из-за конфликта совместимости, см. эту проблему в руководстве по совместимости.

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

Если вы используете kotlinx библиотеку и вам нужна платформенно-специфичная зависимость, вы можете использовать платформенно-специфичные варианты библиотек с суффиксом, например, -jvm или -js, например, kotlinx-coroutines-core-jvm. Вы также можете использовать имя базового артефакта библиотеки — kotlinx-coroutines-core.

kotlin {
    sourceSets {
        val jvmMain by getting {
            dependencies {
                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.7.1")
            }
        }
    }
}

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

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

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.1")
            }
        }
    }
}

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

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

В качестве альтернативы вы можете указать зависимости на верхнем уровне, используя следующий шаблон для имён конфигураций: <sourceSetName><DependencyType>. Это может быть полезно для некоторых встроенных зависимостей Gradle, таких как gradleApi(), localGroovy(), или gradleTestKit(), которые недоступны в DSL зависимостей наборов исходных файлов.

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

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