Using Gradle

In order to build a Kotlin project with Gradle, you should apply the Kotlin Gradle plugin to your project and configure dependencies.

Plugin and versions

Apply the Kotlin Gradle plugin by using the Gradle plugins DSL.

The Kotlin Gradle plugin 1.4.10 works with Gradle 5.4 and later. The kotlin-multiplatform plugin requires Gradle 6.0 or later.

plugins {
    id 'org.jetbrains.kotlin.<...>' version '1.4.10'
}

plugins {
    kotlin("<...>") version "1.4.10"
}

The placeholder <...> should be replaced with one of the plugin names that can be found in further sections.

Targeting multiple platforms

Projects targeting multiple platforms, called multiplatform projects, require the kotlin-multiplatform plugin. Learn more about the plugin.

The kotlin-multiplatform plugin works with Gradle 6.0 or later.

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '1.4.10'
}

plugins {
    kotlin("multiplatform") version "1.4.10"
}

Targeting the JVM

To target the JVM, apply the Kotlin JVM plugin.

plugins {
    id "org.jetbrains.kotlin.jvm" version "1.4.10"
}

plugins {
    kotlin("jvm") version "1.4.10"
}

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

Alternatively, you can use the older apply plugin approach:

apply plugin: 'kotlin'

It's not recommended that you apply Kotlin plugins with apply in Gradle Kotlin DSL – see why.

Kotlin and Java sources

Kotlin sources can be stored with Java sources in the same folder, or placed to 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'
}

sourceSets.main {
    java.srcDirs("src/main/myJava", "src/main/myKotlin")
}

Targeting JavaScript

When targeting only JavaScript, use the kotlin-js plugin. Learn more

plugins {
    id 'org.jetbrains.kotlin.js' version '1.4.10'
}

plugins {
    kotlin("js") version "1.4.10"
}

Kotlin and Java sources

This plugin only works for Kotlin files so it is recommended that you keep Kotlin and Java files separately (in case the project contains Java files). If you don't store them separately , specify the source folder in the sourceSets block:

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

kotlin {
    sourceSets["main"].apply {    
        kotlin.srcDir("src/main/myKotlin") 
    }
}

Targeting Android

It's recommended that you use Android Studio for creating Android applications. Learn how to use Android Gradle plugin.

Configuring dependencies

To add a dependency on a library, set the dependency of the required type (for example, implementation) in the dependencies block of the source sets DSL.

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation 'com.example:my-library:1.0'
            }
        }
    }
}

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("com.example:my-library:1.0")
            }
        }
    }
}

Alternatively, you can set dependencies at the top level.

Dependency types

Choose the dependency type based on your requirements.

Dependency on the standard library

A dependency on a standard library (stdlib) in each source set is added automatically. The version of the standard library is the same as the version of the Kotlin Gradle plugin.

For platform-specific source sets, the corresponding platform-specific variant of the library is used, while a common standard library is added to the rest. The Kotlin Gradle plugin will select the appropriate JVM standard library depending on the kotlinOptions.jvmTarget compiler option of your Gradle build script.

If you declare a standard library dependency explicitly (for example, if you need a different version), the Kotlin Gradle plugin won’t override it or add a second standard library.

If you do not need a standard library at all, you can add the opt-out flag to the gradle.properties:

kotlin.stdlib.default.dependency=false

Set dependencies on test libraries

The kotlin.test API is available for testing different Kotlin projects.

Add the corresponding dependencies on test libraries:

• For commonTest, add the kotlin-test-common and kotlin-test-annotations-common dependencies.
• For JVM targets, use kotlin-test-junit or kotlin-test-testng for the corresponding asserter implementation and annotations mapping.
• For Kotlin/JS targets, add kotlin-test-js as a test dependency.

Kotlin/Native targets do not require additional test dependencies, and the kotlin.test API implementations are built-in.

kotlin{
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin('test-common')
                implementation kotlin('test-annotations-common')
            }
        }
        jvmTest {
            dependencies {
                implementation kotlin('test-junit')
            }
        }
        jsTest {
            dependencies {
                implementation kotlin('test-js')
            }
        }
    }
}

kotlin{
    sourceSets {
        val commonTest by getting {
            dependencies {
                implementation(kotlin("test-common"))
                implementation(kotlin("test-annotations-common"))
            }
        }
        val jvmTest by getting {
            dependencies {
                implementation(kotlin("test-junit"))
            }
        }
        val jsTest by getting {
            dependencies {
                implementation(kotlin("test-js"))
            }
        }
    }
}

You can use shorthand for a dependency on a Kotlin module, for example, kotlin("test") for "org.jetbrains.kotlin:kotlin-test".

Set a dependency on a kotlinx library

If you use a kotlinx library and need a platform-specific dependency, you can use platform-specific variants of libraries with suffixes such as -jvm or -js, for example, kotlinx-coroutines-core-jvm. You can also use the library base artifact name instead – kotlinx-coroutines-core.

kotlin {
    sourceSets {
        jvmMain {
            dependencies {
                implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.4.1'
            }
        }
    }
}

kotlin {
    sourceSets {
        val jvmMain by getting {
            dependencies {
                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.4.1")
            }
        }
    }
}

If you use a multiplatform library and need to depend on the shared code, set the dependency only once in the shared source set. Use the library base artifact name, such as kotlinx-coroutines-core or ktor-client-core.

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.1'
            }
        }
    }
}

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.1")
            }
        }
    }
}

Set dependencies at the top level

Alternatively, you can specify the dependencies at the top level with the configuration names following the pattern <sourceSetName><DependencyType>. This is helpful for some Gradle built-in dependencies, like gradleApi(), localGroovy(), or gradleTestKit(), which are not available in the source sets dependency DSL.

dependencies {
    commonMainImplementation 'com.example:my-library:1.0'
}

dependencies {
    "commonMainImplementation"("com.example:my-library:1.0")
}

Annotation processing

Kotlin supports annonation processing via the Kotlin annotation processing tool kapt.

Incremental compilation

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

Incremental compilation is supported for Kotlin/JVM and Kotlin/JS projects.

There are several ways to override the default setting:

• Add the following line to the gradle.properties or local.properties file:
  • kotlin.incremental=<value> for Kotlin/JVM
  • kotlin.incremental.js=<value> for Kotlin/JS projects .
    <value> is a boolean value reflecting the usage of incremental compilation.
• As the command line parameter, use -Pkotlin.incremental or -Pkotlin.incremental.js with the boolean value reflecting the usage of incremental compilation.
  Note that in this case the parameter should be added to each subsequent build, and any build with disabled incremental compilation invalidates incremental caches.

Note that the first build isn't incremental in any case.

Gradle build cache support

The Kotlin plugin supports Gradle Build Cache.

To disable the caching for all Kotlin tasks, set the system property flag kotlin.caching.enabled to false (run the build with the argument -Dkotlin.caching.enabled=false).

If you use kapt, note that the kapt annotation processing tasks are not cached by default. However, you can enable caching for them manually.

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 are called accordingly to the compile<Name>Kotlin pattern.

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

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

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

compileKotlin {
    kotlinOptions.suppressWarnings = true
}

//or

compileKotlin {
    kotlinOptions {
        suppressWarnings = true
    }
}

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
// ...

val compileKotlin: KotlinCompile by tasks

compileKotlin.kotlinOptions.suppressWarnings = true

Note that with Gradle Kotlin DSL, you should get the task from the project's tasks first.

Use the types Kotlin2JsCompile and KotlinCompileCommon for the JS and Common targets, accordingly.

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

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
    kotlinOptions { //... }
}

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

tasks.withType<KotlinCompile>().configureEach {
    kotlinOptions.suppressWarnings = true
}

The complete list of options for the Gradle tasks is the following:

Attributes common for JVM, JS, and JS DCE

Attributes common for JVM and JS

Attributes specific for JVM

Attributes specific for JS

Generating documentation

To generate documentation for Kotlin projects, use Dokka; please refer to the Dokka README for configuration instructions. Dokka supports mixed-language projects and can generate output in multiple formats, including standard JavaDoc.

OSGi

For OSGi support see the Kotlin OSGi page.

Using Gradle Kotlin DSL

When using Gradle Kotlin DSL, apply the Kotlin plugins using the plugins { ... } block. If you apply them with apply { plugin(...) } instead, you may encounter unresolved references to the extensions generated by Gradle Kotlin DSL. To resolve that, you can comment out the erroneous usages, run the Gradle task kotlinDslAccessorsSnapshot, then uncomment the usages back and rerun the build or reimport the project into the IDE.