# Building Kotlin Applications Sample

version 7.1

- Groovy DSL

- Kotlin DSL

| You can open this sample inside an IDE using the IntelliJ native importer or Eclipse Buildship.

This guide demonstrates how to create a Kotlin application with Gradle using `gradle init`. You can follow the guide step-by-step to create a new project from scratch or download the complete sample project using the links above.

## What you’ll build

You’ll generate a Kotlin application that follows Gradle’s conventions.

## What you’ll need

- A text editor or IDE - for example IntelliJ IDEA

- A Java Development Kit (JDK), version 8 or higher - for example AdoptOpenJDK

- The latest Gradle distribution

## Create a project folder

Gradle comes with a built-in task, called `init`, that initializes a new Gradle project in an empty folder. The `init` task uses the (also built-in) `wrapper` task to create a Gradle wrapper script, `gradlew`.

The first step is to create a folder for the new project and change directory into it.

    $ mkdir demo
    $ cd demo

## Run the init task

From inside the new project directory, run the `init` task using the following command in a terminal: `gradle init`. When prompted, select the `2: application` project type and `4: Kotlin` as implementation language. Next you can choose the DSL for writing buildscripts - `1 : Groovy` or `2: Kotlin`. For the other questions, press enter to use the default values.

The output will look like this:

    $ gradle init

    Select type of project to generate:
      1: basic
      2: application
      3: library
      4: Gradle plugin
    Enter selection (default: basic) [1..4] 2

    Select implementation language:
      1: C++
      2: Groovy
      3: Java
      4: Kotlin
      5: Scala
      6: Swift
    Enter selection (default: Java) [1..6] 4

    Select build script DSL:
      1: Groovy
      2: Kotlin
    Enter selection (default: Groovy) [1..2] 1

    Project name (default: demo):
    Source package (default: demo):

    BUILD SUCCESSFUL
    2 actionable tasks: 2 executed

The `init` task generates the new project with the following structure:

    ├── gradle (1)
    │   └── wrapper
    │       ├── gradle-wrapper.jar
    │       └── gradle-wrapper.properties
    ├── gradlew (2)
    ├── gradlew.bat (2)
    ├── settings.gradle (3)
    └── app
        ├── build.gradle (4)
        └── src
            ├── main
            │   └── kotlin (5)
            │       └── demo
            │           └── App.kt
            └── test
                └── kotlin (6)
                    └── demo
                        └── AppTest.kt

    ├── gradle (1)
    │   └── wrapper
    │       ├── gradle-wrapper.jar
    │       └── gradle-wrapper.properties
    ├── gradlew (2)
    ├── gradlew.bat (2)
    ├── settings.gradle.kts (3)
    └── app
        ├── build.gradle.kts (4)
        └── src
            ├── main
            │   └── kotlin (5)
            │       └── demo
            │           └── App.kt
            └── test
                └── kotlin (6)
                    └── demo
                        └── AppTest.kt

1 | Generated folder for wrapper files
2 | Gradle wrapper start scripts
3 | Settings file to define build name and subprojects
4 | Build script of `app` project
5 | Default Kotlin source folder
6 | Default Kotlin test source folder

You now have the project setup to build a Kotlin application.

## Review the project files

The `settings.gradle(.kts)` file has two interesting lines:

settings.gradle

    rootProject.name = 'demo'
    include('app')

settings.gradle.kts

    rootProject.name = "demo"
    include("app")

- `rootProject.name` assigns a name to the build, which overrides the default behavior of naming the build after the directory it’s in. It’s recommended to set a fixed name as the folder might change if the project is shared - e.g. as root of a Git repository.

- `include("app")` defines that the build consists of one subproject called `app` that contains the actual code and build logic. More subprojects can be added by additional `include(…​)` statements.

Our build contains one subproject called `app` that represents the Kotlin application we are building. It is configured in the `app/build.gradle(.kts)` file:

app/build.gradle

    plugins {
        id 'org.jetbrains.kotlin.jvm' version '1.4.31' (1)

        id 'application' (2)
    }

    repositories {
        mavenCentral() (3)
    }

    dependencies {
        implementation platform('org.jetbrains.kotlin:kotlin-bom') (4)

        implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk8' (5)

        implementation 'com.google.guava:guava:30.1-jre' (6)

        testImplementation 'org.jetbrains.kotlin:kotlin-test' (7)

        testImplementation 'org.jetbrains.kotlin:kotlin-test-junit' (8)
    }

    application {
        mainClass = 'demo.AppKt' (9)
    }

app/build.gradle.kts

    plugins {
        id("org.jetbrains.kotlin.jvm") version "1.4.31" (1)

        application (2)
    }

    repositories {
        mavenCentral() (3)
    }

    dependencies {
        implementation(platform("org.jetbrains.kotlin:kotlin-bom")) (4)

        implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8") (5)

        implementation("com.google.guava:guava:30.1-jre") (6)

        testImplementation("org.jetbrains.kotlin:kotlin-test") (7)

        testImplementation("org.jetbrains.kotlin:kotlin-test-junit") (8)
    }

    application {
        mainClass.set("demo.AppKt") (9)
    }

1 | Apply the org.jetbrains.kotlin.jvm Plugin to add support for Kotlin.
2 | Apply the application plugin to add support for building a CLI application in Java.
3 | Use Maven Central for resolving dependencies.
4 | Align versions of all Kotlin components
5 | Use the Kotlin JDK 8 standard library.
6 | This dependency is used by the application.
7 | Use the Kotlin test library.
8 | Use the Kotlin JUnit integration.
9 | Define the main class for the application.

The file `src/main/kotlin/demo/App.kt` is shown here:

Generated src/main/kotlin/demo/App.kt

    /*
     * This Kotlin source file was generated by the Gradle 'init' task.
     */
    package demo

    class App {
        val greeting: String
            get() {
                return "Hello World!"
            }
    }

    fun main() {
        println(App().greeting)
    }

The generated test, `src/test/kotlin/demo/App.kt` is shown next:

Generated src/test/kotlin/demo/AppTest.kt

    /*
     * This Kotlin source file was generated by the Gradle 'init' task.
     */
    package demo

    import kotlin.test.Test
    import kotlin.test.assertNotNull

    class AppTest {
        @Test fun appHasAGreeting() {
            val classUnderTest = App()
            assertNotNull(classUnderTest.greeting, "app should have a greeting")
        }
    }

The generated test class has a single kotlin.test test. The test instantiates the `App` class, invokes a method on it, and checks that it returns the expected value.

## Run the application

Thanks to the `application` plugin, you can run the application directly from the command line. The `run` task tells Gradle to execute the `main` method in the class assigned to the `mainClass` property.

    $ ./gradlew run

    > Task :app:run
    Hello world!

    BUILD SUCCESSFUL
    2 actionable tasks: 2 executed

| The first time you run the wrapper script, `gradlew`, there may be a delay while that version of `gradle` is downloaded and stored locally in your `~/.gradle/wrapper/dists` folder.

## Bundle the application

The `application` plugin also bundles the application, with all its dependencies, for you. The archive will also contain a script to start the application with a single command.

    $ ./gradlew build

    BUILD SUCCESSFUL in 0s
    8 actionable tasks: 8 executed

If you run a full build as shown above, Gradle will have produced the archive in two formats for you: `app/build/distributions/app.tar` and `app/build/distributions/app.zip`.

## Publish a Build Scan

The best way to learn more about what your build is doing behind the scenes, is to publish a build scan. To do so, just run Gradle with the `--scan` flag.

    $ ./gradlew build --scan

    BUILD SUCCESSFUL in 0s
    8 actionable tasks: 8 executed

    Publishing a build scan to scans.gradle.com requires accepting the Gradle Terms of Service defined at https://gradle.com/terms-of-service.
    Do you accept these terms? [yes, no] yes

    Gradle Terms of Service accepted.

    Publishing build scan...
    https://gradle.com/s/5u4w3gxeurtd2

Click the link and explore which tasks where executed, which dependencies where downloaded and many more details!

## Summary

That’s it! You’ve now successfully configured and built a Kotlin application project with Gradle. You’ve learned how to:

- Initialize a project that produces a Kotlin application

- Run the build and view the test report

- Execute a Kotlin application using the `run` task from the `application` plugin

- Bundle the application in an archive

## Next steps

To learn more about how you can further customize Kotlin application projects, check out the following user manual chapters:

- Building Java & JVM projects

- Java Application Plugin documentation