Appendix. Building Kotlin projects

This appendix explains how to build Kotlin code with Gradle, Maven, and Ant. It also covers how to build Kotlin Android applications.

A.1. Building Kotlin code with Gradle

The recommended system for building Kotlin projects is Gradle. Gradle is the standard build system for Android projects, and it also supports all other kinds of projects where Kotlin can be used. Gradle has a flexible project model and delivers great build performance thanks to its support for incremental builds, long-lived build processes (the Gradle daemon), and other advanced techniques.

The Gradle team is working on the support for writing Gradle build scripts in Kotlin, which will allow you to use the same language for writing your application and its build scripts. As of this writing, this work is still in progress; you can find more information about it at https://github.com/gradle/gradle-script-kotlin. In this book, we use Groovy syntax for Gradle build scripts.

The standard Gradle build script for building a Kotlin project looks like this:

The script looks for Kotlin source files in the following locations:

In most cases, the recommended approach is to store both Kotlin and Java source files in the same directory. Especially when you’re introducing Kotlin into an existing project, using a single source directory reduces friction when converting Java files to Kotlin.

If you’re using Kotlin reflection, you need to add one more dependency: the Kotlin reflection library. To do so, add the following in the dependencies section of your Gradle build script: 

compile "org.jetbrains.kotlin:kotlin-reflect:$kotlin_version"

A.1.1. Building Kotlin Android applications with Gradle

Android applications use a different build process compared to regular Java applications, so you need to use a different Gradle plugin to build them. Instead of apply plugin: ‘kotlin’, add the following line to your build script: 

apply plugin: 'kotlin-android'

The rest of the setup is the same as for non-Android applications.

If you prefer to store your Kotlin source code in Kotlin-specific directories such as src/main/kotlin, you need to register them so that Android Studio recognizes them as source roots. You can do this using the following snippet: 

android {
    ...

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

A.1.2. Building projects that use annotation processing

Many Java frameworks, especially those used in Android development, rely on annotation processing to generate code at compile time. To use those frameworks with Kotlin, you need to enable Kotlin annotation processing in your build script. You can do this by adding the following line: 

apply plugin: 'kotlin-kapt'

If you have an existing Java project that uses annotation processing and you’re introducing Kotlin to it, you need to remove the existing configuration of the apt tool. The Kotlin annotation processing tool handles both Java and Kotlin classes, and having two separate annotation processing tools would be redundant. To configure dependencies required for annotation processing, use the kapt dependency configuration: 

dependencies {
    compile 'com.google.dagger:dagger:2.4'
    kapt 'com.google.dagger:dagger-compiler:2.4'
}

If you use annotation processors for your androidTest or test source, the respective kapt configurations are named kaptAndroidTest and kaptTest.

A.2. Building Kotlin projects with Maven

If you prefer to build your projects with Maven, Kotlin supports that as well. The easiest way to create a Kotlin Maven project is to use the org.jetbrains.kotlin: kotlin--archetype-jvm archetype. For existing Maven projects, you can easily add Kotlin support by choosing Tools > Kotlin > Configure Kotlin in Project in the Kotlin IntelliJ IDEA plugin.

To add Maven support to a Kotlin project manually, you need to perform the following steps:

  1. Add dependency on the Kotlin standard library (group ID org.jetbrains.kotlin, artifact ID kotlin-stdlib).
  2. Add the Kotlin Maven plugin (group ID org.jetbrains.kotlin, artifact ID kotlin-maven-plugin), and configure its execution in the compile and test-compile phases.
  3. Configure source directories, if you prefer to keep your Kotlin code in a source root separate from Java source code.

For reasons of space, we’re not showing full pom.xml examples here, but you can find them in the online documentation at https://kotlinlang.org/docs/reference/using-maven.html.

In a mixed Java/Kotlin project, you need to configure the Kotlin plugin so that it runs before the Java plugin. This is necessary because the Kotlin plugin can parse Java sources, whereas the Java plugin can only read .class files; so, the Kotlin files need to be compiled to .class before the Java plugin runs. You can find an example showing how this can be configured at http://mng.bz/73od.

A.3. Building Kotlin code with Ant

To build projects with Ant, Kotlin provides two different tasks: the <kotlinc> task compiles pure Kotlin modules, whereas <withKotlin> is an extension to the <javac> task for building mixed Kotlin/Java modules. Here’s a minimal example of using <kotlinc>:

The <kotlinc> Ant task adds the standard library dependency automatically, so you don’t need to add any extra arguments to configure it. It also supports packaging the compiled .class files into a jar file.

Here’s an example of using a <withKotlin> task to build a mixed Java/Kotlin module:

Unlike the <kotlinc> task, <withKotlin> doesn’t support automatic packaging of compiled classes, so this example uses a separate <jar> task to package them.