Using Gradle

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

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

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

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

Targeting the JVM

To target the JVM, apply the Kotlin JVM plugin.

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

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

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

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

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.

Type	Description	When to use
`api`	Used both during compilation and at runtime and is exported to library consumers.	If any type from a dependency is used in the public API of the current module, use an `api` dependency.
`implementation`	Used during compilation and at runtime for the current module, but is not exposed for compilation of other modules depending on the one with the `implementation` dependency.	Use for dependencies needed for the internal logic of a module. If a module is an endpoint application which is not published, use `implementation` dependencies instead of `api` dependencies.
`compileOnly`	Used for compilation of the current module and is not available at runtime nor during compilation of other modules.	Use for APIs which have a third-party implementation available at runtime.
`runtimeOnly`	Available at runtime but is not visible during compilation of any module.

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

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

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

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

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

There are several ways to disable the setting:

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 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 { /*...*/ }
}

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

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

Attributes common for JVM, JS, and JS DCE

Name	Description	Default value
`allWarningsAsErrors`	Report an error if there are any warnings	false
`suppressWarnings`	Generate no warnings	false
`verbose`	Enable verbose logging output	false
`freeCompilerArgs`	A list of additional compiler arguments	[]

Attributes common for JVM and JS

Name	Description	Possible values	Default value
`apiVersion`	Allow using declarations only from the specified version of bundled libraries	“1.2” (DEPRECATED), “1.3”, “1.4”, “1.5” (EXPERIMENTAL)
`languageVersion`	Provide source compatibility with the specified version of Kotlin	“1.2” (DEPRECATED), “1.3”, “1.4”, “1.5” (EXPERIMENTAL)

Attributes specific for JVM

Name	Description	Possible values	Default value
`javaParameters`	Generate metadata for Java 1.8 reflection on method parameters		false
`jdkHome`	Include a custom JDK from the specified location into the classpath instead of the default JAVA_HOME
`jvmTarget`	Target version of the generated JVM bytecode	“1.6”, “1.8”, “9”, “10”, “11”, “12”, “13”, “14”, “15”	“1.6”
`noJdk`	Don’t automatically include the Java runtime into the classpath		false
`noReflect`	Don’t automatically include Kotlin reflection into the classpath		true
`noStdlib`	Don’t automatically include the Kotlin/JVM stdlib and Kotlin reflection into the classpath		true
`useIR`	Use the IR backend		false

Attributes specific for 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”	“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”	“umd”
`noStdlib`	Don’t automatically include the default Kotlin/JS stdlib into compilation dependencies		true
`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 source map	“never”, “always”, “inlining”
`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

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.