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 just let intelliJ create it for you following the IntelliJ guide.

The initial file would look 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 on 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 in Kotlin, 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 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 how to configure Ktor with Nett. For other engines see artifacts for list of available artifacts.

You will add a dependency for ktor-server-netty using the ktor_version property you have created. This module provides Netty as a 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:

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 further in the logging page.