Компиляция и кэши в плагине Kotlin Gradle

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

Плагин 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 и его использование с Gradle

Демон Kotlin:

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

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

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

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

org.gradle.jvmargs=-Xmx1500m -Xms=500m

org.gradle.jvmargs=-Dkotlin.daemon.jvm.options=-Xmx1500m,Xms=500m

kotlin.daemon.jvmargs=-Xmx1500m -Xms=500m

kotlin {
    kotlinDaemonJvmArgs = listOf("-Xmx486m", "-Xms256m", "-XX:+UseParallelGC")
}

kotlin {
    kotlinDaemonJvmArgs = ["-Xmx486m", "-Xms256m", "-XX:+UseParallelGC"]
}

tasks.withType<CompileUsingKotlinDaemon>().configureEach {
    kotlinDaemonJvmArguments.set(listOf("-Xmx486m", "-Xms256m", "-XX:+UseParallelGC"))
}

tasks.withType(CompileUsingKotlinDaemon::class).configureEach { task ->
    task.kotlinDaemonJvmArguments.set(["-Xmx1g", "-Xms512m"])
}

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

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

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

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

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

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

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

Доступные значения для свойства kotlin.compiler.execution.strategy:

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.CompileUsingKotlinDaemon
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilerExecutionStrategy

// ...

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

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

// ...

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

Стратегия резервного копирования компилятора Kotlin

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

Когда происходит эта резервная стратегия, в выходных данных сборки Gradle отображаются следующие предупреждающие строки:

Failed to compile with Kotlin daemon: java.lang.RuntimeException: Could not connect to Kotlin compile daemon
[exception stacktrace]
Using fallback strategy: Compile without Kotlin daemon
Try ./gradlew --stop if this issue persists.

Однако, пассивное переключение на другую стратегию может потреблять много системных ресурсов или приводить к непредсказуемым сборкам. Подробнее об этом можно прочитать в этом вопросе на YouTrack. Чтобы этого избежать, существует свойство Gradle kotlin.daemon.useFallbackStrategy, значение которого по умолчанию true. Когда значение равно false, сборки завершаются ошибкой при проблемах с запуском или взаимодействием демона. Объявите это свойство в gradle.properties:

kotlin.daemon.useFallbackStrategy=false

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

tasks {
    compileKotlin {
        useDaemonFallbackStrategy.set(false)
    }   
}

tasks.named("compileKotlin").configure {
    useDaemonFallbackStrategy = false
}

Если памяти недостаточно для выполнения компиляции, в логах отобразится сообщение об этом.

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

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

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

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

Существует две распространённые ситуации, при решении которых анализ отчётов о сборке для длительных компиляций может быть полезен:

• Сборка не была инкрементальной. Проанализируйте причины и исправьте лежащие в основе проблемы.

• Сборка была инкрементальной, но заняла слишком много времени. Попробуйте переорганизовать исходные файлы — разделить большие файлы, сохранить отдельные классы в разных файлах, переработать большие классы, объявить функции верхнего уровня в разных файлах и так далее.

Узнайте как читать отчёты о сборке и как JetBrains использует отчёты о сборке.

kotlin.build.report.output=file

# Required outputs. Any combination is allowed
kotlin.build.report.output=file,single_file,http,build_scan

# Mandatory if single_file output is used. Where to put reports 
# Use instead of the deprecated `kotlin.internal.single.build.metrics.file` property
kotlin.build.report.single_file=some_filename

# 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 (for example, debug parameters)
kotlin.build.report.label=some_label

Maximum number of custom values (1,000) exceeded

kotlin.build.report.build_scan.custom_values_limit=500

Что дальше?

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

• Основы и особенности Gradle.

• Поддержка вариантов плагинов Gradle.