Compiler options in the Kotlin Gradle plugin

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.

Using a build script, you can specify additional compilation options. Use the compilerOptions property of a Kotlin compilation task for it. For example:

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

Target the JVM

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.

The names of the tasks in Android Projects contain build variant names and follow the compile<BuildVariant>Kotlin pattern, for example, compileDebugKotlin or compileReleaseUnitTestKotlin.

For both the JVM and Android projects, it's possible to define options using the project Kotlin extension DSL:

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

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

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.set(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.

For all Kotlin compilation tasks

It is also possible to configure all of 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 Gradle tasks:

Common attributes

Name	Description	Possible values	Default value
`optIn`	A property for configuring a list of opt-in compiler arguments	`listOf( /* opt-ins */ )`	`emptyList()`
`progressiveMode`	Enables the progressive compiler mode	`true`, `false`	`false`

Attributes specific to JVM

Name	Description	Possible values	Default value
`javaParameters`	Generate metadata for Java 1.8 reflection on method parameters		false
`jvmTarget`	Target version of the generated JVM bytecode	"1.8", "9", "10", ..., "20", "21". Also, see Types for compiler options	"1.8"
`noJdk`	Don't automatically include the Java runtime into the classpath		false
`jvmTargetValidationMode`	Validation of the JVM target compatibility between Kotlin and Java A property for tasks of the `KotlinCompile` type.	`WARNING`, `ERROR`, `INFO`	`ERROR`

Attributes common to JVM, JS, and JS DCE

Name	Description	Default value
`allWarningsAsErrors`	Report an error if there are any warnings	false
`suppressWarnings`	Don't generate warnings	false
`verbose`	Enable verbose logging output. Works only when the Gradle debug log level enabled	false
`freeCompilerArgs`	A list of additional compiler arguments. You can use experimental `-X` arguments here too. See an example	[]

Example of additional arguments usage via freeCompilerArgs

Use the attribute freeCompilerArgs 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
// ...

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

Attributes common to JVM and JS

Name	Description	Possible values	Default value
`apiVersion`	Restrict the use of declarations to those from the specified version of bundled libraries	"1.4" (DEPRECATED), "1.5" (DEPRECATED), "1.6", "1.7", "1.8", "1.9", "2.0" (EXPERIMENTAL), "2.1" (EXPERIMENTAL)
`languageVersion`	Provide source compatibility with the specified version of Kotlin	"1.4" (DEPRECATED), "1.5" (DEPRECATED), "1.6", "1.7", "1.8", "1.9", "2.0" (EXPERIMENTAL), "2.1" (EXPERIMENTAL)

Example of setting a languageVersion

To set a language version, use the following syntax:

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

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

Also, see Types for compiler options.

Attributes specific to JS

Name	Description	Possible values	Default value
`friendModulesDisabled`	Disable internal declaration export		false
`main`	Define whether the `main` function should be called upon execution	"call", "noCall". Also, see Types for compiler options	"call"
`metaInfo`	Generate .meta.js and .kjsm files with metadata. Use to create a library		true
`moduleKind`	The kind of JS module generated by the compiler	"umd", "commonjs", "amd", "plain", "es". Also, see Types for compiler options	"umd"
`outputFile`	Destination *.js file for the compilation result		"<buildDir>/js/packages/<project.name>/kotlin/<project.name>.js"
`sourceMap`	Generate source map		true
`sourceMapEmbedSources`	Embed source files into the source map	"never", "always", "inlining". Also, see Types for compiler options
`sourceMapNamesPolicy`	Add variable and function names that you declared in Kotlin code into the source map. For more information on the behavior, see our compiler reference.	"simple-names", "fully-qualified-names", "no". Also, see Types for compiler options	"simple-names"
`sourceMapPrefix`	Add the specified prefix to paths in the source map
`target`	Generate JS files for specific ECMA version	"v5"	"v5"
`typedArrays`	Translate primitive arrays to JS typed arrays		true

Types for compiler options

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

Option	Type	Example
`jvmTarget`	`JvmTarget`	`compilerOptions.jvmTarget.set(JvmTarget.JVM_11)`
`apiVersion` and `languageVersion`	`KotlinVersion`	`compilerOptions.languageVersion.set(KotlinVersion.KOTLIN_2_0)`
`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)`

What's next?

Learn more about:

Last modified: 15 April 2024