Setting up a Gradle Build

Estimated reading time: 3 minutes

In this guide, we will show you how to create a build.gradle file and how to configure it to support Ktor.

Table of contents:

Basic Kotlin build.gradle file (without Ktor)

First of all, you need a skeleton build.gradle file including Kotlin. You can create it with any text editor, or you can use IntelliJ to create it following the IntelliJ guide.

The initial file looks like this:

group 'Example'
version '1.0-SNAPSHOT'

buildscript {
    ext.kotlin_version = '1.2.40'

    repositories {
        mavenCentral()
    }
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

apply plugin: 'java'
apply plugin: 'kotlin'

sourceCompatibility = 1.8

repositories {
    jcenter()
}

dependencies {
    compile "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
    testCompile group: 'junit', name: 'junit', version: '4.12'
}

Add Ktor dependencies and configure build settings

Ktor artifacts are located in a specific repository on bintray. And its core has dependencies on the kotlinx.coroutines library that can be found on jcenter.

You have to add both to the repositories block in the build.gradle file:

jcenter()
maven { url "https://dl.bintray.com/kotlin/ktor" }

Visit Bintray and determine the latest version of ktor. In this case it is 0.9.2.

You have to specify that version in each Ktor artifact reference, and to avoid repetitions, you can specify that version in an extra property in the buildscript block (or in a gradle.properties file) for using it later:

ext.ktor_version = '0.9.2'

Now you have to add the ktor-server-core artifact, referencing the ktor_version you specified:

compile "io.ktor:ktor-server-core:$ktor_version"

In groovy, there are single-quoted strings (instead of characters) and double-quoted strings, to be able to interpolate variables like versions, you have to use double-quoted strings.

As for Kotlin 1.2x, coroutines are still an experimental feature, so you will need to tell the compiler that it is okay to use them to avoid warnings:

kotlin {
    experimental {
        coroutines "enable"
    }
}

You also need to tell the Kotlin compiler to generate bytecode compatible with Java 8:

compileKotlin {
    kotlinOptions.jvmTarget = "1.8"
}
compileTestKotlin {
    kotlinOptions.jvmTarget = "1.8"
}

Choose your engine and configure it

Ktor can run in many environments, such as Netty, Jetty or any other Servlet-compatible Application Container such as Tomcat.

This example shows you how to configure Ktor with Netty. For other engines see artifacts for a list of available artifacts.

You will add a dependency for ktor-server-netty using the ktor_version property you have created. This module provides a Netty web server and all the required code to run Ktor application on top of it:

compile "io.ktor:ktor-server-netty:$ktor_version"

Final build.gradle (with Ktor)

When you are done, the build.gradle file should look like this:

group 'Example'
version '1.0-SNAPSHOT'

buildscript {
    ext.kotlin_version = '1.2.40'
    ext.ktor_version = '0.9.2'

    repositories {
        mavenCentral()
    }
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

apply plugin: 'java'
apply plugin: 'kotlin'

sourceCompatibility = 1.8
compileKotlin {
    kotlinOptions.jvmTarget = "1.8"
}
compileTestKotlin {
    kotlinOptions.jvmTarget = "1.8"
}

kotlin {
    experimental {
        coroutines "enable"
    }
}

repositories {
    jcenter()
    maven { url "https://dl.bintray.com/kotlin/ktor" }
}

dependencies {
    compile "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
    compile "io.ktor:ktor-server-netty:$ktor_version"
    testCompile group: 'junit', name: 'junit', version: '4.12'
}

You can now run Gradle (just gradle or ./gradlew if using the wrapper) to fetch dependencies and verify everything is set up correctly.

Configure logging

If you want to log application events and useful information, you can read about it further in the logging page.