Using Gradle

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

    The Kotlin Gradle plugin 1.4.21 works with Gradle 5.4 and later. The plugin requires Gradle 6.0 or later.

    1. plugins {
    2.     kotlin("<...>") version "1.4.21"
    3. }

    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 , require the kotlin-multiplatform plugin. Learn more about the plugin.

    1. plugins {
    2.     id 'org.jetbrains.kotlin.multiplatform' version '1.4.21'
    3. }
    1. plugins {
    2.     kotlin("multiplatform") version "1.4.21"
    3. }

    Targeting the JVM

    To target the JVM, apply the Kotlin JVM plugin.

    1. plugins {
    2.     id "org.jetbrains.kotlin.jvm" version "1.4.21"
    3. }
    1. plugins {
    2.     kotlin("jvm") version "1.4.21"
    3. }

    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:

    1. apply plugin: 'kotlin'

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

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

    1. project
    2.     - src
    3.         - main (root)
    4.             - kotlin
    5.             - java

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

    1. sourceSets {
    2.     main.kotlin.srcDirs += 'src/main/myKotlin'
    3.     main.java.srcDirs += 'src/main/myJava'
    4. }

    Targeting JavaScript

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

    1. plugins {
    2.     id 'org.jetbrains.kotlin.js' version '1.4.21'
    3. }
    1. plugins {
    2.     kotlin("js") version "1.4.21"
    3. }

    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:

    1. kotlin {
    2.     sourceSets {
    3.     }
    4. }
    1. kotlin {
    2.     sourceSets["main"].apply {    
    3.         kotlin.srcDir("src/main/myKotlin") 
    4.     }
    5. }

    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.

    1. kotlin {
    2.     sourceSets {
    3.         commonMain {
    4.             dependencies {
    5.                 implementation 'com.example:my-library:1.0'
    6.             }
    7.         }
    8.     }
    9. }
    1. kotlin {
    2.     sourceSets {
    3.         val commonMain by getting {
    4.             dependencies {
    5.                 implementation("com.example:my-library:1.0")
    6.             }
    7.         }
    8.     }
    9. }

    Alternatively, you can .

    Dependency types

    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 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:

    1. kotlin.stdlib.default.dependency=false

    Set dependencies on test libraries

    The 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.

    1. kotlin{
    2.     sourceSets {
    3.         commonTest {
    4.             dependencies {
    5.                 implementation kotlin('test-common')
    6.                 implementation kotlin('test-annotations-common')
    7.             }
    8.         }
    9.         jvmTest {
    10.             dependencies {
    11.                 implementation kotlin('test-junit')
    12.             }
    13.         }
    14.         jsTest {
    15.             dependencies {
    16.                 implementation kotlin('test-js')
    17.             }
    18.         }
    19.     }
    20. }

    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.

    1. kotlin {
    2.     sourceSets {
    3.         jvmMain {
    4.             dependencies {
    5.                 implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.4.2'
    6.             }
    7.         }
    8.     }
    1. kotlin {
    2.     sourceSets {
    3.         val jvmMain by getting {
    4.             dependencies {
    5.                 implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.4.2")
    6.             }
    7.         }
    8.     }
    9. }

    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.

    1. kotlin {
    2.     sourceSets {
    3.         commonMain {
    4.             dependencies {
    5.                 implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.2'
    6.             }
    7.         }
    8.     }
    9. }
    1. kotlin {
    2.     sourceSets {
    3.         val commonMain by getting {
    4.             dependencies {
    5.                 implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.2")
    6.             }
    7.         }
    8.     }
    9. }

    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 , which are not available in the source sets dependency DSL.

    1. dependencies {
    2.     commonMainImplementation 'com.example:my-library:1.0'
    3. }
    1. dependencies {
    2.     "commonMainImplementation"("com.example:my-library:1.0")
    3. }

    Annotation processing

    Kotlin supports annonation processing via the Kotlin annotation processing tool .

    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 and is enabled by default since Kotlin 1.1.1.

    • Add the following line to the gradle.properties or local.properties file:
      • kotlin.incremental=false for Kotlin/JVM
      • kotlin.incremental.js=false for Kotlin/JS projects

    • As the command line parameter, use -Pkotlin.incremental=false or -Pkotlin.incremental.js=false.

      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 .

    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 .

    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 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:

    1. compileKotlin {
    2.     kotlinOptions.suppressWarnings = true
    3. }
    5. //or
    7. compileKotlin {
    8.     kotlinOptions {
    9.         suppressWarnings = true
    10.     }
    11. }
    1. import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
    2. // ...
    4. val compileKotlin: KotlinCompile by tasks
    6. 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:

    1. tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {
    2.     kotlinOptions { /*...*/ }
    3. }

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

    Attributes common for JVM and JS

    Attributes specific for JVM

    Generating documentation

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

    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.