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

Для построения проекта Kotlin с помощью Gradle необходимо применить плагин Kotlin Gradle к проекту и настроить зависимости.

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

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

Плагин Kotlin Gradle версии 1.4.10 работает с Gradle 5.4 и выше. Плагин kotlin-multiplatform требует Gradle 6.0 или выше.

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

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

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

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

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

Плагин kotlin-multiplatform работает с Gradle 6.0 или выше.

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

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

Назначение для JVM

Для назначения для JVM примените плагин Kotlin JVM.

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

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

Значение version должно быть литеральным в этом блоке, и его нельзя применять из другого скрипта сборки.

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

apply plugin: 'kotlin'

Не рекомендуется применять плагины Kotlin с apply в Gradle Kotlin DSL – почему.

Kotlin и Java исходники

Исходники Kotlin можно хранить вместе с исходниками Java в одной папке или в разных. По умолчанию используются разные папки:

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

Соответствующая sourceSets свойство нужно обновить, если не используется соглашение по умолчанию:

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

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

Назначение для JavaScript

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

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

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

Kotlin и Java исходники

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

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

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

Назначение для Android

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

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

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

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

kotlin {
    sourceSets {
        val commonMain by getting {
            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.

Добавьте соответствующие зависимости от библиотек тестов:

• Для commonTest, добавьте зависимости kotlin-test-common и kotlin-test-annotations-common.
• Для целей JVM используйте kotlin-test-junit или kotlin-test-testng для реализации соответствующего утверждения и сопоставления аннотаций.
• Для целей Kotlin/JS добавьте kotlin-test-js как зависимость для тестов.

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

kotlin{
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin('test-common')
                implementation kotlin('test-annotations-common')
            }
        }
        jvmTest {
            dependencies {
                implementation kotlin('test-junit')
            }
        }
        jsTest {
            dependencies {
                implementation kotlin('test-js')
            }
        }
    }
}

kotlin{
    sourceSets {
        val commonTest by getting {
            dependencies {
                implementation(kotlin("test-common"))
                implementation(kotlin("test-annotations-common"))
            }
        }
        val jvmTest by getting {
            dependencies {
                implementation(kotlin("test-junit"))
            }
        }
        val jsTest by getting {
            dependencies {
                implementation(kotlin("test-js"))
            }
        }
    }
}

Вы можете использовать сокращения для зависимости от модуля Kotlin, например, kotlin("test") для "org.jetbrains.kotlin:kotlin-test".

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

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

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

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

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

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

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

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

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

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

• Добавьте следующую строку в файл gradle.properties или local.properties:
  • kotlin.incremental=<value> для Kotlin/JVM
  • kotlin.incremental.js=<value> для проектов Kotlin/JS.
    <value> — это булевое значение, отражающее использование инкрементной компиляции.
• В качестве параметра командной строки используйте -Pkotlin.incremental или -Pkotlin.incremental.js с булевым значением, отражающим использование инкрементной компиляции.
  Обратите внимание, что в этом случае параметр должен добавляться к каждой последующей сборке, и любая сборка с отключенной инкрементной компиляцией делает недействительными кэши инкрементной компиляции.

Обратите внимание, что первая сборка в любом случае не является инкрементной.

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

Плагин Kotlin поддерживает кэш сборки Gradle.

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

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

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

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

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

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

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

Для настройки отдельной задачи используйте её имя. Примеры:

compileKotlin {
    kotlinOptions.suppressWarnings = true
}

//or

compileKotlin {
    kotlinOptions {
        suppressWarnings = true
    }
}

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

val compileKotlin: KotlinCompile by tasks

compileKotlin.kotlinOptions.suppressWarnings = true

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

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

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

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

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

tasks.withType<KotlinCompile>().configureEach {
    kotlinOptions.suppressWarnings = true
}

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

Атрибуты, общие для JVM, JS и JS DCE

Атрибуты, общие для JVM и JS

Атрибуты, специфичные для JVM

Атрибуты, специфичные для JS

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

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

OSGi

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

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

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