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

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

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

В Kotlin/JVM инкрементальная компиляция опирается на снимки пути к классам, которые фиксируют структуру API модулей и позволяют определить, когда требуется повторная компиляция. Для оптимизации всего конвейера компилятор Kotlin использует два типа снимков пути к классам:

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

• Укрупнённые снимки: содержат только хэш ABI класса. Если часть ABI изменяется, компилятор Kotlin повторно компилирует все классы, зависящие от изменённого класса. Это полезно для классов, которые меняются редко, например для внешних библиотек.

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

• Установите 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).

Поддержка кэша конфигурации 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 -Xms500m -XX:MaxMetaspaceSize=1g

-Xmx1500m -XX:ReservedCodeCacheSize=320m -XX:MaxMetaspaceSize=1g -XX:UseParallelGC -ea -XX:+UseCodeCacheFlushing -XX:+HeapDumpOnOutOfMemoryError -Djava.awt.headless=true -Djava.rmi.server.hostname=127.0.0.1 --add-exports=java.base/sun.nio.ch=ALL-UNNAMED

org.gradle.jvmargs=-Dkotlin.daemon.jvm.options=-Xmx1500m,Xms500m

kotlin.daemon.jvmargs=-Xmx1500m -Xms500m

-Xmx1500m -XX:ReservedCodeCacheSize=320m -Xms500m

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).configureEach { task ->
    task.kotlinDaemonJvmArguments = ["-Xmx1g", "-Xms512m"]
}

Возврат к предыдущему компилятору

Начиная с Kotlin 2.0.0 по умолчанию используется компилятор K2.

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

• В файле build.gradle.kts задайте версию языка 1.9.

  ИЛИ

• Используйте следующий параметр компилятора: -language-version 1.9.

Подробнее о преимуществах компилятора K2 см. в руководстве по переходу на компилятор K2.

Использование последней версии языка

Начиная с Kotlin 2.0.0, чтобы попробовать последнюю версию языка, задайте свойство kotlin.experimental.tryNext в файле gradle.properties. При использовании этого свойства плагин Kotlin для Gradle увеличивает версию языка на единицу относительно значения по умолчанию для вашей версии Kotlin. Например, в Kotlin 2.0.0 версия языка по умолчанию — 2.0, поэтому это свойство задаёт версию языка 2.1.

Также можно выполнить следующую команду:

./gradlew assemble -Pkotlin.experimental.tryNext=true

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

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

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

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

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

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

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

В отчётах о сборке также отображается версия Kotlin, используемая в проекте. Кроме того, начиная с Kotlin 1.9.0, можно посмотреть, какой компилятор использовался для компиляции кода, в сканированиях сборки Gradle.

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

kotlin.build.report.output=file

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

# 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=my/directory/path/some_filename

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

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

# Mandatory. 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. Add a Git branch name of a build to a build report
kotlin.build.report.http.include_git_branch.name=true|false

# Optional. Add compiler arguments to a build report
# If a project contains many modules, its compiler arguments in the report can be very heavy and not that helpful
kotlin.build.report.include_compiler_arguments=true|false

Maximum number of custom values (1,000) exceeded

kotlin.build.report.build_scan.custom_values_limit=500

Что дальше?

Подробнее:

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

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

• Стратегия выполнения компилятора