Параметры компилятора в плагине Kotlin Gradle

Каждый выпуск Kotlin включает компиляторы для поддерживаемых целевых платформ: JVM, JavaScript и нативных двоичных файлов для поддерживаемых платформ.

Эти компиляторы используются:

IDE, когда вы нажимаете кнопку Компилировать или Запустить для проекта Kotlin.
Gradle, когда вы вызываете gradle build в консоли или IDE.
Maven, когда вы вызываете mvn compile или mvn test-compile в консоли или IDE.

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

Как задавать параметры

Компиляторы Kotlin предоставляют ряд параметров для настройки процесса компиляции.

DSL Gradle позволяет гибко настраивать параметры компилятора. Он доступен для проектов Kotlin Multiplatform и JVM/Android.

С помощью DSL Gradle можно настраивать параметры компилятора в скрипте сборки на трёх уровнях:

Уровень расширения — в блоке kotlin {} для всех целевых платформ и общих наборов исходного кода.
Уровень целевой платформы — в блоке для определённой целевой платформы.
Уровень единицы компиляции — обычно в определённой задаче компиляции.

Параметры, заданные на более высоком уровне, используются как соглашение (значение по умолчанию) для более низкого уровня:

Параметры компилятора, заданные на уровне расширения, используются по умолчанию для параметров уровня целевой платформы, включая общие наборы исходного кода, такие как commonMain, nativeMain и commonTest.
Параметры компилятора, заданные на уровне целевой платформы, используются по умолчанию для параметров на уровне единицы компиляции (задачи), например для задач compileKotlinJvm и compileTestKotlinJvm.

В свою очередь, конфигурации, заданные на более низком уровне, переопределяют соответствующие настройки более высокого уровня:

Параметры компилятора на уровне задачи переопределяют соответствующие конфигурации на уровне целевой платформы или расширения.
Параметры компилятора на уровне целевой платформы переопределяют соответствующие конфигурации на уровне расширения.

Чтобы узнать, какой уровень аргументов компилятора применяется при компиляции, используйте уровень DEBUG ведения журнала Gradle. См. раздел ведения журнала. Для задач JVM и JS/WASM ищите в журналах строку "Kotlin compiler args:"; для задач Native — строку "Arguments =".

Уровень расширения

Общие параметры компилятора для всех целевых платформ и общих наборов исходного кода можно настроить в блоке compilerOptions {} на верхнем уровне:

kotlin {
    compilerOptions {
        optIn.add("kotlin.RequiresOptIn")
    }
}

Уровень целевой платформы

Параметры компилятора для целевой платформы JVM/Android можно настроить в блоке compilerOptions {} внутри блока target {}:

kotlin {
    target {
        compilerOptions {
            optIn.add("kotlin.RequiresOptIn")
        }
    }
}

В проектах Kotlin Multiplatform можно настроить параметры компилятора внутри определённой целевой платформы. Например, jvm { compilerOptions {}}. Дополнительную информацию см. в справочнике по DSL Gradle для Multiplatform.

Уровень единицы компиляции

Параметры компилятора для определённой единицы компиляции или задачи можно настроить в блоке compilerOptions {} внутри конфигурации задачи:

tasks.named<KotlinJvmCompile>("compileKotlin"){
    compilerOptions {
        optIn.add("kotlin.RequiresOptIn")
    }
}

Вы также можете получать доступ к параметрам компилятора и настраивать их на уровне единицы компиляции с помощью KotlinCompilation:

kotlin {
    target {
        val main by compilations.getting {
            compileTaskProvider.configure {
                compilerOptions {
                    optIn.add("kotlin.RequiresOptIn")
                }
            }
        }
    }
}

Чтобы настроить плагин для целевой платформы, отличной от JVM/Android и Kotlin Multiplatform, используйте свойство compilerOptions {} соответствующей задачи компиляции Kotlin. В следующих примерах показана настройка в DSL Kotlin и Groovy:

tasks.named("compileKotlin", org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask::class.java) {
    compilerOptions {
        apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
    }
}

tasks.named('compileKotlin', org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class) {
    compilerOptions {
        apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_0)
    }
}

Переход с `kotlinOptions {}` на `compilerOptions {}`

До Kotlin 2.2.0 параметры компилятора можно было настраивать с помощью блока kotlinOptions {}. Поскольку блок kotlinOptions {} устарел начиная с Kotlin 2.0.0, в этом разделе приведены рекомендации по переносу скриптов сборки на использование блока compilerOptions {}:

Централизуйте параметры компилятора и используйте типы
Перейдите с android.kotlinOptions
Перейдите с freeCompilerArgs

Централизуйте параметры компилятора и используйте типы

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

В блоке compilerOptions {} нельзя использовать строки без указания типа, поэтому преобразуйте их в типизированные значения. Например, если у вас есть:

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

tasks.withType<KotlinCompile>().configureEach {
    kotlinOptions {
        jvmTarget = "17"
        languageVersion = "2.4"
        apiVersion = "2.4"
    }
}

plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.4.20'
}

tasks.withType(KotlinCompile).configureEach {
    kotlinOptions {
        jvmTarget = '17'
        languageVersion = '2.4'
        apiVersion = '2.4'
    }
}

После переноса код должен выглядеть так:

import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.dsl.KotlinVersion

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

kotlin {
    // Extension level
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
        languageVersion = KotlinVersion.fromVersion("2.4")
        apiVersion = KotlinVersion.fromVersion("2.4")
    }
}

// Example of overriding at compilation unit level
tasks.named<KotlinJvmCompile>("compileKotlin"){
    compilerOptions {
        apiVersion = KotlinVersion.fromVersion("2.4")
    }
}

import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.dsl.KotlinVersion

plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.4.20'
}

kotlin {
  // Extension level
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
        languageVersion = KotlinVersion.fromVersion("2.4")
        apiVersion = KotlinVersion.fromVersion("2.4")
    }
}

// Example of overriding at compilation unit level
tasks.named("compileKotlin", KotlinJvmCompile).configure {
    compilerOptions {
        apiVersion = KotlinVersion.fromVersion("2.4")
    }
}

Перейдите с `android.kotlinOptions`

Если в скрипте сборки ранее использовался android.kotlinOptions, замените его на kotlin.compilerOptions. Настройку можно задать на уровне расширения или целевой платформы.

Например, если у вас есть проект Android:

plugins {
    id("com.android.application")
    kotlin("android")
}

android {
    kotlinOptions {
        jvmTarget = "17"
    }
}

plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
}

android {
    kotlinOptions {
        jvmTarget = '17'
    }
}

Замените его на:

plugins {
    id("com.android.application")
    kotlin("android")
}

kotlin {
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
    }
}

plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
}

kotlin {
    compilerOptions {
        jvmTarget = JvmTarget.fromTarget("17")
    }
}

А если у вас есть проект Kotlin Multiplatform с целевой платформой Android:

plugins {
    kotlin("multiplatform")
    id("com.android.application")
}

kotlin {
    androidTarget {
        compilations.all {
            kotlinOptions.jvmTarget = "17"
        }
    }
}

plugins {
    id 'org.jetbrains.kotlin.multiplatform'
    id 'com.android.application'
}

kotlin {
    androidTarget {
        compilations.all {
            kotlinOptions {
                jvmTarget = '17'
            }
        }
    }
}

Замените его на:

plugins {
    kotlin("multiplatform")
    id("com.android.application")
}

kotlin {
    androidTarget {
        compilerOptions {
            jvmTarget = JvmTarget.fromTarget("17")
        }
    }
}

plugins {
    id 'org.jetbrains.kotlin.multiplatform'
    id 'com.android.application'
}

kotlin {
    androidTarget {
        compilerOptions {
            jvmTarget = JvmTarget.fromTarget("17")
        }
    }
}

Перейдите с `freeCompilerArgs`

Замените все операции += на функции add() или addAll().
Если вы используете параметр компилятора -opt-in, проверьте, доступен ли для него специализированный DSL в справочнике по API KGP, и используйте его.
Переведите все случаи использования параметра компилятора -progressive на специализированный DSL: progressiveMode.set(true).

Переведите все случаи использования параметра компилятора -Xjvm-default на специализированный DSL: jvmDefault.set(). Для параметров используйте следующее соответствие:

До	После
`-Xjvm-default=all-compatibility`	`jvmDefault.set(JvmDefaultMode.ENABLE)`
`-Xjvm-default=all`	`jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)`
`-Xjvm-default=disable`	`jvmDefault.set(JvmDefaultMode.DISABLE)`

Например, если у вас есть:

kotlinOptions {
    freeCompilerArgs += "-opt-in=kotlin.RequiresOptIn"
    freeCompilerArgs += listOf("-Xcontext-receivers", "-Xinline-classes", "-progressive", "-Xjvm-default=all")
}

kotlinOptions {
    freeCompilerArgs += "-opt-in=kotlin.RequiresOptIn"
    freeCompilerArgs += ["-Xcontext-receivers", "-Xinline-classes", "-progressive", "-Xjvm-default=all"]
}

Перейдите на:

kotlin {
    compilerOptions {
        optIn.add("kotlin.RequiresOptIn")
        freeCompilerArgs.addAll(listOf("-Xcontext-receivers", "-Xinline-classes"))
        progressiveMode.set(true)
        jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)
    }
}

kotlin {
    compilerOptions {
        optIn.add("kotlin.RequiresOptIn")
        freeCompilerArgs.addAll(["-Xcontext-receivers", "-Xinline-classes"])
        progressiveMode.set(true)
        jvmDefault.set(JvmDefaultMode.NO_COMPATIBILITY)
    }
}

Целевая платформа JVM

Как упоминалось выше, параметры компилятора для проектов JVM/Android можно задавать на уровне расширения, целевой платформы и единицы компиляции (задачи).

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

Список задач компиляции Android можно просмотреть, выполнив в терминале команду gradlew tasks --all и выполнив поиск задач с именами compile*Kotlin в группе Other tasks.

Обратите внимание на следующие важные детали:

kotlin.compilerOptions настраивает каждую задачу компиляции Kotlin в проекте.
Конфигурацию, применённую DSL kotlin.compilerOptions, можно переопределить с помощью подхода tasks.named<KotlinJvmCompile>("compileKotlin") { } (или tasks.withType<KotlinJvmCompile>().configureEach { }).

Целевая платформа JavaScript

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

Чтобы настроить отдельную задачу, укажите её имя:

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

val compileKotlin: KotlinCompilationTask<*> by tasks

compileKotlin.compilerOptions.suppressWarnings.set(true)

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

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        suppressWarnings = true
    }
}

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

Для целевых платформ JS и common соответственно используйте типы Kotlin2JsCompile и KotlinCompileCommon.

Список задач компиляции JavaScript можно просмотреть, выполнив в терминале команду gradlew tasks --all и выполнив поиск задач с именами compile*KotlinJS в группе Other tasks.

Все задачи компиляции Kotlin

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

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

tasks.named<KotlinCompilationTask<*>>("compileKotlin").configure {
    compilerOptions { /*...*/ }
}

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

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions { /*...*/ }
}

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

Полный список параметров компилятора Gradle:

Общие атрибуты

Название	Описание	Возможные значения	Значение по умолчанию
`optIn`	Свойство для настройки списка аргументов компилятора, требующих явного согласия	`listOf( /* opt-ins */ )`	`emptyList()`
`progressiveMode`	Включает прогрессивный режим компилятора	`true`, `false`	`false`
`extraWarnings`	Включает дополнительные проверки объявлений, выражений и типов компилятором, которые при значении true выводят предупреждения	`true`, `false`	`false`

Атрибуты, относящиеся к JVM

Название	Описание	Возможные значения	Значение по умолчанию
`javaParameters`	Создавать метаданные для рефлексии Java 1.8 по параметрам методов		false
`jvmTarget`	Целевая версия генерируемого байт-кода JVM	"1.8", "9", "10", ..., "25", 26". Также см. раздел Типы параметров компилятора	"1.8"
`noJdk`	Не включать среду выполнения Java в classpath автоматически		false
`jvmTargetValidationMode`	Проверка совместимости целевых версий JVM для Kotlin и Java Свойство для задач типа `KotlinCompile`.	`WARNING`, `ERROR`, `IGNORE`	`ERROR`
`jvmDefault`	Определяет, как функции, объявленные в интерфейсах, компилируются в методы по умолчанию в JVM	`ENABLE`, `NO_COMPATIBILITY`, `DISABLE`	`ENABLE`

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

Название	Описание	Возможные значения	Значение по умолчанию
`allWarningsAsErrors`	Выдавать ошибку, если есть предупреждения		false
`suppressWarnings`	Не выводить предупреждения		false
`verbose`	Включить подробный вывод журналов. Работает только при включенном уровне отладки журнала Gradle		false
`freeCompilerArgs`	Список дополнительных аргументов компилятора. Здесь также можно использовать экспериментальные аргументы `-X`. См. пример		[]
`apiVersion`	Определяет, какие API Kotlin может использовать ваш код. Подробнее см. в разделе `-api-version`.	"2.0", "2.1", "2.2", "2.3", "2.4", "2.5" (ЭКСПЕРИМЕНТАЛЬНЫЙ)
`languageVersion`	Определяет, какие языковые возможности и синтаксические конструкции Kotlin доступны во время компиляции. Подробнее см. в разделе `-language-version`.	"2.0", "2.1", "2.2", "2.3", "2.4", "2.5" (ЭКСПЕРИМЕНТАЛЬНЫЙ)

Пример использования дополнительных аргументов через freeCompilerArgs

Используйте атрибут freeCompilerArgs, чтобы передать дополнительные аргументы компилятора (в том числе экспериментальные). В этот атрибут можно добавить один аргумент или список аргументов:

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

kotlin {
    compilerOptions {
        // Specifies the version of the Kotlin API and the JVM target
        apiVersion.set(KotlinVersion.KOTLIN_2_4)
        jvmTarget.set(JvmTarget.JVM_1_8)
        
        // Single experimental argument
        freeCompilerArgs.add("-Xexport-kdoc")

        // Single additional argument
        freeCompilerArgs.add("-Xno-param-assertions")

        // List of arguments
        freeCompilerArgs.addAll(
            listOf(
                "-Xno-receiver-assertions",
                "-Xno-call-assertions"
            )
        ) 
    }
}

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

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        // Specifies the version of the Kotlin API and the JVM target
        apiVersion = KotlinVersion.KOTLIN_2_4
        jvmTarget = JvmTarget.JVM_1_8
        
        // Single experimental argument
        freeCompilerArgs.add("-Xexport-kdoc")
        
        // Single additional argument, can be a key-value pair
        freeCompilerArgs.add("-Xno-param-assertions")
        
        // List of arguments
        freeCompilerArgs.addAll(["-Xno-receiver-assertions", "-Xno-call-assertions"])
    }
}

Пример задания languageVersion

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

kotlin {
    compilerOptions {
        languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_4)
    }
}

tasks
    .withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class)
    .configureEach {
        compilerOptions.languageVersion =
            org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_2_4
    }

Также см. раздел Типы параметров компилятора.

Атрибуты, относящиеся к JavaScript

Название	Описание	Возможные значения	Значение по умолчанию
`friendModulesDisabled`	Отключить экспорт внутренних объявлений		`false`
`main`	Указывает, следует ли вызывать функцию `main` при выполнении	`JsMainFunctionExecutionMode.CALL`, `JsMainFunctionExecutionMode.NO_CALL`	`JsMainFunctionExecutionMode.CALL`
`moduleKind`	Тип JS-модуля, создаваемого компилятором	`JsModuleKind.MODULE_AMD`, `JsModuleKind.MODULE_PLAIN`, `JsModuleKind.MODULE_ES`, `JsModuleKind.MODULE_COMMONJS`, `JsModuleKind.MODULE_UMD`	`null`
`sourceMap`	Создавать source map		`false`
`sourceMapEmbedSources`	Встраивать исходные файлы в source map	`JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING`, `JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_NEVER`, `JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_ALWAYS`	`null`
`sourceMapNamesPolicy`	Добавлять в source map имена переменных и функций, объявленных в коде Kotlin. Подробнее о поведении см. в справочнике компилятора	`JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES`, `JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_SIMPLE_NAMES`, `JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_NO`	`null`
`sourceMapPrefix`	Добавлять указанный префикс к путям в source map		`null`
`target`	Создавать JS-файлы для указанной версии ECMA	`"es5"`, `"es2015"`	`"es5"`
`useEsClasses`	Разрешить генерируемому коду JavaScript использовать классы ES2015. Включено по умолчанию при использовании цели ES2015		`null`

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

В некоторых параметрах compilerOptions используются новые типы вместо типа String:

Параметр	Тип	Пример
`jvmTarget`	`JvmTarget`	`compilerOptions.jvmTarget.set(JvmTarget.JVM_11)`
`apiVersion` и `languageVersion`	`KotlinVersion`	`compilerOptions.languageVersion.set(KotlinVersion.KOTLIN_2_4)`
`main`	`JsMainFunctionExecutionMode`	`compilerOptions.main.set(JsMainFunctionExecutionMode.NO_CALL)`
`moduleKind`	`JsModuleKind`	`compilerOptions.moduleKind.set(JsModuleKind.MODULE_ES)`
`sourceMapEmbedSources`	`JsSourceMapEmbedMode`	`compilerOptions.sourceMapEmbedSources.set(JsSourceMapEmbedMode.SOURCE_MAP_SOURCE_CONTENT_INLINING)`
`sourceMapNamesPolicy`	`JsSourceMapNamesPolicy`	`compilerOptions.sourceMapNamesPolicy.set(JsSourceMapNamesPolicy.SOURCE_MAP_NAMES_POLICY_FQ_NAMES)`

Что дальше?

Узнайте больше о следующих темах:

13 июля 2026

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