You can open this sample in an IDE that supports Gradle.

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

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 1: application project type and 2: Kotlin as the implementation language. Next you can choose the DSL for writing buildscripts - 1 : Kotlin or 2: Groovy. For the other questions, press enter to use the default values.

The output will look like this:

$ gradle init

Select type of build to generate:
  1: Application
  2: Library
  3: Gradle plugin
  4: Basic (build structure only)
Enter selection (default: Application) [1..4] 1

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

Enter target Java version (min: 7, default: 21):

Project name (default: demo):

Select application structure:
  1: Single application project
  2: Application and library project
Enter selection (default: Single application project) [1..2] 1

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

Select test framework:
  1: JUnit 4
  2: TestNG
  3: Spock
  4: JUnit Jupiter
Enter selection (default: JUnit Jupiter) [1..4]

Generate build using new APIs and behavior (some features may change in the next minor release)? (default: no) [yes, no]

BUILD SUCCESSFUL
1 actionable task: 1 executed

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

├── gradle (1)
│   ├── libs.versions.toml (2)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew (3)
├── gradlew.bat (3)
├── settings.gradle.kts (4)
└── app
    ├── build.gradle.kts (5)
    └── src
        ├── main
        │   └── kotlin (6)
        │       └── demo
        │           └── App.kt
        └── test
            └── kotlin (7)
                └── demo
                    └── AppTest.kt
├── gradle (1)
│   ├── libs.versions.toml (2)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew (3)
├── gradlew.bat (3)
├── settings.gradle (4)
└── app
    ├── build.gradle (5)
    └── src
        ├── main
        │   └── kotlin (6)
        │       └── demo
        │           └── App.kt
        └── test
            └── kotlin (7)
                └── demo
                    └── AppTest.kt
1 Generated folder for wrapper files
2 Generated version catalog
3 Gradle wrapper start scripts
4 Settings file to define build name and subprojects
5 Build script of app project
6 Default Kotlin source folder
7 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.kts
rootProject.name = "demo"
include("app")
settings.gradle
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.kts
plugins {
    alias(libs.plugins.kotlin.jvm) (1)
    application (2)
}

repositories {
    mavenCentral() (3)
}

dependencies {
    testImplementation("org.jetbrains.kotlin:kotlin-test-junit5") (4)

    testImplementation(libs.junit.jupiter.engine) (5)

    testRuntimeOnly("org.junit.platform:junit-platform-launcher")

    implementation(libs.guava) (6)
}

application {
    mainClass = "demo.AppKt" (7)
}

tasks.named<Test>("test") {
    useJUnitPlatform() (8)
}
app/build.gradle
plugins {
    alias(libs.plugins.kotlin.jvm) (1)
    id 'application' (2)
}

repositories {
    mavenCentral() (3)
}

dependencies {
    testImplementation 'org.jetbrains.kotlin:kotlin-test-junit5' (4)

    testImplementation libs.junit.jupiter.engine (5)

    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

    implementation libs.guava (6)
}

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

tasks.named('test') {
    useJUnitPlatform() (8)
}
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 Use the Kotlin JUnit 5 integration.
5 Use the JUnit 5 integration.
6 This dependency is used by the application.
7 Define the main class for the application.
8 Use JUnit Platform for unit tests.

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

Generated src/main/kotlin/demo/App.kt
/*
 * This 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 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: