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

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

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

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

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

Как определить параметры

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

Используя скрипт сборки, вы можете указать дополнительные параметры компиляции. Для этого используйте свойство compilerOptions задачи компиляции Kotlin. Например:

tasks.named("compileKotlin", org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask::class.java) {
    compilerOptions {
        freeCompilerArgs.add("-Xexport-kdoc")
    }
}

tasks.named('compileKotlin', org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class) {
    compilerOptions {
        freeCompilerArgs.add("-Xexport-kdoc")
    }
}

Целевое окружение JVM

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

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

Для проектов JVM и Android можно определять параметры с помощью DSL расширения проекта Kotlin:

kotlin {
    compilerOptions {
        apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9)
    }
}

kotlin {
    compilerOptions {
        apiVersion = org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
    }
}

Некоторые важные моменты:

Блоки конфигурации android.kotlinOptions и kotlin.compilerOptions перекрывают друг друга. Действует последний (нижний) блок.
kotlin.compilerOptions настраивает каждую задачу компиляции Kotlin в проекте.
Вы можете переопределить конфигурацию, примененную kotlin.compilerOptions DSL, используя подход 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.set(true)
    }
}

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

Используйте типы Kotlin2JsCompile и KotlinCompileCommon для JavaScript и общих целей соответственно.

Для всех задач компиляции 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`

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

Имя	Описание	Возможные значения	Значение по умолчанию
`javaParameters`	Генерация метаданных для рефлексии Java 1.8 на параметрах метода		false
`jvmTarget`	Целевая версия сгенерированного байткода JVM	"1.8", "9", "10", ..., "19". Также см. Типы параметров компилятора	"1.8"
`noJdk`	Не включать автоматически Java runtime в пути к классам		false
`jvmTargetValidationMode`	Проверка совместимости целевой JVM между Kotlin и Java Свойство для задач типа `KotlinCompile`.	`WARNING`, `ERROR`, `INFO`	`ERROR`

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

Имя	Описание	Значение по умолчанию
`allWarningsAsErrors`	Вывести ошибку, если есть предупреждения	false
`suppressWarnings`	Не генерировать предупреждения	false
`verbose`	Включить подробный вывод логов. Работает только при включенном уровне отладки логов Gradle.	false
`freeCompilerArgs`	Список дополнительных аргументов компилятора. Здесь можно использовать экспериментальные аргументы `-X`. См. пример	[]

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

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

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

val compileKotlin: KotlinCompilationTask<*> by tasks

// Single experimental argument
compileKotlin.compilerOptions.freeCompilerArgs.add("-Xexport-kdoc")
// Single additional argument, can be a key-value pair
compileKotlin.compilerOptions.freeCompilerArgs.add("-Xno-param-assertions")
// List of arguments
compileKotlin.compilerOptions.freeCompilerArgs.addAll(listOf("-Xno-receiver-assertions", "-Xno-call-assertions"))

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

tasks.named('compileKotlin', KotlinCompilationTask) {
    compilerOptions {
        // 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"])
    }
}

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

Имя	Описание	Возможные значения	Значение по умолчанию
`apiVersion`	Ограничить использование деклараций теми, которые из указанной версии связанных библиотек	"1.3" (УСТАРЕЛО), "1.4" (УСТАРЕЛО), "1.5", "1.6", "1.7", "1.8", "1.9" (ЭКСПЕРИМЕНТАЛЬНО)
`languageVersion`	Обеспечить совместимость исходного кода с указанной версией Kotlin	"1.3" (УСТАРЕЛО), "1.4" (УСТАРЕЛО), "1.5", "1.6", "1.7", "1.8", "1.9" (ЭКСПЕРИМЕНТАЛЬНО)

Пример установки языкаVersion

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

tasks
    .withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>()
    .configureEach {
        compilerOptions
            .languageVersion
            .set(
              org.jetbrains.kotlin.gradle.dsl.KotlinVersion.KOTLIN_1_9
            )
    }

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

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

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

Имя	Описание	Возможные значения	Значение по умолчанию
`friendModulesDisabled`	Отключить экспорт внутренних деклараций		false
`main`	Определить, должна ли вызываться функция `main` при выполнении	"call", "noCall". Также см. Типы параметров компилятора	"call"
`metaInfo`	Генерировать файлы .meta.js и .kjsm с метаданными. Используется для создания библиотеки		true
`moduleKind`	Тип JS-модуля, генерируемого компилятором	"umd", "commonjs", "amd", "plain", "es". Также см. Типы параметров компилятора	"umd"
`outputFile`	Целевой *.js файл для результата компиляции		"<buildDir>/js/packages/<project.name>/kotlin/<project.name>.js"
`sourceMap`	Генерировать карту исходных позиций (source map)		true
`sourceMapEmbedSources`	Встраивать исходные файлы в карту исходных позиций	"never", "always", "inlining". Также см. Типы параметров компилятора
`sourceMapNamesPolicy`	Добавлять имена переменных и функций, объявленных в Kotlin-коде, в карту исходных позиций. Подробнее о поведении см. в нашей справке по компилятору.	"simple-names", "fully-qualified-names", "no". Также см. Типы параметров компилятора	"simple-names"
`sourceMapPrefix`	Добавить указанный префикс к путям в карте исходных позиций
`target`	Генерировать JS-файлы для определённой версии ECMA	"v5"	"v5"
`typedArrays`	Преобразовывать примитивные массивы в JS-типизированные массивы		true

END_OF_DOCUMENT_MARKER

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

Некоторые из compilerOptions используют новые типы вместо типа String.

Параметр	Тип	Пример
`jvmTarget`	`JvmTarget`	`compilerOptions.jvmTarget.set(JvmTarget.JVM_11)`
`apiVersion` и `languageVersion`	`KotlinVersion`	`compilerOptions.languageVersion.set(KotlinVersion.KOTLIN_1_9)`
`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)`

Что дальше?

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

Последнее изменение: 14 июля 2023 г.

© 2010–2023 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