Настройка проекта 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 на:

• error – плагин завершит сборку с ошибкой; значение по умолчанию для проектов на Gradle 8.0+.

• warning – плагин Kotlin Gradle выведет сообщение об ошибке; значение по умолчанию для проектов на Gradle менее 8.0.

• ignore – плагин пропустит проверку и не выведет никаких сообщений.

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

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

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

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

Gradle 6.7 представил поддержку Java toolchains. Используя эту функцию, вы можете:

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

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

С поддержкой toolchains, Gradle может автоматически обнаруживать локальные JDK и устанавливать недостающие JDK, необходимые для сборки. Теперь сам 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>)) // "8"
    }
    // Or shorter:
    jvmToolchain(<MAJOR_JDK_VERSION>) // "8"
}

kotlin {
    jvmToolchain {
        languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)) // "8"
    }
    // Or shorter:
    jvmToolchain(<MAJOR_JDK_VERSION>) // "8"
}

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

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

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

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

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

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

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

val service = project.extensions.getByType<JavaToolchainService>()
val customLauncher = service.launcherFor {
    it.languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)) // "8"
}
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>)) // "8"
}
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 объектам из функциональных тестов.

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

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

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

Зависимость от стандартной библиотеки (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.6.4")
            }
        }
    }
}

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

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

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

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

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

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

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

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