Edit Page

Using Gradle

In order to build Kotlin with Gradle you should set up the kotlin-gradle plugin, apply it to your project and add kotlin-stdlib dependencies. Those actions may also be performed automatically in IntelliJ IDEA by invoking the Tools | Kotlin | Configure Kotlin in Project action.

Plugin and Versions

The kotlin-gradle-plugin compiles Kotlin sources and modules.

The version of Kotlin to use is usually defined as the kotlin_version property:

buildscript {
    ext.kotlin_version = '<version to use>'

    repositories {
        mavenCentral()
    }

    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

This is not required when using Kotlin Gradle plugin 1.1.1 and above with the Gradle plugins DSL.

Targeting the JVM

To target the JVM, the Kotlin plugin needs to be applied:

apply plugin: "kotlin"

Or, starting with Kotlin 1.1.1, the plugin can be applied using the Gradle plugins DSL:

plugins {
    id "org.jetbrains.kotlin.jvm" version "<version to use>"
}

The version should be literal in this block, and it cannot be applied from another build script.

Kotlin sources can be mixed with Java sources in the same folder, or in different folders. The default convention is using different folders:

project
    - src
        - main (root)
            - kotlin
            - java

The corresponding sourceSets property should be updated if not using the default convention

sourceSets {
    main.kotlin.srcDirs += 'src/main/myKotlin'
    main.java.srcDirs += 'src/main/myJava'
}

Targeting JavaScript

When targeting JavaScript, a different plugin should be applied:

apply plugin: "kotlin2js"

This plugin only works for Kotlin files so it is recommended to keep Kotlin and Java files separate (if it's the case that the same project contains Java files). As with targeting the JVM, if not using the default convention, we need to specify the source folder using sourceSets

sourceSets {
    main.kotlin.srcDirs += 'src/main/myKotlin'
}

In addition to the output JavaScript file, the plugin by default creates an additional JS file with binary descriptors. This file is required if you're building a re-usable library that other Kotlin modules can depend on, and should be distributed together with the result of translation. The generation is controlled by the kotlinOptions.metaInfo option:

compileKotlin2Js {
	kotlinOptions.metaInfo = true
}

Targeting Android

Android's Gradle model is a little different from ordinary Gradle, so if we want to build an Android project written in Kotlin, we need kotlin-android plugin instead of kotlin:

buildscript {
    ...
}
apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'

Android Studio

If using Android Studio, the following needs to be added under android:

android {
  ...

  sourceSets {
    main.java.srcDirs += 'src/main/kotlin'
  }
}

This lets Android Studio know that the kotlin directory is a source root, so when the project model is loaded into the IDE it will be properly recognized. Alternatively, you can put Kotlin classes in the Java source directory, typically located in src/main/java.

Configuring Dependencies

In addition to the kotlin-gradle-plugin dependency shown above, you need to add a dependency on the Kotlin standard library:

repositories {
    mavenCentral()
}

dependencies {
    compile "org.jetbrains.kotlin:kotlin-stdlib"
}

If you target JavaScript, use compile "org.jetbrains.kotlin:kotlin-stdlib-js" instead.

If you're targeting JDK 7 or JDK 8, you can use extended versions of the Kotlin standard library which contain additional extension functions for APIs added in new JDK versions. Instead of kotlin-stdlib, use one of the following dependencies:

compile "org.jetbrains.kotlin:kotlin-stdlib-jre7"
compile "org.jetbrains.kotlin:kotlin-stdlib-jre8"

If your project uses Kotlin reflection or testing facilities, you need to add the corresponding dependencies as well:

compile "org.jetbrains.kotlin:kotlin-reflect"
testCompile "org.jetbrains.kotlin:kotlin-test"
testCompile "org.jetbrains.kotlin:kotlin-test-junit"

Starting with Kotlin 1.1.2, the dependencies with group org.jetbrains.kotlin are by default resolved with the version taken from the applied plugin. You can provide the version manually using the full dependency notation like compile "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version".

Annotation processing

The Kotlin plugin supports annotation processors like Dagger or DBFlow. In order for them to work with Kotlin classes, apply the kotlin-kapt plugin:

apply plugin: 'kotlin-kapt'

Or, starting with Kotlin 1.1.1, you can apply it using the plugins DSL:

plugins {
    id "org.jetbrains.kotlin.kapt" version "<version to use>"
}

Then add the respective dependencies using the kapt configuration in your dependencies block:

dependencies {
    kapt 'groupId:artifactId:version'
}

If you previously used the android-apt plugin, remove it from your build.gradle file and replace usages of the apt configuration with kapt. If your project contains Java classes, kapt will also take care of them.

If you use annotation processors for your androidTest or test sources, the respective kapt configurations are named kaptAndroidTest and kaptTest. Note that kaptAndroidTest and kaptTest extends kapt, so you can just provide the kapt dependency and it will be available both for production sources and tests.

Some annotation processors (such as AutoFactory) rely on precise types in declaration signatures. By default, Kapt replaces every unknown type (including types for the generated classes) to NonExistentClass, but you can change this behavior. Add the additional flag to the build.gradle file to enable error type inferring in stubs:

kapt {
    correctErrorTypes = true
}

Note that this option is experimental and it is disabled by default.

Incremental compilation

Kotlin supports optional incremental compilation in Gradle. Incremental compilation tracks changes of source files between builds so only files affected by these changes would be compiled.

Starting with Kotlin 1.1.1, incremental compilation is enabled by default.

There are several ways to override the default setting:

  1. add kotlin.incremental=true or kotlin.incremental=false line either to a gradle.properties or a local.properties file;

  2. add -Pkotlin.incremental=true or -Pkotlin.incremental=false to gradle command line parameters. Note that in this case the parameter should be added to each subsequent build, and any build with disabled incremental compilation invalidates incremental caches.

When incremental compilation is enabled, you should see the following warning message in your build log:

Using kotlin incremental compilation

Note, that the first build won't be incremental.

Coroutines support

Coroutines support is an experimental feature in Kotlin 1.1, so the Kotlin compiler reports a warning when you use coroutines in your project. To turn off the warning, add the following block to your build.gradle file:

kotlin {
    experimental {
        coroutines 'enable'
    }
}

Compiler Options

To specify additional compilation options, use the kotlinOptions property of a Kotlin compilation task.

When targeting the JVM, the tasks are called compileKotlin for production code and compileTestKotlin for test code. The tasks for custom source sets of are called accordingly to the compile<Name>Kotlin pattern.

When targeting JavaScript, the tasks are called compileKotlin2Js and compileTestKotlin2Js respectively, and compile<Name>Kotlin2Js for custom source sets.

Examples:

compileKotlin {
    kotlinOptions.suppressWarnings = true
}

compileKotlin {
    kotlinOptions {
        suppressWarnings = true
    }
}

A complete list of options for the Gradle tasks follows:

Attributes common for JVM and JS

Name Description Possible values Default value
apiVersion Allow to use declarations only from the specified version of bundled libraries "1.0", "1.1" "1.1"
languageVersion Provide source compatibility with specified language version "1.0", "1.1" "1.1"
suppressWarnings Generate no warnings   false
verbose Enable verbose logging output   false
freeCompilerArgs A list of additional compiler arguments   []

Attributes specific for JVM

Name Description Possible values Default value
javaParameters Generate metadata for Java 1.8 reflection on method parameters   false
jdkHome Path to JDK home directory to include into classpath, if differs from default JAVA_HOME    
jvmTarget Target version of the generated JVM bytecode (1.6 or 1.8), default is 1.6 "1.6", "1.8" "1.6"
noJdk Don't include Java runtime into classpath   false
noReflect Don't include Kotlin reflection implementation into classpath   true
noStdlib Don't include Kotlin runtime into classpath   true

Attributes specific for JS

Name Description Possible values Default value
main Whether a main function should be called "call", "noCall" "call"
metaInfo Generate .meta.js and .kjsm files with metadata. Use to create a library   true
moduleKind Kind of a module generated by compiler "plain", "amd", "commonjs", "umd" "plain"
noStdlib Don't use bundled Kotlin stdlib   true
outputFile Output file path    
sourceMap Generate source map   false
target Generate JS files for specific ECMA version "v5" "v5"

OSGi

For OSGi support see the Kotlin OSGi page.

Examples

The following examples show different possibilities of configuring the Gradle plugin: