Kotlin Help

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

WARNING, ERROR, INFO

ERROR

Attributes common to JVM, JS, and JS DCE

Name

Description

Possible values

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: 27 October 2023