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.

You can also enable incremental compilation to make your builds faster.

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

The correspondence between Kotlin releases and versions is displayed below:

Targeting the JVM

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

apply plugin: "kotlin"

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

If you want to create a re-usable library, use kotlinOptions.metaInfo to generate additional JS file with binary descriptors. This file should be distributed together with the result of translation.

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:

buildscript {
   ext.kotlin_version = '<version to use>'
  repositories {
    mavenCentral()
  }
  dependencies {
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
  }
}

apply plugin: "kotlin" // or apply plugin: "kotlin2js" if targeting JavaScript

repositories {
  mavenCentral()
}

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

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

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

Annotation processing

The Kotlin plugin supports annotation processors like Dagger or DBFlow. In order for them to work with Kotlin classes, 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.

Some annotation processing libraries require you to reference generated classes from within your code. For this to work, you'll need to add an additional flag to enable the generation of stubs to your build file:

kapt {
    generateStubs = true
}

Note, that generation of stubs slows down your build somewhat, which is why it's disabled by default. If generated classes are referenced only in a few places in your code, you can alternatively revert to using a helper class written in Java which can be seamlessly called from your Kotlin code.

For more information on kapt refer to the official blogpost.

Incremental compilation

Kotlin 1.0.2 introduced new experimental incremental compilation mode in Gradle. Incremental compilation tracks changes of source files between builds so only files affected by these changes would be compiled.

There are several ways to enable it:

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

2. add -Pkotlin.incremental=true to gradle command line parameters. Note that in this case the parameter should be added to each subsequent build (any build without this parameter invalidates incremental caches).

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

Using experimental kotlin incremental compilation

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

OSGi

For OSGi support see the Kotlin OSGi page.

Examples

The Kotlin Repository contains examples:

• Kotlin
• Mixed Java and Kotlin
• Android
• JavaScript