Configure compilations

    For each target, default compilations include:

    • and test compilations for JVM, JS, and Native targets.
    • A compilation per , for Android targets.

    If you need to compile something other than production code and unit tests, for example, integration or performance tests, you can create a custom compilation.

    You can configure how artifacts are produced in:

    See the list of compilation parameters and available for all or specific targets.

    Configure compilations for one target

    1. kotlin {
    2.     jvm().compilations.all {
    3.         kotlinOptions {
    4.             sourceMap = true
    5.             metaInfo = true
    6.         }
    7.     }
    8. }
    1. kotlin {
    2.     targets.jvm.compilations.all {
    3.         kotlinOptions {
    4.             sourceMap = true
    5.             metaInfo = true
    6.         }
    7.     }
    8. }
    1. kotlin {
    2.     jvm {
    3.         val main by compilations.getting {
    4.             kotlinOptions {
    5.                 jvmTarget = "1.8"
    6.             }
    7.         }
    8.     }
    9. }

    Create a custom compilation

    If you need to compile something other than production code and unit tests, for example, integration or performance tests, create a custom compilation.

    For example, to create a custom compilation for integration tests of the jvm() target, add a new item to the compilations collection.

    1. kotlin {
    2.         compilations.create('integrationTest') {
    3.             defaultSourceSet {
    4.                 dependencies {
    5.                     def main = compilations.main
    6.                     // Compile against the main compilation's compile classpath and outputs:
    7.                     implementation(main.compileDependencyFiles + main.output.classesDirs)
    8.                     implementation kotlin('test-junit')
    9.                     /* ... */
    10.                 }
    11.             }
    13.             // Create a test task to run the tests produced by this compilation:
    14.             tasks.register('jvmIntegrationTest', Test) {
    16.                 // runtime dependencies, and the outputs of this compilation:
    17.                 classpath = compileDependencyFiles + runtimeDependencyFiles + output.allOutputs
    19.                 // Run only the tests from this compilation's outputs:
    20.                 testClassesDirs = output.classesDirs
    21.             }
    22.         }
    23.     }
    24. }

    You also need to create a custom compilation in other cases, for example, if you want to combine compilations for different JVM versions in your final artifact, or you have already set up source sets in Gradle and want to migrate to a multiplatform project.

    To include Java sources in the compilations of the JVM target, explicitly enable the Java language support for the target:

    The Java source files are placed in the child directories of the Kotlin source roots. For example, the paths are:

    The common source sets cannot include Java sources.

    Due to current limitations, the Kotlin plugin replaces some tasks configured by the Java plugin:

    • The target’s JAR task instead of jar (for example, jvmJar).
    • The target’s test task instead of test (for example, jvmTest).
    • The resources are processed by the equivalent tasks of the compilations instead of *ProcessResources tasks.

    Configure interop with native languages

    Kotlin provides interoperability with native languages and DSL to configure this for a specific compilation.

    A compilation can interact with several native libraries. Configure interoperability in the cinterops block of the compilation with .

    1. kotlin {
    2.     linuxX64 { // Replace with a target you need.
    3.         compilations.main {
    4.             cinterops {
    5.                 myInterop {
    6.                     // Def-file describing the native API.
    7.                     defFile project.file("def-file.def")
    9.                     // Package to place the Kotlin API generated.
    10.                     packageName 'org.sample'
    12.                     // Options to be passed to compiler by cinterop tool.
    13.                     compilerOpts '-Ipath/to/headers'
    15.                     // Directories for header search (an eqivalent of the -I<path> compiler option).
    16.                     includeDirs.allHeaders("path1", "path2")
    18.                     // Additional directories to search headers listed in the 'headerFilter' def-file option.
    19.                     // -headerFilterAdditionalSearchPrefix command line option equivalent.
    20.                     includeDirs.headerFilterOnly("path1", "path2")
    22.                     // A shortcut for includeDirs.allHeaders.
    24.                 }
    26.                 anotherInterop { /* ... */ }
    27.             }
    28.         }
    29.     }
    30. }

    The compilations created for an Android target by default are tied to Android build variants: for each build variant, a Kotlin compilation is created under the same name.

    Then, for each compiled for each of the variants, a Kotlin source set is created under that source set name prepended by the target name, like the Kotlin source set androidDebug for an Android source set debug and the Kotlin target named android. These Kotlin source sets are added to the variants’ compilations accordingly.

    The default source set commonMain is added to each production (application or library) variant’s compilation. The commonTest source set is similarly added to the compilations of unit test and instrumented test variants.

    Annotation processing with kapt is also supported, but due to current limitations it requires that the Android target is created before the kapt dependencies are configured, which needs to be done in a top-level dependencies block rather than within Kotlin source set dependencies.

    1. kotlin {
    2.     android { /* ... */ }
    3. }
    5. dependencies {
    6.     kapt("com.my.annotation:processor:1.0.0")
    7. }

    Compilation of the source set hierarchy

    Kotlin can build a source set hierarchy with the dependsOn relation.

    Source set hierarchy

    If the source set jvmMain depends on a source set commonMain then:

    • Whenever jvmMain is compiled for a certain target, commonMain takes part in that compilation as well and is also compiled into the same target binary form, such as JVM class files.
    • Sources of jvmMain ‘see’ the declarations of commonMain, including internal declarations, and also see the of commonMain, even those specified as implementation dependencies.
    • jvmMain can contain platform-specific implementations for the expected declarations of commonMain.
    • The resources of commonMain are always processed and copied along with the resources of jvmMain.
    • The of jvmMain and commonMain should be consistent.
    • jvmMain should set a languageVersion that is greater than or equal to that of commonMain.
    • jvmMain should enable all unstable language features that commonMain enables (there’s no such requirement for bugfix features).
    • jvmMain should use all experimental annotations that commonMain uses.