Write Your First Script (Kotlin)

This page walks through the Kotlin flow for adding a script to your build. For what a script is and why bleep models scripts as a core concept, see Scripts and source generation.

Other languages: Java → · Scala →

Prerequisites

• A working bleep project (see Your First Project (Kotlin))
• Kotlin 2.x

Step 1: Add a scripts project

The scripts project depends on bleepscript (Java) and is registered under the top-level scripts: section. Both kotlin: and java: blocks are present — Kotlin always emits JVM bytecode against a Java target.

$schema: https://raw.githubusercontent.com/oyvindberg/bleep/master/schema.json
$version: 1.0.0-M9
jvm:
  name: graalvm-community:25.0.1
projects:
  myapp:
    kotlin:
      jvmTarget: "25"
      version: 2.3.0
    platform:
      name: jvm
      mainClass: com.example.MainKt
  scripts:
    dependencies:
      - build.bleep:bleepscript:${BLEEP_VERSION}
    kotlin:
      jvmTarget: "25"
      version: 2.3.0
    platform:
      name: jvm
scripts:
  hello:
    main: scripts.HelloScript
    project: scripts

Key points:

• ${BLEEP_VERSION} is interpolated by bleep to your installed version.
• scripts.HelloScript resolves to the JVM class generated for the Kotlin class HelloScript below — no Kt suffix because it's a class, not top-level functions.

Step 2: Write the script

Extend bleepscript.BleepScript and implement run:

package scripts

import bleepscript.BleepScript
import bleepscript.Commands
import bleepscript.Started

class HelloScript : BleepScript("hello") {
  override fun run(started: Started, commands: Commands, args: List<String>) {
    val projectCount = started.build().explodedProjects().size
    started.logger().info("This build has $projectCount projects")
    if (args.isEmpty()) {
      started.logger().info("Hello, world!")
    } else {
      started.logger().info("Hello, ${args.joinToString(" ")}!")
    }
  }
}

Notes:

• The Kotlin primary constructor passes the script name to the Java super constructor: class HelloScript : BleepScript("hello").
• BleepScript supplies main by reflection — you don't write your own.
• args is List<String> (Kotlin's interface, but compatible with the Java List<String> signature on the base class).

Step 3: Run it

bleep hello

This build has 2 projects
Hello, world!

bleep hello Alice

This build has 2 projects
Hello, Alice!

Where to go from here

• Bleep scripts (concept) — the full BleepScript API and how to call it from Kotlin via standard Java interop.
• Source generation scripts — for scripts whose output is consumed by compile.
• Java script tutorial — same API, different language.