API средств сборки

В Kotlin есть API средств сборки (BTA), который упрощает интеграцию систем сборки с компилятором Kotlin.

Добавление полной поддержки Kotlin в систему сборки (например, инкрементальной компиляции, плагинов компилятора Kotlin, демонов и Kotlin Multiplatform) требует значительных усилий. BTA призван упростить эту задачу, предоставляя единый API для систем сборки и экосистемы компилятора Kotlin.

BTA определяет единую точку входа, которую могут реализовать системы сборки. Это избавляет от необходимости глубоко интегрироваться с внутренними особенностями компилятора.

Уровень стабильности различается в зависимости от целевой платформы: BTA имеет статус Beta для Kotlin/JVM и Alpha для Kotlin/JS и Kotlin/Wasm. Подробнее см. в разделе API средств сборки (BTA). Для использования BTA требуется opt-in с помощью @OptIn(ExperimentalBuildToolsApi::class).

Интеграция с Gradle

Плагин Kotlin Gradle (KGP) по умолчанию использует BTA для компиляции Kotlin/JVM.

Включение BTA для Kotlin/JS, Kotlin/Wasm и метаданных Kotlin

Начиная с Kotlin 2.4.20, KGP также может выполнять компиляцию Kotlin/JS, Kotlin/Wasm и метаданных Kotlin через BTA. Благодаря этому взаимодействие KGP с компилятором становится более последовательным, а в некоторых случаях компиляция выполняется быстрее и стабильнее.

В Kotlin 2.4.20 эти целевые платформы доступны в качестве opt-in. Чтобы попробовать их, добавьте соответствующие свойства в файл gradle.properties:

kotlin.js.runViaBuildToolsApi = true
kotlin.wasm.runViaBuildToolsApi = true
kotlin.metadata.runViaBuildToolsApi = true

Настройка разных версий компилятора

С помощью BTA теперь можно использовать версию компилятора Kotlin, отличную от версии, используемой KGP. Это полезно в следующих случаях:

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

Пример настройки в файле build.gradle.kts:

import org.jetbrains.kotlin.buildtools.api.ExperimentalBuildToolsApi
import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi

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

group = "org.jetbrains.example"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

kotlin {
    jvmToolchain(8)
    @OptIn(ExperimentalBuildToolsApi::class, ExperimentalKotlinGradlePluginApi::class)
    compilerVersion.set("2.3.21") // <-- different version than 2.4.20
}

Совместимые версии компилятора Kotlin и KGP

BTA поддерживает:

Три предыдущие основные версии компилятора Kotlin.
Одну следующую основную версию.

Например, в KGP 2.2.0 поддерживаются следующие версии компилятора Kotlin:

1.9.25
2.0.x
2.1.x
2.2.x
2.3.x

Ограничения

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

Включение инкрементальной компиляции со стратегией «in process»

KGP поддерживает три стратегии выполнения компилятора. Обычно стратегия «in-process» (при которой компилятор запускается в демоне Gradle) не поддерживает инкрементальную компиляцию.

С помощью BTA стратегия «in-process» теперь поддерживает инкрементальную компиляцию. Чтобы включить её, добавьте следующее свойство в файл gradle.properties:

kotlin.compiler.execution.strategy=in-process

Интеграция с Maven

BTA позволяет kotlin-maven-plugin поддерживать демон Kotlin, который является используемой по умолчанию стратегией выполнения компилятора. kotlin-maven-plugin по умолчанию использует BTA, поэтому настраивать ничего не нужно.

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

25 августа 2026 г.

© 2010–2026 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/build-tools-api.html