Skip to main content

Your First Bleep Project (Kotlin)

This tutorial walks you through scaffolding a small Kotlin project with bleep, running it, running its tests with Kotest, and importing the project into IntelliJ IDEA.

Other languages: Java → · Scala →

Prerequisites​

Step 1: Create the project​

mkdir my-first-bleep-project
cd my-first-bleep-project
bleep new myapp --lang kotlin

bleep new writes a complete, ready-to-run workspace: a bleep.yaml, a myapp project with a hello-world Main.kt, and a myapp-test project wired up with Kotest.

The Kotlin compiler and standard library are downloaded by Coursier on first compile; you don't need a separate kotlinc install.

Step 2: What got generated​

The build file:

$schema: https://raw.githubusercontent.com/oyvindberg/bleep/master/schema.json
$version: 1.0.0-M14
jvm:
  name: graalvm-community:25.0.1
projects:
  myapp:
    extends: template-common
    platform:
      mainClass: com.example.MainKt
  myapp-test:
    dependencies: io.kotest:kotest-runner-junit5-jvm:6.2.4
    dependsOn: myapp
    extends: template-common
    isTestProject: true
templates:
  template-common:
    kotlin:
      jvmTarget: '25'
      version: 2.4.10
    platform:
      name: jvm

The kotlin block under template-common tells bleep to invoke kotlinc for .kt sources and produces JVM bytecode targeting the JVM the build runs on. Both myapp and myapp-test extend the template, so they share kotlin.version, kotlin.jvmTarget, and platform.name.

The main source, myapp/src/kotlin/com/example/Main.kt:

package com.example

object Main {
  fun greet(name: String): String = "Hello, $name!"
}

fun main() {
  println(Main.greet("World"))
}

Note: Kotlin's compiler generates a JVM class named MainKt for a top-level main function in Main.kt, that's the mainClass set in bleep.yaml.

The test, myapp-test/src/kotlin/com/example/MainTest.kt:

package com.example

import io.kotest.core.spec.style.FunSpec
import io.kotest.matchers.shouldBe

class MainTest : FunSpec({
  test("greets by name") {
    Main.greet("World") shouldBe "Hello, World!"
  }
})

Step 3: Run it​

bleep run myapp
Hello, World!

Step 4: Run the tests​

bleep test myapp-test

Step 5: Add a dependency​

Java/Kotlin dependencies use a single colon :. To add a logging library, edit bleep.yaml:

projects:
  myapp:
    extends: template-common
    dependencies:
      - io.github.microutils:kotlin-logging-jvm:3.0.5
      - org.slf4j:slf4j-simple:2.0.9
    platform:
      mainClass: com.example.MainKt

Step 6: Open it in your IDE​

bleep setup-ide

setup-ide writes a BSP configuration any BSP-aware editor can consume.

IntelliJ IDEA​

Open → select the project directory. The bundled Kotlin plugin handles .kt files automatically once BSP has imported the project. This is the smoothest path for Kotlin projects.

VS Code with Metals​

Install the Metals extension and open the project folder. Metals detects the BSP server. Metals is Scala-focused; for full Kotlin language features you'll usually pair it with the Kotlin extension, which provides syntax + completion. IntelliJ remains the more polished choice for Kotlin.

Compiler plugins​

Bleep ships first-class support for the standard Kotlin compiler plugins (spring, jpa, allopen, noarg, serialization):

projects:
  myapp:
    extends: template-common
    kotlin:
      compilerPlugins:
        - spring
        - jpa

Using KSP processors? Room, Hilt, Moshi codegen, Koin KSP, kotlinx.serialization (KSP variant), kotlin-inject, Wire, and similar are supported via kotlin.symbolProcessors: / kotlin.kspVersion:. See Annotation processing for the full surface, scan-vs-explicit modes, and current incremental-compile limitations. KAPT is not supported; migrate to KSP first.

Project structure​

my-first-bleep-project/
├── bleep.yaml
├── myapp/
│   └── src/
│       └── kotlin/
│           └── com/
│               └── example/
│                   └── Main.kt
└── myapp-test/
    └── src/
        └── kotlin/
            └── com/
                └── example/
                    └── MainTest.kt

Coming from Gradle? Bleep uses src/kotlin/ rather than src/main/kotlin/ because there is no src/test/kotlin/ to contrast with, tests live in their own sibling project (myapp-test) rather than under a test/ subtree. Same files, shorter paths.

Next steps​