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:

compileKotlin.compilerOptions.freeCompilerArgs.add("-Xexport-kdoc")

compileKotlin {
    compilerOptions.freeCompilerArgs.add("-Xexport-kdoc")
}

//or

compileKotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xexport-kdoc")
    }
}

When targeting the JVM, the 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.

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

To configure a single task, use its name. Examples:

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.

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

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask<*>>().configureEach {
    compilerOptions { /*...*/ }
}

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask).configureEach {
    compilerOptions { /*...*/ }
}

Here is a complete list of options for Gradle tasks:

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", ..., "19". Also, see Types for compiler options	"1.8"
`noJdk`	Don't automatically include the Java runtime into the classpath		false

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("-opt-in=org.mylibrary.OptInAnnotation")
// List of arguments
compileKotlin.compilerOptions.freeCompilerArgs.addAll(listOf("-Xno-param-assertions", "-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("-opt-in=org.mylibrary.OptInAnnotation")
        // List of arguments
        freeCompilerArgs.addAll(["-Xno-param-assertions", "-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.3" (DEPRECATED), "1.4" (DEPRECATED), "1.5", "1.6", "1.7", "1.8", "1.9"
`languageVersion`	Provide source compatibility with the specified version of Kotlin	"1.4" (DEPRECATED), "1.5", "1.6", "1.7", "1.8", "1.9"

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
`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_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)`

What's next?

Learn more about:

Last modified: 10 January 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

Docs

Docs4dev

Title here