Gradle

Применение плагина

Для применения плагина Kotlin Gradle используйте блок plugins из DSL плагинов Gradle:

// replace `<...>` with the plugin name 
plugins {
    kotlin("<...>") version "1.7.20"
}

// replace `<...>` with the plugin name
plugins {
    id 'org.jetbrains.kotlin.<...>' version '1.7.20'
}

При настройке проекта проверьте совместимость плагина Kotlin Gradle с доступными версиями Gradle:

Например, плагин Kotlin Gradle и плагин kotlin-multiplatform 1.7.20 требуют минимальной версии Gradle 6.7.1 для компиляции вашего проекта.

В свою очередь, максимальная полностью поддерживаемая версия — 7.1.1. Она не содержит устаревших методов и свойств Gradle и поддерживает все текущие функции Gradle.

Настройка для нескольких платформ

Проекты, нацеленные на несколько платформ, называемые проектами для нескольких платформ, требуют плагин kotlin-multiplatform. Узнайте больше о плагине.

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

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

Настройка для JVM

Для настройки работы с JVM используйте плагин Kotlin JVM.

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

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

Этот version блок должен быть литеральным и не может быть применён из другого скрипта сборки.

В качестве альтернативы, можно использовать более старый подход apply plugin:

apply plugin: 'kotlin'

Применение плагинов Kotlin с apply в Kotlin Gradle DSL не рекомендуется – подробнее.

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

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

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

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

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

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

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

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

Нацеливание на JavaScript

При нацеливании только на JavaScript используйте плагин kotlin-js. Узнать больше

plugins {
    kotlin("js") version "1.7.20"
}

plugins {
    id 'org.jetbrains.kotlin.js' version '1.7.20'
}

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

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

Нацеливание на Android

Рекомендуется использовать Android Studio для создания приложений для Android. Узнайте, как использовать плагин Android Gradle.

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

Для добавления зависимости от библиотеки установите зависимость требуемого типа (например, implementation) в блоке dependencies DSL-файла наборов исходных кодов.

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

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

В качестве альтернативы можно указать зависимости на верхнем уровне.

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

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

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

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

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

kotlin.stdlib.default.dependency=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'
}

Обработка аннотаций

Kotlin поддерживает обработку аннотаций с помощью инструмента для обработки аннотаций Kotlin kapt.

Инкрементальная компиляция

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

Инкрементальная компиляция поддерживается для проектов Kotlin/JVM и Kotlin/JS и включена по умолчанию.

Существует несколько способов отключить инкрементальную компиляцию:

• kotlin.incremental=false для Kotlin/JVM.

• kotlin.incremental.js=false для проектов Kotlin/JS.

• Используйте -Pkotlin.incremental=false или -Pkotlin.incremental.js=false в качестве параметра командной строки.

  Параметр должен быть добавлен в каждую последующую сборку, и любая сборка с отключённой инкрементальной компиляцией аннулирует кеши инкрементальной компиляции.

Первая сборка никогда не является инкрементальной.

kotlin.incremental.useClasspathSnapshot=true

Поддержка кеша сборки Gradle

Плагин Kotlin использует кеш сборки Gradle, который хранит выходные данные сборки для повторного использования в будущих сборках.

Чтобы отключить кеширование для всех задач Kotlin, установите системную переменную kotlin.caching.enabled в значение false (запустите сборку с аргументом -Dkotlin.caching.enabled=false).

Если вы используете kapt, обратите внимание, что задачи обработки аннотаций kapt по умолчанию не кэшируются. Однако вы можете включить кеширование для них вручную.

Поддержка кеша конфигурации Gradle

Плагин Kotlin использует кеш конфигурации Gradle, что ускоряет процесс сборки, повторно используя результаты фазы конфигурации.

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

Отчеты о сборке

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

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

Чтобы включить отчеты о сборке, укажите, куда сохранить выходные данные отчёта о сборке в gradle.properties:

kotlin.build.report.output=file

Доступны следующие значения и их комбинации для вывода:

Вот полный список доступных вариантов для kotlin.build.report:

# Required outputs. Any combinations are allowed
kotlin.build.report.output=file,http,build_scan

# Optional. Output directory for file-based reports. Default: build/reports/kotlin-build/
kotlin.build.report.file.output_dir=kotlin-reports

# Mandatory if http output is used. Where to post HTTP(S)-based reports
kotlin.build.report.http.url=http://127.0.0.1:8080

# Optional. User and password if the HTTP endpoint requires authentication
kotlin.build.report.http.user=someUser
kotlin.build.report.http.password=somePassword

# Optional. Label for marking your build report (e.g. debug parameters)
kotlin.build.report.label=some_label

Параметры компилятора

Используйте свойство kotlinOptions задачи компиляции Kotlin для указания дополнительных параметров компиляции.

При компиляции для JVM задачи называются compileKotlin для производственного кода и compileTestKotlin для тестового кода. Задачи для пользовательских наборов исходных кодов называются в соответствии с шаблонами compile<Name>Kotlin.

Имена задач в проектах Android содержат имена вариантов сборки и следуют шаблону compile<BuildVariant>Kotlin, например, compileDebugKotlin или compileReleaseUnitTestKotlin.

При компиляции для JavaScript задачи называются compileKotlinJs для производственного кода и compileTestKotlinJs для тестового кода, и compile<Name>KotlinJs для пользовательских наборов исходных кодов.

Чтобы настроить отдельную задачу, используйте её имя. Примеры:

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
// ...

val compileKotlin: KotlinCompile by tasks

compileKotlin.kotlinOptions.suppressWarnings = true

compileKotlin {
    kotlinOptions.suppressWarnings = true
}

//or

compileKotlin {
    kotlinOptions {
        suppressWarnings = true
    }
}

Обратите внимание, что в Gradle Kotlin DSL вы должны сначала получить задачу из tasks проекта.

Используйте типы Kotlin2JsCompile и KotlinCompileCommon для целей JS и common соответственно.

Также можно настроить все задачи компиляции Kotlin в проекте:

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {
    kotlinOptions { /*...*/ }
}

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
    kotlinOptions { /*...*/ }
}

Вот полный список параметров для задач Gradle:

Генерация документации

Для генерации документации для проектов Kotlin используйте Dokka; пожалуйста, обратитесь к Dokka README для инструкций по конфигурации. Dokka поддерживает проекты на смешанных языках и может генерировать выходные данные в нескольких форматах, включая стандартный Javadoc.

OSGi

Для поддержки OSGi см. страницу Kotlin OSGi.

Использование Gradle Kotlin DSL

При использовании Gradle Kotlin DSL, применяйте плагины Kotlin, используя блок plugins { ... }. Если вы применяете их с помощью apply { plugin(...) }, вы можете столкнуться с неразрешёнными ссылками на расширения, сгенерированные Gradle Kotlin DSL. Чтобы решить эту проблему, вы можете закомментировать ошибочные использования, запустить задачу Gradle kotlinDslAccessorsSnapshot, а затем раскомментировать использования и повторно запустить сборку или повторно импортировать проект в IDE.

Kotlin-демон и его использование с Gradle

Kotlin-демон:

• Работает вместе с демоном Gradle для компиляции проекта.

• Работает отдельно, когда вы компилируете проект с интегрированной системой сборки IntelliJ IDEA.

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

Kotlin-демон использует ту же JDK, что и демон Gradle.

Определение стратегии выполнения компилятора Kotlin

Стратегия выполнения компилятора Kotlin определяет место выполнения компилятора Kotlin и поддерживается ли инкрементная компиляция в каждом случае.

Существует три стратегии выполнения компилятора:

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

• Свойство Gradle kotlin.compiler.execution.strategy.

• Свойство задачи компиляции compilerExecutionStrategy.

• Устаревшее свойство -Dkotlin.compiler.execution.strategy, которое будет удалено в будущих выпусках.

Приоритет свойств следующий:

• Свойство задачи compilerExecutionStrategy имеет приоритет над системным свойством и свойством Gradle kotlin.compiler.execution.strategy.

• Свойство Gradle имеет приоритет над системным свойством.

Доступные значения для свойств kotlin.compiler.execution.strategy (как системных, так и Gradle) следующие:

1. daemon (по умолчанию)

2. in-process

3. out-of-process

Используйте свойство Gradle kotlin.compiler.execution.strategy в gradle.properties:

kotlin.compiler.execution.strategy=out-of-process

Доступные значения для свойства задачи compilerExecutionStrategy следующие:

1. org.jetbrains.kotlin.gradle.tasks.KotlinCompilerExecutionStrategy.DAEMON (по умолчанию)

2. org.jetbrains.kotlin.gradle.tasks.KotlinCompilerExecutionStrategy.IN_PROCESS

3. org.jetbrains.kotlin.gradle.tasks.KotlinCompilerExecutionStrategy.OUT_OF_PROCESS

Используйте свойство задачи compilerExecutionStrategy в ваших скриптах сборки:

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilerExecutionStrategy

// ...

tasks.withType<KotlinCompile>().configureEach {
    compilerExecutionStrategy.set(KotlinCompilerExecutionStrategy.IN_PROCESS)
} 

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilerExecutionStrategy

// ...

tasks.withType(KotlinCompile)
    .configureEach {
         compilerExecutionStrategy.set(KotlinCompilerExecutionStrategy.IN_PROCESS)
    }

Выполнение действий конфигурации с интерфейсом KotlinBasePlugin

Чтобы выполнить какое-либо действие конфигурации всякий раз, когда применяется любой плагин Kotlin Gradle (JVM, JS, Multiplatform, Native и другие), используйте интерфейс KotlinBasePlugin, который унаследован от всех плагинов Kotlin:

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

// ...

project.plugins.withType<KotlinBasePlugin>() {
// Configure your action here
}

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

// ...

project.plugins.withType(KotlinBasePlugin.class) {
// Configure your action here
}