Compiler options in the Kotlin Gradle plugin | Kotlin (original) (raw)

Each release of Kotlin includes compilers for the supported targets: JVM, JavaScript, and native binaries for supported platforms.

These compilers are used by:

• The IDE, when you click the Compile or Run button for your Kotlin project.
• Gradle, when you call gradle build in a console or in the IDE.
• Maven, when you call mvn compile or mvn test-compile in a console or in the IDE.

You can also run Kotlin compilers manually from the command line as described in the Working with command-line compiler tutorial.

How to define options

Kotlin compilers have a number of options for tailoring the compiling process.

The Gradle DSL allows comprehensive configuration of compiler options. It is available for Kotlin Multiplatform and JVM/Android projects.

With the Gradle DSL, you can configure compiler options within the build script at three levels:

• Extension level, in the kotlin {} block for all targets and shared source sets.
• Target level, in the block for a specific target.
• Compilation unit level, usually in a specific compilation task.

The settings at a higher level are used as a convention (default) for a lower level:

• Compiler options set at the extension level are the default for target-level options, including shared source sets like commonMain, nativeMain, and commonTest.
• Compiler options set at the target level are the default for options at the compilation unit (task) level, like compileKotlinJvm and compileTestKotlinJvm tasks.

In turn, configurations made at a lower level override related settings at a higher level:

• Task-level compiler options override related configurations at the target or the extension level.
• Target-level compiler options override related configurations at the extension level.

To find out which level of compiler arguments is applied to the compilation, use the DEBUG level of Gradle logging. For JVM and JS/WASM tasks, search for the "Kotlin compiler args:" string within the logs; for Native tasks, search for the "Arguments =" string.

Extension level

You can configure common compiler options for all the targets and shared source sets in the compilerOptions {} block at the top level:

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

Target level

You can configure compiler options for the JVM/Android target in the compilerOptions {} block inside the target {} block:

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

In Kotlin Multiplatform projects, you can configure compiler options inside the specific target. For example, jvm { compilerOptions {}}. For more information, see Multiplatform Gradle DSL reference.

Compilation unit level

You can configure compiler options for a specific compilation unit or task in a compilerOptions {} block inside the task configuration:

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

You can also access and configure compiler options at a compilation unit level via KotlinCompilation:

kotlin { target { val main by compilations.getting { compileTaskProvider.configure { compilerOptions { } } } } }

If you want to configure a plugin of a target different from JVM/Android and Kotlin Multiplatform, use the compilerOptions {} property of the corresponding Kotlin compilation task. The following examples show how to set this configuration up in both Kotlin and Groovy DSLs:

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) } }

Target the JVM

As explained before, you can define compiler options for your JVM/Android projects at the extension, target, and compilation unit levels (tasks).

Default JVM compilation tasks are called compileKotlin for production code and compileTestKotlin for test code. The tasks for custom source sets are named according to their compile<Name>Kotlin patterns.

You can see the list of Android compilation tasks by running the gradlew tasks --all command in the terminal and searching for compile*Kotlin task names in the Other tasks group.

Some important details to be aware of:

• The android.kotlinOptions and kotlin.compilerOptions configuration blocks override each other. The last (lowest) block takes effect.
• kotlin.compilerOptions configures every Kotlin compilation task in the project.
• You can override the configuration applied by kotlin.compilerOptions DSL using the tasks.named<KotlinJvmCompile>("compileKotlin") { } (or tasks.withType<KotlinJvmCompile>().configureEach { }) approach.

Target JavaScript

JavaScript compilation tasks are called compileKotlinJs for production code, compileTestKotlinJs for test code, and compile<Name>KotlinJs for custom source sets.

To configure a single task, use its name:

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 } }

Note that with the Gradle Kotlin DSL, you should get the task from the project's tasks first.

Use the Kotlin2JsCompile and KotlinCompileCommon types for JS and common targets, respectively.

You can see the list of JavaScript compilation tasks by running the gradlew tasks --all command in the terminal and searching for compile*KotlinJS task names in the Other tasks group.

All Kotlin compilation tasks

It is also possible to configure all the Kotlin compilation tasks in the project:

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 { /*...*/ } }

All compiler options

Here is a complete list of options for the Gradle compiler:

Common attributes

Attributes specific to JVM

Attributes common to JVM and JavaScript

Example of additional arguments usage via freeCompilerArgs

Use the freeCompilerArgs attribute to supply additional (including experimental) compiler arguments. You can add a single argument to this attribute or a list of arguments:

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_1) 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_1 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"]) } }

Example of setting languageVersion

To set a language version, use the following syntax:

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

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

Also, see Types for compiler options.

Attributes specific to JavaScript

Types for compiler options

Some of the compilerOptions use the new types instead of the String type:

What's next?

Learn more about:

• Kotlin Multiplatform DSL reference.
• Incremental compilation, caches support, build reports, and the Kotlin daemon.
• Gradle basics and specifics.
• Support for Gradle plugin variants.

Last modified: 03 April 2025