Gradle

Плагин и версии

Примените плагин Kotlin Gradle, используя DSL плагинов Gradle.

Плагин Kotlin Gradle и плагин kotlin-multiplatform 1.6.20 требуют Gradle версии 6.1 или выше.

plugins {
  kotlin("<...>") version "1.6.20"
}

plugins {
  id 'org.jetbrains.kotlin.<...>' version '1.6.20'
}

Заполнитель <...> следует заменить именем одного из плагинов, которые будут рассмотрены в последующих разделах.

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

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

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

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

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

Для работы с JVM примените плагин Kotlin JVM.

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

plugins {
    id "org.jetbrains.kotlin.jvm" version "1.6.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'
}

kotlin {
    jvmToolchain {
        (this as JavaToolchainSpec).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.6.20"
}

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

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

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

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

Для создания приложений Android рекомендуется использовать Android Studio. Узнайте, как использовать плагин 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.0")
            }
        }
    }
}

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

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

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

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

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

В качестве альтернативы, вы можете указать зависимости на верхнем уровне, используя следующую схему для имён конфигураций: <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 в качестве параметра командной строки.

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

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

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

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

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

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

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

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

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

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

Используйте свойство 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. ouf-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)
    }